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.

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. Confirme buscando pelo CPF e guarde o idEmployee retornado, usado em praticamente todas as outras operações.

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

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

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

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