Guia de Integração - Corporate Gateway API

Bienvenue! Este guia foi feito para o time de engenharia da sua empresa integrar com a API do Corporate Gateway da Swile. Ele reúne exemplos práticos com curl pros principais fluxos, na ordem em que normalmente são usados durante uma integração - login, cadastro de filiais e colaboradores, criação de pedidos e solicitação de cartão físico.

Ambientes

Use o ambiente de homologação pra desenvolver e testar sua integração, e só troque para produção depois que tudo estiver validado.

Os exemplos abaixo usam o ambiente de homologação. Basta trocar a URL base para produção quando estiver tudo certo.

Formatos de campo

Estes seis campos aparecem em quase toda chamada da API e cada um aceita um conjunto fechado de formatos. Vale a mesma regra em todos os endpoints, então dá pra conferir aqui uma vez e seguir.

Limites de uso

Cada credencial tem um limite de chamadas por minuto. O limite é por endpoint, porque endpoints diferentes custam coisas diferentes do lado da Swile: cada endpoint tem a sua própria cota, então estourar o limite de um não impede o uso dos outros. Existe também um teto que vale para a soma de todas as chamadas da credencial.

Cada endpoint tem também um limite de rajada, numa janela de 10 segundos, para evitar que o orçamento de um minuto inteiro seja gasto de uma vez. Toda resposta traz os números exatos nos headers, então dá pra se guiar por eles em vez de fixar os valores no código:

Ao estourar, a resposta é 429 com o código 42900 e o header Retry-After, em segundos:

{
  "error": { "code": 42900, "type": "RATE_LIMIT_EXCEEDED" },
  "message": "Rate limit exceeded.",
  "details": "You have exceeded your rate limit: 180 requests per minute, 30 per 10 seconds. You can try again in 6 seconds."
}

Autenticação

Toda integração começa por aqui. Você vai usar o username e password que a Swile forneceu pra sua empresa pra pedir um token de acesso (JWT) - e esse token é o que você envia em todas as outras chamadas da API, provando que a requisição é sua. Não existe cadastro self-service: as credenciais de acesso são fornecidas pela Swile. Se sua empresa ainda não as recebeu, entre em contato com a Central de Ajuda Swile para Empresas pra solicitá-las.

