Gere um boleto registrado 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 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 escopoDescrição
invoiceAPI 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

Bora pro código?

383

Parâmetros da requisição

ParâmetroTipoDescrição
code
opcional
StringCó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
CustomerObjeto Customer
services
obrigatório
Lista de ServicesLista de Objetos Services
payment_terms
obrigatório
PaymentTermsObjeto PaymentTerms
notifications
opcional
NotificationsObjeto Notifications

Parâmetros da resposta

ParâmetroTipoDescrição
id
obrigatório
StringIdentificador da fatura na Cora. Esse id poderá ser usado para consultar os detalhes da fatura.
status
obrigatório
StringIndica qual é o estado do boleto. Os status possíveis estão na Tabela de Estados dos Boletos.
created_at
obrigatório
StringData de criação da fatura.
total_amount
obrigatório
IntValor total em centavos da fatura. Esse valor é a soma dos valores informados no parâmetro Services.
total_paid
obrigatório
IntValor total pago (em centavos), caso o boleto ainda não tenha sido pago, ele será zerado.
occurrence_date
opcional
StringData que o cliente efetuou o pagamento do boleto junto ao banco.
code
obrigatório
StringCó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
CustomerObjeto Customer
services
obrigatório
Lista de ServicesLista de Objetos Services
payment_terms
obrigatório
PaymentTermsObjeto PaymentTerms
payment_options
obrigatório
PaymentOptionsObjeto PaymentOptions
payments
obrigatório
PaymentsLista de Objetos Payments. Caso o pagamento ainda não tenha sido feito o array será vazio.
pix
obrigatório
PixObjeto Pix
notifications
opcional
NotificationsObjeto Notifications

Dicas de implementação

188

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 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:

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

- Inclusão apenas da String “PIX” no campo payment_forms

- 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

ParâmetroTipoDescrição
name
obrigatório
StringNome do seu cliente (máximo 60 caracteres)
email
opcional
StringE-mail do seu cliente (máximo 60 caracteres)
document
obrigatório
DocumentObjeto Document
address
opcional
AddressObjeto Address

Objeto Document

ParâmetroTipoDescrição
identity
obrigatório
StringNúmero do documento do seu cliente (apenas números, sem traços e pontos). Deve ser enviado como uma string.
type
obrigatório
StringTipo 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âmetroTipoDescrição
street
obrigatório
StringNome da rua do seu cliente.
number
obrigatório
StringNúmero da rua do seu cliente.
district
obrigatório
StringBairro do seu cliente.
city
obrigatório
StringCidade do seu cliente.
state
obrigatório
StringEstado do seu cliente no formato AA. Exemplos: SP, AC, GO, RJ.
complement
obrigatório
StringComplemento do endereço do seu cliente.
country
opcional
StringPaís do seu cliente.
zip_code
obrigatório
StringCEP do seu cliente. Formatos possíveis: 00111222 e 00111-222.

Objeto Services

ParâmetroTipoDescrição
name
obrigatório
StringNome do serviço prestado.
description
obrigatório
StringDescrição do serviço prestado. Máximo de 100 caracteres.
amount
obrigatório
IntValor do serviço prestado.

Objeto PaymentTerms

ParâmetroTipoDescrição
due_date
obrigatório
StringData de vencimento do boleto. Deve seguir o formato AAAA-MM-DD.
fine
opcional
FineObjeto Fine
interest
opcional
InterestObjeto Interest
discount
opcional
DiscountObjeto Discount

Objeto Fine

ParâmetroTipoDescrição
date
opcional
StringData 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
IntValor 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
DoubleValor 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âmetroTipoDescrição
rate
obrigatório
DoubleTaxa de juros a ser cobrada. Valores possíveis: de 0 a 100 (com duas casas decimais).

Objeto Discount

ParâmetroTipoDescrição
type
obrigatório
StringTipo de desconto aplicado. Valor fixo FIXED ou percentual PERCENT .
value
obrigatório
DoubleValor 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âmetroTipoDescrição
percent
opcional
DoubleValor definido no Objeto Discount como tipo PERCENT.
amount
opcional
IntValor definido no Objeto Discount como tipo FIXED.

Objeto Notifications

ParâmetroTipoDescrição
channels
obrigatório
Lista de StringsLista 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
InvoiceDestinationObjeto InvoiceDestination
rules
obrigatório
Lista de StringsLista 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âmetroTipoDescrição
id
obrigatório
StringIdentificador do objeto de notificações criado.
channels
obrigatório
Lista de stringsLista 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
InvoiceDestinationObjeto InvoiceDestination
schedules
obrigatório
InvoiceSchedulesObjeto InvoiceSchedules

Objeto InvoiceDestination

ParâmetroTipoDescrição
name
obrigatório
StringNome do contato para quem será enviada a notificação de cobrança (máximo 60 caracteres).
email
obrigatório
StringE-mail do contato para quem será enviada a notificação de cobrança (máximo 60 caracteres).
phone
opcional
StringNúmero do telefone para o qual a notificação de cobrança será enviada.

