Emissão de carnê

Gere um boleto parcelado 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 carnê?

Um carnê ou boleto parcelado é uma forma de pagamento em que uma compra é dividida em várias parcelas e valores fixos. Cada parcela é representada por um boleto individual.

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
  • Parcelas para distribuir o valor total em diferentes datas de vencimento

Qual o limite de parcelas do carnê?

É possível emitir um carnê com até 24 parcelas, mas é necessário aguardar um tempo maior pela resposta. Quanto mais parcelas, mais demorada pode ser a resposta, podendo chegar a aproximadamente 40 segundos em casos extremos. Por essa razão, é importante configurar um tempo de timeout maior do que o padrão. Para evitar tempos de resposta maiores, apenas o primeiro boleto é registrado no momento da solicitação, enquanto os outros são registrados em paralelo. O registro não costuma levar mais do que um minuto após a requisição ser finalizada.

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
service
obrigatório
ServiceObjeto Service
payment_terms
opcional
PaymentTermsInstallmentObjeto PaymentTermsInstallment
installment
obrigatório
InstallmentObjeto Installment
notifications
opcional
NotificationsObjeto Notifications
payment_forms
opcional
Lista de stringsLista de Strings que representam as formas de pagamento escolhidas. Hoje o parâmetro aceita apenas "BANK_SLIP"

Parâmetros da resposta

ParâmetroTipoDescrição
document_url
obrigatório
StringLink que permite download do carnê em formato PDF
result
obrigatório
Lista de ResultLista de Objetos Result

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:

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)

- Campo que indica número de parcelas (number_of) com valor menor que 2 ou maior que 24

- Inclusão 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.

- Campo que indica dia data de vencimento day_of_month com número maior que 31. (Caso você defina o dia como 31, as datas de vencimento respeitarão o último dia disponível do mês)
415 (Unsupported Media Type)Falta do Content-Type application/json no header da requisição.
422 (Unprocessable Entity)Ambos os campos dentro do objeto due_date estão definidos como null.

Tipos de Objetos

Objeto Installment

ParâmetroTipoDescrição
number_of
obrigatório
IntNúmero de parcelas do carnê
due_date
obrigatório
DueDateInstallmentObjeto DueDateInstallment

Objeto DueDateInstallment

ParâmetroTipoDescrição
day_of_month
opcional
IntDia do mês que será incluído em todas as parcelas
dates
opcional
Lista de StringsLista de datas de vencimento customizadas

Objeto PaymentTermsInstallment

ParâmetroTipoDescrição
interest_monthly_percent
opcional
DoubleTaxa percentual de juros a ser cobrada
fine_percent
opcional
DoublePorcentagem do valor total a ser cobrada quando o pagamento é atrasado ou não realizado dentro do prazo estipulado
fine_value
opcional
IntValor fixo a ser cobrado quando o pagamento não é realizado dentro do prazo estipulado
discount_percent
opcional
DoublePorcentagem do valor total a ser reduzido em forma de desconto caso o pagamento seja realizado um dia antes da data de vencimento definida
discount_value
opcional
IntValor fixo a ser reduzido em forma de desconto caso o pagamento seja realizado um dia antes da data de vencimento definida

Objeto Result

ParâmetroTipoDescrição
id
obrigatório
StringIdentificador da fatura na Cora. Esse id poderá ser usado para consultar os detalhes da fatura.
amount_total
obrigatório
IntValor total em centavos da parcela. Equivale ao valor informado no parâmetro amount dividido pela quantidade de parcelas indicada
status
obrigatório
StringIndica qual é o estado da fatura. Os status possíveis estão na Tabela de status da fatura Tabela de status da fatura
document_url
obrigatório
StringLink que permite download da parcela do carnê em formato PDF
buyer
obrigatório
BuyerObject Buyer
seller
obrigatório
SellerObject Seller
bank_slip
obrigatório
BankSlipInstallmentObject BankSlipInstallment
pix
obrigatório
PixObjeto Pix
services
obrigatório
Lista de ServicesLista de objetos Services
payment_terms
obrigatório
PaymentTermsObjeto PaymentTerms
payments
obrigatório
PaymentsLista de objetos Payments. Caso o pagamento ainda não tenha sido feito o array será vazio
payment_forms
obrigatório
Lista de StringsLista de Strings que representam as formas de pagamento escolhidas ao gerar carnê
created_at
obrigatório
StringData de criação da fatura.
notification
obrigatório
NotificationsObjeto Notifications

Objeto Buyer

ParâmetroTipoDescrição
name
obrigatório
StringNome do seu cliente (máximo 60 caracteres)
document
obrigatório
DocumentObjeto Document
email
obrigatório
StringE-mail do seu cliente (máximo 60 caracteres)
type
obrigatório
StringIdentificação do pagador do boleto como PJ ou PF
address
obrigatório
AddressObjeto Address

Objeto Seller

ParâmetroTipoDescrição
business_id
obrigatório
StringDia do mês que será incluído em todas as parcelas
name
obrigatório
StringNome do beneficiário do boleto
document
obrigatório
StringDocumento de identificação do beneficiário do boleto. Apenas números, sem pontos ou hífens
type
obrigatório
StringIdentificação do beneficiário do boleto como PJ ou PF

Objeto BankSlipInstallment

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.
our_number
obrigatório
StringNosso número. Número do convênio concatenado com a sequência do documento.
registered
obrigatório
BooleanInforma 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)
fine
obrigatório
IntSerá definido como 0 no momento da criação do carnê.
interest
obrigatório
IntSerá definido como 0 no momento da criação do carnê.
document_sequence
obrigatório
IntNúmero da sequência do documento
interest_monthly_percent
obrigatório
DoubleTaxa percentual de juros a ser cobrada
fine_percent
obrigatório
DoublePorcentagem do valor total a ser cobrada quando o pagamento é atrasado ou não realizado dentro do prazo estipulado
fine_value
obrigatório
IntValor fixo a ser cobrado quando o pagamento não é realizado dentro do prazo estipulado
discount_percent
obrigatório
DoublePorcentagem do valor total a ser reduzido em forma de desconto caso o pagamento seja realizado um dia antes da data de vencimento definida
discount_value
obrigatório
IntValor fixo a ser reduzido em forma de desconto caso o pagamento seja realizado um dia antes da data de vencimento definida

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.
Imagem
Opa, agora é hora do lanche! Sim, finalizamos mais uma etapa de sua integração
Language
Authorization
OAuth2
Click Try It! to start a request and see the response here!