sequenceDiagram
    participant C as Sistema da sua empresa
    participant G as Corporate Gateway
    C->>G: GET /api/v1/auth/login (Basic Auth)
    G->>C: 200 OK - token JWT, validade 120 min
    Note over G: Todas as chamadas seguintes usam Authorization: Bearer token
    C->>G: Qualquer endpoint /api/v1/**
    G->>C: 200 OK ou erro de negocio
    

Requisição

As credenciais vão como HTTP Basic Auth:

curl -u "usuario:senha" \
  https://corporate-gateway-staging.swile.com.br/api/v1/auth/login

Resposta

{
  "token": "eyJhbGciOiJIUzI1NiJ9...",
  "issuedAt": "2026-07-13T12:00:00.000+00:00",
  "expiresAt": "2026-07-13T14:00:00.000+00:00"
}

Criar Filial

Uma filial representa uma unidade ou CNPJ específico da sua empresa dentro do Corporate Gateway. Se sua empresa opera com mais de um CNPJ (matriz e filiais, por exemplo), cadastrar cada uma separadamente permite organizar work groups, pedidos e faturamento de forma independente por unidade - útil se cada filial tem orçamento ou responsável próprio. Se sua empresa tem só um CNPJ, esse passo pode não ser necessário; confirme com o time da Swile responsável pela sua implantação antes de pular pra próxima etapa.

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Filial São Paulo",
    "nameOnCard": "Empresa SP",
    "document": "12345678000190",
    "createdBy": "rh@empresa.com.br",
    "address": {
      "street": "Av. Paulista",
      "number": "123",
      "neighborhood": "Bela Vista",
      "zipCode": "01311000",
      "city": "São Paulo",
      "state": "SP"
    }
  }' \
  https://corporate-gateway-staging.swile.com.br/api/v1/corporate/branch/add

Resposta: 202 Accepted, sem corpo - a criação é assíncrona. Confirme que a filial foi criada com:

curl -H "Authorization: Bearer $TOKEN" \
  "https://corporate-gateway-staging.swile.com.br/api/v1/corporate/branch?branchDocument=12345678000190"

Criar Work Group

Um work group é como você organiza os colaboradores da sua empresa dentro do Corporate Gateway - normalmente por departamento, cargo, ou qualquer critério que faça sentido pro seu negócio. Todo colaborador precisa pertencer a um work group antes de poder receber benefícios, então esse é o próximo passo depois de autenticar (e, se for o seu caso, criar a filial). Você pode criar um work group direto sob a sua empresa principal, ou vinculado a uma filial específica.

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Novo Grupo",
    "description": "Grupo para colaboradores do time X",
    "document": "12345678000190"
  }' \
  https://corporate-gateway-staging.swile.com.br/api/v1/workgroup

Resposta: 200 OK com o id do grupo - guarde-o, é o idWorkGroup que você vai usar ao adicionar colaboradores.

Adicionar e Editar Employees

Employees são os colaboradores da sua empresa que vão receber os benefícios Swile (carteira digital, cartão físico, etc). Antes de criar pedidos ou solicitar cartões, cada colaborador precisa estar cadastrado aqui, vinculado a um work group.

Adicionar

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "employees": [
      {
        "idWorkGroup": 1,
        "name": "João da Silva",
        "email": "joao@empresa.com.br",
        "phoneNumber": "(11) 99999-9999",
        "document": "11111111111",
        "birthDate": "1990-01-01",
        "externalId": "abc123"
      }
    ]
  }' \
  https://corporate-gateway-staging.swile.com.br/api/v1/employee/add

Resposta: 202 Accepted, sem corpo - o cadastro é assíncrono, veja como confirmar que deu certo logo abaixo.

Confirmando a criação

O 202 Accepted confirma só que a Swile aceitou o pedido de cadastro para processar - não que o colaborador já existe de fato. O processamento é assíncrono, então pode levar alguns segundos até ele aparecer.

Depois de chamar /employee/add, faça polling em GET /api/v1/employee filtrando pelo CPF em identifier, até o colaborador aparecer na lista:

curl -H "Authorization: Bearer $TOKEN" \
  "https://corporate-gateway-staging.swile.com.br/api/v1/employee?identifier=11111111111&page=0&pageSize=1"

Quando ele aparecer, guarde o idEmployee retornado - é ele que você vai usar em praticamente todas as outras operações (editar, solicitar cartão, criar pedido etc), não o CPF.

Editar

Atualização parcial - envie só os campos que quer alterar:

curl -X PATCH \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "novo-email@empresa.com.br",
    "phoneNumber": "(11) 98888-8888"
  }' \
  https://corporate-gateway-staging.swile.com.br/api/v1/employee/123

Erros de validação

Vale para Adicionar e Editar. Antes de gravar qualquer coisa a Swile valida a lista inteira: se algum colaborador não passar, nada é gravado e a resposta é um 400 com o código 40028 e a lista errors, com um item para cada problema encontrado.

{
  "error": { "code": 40028, "type": "INVALID_EMPLOYEES" },
  "message": "Invalid employees in the request",
  "details": "1 invalid employee found",
  "errors": [
    {
      "row": 2,
      "kind": "MISSING_DATA",
      "message": "The employee needs at least one contact method: send email or phoneNumber"
    }
  ]
}

Os campos funcionam igual aos da remessa de cartões: row é a posição do colaborador na lista employees que você enviou, começando em 1, field é o campo que falhou e kind é o tipo da falha. Em Editar não existe row, já que a chamada trata de um colaborador só.

Recusas que não estão ligadas a um colaborador específico vêm como 400 com o código 40000 (ao adicionar) ou 40007 (ao editar) e a explicação em details, sem a lista errors. Outros tipos de recusa são repassados com o mesmo status HTTP que a Swile recebeu internamente, com o código 40029.

Alterar Status

Ativa ou desativa employees em lote:

curl -X PUT \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "INACTIVE",
    "employeeIds": [123, 456]
  }' \
  https://corporate-gateway-staging.swile.com.br/api/v1/employee/update/status

Criação de Pedidos

Um pedido (order) é a operação que efetivamente credita valores nas carteiras dos colaboradores - é assim que o benefício chega até eles. Existem 3 formas de criar um pedido; todas terminam no mesmo lugar, mas com fluxos diferentes dependendo de como sua empresa quer operar:

Códigos de carteira (wallet codes)

O campo card em cardValues identifica o tipo de carteira/benefício a creditar. Não é uma lista fechada - sua empresa pode ter códigos adicionais provisionados especificamente pra ela; confira o campo cardTypes de GET /api/v1/workgroup pra ver os códigos disponíveis pra sua empresa/filial. Códigos conhecidos:

Faturamento para uma filial (opcional)

Por padrão, o pedido é faturado/agrupado pra sua empresa principal. Se quiser que ele seja faturado e agrupado por uma filial específica, informe o CNPJ dela em benefitPayerDocument (pedidos de benefício) e/ou campaignPayerDocument (pedidos de campanha) - use o que fizer sentido pro seu caso. Os dois campos existem em /order/create, /order/create/express e /order/create/import/express:

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "data": [
      { "document": "11111111111", "cardValues": [{ "card": "v4", "value": 200.00 }] }
    ],
    "paymentMethod": "PIX",
    "creditDate": "2026-07-14T00:00:00",
    "campaignPayerDocument": "12345678000195"
  }' \
  https://corporate-gateway-staging.swile.com.br/api/v1/order/create/express

Fluxo 1: Summary + Create

sequenceDiagram
    participant C as Sistema da sua empresa
    participant G as Corporate Gateway
    C->>G: POST /api/v1/order/summary
    G->>C: 200 OK - summaryId e valores calculados
    Note over C: Você confere os valores antes de confirmar
    C->>G: POST /api/v1/order/create (com o summaryId)
    G->>C: 200 OK - status do pedido
    

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "data": [
      { "document": "11111111111", "cardValues": [{ "card": "v4", "value": 200.00 }] }
    ]
  }' \
  https://corporate-gateway-staging.swile.com.br/api/v1/order/summary

Guarde o summaryId retornado e confirme:

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "summaryId": "SUM123456",
    "paymentMethod": "PIX",
    "creditDate": "2026-07-14T00:00:00"
  }' \
  https://corporate-gateway-staging.swile.com.br/api/v1/order/create

Fluxo 2: Express

sequenceDiagram
    participant C as Sistema da sua empresa
    participant G as Corporate Gateway
    C->>G: POST /api/v1/order/create/express (dados completos)
    G->>C: 200 OK - status do pedido
    

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "data": [
      { "document": "11111111111", "cardValues": [{ "card": "v4", "value": 200.00 }] }
    ],
    "paymentMethod": "PIX",
    "creditDate": "2026-07-14T00:00:00"
  }' \
  https://corporate-gateway-staging.swile.com.br/api/v1/order/create/express

Fluxo 3: Express via Planilha

sequenceDiagram
    participant C as Sistema da sua empresa
    participant G as Corporate Gateway
    participant S3 as Storage (S3)
    C->>G: GET /api/v1/order/upload/arquivo.csv
    G->>C: 200 OK - URL pré-assinada e file key
    C->>S3: PUT do arquivo na URL pré-assinada
    C->>G: POST /api/v1/order/create/import/express (fileKey e mapping)
    G->>C: 200 OK - status do pedido
    

curl -H "Authorization: Bearer $TOKEN" \
  "https://corporate-gateway-staging.swile.com.br/api/v1/order/upload/pedido-julho.csv"

Depois de subir o arquivo na URL retornada, crie o pedido:

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "fileKey": "orders/imports/abc123-pedido-julho.csv",
    "mapping": { "document": 0, "v4": 1 },
    "paymentMethod": "PIX",
    "creditDate": "2026-07-14T00:00:00"
  }' \
  https://corporate-gateway-staging.swile.com.br/api/v1/order/create/import/express

Consultando o status (e confirmando o pagamento)

As três chamadas de criação respondem na hora, mas o status que elas devolvem é só uma foto do instante da criação - o processamento continua depois disso de forma assíncrona (cobrança do pagamento, crédito nas carteiras dos colaboradores etc). "O pedido foi criado" não é a mesma coisa que "o pedido foi pago": pra saber isso é preciso consultar de novo, mais tarde.

Guarde o orderGroupCode retornado na criação e use ele pra consultar:

curl -H "Authorization: Bearer $TOKEN" \
  "https://corporate-gateway-staging.swile.com.br/api/v1/order/group?code=SWO123456789&page=0&size=10"

Pra saber se o pedido foi pago, olhe o status retornado: o pagamento já está confirmado assim que ele sai de WAITING_PAYMENT e chega em PAID (ou em qualquer status posterior no fluxo, como ON_QUEUE, PROCESSING ou APPROVED). Veja o significado de cada um:

Solicitação de Cartão - Logística

Se sua empresa oferece cartão físico Swile pros colaboradores (além ou no lugar da carteira digital), é aqui que você solicita a emissão e o envio dele. O pedido de cartão físico e o endereço de entrega são feitos juntos, numa única chamada - não existe um "criar cartão" separado do "pedir entrega".

sequenceDiagram
    participant C as Sistema da sua empresa
    participant G as Corporate Gateway
    participant T as Transportadora
    C->>G: POST /api/v1/logistics/shipment/employee
    G->>C: 200 OK - code da remessa e status inicial
    G-->>T: Processamento interno do envio
    C->>G: GET /api/v1/logistics/parcel/track/code
    G->>C: status atualizado (PROCESSING, IN_TRANSIT, DELIVERED...)
    

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "contactName": "Raquel Milena",
    "contactPhone": "(11) 99999-9999",
    "contactEmail": "raquel@empresa.com.br",
    "contactDocument": "11111111111",
    "delivered": false,
    "employees": [
      {
        "name": "João da Silva",
        "phoneNumber": "(11) 99999-9999",
        "email": "joao@empresa.com.br",
        "document": "11111111111",
        "externalId": "abc123",
        "address": {
          "postalCode": "01121000",
          "buildingNumber": "966",
          "street": "Rua Prates",
          "neighborhood": "Bom Retiro",
          "city": "São Paulo",
          "state": "SP"
        }
      }
    ]
  }' \
  https://corporate-gateway-staging.swile.com.br/api/v1/logistics/shipment/employee

Erros de validação

Antes de criar a remessa, a Swile valida cada colaborador da lista: confere o CPF, o endereço e se a pessoa está cadastrada na sua empresa. Se algum colaborador não passar, nada é criado e a resposta é um 400 com o código 40026 e a lista errors, com um item para cada problema encontrado.

{
  "error": { "code": 40026, "type": "INVALID_SHIPMENT_EMPLOYEES" },
  "message": "Invalid employees in the shipment request",
  "details": "2 invalid employees found",
  "errors": [
    {
      "row": 1,
      "field": "postalCode",
      "kind": "INVALID_POSTAL_CODE",
      "message": "O CEP não corresponde ao Estado informado. CEP: 72600-411, Estado: SP"
    },
    {
      "row": 3,
      "field": "document",
      "kind": "EMPLOYEE_NOT_FROM_CORPORATE",
      "message": "O CPF 111.111.111-11 não foi encontrado entre os colaboradores da empresa informada"
    }
  ]
}

Se a requisição for recusada sem estar ligada a um colaborador específico, a resposta vem como 400 com o código 40013 e a explicação no campo details, sem a lista errors.

Recusas de outros tipos são repassadas com o mesmo status HTTP que a Swile recebeu internamente (por exemplo 409 ou 422), com o código 40027 e a explicação em details. Um 500 significa falha do nosso lado, não do seu payload: nesse caso vale tentar de novo antes de abrir chamado.

Acompanhando a entrega

Guarde o code de cada parcel (não o da remessa como um todo) para rastrear a entrega:

curl -H "Authorization: Bearer $TOKEN" \
  https://corporate-gateway-staging.swile.com.br/api/v1/logistics/parcel/track/SWB123456789P