Emissão de boleto registrado

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 os 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: aplicado até o dia anterior a data de vencimento
  • Notificação de cobrança: para lembrar o cliente sobre o pagamento

Além dessas configurações, este boleto também pode ser pago por QR code Pix — basta incluir a forma de pagamento na emissão. Veja como em Emitir um boleto com QR-code Pix.

Atenção

Para gerar o QR code é preciso ter ao menos uma chave Pix cadastrada. Sem chave, o boleto é gerado apenas com o código de barras, sem erro na resposta.

Bora pro código?

383

Headers

HeaderValor
Content-Typeapplication/jsonobrigatório
AuthorizationBearer {{access_token}}obrigatório
Idempotency-Key(random-uuid)obrigatório
Atenção

O prefixo Bearer seguido de um espaço é obrigatório neste endpoint.

O Idempotency-Key é um UUID gerado por você, novo a cada boleto. Ele serve para você repetir uma chamada com segurança: se você não receber a resposta e reenviar a mesma chave, nós devolvemos o boleto já criado em vez de duplicar a cobrança. Por isso, nunca reutilize uma chave para emitir um boleto diferente — você receberá de volta o boleto anterior.

Parâmetros da requisição

ParâmetroTipoDescrição
code opcionalStringCó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órioCustomerObjeto Customer
services\ obrigatórioLista de ServicesLista de Objetos Services. Utilize este campo para descrever o que está sendo cobrado. Atenção: O nó services agrupa itens dentro de uma única invoice. Para emitir múltiplos boletos, realize chamadas separadas para o endpoint.
payment_terms\ obrigatórioPaymentTermsObjeto PaymentTerms
notification\ opcionalNotificationObjeto Notification
payment_forms\ opcionalLista de StringsFormas de pagamento aceitas: "BANK_SLIP", "PIX" ou as duas. Se você não enviar, o padrão é ["BANK_SLIP"]. Veja Emitir um boleto com QR-code Pix.

Parâmetros da resposta

ParâmetroTipoDescrição
id obrigatórioStringIdentificador da fatura na Cora. Esse id poderá ser usado para consultar os detalhes da fatura.
status\ obrigatórioStringIndica qual é o estado do boleto. Os status possíveis estão na Tabela de Estados dos Boletos.
created_at\ obrigatórioStringData de criação da fatura.
total_amount\ obrigatórioIntValor total em centavos da fatura. Esse valor é a soma dos valores informados no parâmetro Services.
total_paid\ obrigatórioIntValor total pago (em centavos), caso o boleto ainda não tenha sido pago, ele será zerado.
occurrence_date\ opcionalStringData que o cliente efetuou o pagamento do boleto junto ao banco.
code\ obrigatórioStringCó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órioCustomerObjeto Customer
services\ obrigatórioLista de ServicesLista de Objetos Services
payment_terms\ obrigatórioPaymentTermsObjeto PaymentTerms
payment_options\ obrigatórioPaymentOptionsObjeto PaymentOptions
payments\ obrigatórioPaymentsLista de Objetos Payments. Caso o pagamento ainda não tenha sido feito o array será vazio.
pix\ obrigatórioPixObjeto Pix

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

ParâmetroTipoDescrição
name obrigatórioStringNome do seu cliente. Mínimo de 3 e máximo de 255 caracteres.
email\ opcionalStringE-mail do seu cliente. Precisa ser um endereço válido.
document\ obrigatórioDocumentObjeto Document
address\ opcionalAddressObjeto Address
code\ opcionalStringCódigo do seu cliente no seu sistema. Máximo de 64 caracteres.

Objeto Document

ParâmetroTipoDescrição
identity obrigatórioStringDocumento do seu cliente, apenas números, sem pontos, traços ou barras. Envie como String.
type\ opcionalString"CPF" ou "CNPJ". Este campo é informativo: nós determinamos o tipo pela quantidade de caracteres do identity (11 para CPF), independente do que for enviado aqui.
Atenção

Envie o documento só com números. Quem decide entre CPF e CNPJ é o tamanho do que você manda: exatamente 11 caracteres vira CPF, qualquer outro tamanho vira CNPJ. Um CPF com pontuação tem 14 caracteres e não é tratado como CPF. O campo type que você enviar é ignorado — nós sempre recalculamos por esse critério.

Objeto Address

O objeto Address é opcional. Se você enviar, estes campos passam a ser obrigatórios dentro dele:

