Criação de endpoints

Importante para Integração Direta Para você conseguir efetuar essa integração é obrigatória a leitura sobre "Utilização das APIs" e recomendada a leitura sobre "Instruções Iniciais" e "Client Credentials e Client ID"

O que é um endpoint?

Um endpoint é um ponto final de comunicação em um sistema de computador ou na internet. Em outras palavras, é uma URL (Uniform Resource Locator) para o qual podemos enviar dados ou informações em tempo real por meio de uma chamada de API. Fique à vontade para adicionar quantos endpoints desejar. É possível receber todos os status em um único endpoint ou até mesmo adicionar um endpoint diferente para cada status ou recurso.

Quais os benefícios de utilizar notificações webhook?

As notificações webhook são uma forma eficiente de enviar informações em tempo real. Quando um evento ocorre na Cora, é enviada uma mensagem para uma URL específica, o endpoint, que é definido através de API. Essas mensagens são úteis para várias propósitos, incluindo:

Atualizações em tempo real: As notificações webhook permitem que aplicativos e serviços recebam informações em tempo real, permitindo que eles sejam atualizados instantaneamente
Automação de processos: As notificações webhook podem ser usadas para automatizar processos, como atualizações de banco de dados, sincronização de dados entre aplicativos e muito mais
Redução da sobrecarga de rede: As notificações webhook são enviadas apenas quando há uma mudança de estado, em vez de enviar atualizações periódicas, reduzindo a sobrecarga de rede

Quais são os requisitos para a utilização desta API?

Token: possuir um token de acesso válido é essencial. Caso ainda não tenha gerado um, temos um guia detalhado disponível no tópico Fluxos de Autorização e Autenticação.
- Integração Direta: Ter finalizado a etapa de autorização
- Parceria Cora: Já ter feito a etapa de autorização e autenticação

Qual token de acesso devo utilizar?

O token de acesso é um componente crucial para autenticar e autorizar solicitações. Ele é usado para identificar o criador do endpoint e determinar as permissões que este endpoint terá em relação ao acesso e manipulação de informações via API. Isso significa que tokens de Parceiros com grant_type client credentials vinculam o endpoint criado à aplicação, permitindo que todas as notificações relacionadas ao parceiro sejam realizadas no endpoint escolhido. Já tokens de clientes finais com grant_type authorization_code restringem as notificações ao endpoint, permitindo acesso apenas às informações do cliente específico.

Parâmetros da requisição

Parâmetro	Tipo	Descrição
url obrigatório	String	"Endpoint", ou seja, o endereço URL no qual você deseja receber notificações
resource obrigatório	String	Recurso que indica o grupo da notificação que será recebida. Temos grupos como: boletos, transferências, pagamentos e cadastros. É possível consultar os tipos de recurso disponíveis em resource
trigger obrigatório	String	Gatilho que ocasionará a notificação. Gatilhos são associados aos recursos e é possível identificar as opções disponíveis em trigger

Parâmetros da resposta

Parâmetro	Tipo	Descrição
id obrigatório	String	Identificador do endpoint criado. Esse id pode ser utilizado na exclusão de endpoints
url obrigatório	String	Endpoint, ou endereço URL para o qual as notificações serão enviadas
resource obrigatório	String	Recurso escolhido no momento da criação do endpoint, indica o serviço que será associado ao gatilho
trigger obrigatório	String	Gatilho definido ao criar o endpoint, indica o que ocasionará o envio da notificação
connectionTimeout obrigatório	Int	Tempo limite de conexão permitido antes que ocorra um erro de tempo limite
readTimeout obrigatório	Int	Tempo limite de leitura antes que ocorra um erro de tempo limite
includeResource obrigatório	Boolean	false
expandable obrigatório	Boolean	false
active obrigatório	Boolean	Indica se o endpoint está ativo ou não. No momento da criação, será definido como true

Dicas de implementação

Premissas

É fundamental garantir que a URL inserida esteja correta e que o recurso escolhido realmente existe na documentação. Verificar estes pontos pode economizar tempo e evitar frustrações ao tentar receber notificações de recursos indisponíveis.

Erros Comuns

Código de erro	Descrição
401 (Unauthorized)	O token de acesso está inválido ou expirado. Erro comum no momento de trocas de ambientes (Stage/Production).
400 (Bad Request)	Requisição mal formatada. Alguns exemplos comuns: - URL não informada - Campos com algum erro de digitação

Enumeradores

Enum de Recursos

Resource	Descrição
invoice	Recurso de boletos. Poderá ser utilizado na atualização do status de boletos criados através de API, tornando possível, por exemplo, notificações de pagamento em tempo real
transfer	Recurso de transferências. Pode ajudar no monitoramento de erros em transferências e em atualizações de status em tempo real
payment	Recurso de pagamentos. Este recurso poderá ser utilizado no monitoramento de erros em pagamentos e em atualizações de status em tempo real
register	Recurso de pré-cadastro. Poderá ser utilizado para identificar quais indicações realizadas através da API de pré-cadastro foram concluídas com sucesso, ou seja, quantos clientes indicados efetivamente abriram uma conta Cora
service_receipt	Recurso para nota fiscal de serviço. Esse recurso pode ser utilizado para monitorar os eventos relacionados a emissão e cancelamento de uma nota fiscal.
*	Todos os recursos anteriores.

Enum de Triggers

Triggers para Boleto

Resource	Trigger	Descrição
invoice	drafted	Status intermediário da fatura quando ela está sendo criada. As faturas ficam no status DRAFT por um tempo muito pequeno
invoice	created	Fatura em aberto, não está paga, nem vencida e nem cancelada. Possuem o status OPEN
invoice	paid	Fatura paga, possui status PAID
invoice	canceled	Fatura cancelada, possui status CANCELED
invoice	overdue	Fatura atrasada com status LATE (passou da data de vencimento). É possível que faturas mudem de LATE para PAID quando há atraso no recebimento de arquivos pelo banco ou quando a data de vencimento cai em um dia que não há recebimento de arquivos do banco. É possível também que faturas mudem de LATE para CANCELED.
invoice	*	Para receber todos os status possíveis do recurso, utilize * .

Trigger para transferência

Resource	Trigger	Descrição
transfer	refunded	Transferência estornada
transfer	canceled	Transferência cancelada
transfer	completed	Transferência concluída
transfer	*	Para receber todos os status possíveis do recurso, utilize * .

Trigger para pagamento

Resource	Trigger	Descrição
payment	initiated	O pagamento foi iniciado
payment	created	O pagamento foi criado
payment	completed	O pagamento foi realizado com sucesso
payment	error	Houve um erro ao tentar executar o pagamento
payment	reproved	O pagamento iniciado pela API foi reprovado pelo cliente
payment	approved	O pagamento iniciado pela API foi aprovado pelo cliente
payment	*	Para receber todos os status possíveis do recurso, utilize *

Trigger para pré-cadastro

Resource	Trigger	Descrição
register	completed	Cadastro finalizado

Trigger para Nota Fiscal de Serviço

Resource	Trigger	Descrição
service_receipt	issued	Nota fiscal emitida com sucesso.
service_receipt	cancelled	Nota fiscal cancelada.
service_receipt	cancel_error	Erro ao tentar cancelar uma nota fiscal.
service_receipt	error	Erro ao tentar emitir uma nota fiscal.

Integração Direta e Testes

Esta plataforma de documentação, atualmente, não permite o upload de informações importantes como certificados e private keys. Por isso, não recomendamos o uso dela para testes da modalidade de Integração Direta.

Para fazer os testes que incluam essas informações sensíveis pedimos que use um sistema de sua escolha.