Instruções iniciais
Saiba como começar a trabalhar com as nossas APIs
Conhecimento técnico: Intermediário
Criamos uma documentação para você utilizar as APIs da Cora de um jeito simples e fácil, mas recomendamos que você já tenha um conhecimento técnico em desenvolvimento de software.
Modalidade de Integração
Me dá um exemplo, por favor? Temos várias empresas parceiras que estão enquadradas como ERPs (Enterprise Resource Planning), ou seja, empresas que oferecem softwares de gestão empresarial para facilitar a operação de seus clientes. Essas empresas buscam na Cora os produtos bancários que faltavam para complementar a gama de produtos e serviços e dar uma experiência mais fluída na gestão de seu negócio e ao ”Cliente Final”.
Mas empresas da modalidade ERP é apenas um exemplo. Como falamos na seção acima, diversas empresas de outras áreas também vem a Cora como a parceira ideal para oferecer produtos bancários de qualidade.
Credenciais de acesso
As credenciais de acesso às APIs da Cora variam de acordo com a modalidade escolhida, mas todas podem ser solicitadas no menu Conta > Integrações via APIs
Agora, segue exemplos dos valores dessas variáveis (modalidade Parceria Cora):
Credencial | Valor |
---|---|
client-id | app-teste-doc |
client-secret | 81d231f4-f8e5-4b52-9c08-24dc45321a16 |
Controle de versão
Hoje nas APIs da Cora, não temos nenhuma troca de versão das APIs, porém adotaremos o controle de versão por path.
Veja como ficaria a versão 2 da API de emissão de boleto:
https://api.stage.cora.com.br/v2/invoices
Ambientes
Na Cora, disponibilizamos dois ambientes distintos para atender às suas necessidades: o ambiente de teste (Stage) e o ambiente de produção.
Stage
O ambiente de teste, também conhecido como "Stage", é destinado para testes e desenvolvimento. Nele, você pode realizar operações como emissão de cobranças, simulação de pagamentos, efetuação de transferências, consulta de saldo e extrato, entre outros. O ambiente de teste permite que você se familiarize com nossos processos e recursos sem qualquer risco para suas operações financeiras reais. Utilizar o ambiente de teste é essencial para garantir que sua integração com nossa API funcione sem problemas quando você for ao ambiente de produção.
Para a Integração Direta, é necessário utilizar a URL base de Stage, além de verificar se o certificado e key estão relacionados ao ambiente de testes. Veja a URL base de Stage para a Integração Direta:
https://matls-clients.api.stage.cora.com.br/
Veja a URL base de Stage para a Parceria Cora:
https://api.stage.cora.com.br/
Produção
O ambiente de produção é onde as transações financeiras reais ocorrem. Quando você estiver confiante de que sua integração com a API está funcionando perfeitamente no ambiente de teste, é hora de migrar para o ambiente de produção. Aqui, você pode realizar todas as operações financeiras necessárias para o seu negócio, com a segurança e a confiabilidade que você espera.
Para se adaptar ao ambiente de produção após os testes, é necessário alterar a URL base e utilizar as credenciais do ambiente de produção. No caso da Integração Direta, as credenciais de produção incluiriam um certificado e uma private key distintos daqueles utilizados no ambiente de testes. E na Parceria Cora, seria necessário substituir o client secret que era utilizado em ambiente de testes.
Veja a URL base de produção para a Integração Direta:
https://matls-clients.api.cora.com.br/
Veja a URL base de produção para a Parceria Cora:
https://api.cora.com.br/
Paginação
Temos diversas APIs em nossa documentação que são paginadas. O objetivo da paginação é otimizar o envio de grandes volumes de dados de forma desnecessária, ou seja, enviando os dados de acordo com a necessidade e de forma explícita. Para isso usamos dois parâmetros:
Campo | Descrição |
---|---|
page | Número da página. Esse campo inicia no valor 0 |
size | Tamanho da página, ou seja, a quantidade máxima de itens que será retornada na página solicitada. Quando não enviado esse campo assume o valor padrão de 50. |
Formatação de datas
Hoje temos 2 tipos de formatação de data nas requisições e nas respostas.
Nas requisições
A primeira formatação é pensada para simplificar para você, parceiro desenvolvedor. Nas requisições que vocês farão, precisaremos apenas do ano, mês e dia, nessa ordem. Veja só o campo scheduled_at no exemplo abaixo de uma Iniciação de um Pagamento agendado. O formato da data será: “YYYY-MM-DD”
{
"code": "meu_id",
"digitable_line": "00190000090320204700900014033179986620000015000",
"scheduled_at": "2021-10-10"
}
Nas respostas
Nas respostas adotamos o formato ISO Date, pois é preciso dar mais precisão de minuto e segundo que determinada operação foi executada em nosso sistema. Veja um exemplo no campo created_at retorno da API de Iniciação de pagamento. O formato da data será: “YYYY-MM-DDTHH:MM:SS”
{
"created_at": "2021-06-23T13:58:21"
}
Tratamento de Erros
Aqui na Cora, utilizamos o padrão convencional de erros na resposta de nossas APIs. Confira o que cada um deles quer dizer:
Para facilitar ainda mais, estamos no processo de padronização de nossas mensagens de erros para o formato abaixo. Veja um exemplo de requisição inválida por não conter os parâmetros no formato adequado:
{
"code": "invalid_request",
"message": "Request has invalid parameters",
"errors": [
{
"id": "person.identity",
"message": "must not be empty"
}
]
}
Parâmetros da resposta
Campo | Comentário |
---|---|
code | String com a descrição do código de erro |
message | Descrição mais detalhada do motivo do erro |
errors | Lista de erros com seus respectivos caminhos e detalhes. No exemplo acima, o campo identity do objeto person não pode ser nulo. |
Lista de Códigos (code) possíveis
Campo | Message | Status Code | Descrição |
---|---|---|---|
invalid_request | Request has invalid parameters | 400 | Requisição inválida (Bad Request) |
server_error | Unexpected error | 5xx | Código genérico de erro |
Suporte
Se você já iniciou a integração, mas tem dúvidas sobre a implementação, nosso time de suporte está aqui para ajudar você pelo e-mail [email protected]
Conceitos importantes
Idempotência
Idempotência
O conceito de idempotência, quando aplicado ao contexto de APIs Restful (padrão que utilizamos aqui na Cora), significa que requisições idênticas para o mesmo recurso, irão retornar o mesmo valor independente de quantas vezes for chamada.
Esse conceito é bastante importante em APIs do setor financeiras, pois quando aplicado corretamente pode evitar que operações sejam duplicadas por uma eventual falha de conexão.
curl --location --request POST 'https://api.stage.cora.com.br/invoices' \
--header 'Idempotency-Key: f08dad6b-96bc-4e5e-ad82-acb34a8749e4' \
...
Updated 4 months ago