Defina seus endpoints através desta API
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. |