Gere um boleto registrado através desta API
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 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: 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.
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.
Headers
| Header | Valor | |
|---|---|---|
| Content-Type | application/json | obrigatório |
| Authorization | Bearer {{access_token}} | obrigatório |
| Idempotency-Key | (random-uuid) | obrigatório |
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â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. 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ório | PaymentTerms | Objeto PaymentTerms |
| notification\ opcional | Notification | Objeto Notification |
| payment_forms\ opcional | Lista de Strings | Formas 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â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 |
Dicas de implementação
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:
|
415 (Unsupported Media Type) | Falta do Content-Type application/json no header da requisição. |
Tipos de Objetos
Objeto Customer
| Parâmetro | Tipo | Descrição |
|---|---|---|
| name obrigatório | String | Nome do seu cliente. Mínimo de 3 e máximo de 255 caracteres. |
| email\ opcional | String | E-mail do seu cliente. Precisa ser um endereço válido. |
| document\ obrigatório | Document | Objeto Document |
| address\ opcional | Address | Objeto Address |
| code\ opcional | String | Código do seu cliente no seu sistema. Máximo de 64 caracteres. |
Objeto Document
| Parâmetro | Tipo | Descrição |
|---|---|---|
| identity obrigatório | String | Documento do seu cliente, apenas números, sem pontos, traços ou barras. Envie como String. |
| type\ opcional | String | "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. |
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âmetro | Tipo | Descrição |
|---|---|---|
| street obrigatório | String | Nome da rua do seu cliente. |
| number\ obrigatório | String | Número. |
| district\ obrigatório | String | Bairro. |
| city\ obrigatório | String | Cidade. |
| state\ obrigatório | String | Estado no formato de duas letras. Exemplos: SP, AC, GO, RJ. |
| zip_code\ obrigatório | String | CEP. Aceita os formatos 00111222 (8 dígitos) e 00111-222. |
| complement\ opcional | String | Complemento do endereço. |
Objeto Services
| Parâmetro | Tipo | Descrição |
|---|---|---|
| name obrigatório | String | Nome do serviço prestado. Máximo de 255 caracteres. |
| description\ opcional | String | Descrição do serviço prestado. Máximo de 255 caracteres. |
| amount\ obrigatório | Int | Valor do serviço em centavos. Mínimo de 500 (R$ 5,00). |
| code\ opcional | String | Código do serviço no seu sistema. Máximo de 64 caracteres. |
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
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â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 Notification
O objeto Notification é opcional. Se você enviar, name e channels passam a ser obrigatórios dentro dele.
| Parâmetro | Tipo | Descrição |
|---|---|---|
| name obrigatório | String | Nome do contato para quem a notificação será enviada. Máximo de 255 caracteres. |
| channels\ obrigatório | Lista de NotificationChannel | Lista de objetos NotificationChannel. Envie no máximo um objeto por canal. |
Objeto NotificationChannel
| Parâmetro | Tipo | Descrição |
|---|---|---|
| channel obrigatório | String | Canal 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ório | String | Destino 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ório | Lista de Strings | Quando notificar. Os valores possíveis estão no Enum de Tipos de Notificaçã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
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 | Identificador do pagamento na Cora. |
| status\ obrigatório | String | Situação do pagamento. |
| created_at\ obrigatório | String | Data em que o pagamento foi registrado. |
| finalized_at\ opcional | String | Data em que o pagamento foi finalizado. Presente apenas em pagamentos concluídos. |
| total_paid\ obrigatório | Int | Valor total pago, em centavos. |
| method\ obrigatório | String | Meio usado no pagamento: "BANK_SLIP" para código de barras, "PIX" para Pix. |
| order\ obrigatório | Int | Ordem do pagamento, quando o boleto recebe mais de um. |
| interest\ obrigatório | Int | Juros pagos, em centavos. |
| fine\ obrigatório | Int | Multa paga, em centavos. |
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 opcional | Lista de Strings | Formas 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âmetro | Descrição | Onde aparece |
|---|---|---|
| CANCELLED | Boletos cancelados | detalhe e consulta |
| DRAFT | Boletos em rascunho, um estado intermediário entre criação e registro | detalhe e consulta |
| IN_PAYMENT | Boletos em processo de pagamento | apenas no detalhe |
| INITIATED | Boletos iniciados, aguardando a atualização dos próximos passos do fluxo | apenas no detalhe |
| LATE | Boletos com pagamento em atraso, ou seja, após a data de vencimento | detalhe e consulta |
| OPEN | Boletos registrados, mas ainda não pagos | detalhe e consulta |
| PAID | Boletos que foram pagos com sucesso | detalhe e consulta |
| RECURRENCE_DRAFT | Boletos criados com recorrência nos quais o usuário não deu andamento à criação da cobrança | detalhe e consulta |
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â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. |
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.
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.