Objeto InvoiceSchedules

ParâmetroTipoDescrição
rule
obrigatório
StringString que representa a regras das notificação. As possíveis Strings estão detalhadas no Enum de Tipos de Notificação.
status
obrigatório
StringStatus da notificação. Os possíveis estados da notificação estão descritos no Enum de Estados da Notificação.
scheduled_to
obrigatório
StringString formatada indicando a data agendada para ser disparada a notificação.
active
obrigatório
BooleanObjeto que indica se essa regra de notificação está ativa ou não.

Objeto PaymentOptions

ParâmetroTipoDescrição
bank_slip
obrigatório
BankSlipObjeto BankSlip

Objeto BankSlip

ParâmetroTipoDescrição
barcode
obrigatório
StringCódigo de barras do boleto.
digitable
obrigatório
StringLinha digitável do boleto. Número que deverá ser utilizado para pagamento.
registered
obrigatório
StringInforma se o boleto foi registrado ou não.
url
obrigatório
StringURL do PDF do boleto (os boletos são disponibilizados apenas em PDF, não há versão HTML).
our_number
obrigatório
StringNosso número. Número do convênio concatenado com a sequência do documento.

Objeto Payments

ParâmetroTipoDescrição
id
obrigatório
StringID do pagamento atrelado Código de barras do boleto.
status
obrigatório
StringStatus do pagamento.
created_at
obrigatório
StringStatus do pagamento.
finalized_at
obrigatório
StringData do pagamento.
total_paid
obrigatório
IntValor total pago em centavos.
method
obrigatório
StringMétodo de pagamento.
"BANK_SLIP" indica pagamento realizado por código de barras. "PIX" indica pagamento via Pix.
interest
obrigatório
IntValor total em centavos dos juros pagos.
fine
obrigatório
IntValor total em centavos da multa paga.

Objeto PixResponse

ParâmetroTipoDescrição
emv
obrigatório
StringQuando 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âmetroTipoDescrição
payment_forms
obrigatório
StringPara 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âmetroDescrição
CANCELLEDBoletos cancelados
DRAFTBoletos em rascunho, um estado intermediário entre criação e registro
IN_PAYMENTBoletos em processo de pagamento
LATEBoletos com pagamento em atraso, ou seja, após a data de vencimento
OPENBoletos registrados, mas ainda não pagos
PAIDBoletos que foram pagos com sucesso

Enum de Estados da Notificação

ParâmetroDescrição
CREATEDNotificação foi criada, mas ainda não foi agendada.
SCHEDULEDNotificação foi agendada para disparar na data solicitada.
SENTNotificação foi disparada para o destino com sucesso.
ERRORNotificação foi disparada para o destino, porém sem sucesso.
CANCELEDNotificação foi cancelada antes do disparo.

Enum de Tipos de Notificação

ParâmetroDescrição
NOTIFY_FIFTEEN_DAYS_BEFORE_DUE_DATENotifica quinze dias antes da data de vencimento.
NOTIFY_TEN_DAYS_BEFORE_DUE_DATENotifica dez dias antes da data de vencimento.
NOTIFY_SEVEN_DAYS_BEFORE_DUE_DATENotifica sete dias antes da data de vencimento.
NOTIFY_FIVE_DAYS_BEFORE_DUE_DATENotifica cinco dias antes da data de vencimento.
NOTIFY_TWO_DAYS_BEFORE_DUE_DATENotifica dois dias antes da data de vencimento.
NOTIFY_ON_DUE_DATENotifica no dia do vencimento.
NOTIFY_TWO_DAYS_AFTER_DUE_DATENotifica dois dias depois da data de vencimento.
NOTIFY_FIVE_DAYS_AFTER_DUE_DATENotifica cinco dias depois da data de vencimento.
NOTIFY_SEVEN_DAYS_AFTER_DUE_DATENotifica sete dias depois da data de vencimento.
NOTIFY_TEN_DAYS_AFTER_DUE_DATENotifica dez dias depois da data de vencimento.
NOTIFY_FIFTEEN_DAYS_AFTER_DUE_DATENotifica quinze dias depois da data de vencimento.
NOTIFY_WHEN_PAIDNotifica quando o boleto é pago.

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.

Símbolo na cor rosa ao fundo com um pão de forma e ovo frito em cima
Opa, agora é hora do lanche! Sim, finalizamos a etapa de Emissão de boleto

Integração Direta e Testes

Testes na documentação atualmente não permitem o upload de informações importantes, como certificados e private keys, e, por este motivo, não são recomendados para Integração Direta. Para a realização de testes relacionados a essas informações sensíveis, pedimos que utilize o seu sistema de escolha, garantido a confidencialidade dos dados.
Language
Authorization
OAuth2
Click Try It! to start a request and see the response here!