ParâmetroTipoDescrição
street obrigatórioStringNome da rua do seu cliente.
number\ obrigatórioStringNúmero.
district\ obrigatórioStringBairro.
city\ obrigatórioStringCidade.
state\ obrigatórioStringEstado no formato de duas letras. Exemplos: SP, AC, GO, RJ.
zip_code\ obrigatórioStringCEP. Aceita os formatos 00111222 (8 dígitos) e 00111-222.
complement\ opcionalStringComplemento do endereço.

Objeto Services

ParâmetroTipoDescrição
name obrigatórioStringNome do serviço prestado. Máximo de 255 caracteres.
description\ opcionalStringDescrição do serviço prestado. Máximo de 255 caracteres.
amount\ obrigatórioIntValor do serviço em centavos. Mínimo de 500 (R$ 5,00).
code\ opcionalStringCódigo do serviço no seu sistema. Máximo de 64 caracteres.
Atenção

Envie um único serviço na lista. Hoje apenas o primeiro item é considerado; os demais são aceitos e descartados. Para cobrar vários itens, some os valores e descreva o conjunto, ou emita boletos separados.

Objeto PaymentTerms

ParâmetroTipoDescrição
due_date obrigatórioStringData de vencimento do boleto. Deve ser igual ou posterior à data de emissão e seguir o formato AAAA-MM-DD.
fine\ opcionalFineObjeto Fine
interest\ opcionalInterestObjeto Interest
discount\ opcionalDiscountObjeto Discount

Objeto Fine

Parâmetro

Tipo

Descrição

date opcional

String

Data a partir da qual será aplicada multa mensal. 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âmetroTipoDescrição
rate obrigatórioDoubleTaxa de juros a ser cobrada. Valores possíveis: de 0 a 100 (com duas casas decimais).

Objeto Discount

ParâmetroTipoDescrição
type obrigatórioStringTipo de desconto aplicado. Valor fixo FIXED ou percentual PERCENT .
value\ obrigatórioDoubleValor 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 opcionalDoubleValor definido no Objeto Discount como tipo PERCENT.
amount\ opcionalIntValor definido no Objeto Discount como tipo FIXED.

Objeto Notification

O objeto Notification é opcional. Se você enviar, name e channels passam a ser obrigatórios dentro dele.

ParâmetroTipoDescrição
name obrigatórioStringNome do contato para quem a notificação será enviada. Máximo de 255 caracteres.
channels\ obrigatórioLista de NotificationChannelLista de objetos NotificationChannel. Envie no máximo um objeto por canal.

Objeto NotificationChannel

ParâmetroTipoDescrição
channel obrigatórioStringCanal de comunicação. Aceita "EMAIL" e "SMS".

Atenção
Notificações por SMS fazem parte do plano Cora Pro, e a ausência do plano age em dois momentos. Na emissão, sem plano ativo nós removemos o canal SMS da notificação e também o telefone do cliente: o boleto é criado, responde 200, e não há nenhum sinal disso na resposta. Depois, se o plano vencer enquanto o boleto está aberto, as notificações já agendadas são canceladas. Nos dois casos a emissão não retorna erro.
contact\ obrigatórioStringDestino da notificação. Para EMAIL, um endereço válido ([email protected]). Para SMS, um celular com DDD (11999999999). Você pode enviar com ou sem o +55 e com ou sem máscara: (11) 99999-9999 e +5511999999999 também funcionam.
rules\ obrigatórioLista de StringsQuando notificar. Os valores possíveis estão no Enum de Tipos de Notificação.
Atenção

Não envie dois objetos com o mesmo channel. Dois canais "EMAIL" na mesma lista resultam em erro 400. Para notificar dois e-mails diferentes, hoje não há como.

Para SMS, o número precisa ser de celular — 11 dígitos com DDD. Número fixo é aceito na emissão e a notificação falha depois, na entrega.

Objeto PaymentOptions

ParâmetroTipoDescrição
bank_slip obrigatórioBankSlipObjeto BankSlip

Objeto BankSlip

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

Objeto Payments

