Criação de endpoints

Defina seus endpoints através desta API

154
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.

Bora pro código?

383

Parâmetros da requisição

ParâmetroTipoDescrição
url
obrigatório
String"Endpoint", ou seja, o endereço URL no qual você deseja receber notificações
resource
obrigatório
StringRecurso 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
StringGatilho 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âmetroTipoDescrição
id
obrigatório
StringIdentificador do endpoint criado. Esse id pode ser utilizado na exclusão de endpoints
url
obrigatório
StringEndpoint, ou endereço URL para o qual as notificações serão enviadas
resource
obrigatório
StringRecurso escolhido no momento da criação do endpoint, indica o serviço que será associado ao gatilho
trigger
obrigatório
StringGatilho definido ao criar o endpoint, indica o que ocasionará o envio da notificação
connectionTimeout
obrigatório
IntTempo limite de conexão permitido antes que ocorra um erro de tempo limite
readTimeout
obrigatório
IntTempo limite de leitura antes que ocorra um erro de tempo limite
includeResource
obrigatório
Booleanfalse
expandable
obrigatório
Booleanfalse
active
obrigatório
BooleanIndica se o endpoint está ativo ou não. No momento da criação, será definido como true

Dicas de implementação

188

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 erroDescriçã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

ResourceDescrição
invoiceRecurso 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
transferRecurso de transferências. Pode ajudar no monitoramento de erros em transferências e em atualizações de status em tempo real
paymentRecurso de pagamentos. Este recurso poderá ser utilizado no monitoramento de erros em pagamentos e em atualizações de status em tempo real
registerRecurso 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_receiptRecurso 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

ResourceTriggerDescrição
invoicedraftedStatus intermediário da fatura quando ela está sendo criada. As faturas ficam no status DRAFT por um tempo muito pequeno
invoicecreatedFatura em aberto, não está paga, nem vencida e nem cancelada. Possuem o status OPEN
invoicepaidFatura paga, possui status PAID
invoicecanceledFatura cancelada, possui status CANCELED
invoiceoverdueFatura 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

ResourceTriggerDescrição
transferrefundedTransferência estornada
transfercanceledTransferência cancelada
transfercompletedTransferência concluída
transfer*Para receber todos os status possíveis do recurso, utilize * .

Trigger para pagamento

ResourceTriggerDescrição
paymentinitiatedO pagamento foi iniciado
paymentcreatedO pagamento foi criado
paymentcompletedO pagamento foi realizado com sucesso
paymenterrorHouve um erro ao tentar executar o pagamento
paymentreprovedO pagamento iniciado pela API foi reprovado pelo cliente
paymentapprovedO pagamento iniciado pela API foi aprovado pelo cliente
payment*Para receber todos os status possíveis do recurso, utilize *

Trigger para pré-cadastro

ResourceTriggerDescrição
registercompletedCadastro finalizado

Trigger para Nota Fiscal de Serviço

ResourceTriggerDescrição
service_receiptissuedNota fiscal emitida com sucesso.
service_receiptcancelledNota fiscal cancelada.
service_receiptcancel_errorErro ao tentar cancelar uma nota fiscal.
service_receipterrorErro 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.
Language
Authorization
OAuth2
Click Try It! to start a request and see the response here!