A Corporate Gateway API permite que sua empresa integre processos como cadastro de filiais e colaboradores, criação de pedidos, acompanhamento de pagamentos e solicitação de cartões físicos.
Consulte o Guia de Integração da Corporate API para acessar todos os endpoints, campos disponíveis e exemplos de requisições.
Autenticação 120 min Validade do token JWT Limite geral 600/min Chamadas por minuto por credencial Ambientes 2 Homologação e produção
Quem pode utilizar a API?
A API é destinada aos times de tecnologia e engenharia das empresas que desejam automatizar a integração com a Swile.
As credenciais de acesso são fornecidas pela Swile. Não há cadastro automático ou criação de credenciais diretamente pela API.
Quais ambientes estão disponíveis?
A API possui dois ambientes:
Homologação
Ambiente recomendado para desenvolvimento e testes.
https://corporate-gateway-staging.swile.com.br
Produção
Utilize depois de validar o funcionamento da integração.
https://corporate-gateway.swile.com.br
Como funciona a autenticação?
A autenticação começa pelo endpoint de login:
GET /api/v1/auth/loginAs credenciais são enviadas utilizando HTTP Basic Auth. Em resposta, a API retorna um token JWT, que deve ser utilizado nas demais chamadas no header:
Authorization: Bearer <token>O token tem validade de 120 minutos. Depois desse período, é necessário realizar um novo login.
Quais processos podem ser integrados?
A Corporate Gateway API oferece recursos para:
- cadastrar e consultar filiais;
- criar e gerenciar grupos de colaboradores;
- cadastrar, consultar, editar e inativar colaboradores;
- criar pedidos de benefícios;
- consultar o status e o pagamento dos pedidos;
- acompanhar saldos e extratos;
- solicitar cartões físicos;
- acompanhar entregas;
- cancelar remessas ou encomendas, quando aplicável.
Como criar pedidos de benefícios?
Existem três formas de criar um pedido:
1
Summary + Create
Permite consultar um resumo dos valores antes de confirmar o pedido. É indicado quando a empresa precisa revisar ou aprovar os dados antes da criação.
2
Express
Cria o pedido em uma única chamada, sem uma etapa prévia de conferência.
3
Express via planilha
Utiliza um arquivo enviado previamente e é indicado para pedidos com grande volume de colaboradores.
Como consultar o status de um pedido?
Depois de criar um pedido, armazene o orderGroupCode retornado pela API. Esse código deve ser utilizado para consultar o status posteriormente.
A criação do pedido e o pagamento são etapas diferentes. Alguns status possíveis são:
| Status | Significado |
|---|---|
| WAITING_PAYMENT | O pedido foi faturado, mas o pagamento ainda não foi confirmado. |
| PAID | O pagamento foi confirmado. |
| PROCESSING | Os créditos estão sendo processados. |
| APPROVED | Todos os colaboradores foram creditados com sucesso. |
| APPROVED_PARTIALLY | Parte dos colaboradores foi creditada, mas existem pendências. |
Como identificar os códigos das carteiras?
O código da carteira é informado no campo card, dentro de cardValues.
Os códigos disponíveis podem variar de acordo com a empresa e a filial. Por isso, consulte o campo cardTypes no endpoint:
GET /api/v1/workgroupA documentação também apresenta códigos conhecidos para carteiras como Alimentação, Refeição, Multibenefícios, Presente Natal, Multibenefícios Natal e Cesta Natal.
Quais formatos de dados a API aceita?
A API possui formatos específicos para os principais campos:
- CPF: 11 dígitos, com ou sem pontuação;
- CNPJ: 14 dígitos, com ou sem pontuação;
- telefone: número de celular com DDD e 9 dígitos;
- e-mail: deve utilizar caracteres ASCII, domínio válido e extensão com pelo menos duas letras;
- CEP: 8 dígitos, com ou sem hífen;
- UF: duas letras maiúsculas.
400 e o código de erro 40016.Existem limites de utilização?
Sim. A API possui limites por endpoint e também um limite geral para todas as chamadas realizadas com a mesma credencial.
O limite geral é de 600 chamadas por minuto. Cada endpoint possui sua própria cota, que pode ser consultada na documentação.
Ao ultrapassar o limite, a API retorna:
- status HTTP
429; - código de erro
42900; - header
Retry-After, que informa quantos segundos aguardar antes de tentar novamente.
Retry-After. Evite repetir a chamada imediatamente ou criar loops de tentativas.Como definir as datas de crédito e vencimento?
As datas devem ser enviadas em UTC.
Pagamentos via PIX
- a data de crédito deve estar pelo menos um dia útil no futuro;
- não há boleto vinculado à resposta.
Pagamentos via boleto
- a data de crédito deve estar pelo menos dois dias úteis no futuro;
- a data de vencimento deve ser pelo menos um dia antes da data de crédito.
Onde encontro todos os endpoints e campos disponíveis?
O guia de integração apresenta os principais fluxos e exemplos práticos.
Para consultar todos os endpoints, campos e respostas, além de testar requisições diretamente no navegador, utilize a Swagger UI disponível na documentação da API.
Como solicitar credenciais ou suporte?
Caso sua empresa ainda não tenha recebido as credenciais ou precise de ajuda com a integração, entre em contato conosco por meio do card abaixo: Ainda precisa de ajuda?