ParâmetroTipoDescrição
id obrigatórioStringIdentificador do pagamento na Cora.
status\ obrigatórioStringSituação do pagamento.
created_at\ obrigatórioStringData em que o pagamento foi registrado.
finalized_at\ opcionalStringData em que o pagamento foi finalizado. Presente apenas em pagamentos concluídos.
total_paid\ obrigatórioIntValor total pago, em centavos.
method\ obrigatórioStringMeio usado no pagamento: "BANK_SLIP" para código de barras, "PIX" para Pix.
order\ obrigatórioIntOrdem do pagamento, quando o boleto recebe mais de um.
interest\ obrigatórioIntJuros pagos, em centavos.
fine\ obrigatórioIntMulta paga, em centavos.

Objeto PixResponse

ParâmetroTipoDescrição
emv obrigatórioStringQuando 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 opcionalLista de StringsFormas de pagamento aceitas: "BANK_SLIP", "PIX" ou as duas. Se você não enviar, o padrão é ["BANK_SLIP"] e o boleto sai apenas com código de barras.

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çãoOnde aparece
CANCELLEDBoletos canceladosdetalhe e consulta
DRAFTBoletos em rascunho, um estado intermediário entre criação e registrodetalhe e consulta
IN_PAYMENTBoletos em processo de pagamentoapenas no detalhe
INITIATEDBoletos iniciados, aguardando a atualização dos próximos passos do fluxoapenas no detalhe
LATEBoletos com pagamento em atraso, ou seja, após a data de vencimentodetalhe e consulta
OPENBoletos registrados, mas ainda não pagosdetalhe e consulta
PAIDBoletos que foram pagos com sucessodetalhe e consulta
RECURRENCE_DRAFTBoletos criados com recorrência nos quais o usuário não deu andamento à criação da cobrançadetalhe e consulta
Atenção

A consulta de boletos nunca devolve os status IN_PAYMENT e INITIATED, e eles também não são aceitos no filtro state. Enquanto o boleto está em um desses estados, ele continua listado com o status anterior — um boleto em processo de pagamento aparece na consulta como OPEN ou LATE até a liquidação ser concluída.

Ou seja: o status na consulta de boletos pode estar atrasado em relação ao real. Para saber o estado atual de um boleto, use a consulta de detalhes, que reflete a mudança na hora.

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.
Atenção

Envie exatamente um dos valores acima. Um nome de regra fora dessa lista faz a requisição inteira falhar com 400, e a resposta não diz qual regra causou.

Como calculamos a data de envio

Todas as notificações saem às 10h.

As regras antes do vencimento contam a partir da data de vencimento que você informou, mesmo que ela caia num sábado, domingo ou feriado.

As regras no vencimento e depois dele contam a partir do primeiro dia útil a partir do vencimento. Ou seja, um boleto que vence no sábado tem a notificação de vencimento na segunda.

Se a data calculada já passou no momento da emissão, a notificação nasce cancelada e não será enviada. Por exemplo: um boleto emitido para vencer em 3 dias com a regra NOTIFY_FIFTEEN_DAYS_BEFORE_DUE_DATE não gera notificação — e a emissão não retorna erro por isso. Consulte as notificações do boleto para conferir o que foi efetivamente agendado.


Body Params
string
Defaults to meu_id
customer
object
required
services
array of objects
required
length ≥ 1

Envie um único serviço. Hoje apenas o primeiro item é considerado; os demais são aceitos e descartados.

services*
string
required
length ≤ 255

Nome do serviço prestado.

string
length ≤ 255

Descrição do serviço prestado.

int32
required
≥ 500

Valor do serviço em centavos. Mínimo de 500 (R$ 5,00).

string
length ≤ 64

Código do serviço no seu sistema.

payment_terms
object
required
notification
object

Objeto que representa a configuração das notificações de cobrança. Opcional — se enviado, name e channels passam a ser obrigatórios.

payment_forms
array of strings
Defaults to BANK_SLIP

Formas de pagamento aceitas. Envie "BANK_SLIP" para boleto com código de barras, "PIX" para QR code Pix, ou as duas. Se você não enviar o campo, o padrão é apenas boleto. O QR code exige ao menos uma chave Pix cadastrada; sem chave, o boleto sai só com código de barras.

payment_forms
Allowed:
Headers
string
required
Defaults to dd61d5b9-c9fb-4116-b5e0-1f8436993ac4

UUID aleatório gerado por você. Nós utilizamos esse header para evitar duplicidade de registros, ou seja, caso você não tenha recebido a resposta de alguma requisição e mandar o mesmo UUID, nós não duplicaremos o registro.

string
enum
Defaults to application/json

Generated from available response content types

Allowed:
Responses

Language
Credentials
Bearer
JWT
URL
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json