Como realizar a integração de API's da Swile

Avatar de Leonardo da Swile
Leonardo da Swile Editado • …
A Corporate Gateway API permite que sua empresa integre os principais processos de gestão de benefícios diretamente aos seus sistemas, 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.
 

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: https://corporate-gateway-staging.swile.com.br
Produção: https://corporate-gateway.swile.com.br
Recomendamos desenvolver e testar a integração no ambiente de homologação. Utilize a produção somente depois de validar o funcionamento da integração.

Como funciona a autenticação?

A autenticação começa pelo endpoint de login:
GET /api/v1/auth/login
As 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. A API não possui endpoint de renovação automática do token.

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:

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;

Express: Cria o pedido em uma única chamada, sem uma etapa prévia de conferência;

Express via planilha: Utiliza um arquivo enviado previamente e é indicado para pedidos com grande volume de colaboradores.

Independentemente do fluxo escolhido, o processamento do pedido ocorre de forma assíncrona. Por isso, a resposta de criação confirma apenas que o pedido foi recebido, não que o pagamento ou o crédito aos colaboradores já foi concluído.

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. Por exemplo:
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.
Recomendamos consultar o status periodicamente, com intervalos entre as chamadas, em vez de fazer várias requisições em sequência.

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/workgroup
A 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.
Quando um campo não segue o formato esperado, a API retorna o status 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.
Ao receber esse erro, aguarde o período indicado no 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.
Para pagamentos via PIX:
  • a data de crédito deve estar pelo menos um dia útil no futuro;
  • não há boleto vinculado à resposta.
Para 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, respostas e 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 através do card abaixo: "Ainda precisa de ajuda?".

Este artigo foi útil?

Usuários que acharam isso útil: 0 de 0

Ainda precisa de ajuda?

Nossa equipe de especialistas está pronta para te ajudar!

Falar com o suporte
Suporte