Gere um boleto registrado através desta API
![Group 913.png 154](https://files.readme.io/e92482c-Group_913.png)
O que é um boleto registrado?
É um boleto que permite que a Cora saiba para quem a sua empresa está emitindo esta cobrança e com isso podemos acompanhar todo o ciclo de vida deste boleto.
Quem pode usar esta API?
Clientes Cora que estão cadastrados em Integração Direta ou Parceria Cora
Quais são requisitos para a utilização desta API?
Integração Direta: Ter finalizado a etapa de autorização
Parceria Cora: Já ter feito a etapa de autorização e autenticação
Escopo: para a modalidade Parceria Cora, é necessário ter ativado o escopo correto ao solicitar autorização e gerar token de acesso para que sua aplicação possa acessar e interagir com as informações da conta de forma segura e autorizada. É possível consultar mais detalhes sobre o escopo e autorização no tópico Redirecionamento.
Nome do escopo | Descrição |
---|---|
invoice | API de boleto |
O que é possível configurar?
- Juros: para cobrar após a data de vencimento
- Multa: para cobrar após a data de vencimento
- Desconto: ajustável para data configurada ou antes da data de vencimento
- Notificação de cobrança: para lembrar o cliente sobre o pagamento
Parâmetros da requisição
Parâmetro | Tipo | Descrição |
---|---|---|
code opcional | String | Código definido por você, pode ser um id do recurso no seu sistema. Nós iremos retornar esse código sempre que você consultar uma fatura. |
customer obrigatório | Customer | Objeto Customer |
services obrigatório | Lista de Services | Lista de Objetos Services |
payment_terms obrigatório | PaymentTerms | Objeto PaymentTerms |
notifications opcional | Notifications | Objeto Notifications |
Parâmetros da resposta
Parâmetro | Tipo | Descrição |
---|---|---|
id obrigatório | String | Identificador da fatura na Cora. Esse id poderá ser usado para consultar os detalhes da fatura. |
status obrigatório | String | Indica qual é o estado do boleto. Os status possíveis estão na Tabela de Estados dos Boletos. |
created_at obrigatório | String | Data de criação da fatura. |
total_amount obrigatório | Int | Valor total em centavos da fatura. Esse valor é a soma dos valores informados no parâmetro Services. |
total_paid obrigatório | Int | Valor total pago (em centavos), caso o boleto ainda não tenha sido pago, ele será zerado. |
occurrence_date opcional | String | Data que o cliente efetuou o pagamento do boleto junto ao banco. |
code obrigatório | String | Código definido por você, pode ser um id do recurso no seu sistema. Nós iremos retornar esse código sempre que você consultar uma fatura. |
customer obrigatório | Customer | Objeto Customer |
services obrigatório | Lista de Services | Lista de Objetos Services |
payment_terms obrigatório | PaymentTerms | Objeto PaymentTerms |
payment_options obrigatório | PaymentOptions | Objeto PaymentOptions |
payments obrigatório | Payments | Lista de Objetos Payments. Caso o pagamento ainda não tenha sido feito o array será vazio. |
pix obrigatório | Pix | Objeto Pix |
notifications opcional | Notifications | Objeto Notifications |
Dicas de implementação
![188](https://files.readme.io/b95e2f5-Frame_911.png)
Premissas
Os parâmetros que tratam de valores são tipos primitivos inteiros com os centavos sendo representados pelos dois dígitos iniciais (unidade e dezena). Como exemplo, temos o valor de R$ 10,01 que é representado por 1001 dentro do valor total_amount. Veja o json abaixo:{
"total_amount": 1001
}
Problemas conhecidos
- Quando enviado um e-mail ou documentos inválidos a Cora está retornando erros genéricos ao invés de retornar erro 400 (Bad Request)
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: - Idempotency-Key que não está no formato correto (uuid) - Chave payment_term escrito no singular ao invés de payment_terms que é o correto. - Valor do boleto menor do que o mínimo de R$5 (amount: 500) - Campo valor (amount) mal formatado. Ex: 20,00 ao invés de 2000. - Data de vencimento do boleto anterior ao dia atual de emissão. |
415 (Unsupported Media Type) | Falta do Content-Type application/json no header da requisição. |
Tipos de Objetos
Objeto Customer
Objeto Document
Parâmetro | Tipo | Descrição |
---|---|---|
identity obrigatório | String | Número do documento do seu cliente (apenas números, sem traços e pontos). Deve ser enviado como uma string. |
type obrigatório | String | Tipo de documento, os valores possíveis são "CPF" e "CNPJ". Caso não informado, iremos inferir pela quantidade de caracteres informado no parâmetro identity. |
Objeto Address
Parâmetro | Tipo | Descrição |
---|---|---|
street obrigatório | String | Nome da rua do seu cliente. |
number obrigatório | String | Número da rua do seu cliente. |
district obrigatório | String | Bairro do seu cliente. |
city obrigatório | String | Cidade do seu cliente. |
state obrigatório | String | Estado do seu cliente no formato AA. Exemplos: SP, AC, GO, RJ. |
complement obrigatório | String | Complemento do endereço do seu cliente. |
country opcional | String | País do seu cliente. |
zip_code obrigatório | String | CEP do seu cliente. Formatos possíveis: 00111222 e 00111-222. |
Objeto Services
Parâmetro | Tipo | Descrição |
---|---|---|
name obrigatório | String | Nome do serviço prestado. |
description obrigatório | String | Descrição do serviço prestado. Máximo de 100 caracteres. |
amount obrigatório | Int | Valor do serviço prestado. |
Objeto PaymentTerms
Objeto Fine
Parâmetro | Tipo | Descrição |
---|---|---|
date opcional | String | Data a partir da qual será aplicado os juros diários. Essa data é facultativa, caso não informada, o padrão é data de vencimento +1. |
amount opcional | Int | Valor em centavos da multa a ser cobrada. Atenção O parâmetro amount tem precedência sobre o parâmetro rate. Portanto, se for informado os dois parâmetros no objeto fine, apenas o atributo amount será considerado. |
rate opcional | Double | Valor percentual da multa a ser cobrada. Atenção Esse parâmetro tem menor prioridade em relação ao parâmetro amount. Portanto, só será considerado caso o valor amount seja nulo. Valores possíveis: de 0 a 100 (com duas casas decimais). |
Objeto Interest
Parâmetro | Tipo | Descrição |
---|---|---|
rate obrigatório | Double | Taxa de juros a ser cobrada. Valores possíveis: de 0 a 100 (com duas casas decimais). |
Objeto Discount
Parâmetro | Tipo | Descrição |
---|---|---|
type obrigatório | String | Tipo de desconto aplicado. Valor fixo FIXED ou percentual PERCENT . |
value obrigatório | Double | Valor do desconto a ser aplicado. Apesar do campo ser Double, caso o tipo seja FIXED o valor decimal será truncado, mantendo o padrão de envio de valores fixos com centavos. Ex: R$ 20,50 é representado como 2050. |
Objeto DiscountResponse
Parâmetro | Tipo | Descrição |
---|---|---|
percent opcional | Double | Valor definido no Objeto Discount como tipo PERCENT. |
amount opcional | Int | Valor definido no Objeto Discount como tipo FIXED. |
Objeto Notifications
Parâmetro | Tipo | Descrição |
---|---|---|
channels obrigatório | Lista de Strings | Lista de Strings que representam os canais de comunicação escolhidos. Hoje o parâmetro aceita os canais "EMAIL" e "SMS". Atenção Notificações de cobrança via SMS fazem parte de uma funcionalidade do plano Cora Pro. |
destination obrigatório | InvoiceDestination | Objeto InvoiceDestination |
rules obrigatório | Lista de Strings | Lista de Strings que representam as regras das notificações, ou seja, quando elas serão disparadas. As possíveis Strings estão detalhadas no Enum de Tipos de Notificação |
Objeto NotificationsResponse
Parâmetro | Tipo | Descrição |
---|---|---|
id obrigatório | String | Identificador do objeto de notificações criado. |
channels obrigatório | Lista de strings | Lista de Strings que representam os canais de comunicação escolhidos. Hoje o parâmetro aceita os canais "EMAIL" e "SMS". Atenção Notificações de cobrança via SMS fazem parte de uma funcionalidade do plano Cora Pro. |
destination obrigatório | InvoiceDestination | Objeto InvoiceDestination |
schedules obrigatório | InvoiceSchedules | Objeto InvoiceSchedules |
Objeto InvoiceDestination
Parâmetro | Tipo | Descrição |
---|---|---|
name obrigatório | String | Nome do contato para quem será enviada a notificação de cobrança (máximo 60 caracteres). |
email obrigatório | String | E-mail do contato para quem será enviada a notificação de cobrança (máximo 60 caracteres). |
phone opcional | String | Número do telefone para o qual a notificação de cobrança será enviada. |
Objeto InvoiceSchedules
Parâmetro | Tipo | Descrição |
---|---|---|
rule obrigatório | String | String que representa a regras das notificação. As possíveis Strings estão detalhadas no Enum de Tipos de Notificação. |
status obrigatório | String | Status da notificação. Os possíveis estados da notificação estão descritos no Enum de Estados da Notificação. |
scheduled_to obrigatório | String | String formatada indicando a data agendada para ser disparada a notificação. |
active obrigatório | Boolean | Objeto que indica se essa regra de notificação está ativa ou não. |
Objeto PaymentOptions
Objeto BankSlip
Parâmetro | Tipo | Descrição |
---|---|---|
barcode obrigatório | String | Código de barras do boleto. |
digitable obrigatório | String | Linha digitável do boleto. Número que deverá ser utilizado para pagamento. |
registered obrigatório | String | Informa se o boleto foi registrado ou não. |
url obrigatório | String | URL do PDF do boleto (os boletos são disponibilizados apenas em PDF, não há versão HTML). |
our_number obrigatório | String | Nosso número. Número do convênio concatenado com a sequência do documento. |
Objeto Payments
Parâmetro | Tipo | Descrição |
---|---|---|
id obrigatório | String | ID do pagamento atrelado Código de barras do boleto. |
status obrigatório | String | Status do pagamento. |
created_at obrigatório | String | Status do pagamento. |
finalized_at obrigatório | String | Data do pagamento. |
total_paid obrigatório | Int | Valor total pago em centavos. |
method obrigatório | String | Método de pagamento. "BANK_SLIP" indica pagamento realizado por código de barras. "PIX" indica pagamento via Pix. |
interest obrigatório | Int | Valor total em centavos dos juros pagos. |
fine obrigatório | Int | Valor total em centavos da multa paga. |
Objeto PixResponse
Parâmetro | Tipo | Descrição |
---|---|---|
emv obrigatório | String | Quando um QR code é gerado esse campo virá preenchido. Código do Pix Copia e Cola, o mesmo que é utilizado para gerar o QR code. |
Emitir um boleto com QR-code Pix
Objeto Payment_forms
Parâmetro | Tipo | Descrição |
---|---|---|
payment_forms obrigatório | String | Para criar um boleto com opção de pagamento por QR code basta inserir as duas opções de "BANK_SLIP" e "PIX". |
Cancelamento
Ao realizar o pagamento pelo QR Code Pix, o boleto com código de barras é cancelado automaticamente em nossos sistemas e na Câmara Interbancária de Pagamentos, evitando assim o pagamento em duplicidade.
Importante
Para gerar um QR Code Pix no boleto é preciso que o cliente tenha cadastrada ao menos uma chave Pix.
Veja aqui como cadastrar uma chave Pix. Caso o cliente não tenha uma chave Pix cadastrada o boleto será gerado sem o QR code, apenas com o código de barras padrão.
Tipos de Enumeradores
Enum de Estados dos Boletos
Parâmetro | Descrição |
---|---|
CANCELLED | Boletos cancelados |
DRAFT | Boletos em rascunho, um estado intermediário entre criação e registro |
IN_PAYMENT | Boletos em processo de pagamento |
LATE | Boletos com pagamento em atraso, ou seja, após a data de vencimento |
OPEN | Boletos registrados, mas ainda não pagos |
PAID | Boletos que foram pagos com sucesso |
Enum de Estados da Notificação
Parâmetro | Descrição |
---|---|
CREATED | Notificação foi criada, mas ainda não foi agendada. |
SCHEDULED | Notificação foi agendada para disparar na data solicitada. |
SENT | Notificação foi disparada para o destino com sucesso. |
ERROR | Notificação foi disparada para o destino, porém sem sucesso. |
CANCELED | Notificação foi cancelada antes do disparo. |
Enum de Tipos de Notificação
Parâmetro | Descrição |
---|---|
NOTIFY_FIFTEEN_DAYS_BEFORE_DUE_DATE | Notifica quinze dias antes da data de vencimento. |
NOTIFY_TEN_DAYS_BEFORE_DUE_DATE | Notifica dez dias antes da data de vencimento. |
NOTIFY_SEVEN_DAYS_BEFORE_DUE_DATE | Notifica sete dias antes da data de vencimento. |
NOTIFY_FIVE_DAYS_BEFORE_DUE_DATE | Notifica cinco dias antes da data de vencimento. |
NOTIFY_TWO_DAYS_BEFORE_DUE_DATE | Notifica dois dias antes da data de vencimento. |
NOTIFY_ON_DUE_DATE | Notifica no dia do vencimento. |
NOTIFY_TWO_DAYS_AFTER_DUE_DATE | Notifica dois dias depois da data de vencimento. |
NOTIFY_FIVE_DAYS_AFTER_DUE_DATE | Notifica cinco dias depois da data de vencimento. |
NOTIFY_SEVEN_DAYS_AFTER_DUE_DATE | Notifica sete dias depois da data de vencimento. |
NOTIFY_TEN_DAYS_AFTER_DUE_DATE | Notifica dez dias depois da data de vencimento. |
NOTIFY_FIFTEEN_DAYS_AFTER_DUE_DATE | Notifica quinze dias depois da data de vencimento. |
NOTIFY_WHEN_PAID | Notifica quando o boleto é pago. |
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.![Símbolo na cor rosa ao fundo com um pão de forma e ovo frito em cima](https://files.readme.io/1ff5489-Group_918.png)