Instruções iniciais

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

Parceria Cora Essa modalidade é utilizada por empresas que querem em conjunto com a Cora, oferecer uma experiência integrada e diferenciada de gestão de cobranças, pagamentos e visualização de entradas e saídas aos clientes finais.

Em Parceria Cora teremos 3 atores e nesta documentação sempre vamos direcionar a eles da seguinte forma:

Cora Sempre que falarmos "Cora” estamos nos referindo a nós.

Empresa Parceira Sempre que falarmos "Empresa Parceira” estamos nos referindo a você, empresa que buscou a "Cora” para realizar essa parceria.

Cliente Final Sempre que falarmos "Cliente Final” estamos nos referindo ao usuário final que utiliza a sua plataforma e a da "Cora” para gerenciamento.

Para quem é destinada essa modalidade? Empresas ERPs, CRMs, BPO Financeiros, Contabilidades Digitais e vários outros segmentos entram nesta modalidade.
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.

Integração Direta Serão os clientes que utilizam as APIs da Cora diretamente em seus próprios sistemas, sem a necessidade de uma empresa parceira.

Em Integração Direta teremos 2 atores e nesta documentação sempre vamos direcionar a eles da seguinte forma:

Cora Sempre que falarmos "Cora” estamos nos referindo a nós que criamos as soluções tecnológicas.

Cliente Direto Sempre que falarmos "Cliente Direta” estamos nos referindo ao usuário que integra nossas APIs em seu próprio sistema para facilitar seu dia a dia.

Para quem é destinada essa modalidade? Para empresas que têm software próprio de gestão e que desejam integrar diretamente com a Cora para otimizar suas tarefas.

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:

2xx Indicará que a requisição e o processamento foram feitos com sucesso.

4xx Indicarão que houve algum problema nas informações enviadas na requisição. Esses erros podem ser campos mal formatados ou faltantes, erros de permissão e etc.

5xx Indicarão problemas em nossos servidores.

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

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.

Vamos para um caso prático? Se você, através do seu sistema, emitir um boleto através da API de “Gerar uma fatura", e ocorrer uma falha de conexão no momento da resposta, você poderá enviar novamente a requisição idêntica a anterior sem receio que o boleto será emitido duas vezes sem necessidade.

Como é utilizado aqui na Cora? Ao longo de nossa documentação, você irá perceber que nos cabeçalhos (headers) das requisições, teremos uma chave chamada Idempotency-Key que receberá um valor aleatório e único no formato UUID, conforme exemplo do cURL abaixo:

    
    
    curl --location --request POST 'https://api.stage.cora.com.br/invoices' \
--header 'Idempotency-Key: f08dad6b-96bc-4e5e-ad82-acb34a8749e4' \
...

Esse valor em formato UUID será gerado pelo seu sistema e enviado no cabeçalho da requisição. Nós utilizamos essa chave para evitar duplicidade de registros, ou seja, caso você não tenha recebido a resposta de alguma requisição e mandar o mesmo UUID, nós não duplicaremos o registro. Para mais detalhes, consultar RFC9110