Emissão de carnê

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

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

Parâmetros da resposta

Parâmetro	Tipo	Descrição
document_url obrigatório	String	Link que permite download do carnê em formato PDF
result obrigatório	Lista de Result	Lista de Objetos Result

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:

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) - 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âmetro	Tipo	Descrição
number_of obrigatório	Int	Número de parcelas do carnê
due_date obrigatório	DueDateInstallment	Objeto DueDateInstallment

Objeto DueDateInstallment

Parâmetro	Tipo	Descrição
day_of_month opcional	Int	Dia do mês que será incluído em todas as parcelas
dates opcional	Lista de Strings	Lista de datas de vencimento customizadas

Objeto PaymentTermsInstallment

Parâmetro	Tipo	Descrição
interest_monthly_percent opcional	Double	Taxa percentual de juros a ser cobrada
fine_percent opcional	Double	Porcentagem do valor total a ser cobrada quando o pagamento é atrasado ou não realizado dentro do prazo estipulado
fine_value opcional	Int	Valor fixo a ser cobrado quando o pagamento não é realizado dentro do prazo estipulado
discount_percent opcional	Double	Porcentagem 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	Int	Valor fixo a ser reduzido em forma de desconto caso o pagamento seja realizado um dia antes da data de vencimento definida

Objeto Result

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.
amount_total obrigatório	Int	Valor total em centavos da parcela. Equivale ao valor informado no parâmetro amount dividido pela quantidade de parcelas indicada
status obrigatório	String	Indica 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	String	Link que permite download da parcela do carnê em formato PDF
buyer obrigatório	Buyer	Object Buyer
seller obrigatório	Seller	Object Seller
bank_slip obrigatório	BankSlipInstallment	Object BankSlipInstallment
pix obrigatório	Pix	Objeto Pix
services obrigatório	Lista de Services	Lista de objetos Services
payment_terms obrigatório	PaymentTerms	Objeto PaymentTerms
payments obrigatório	Payments	Lista de objetos Payments. Caso o pagamento ainda não tenha sido feito o array será vazio
payment_forms obrigatório	Lista de Strings	Lista de Strings que representam as formas de pagamento escolhidas ao gerar carnê
created_at obrigatório	String	Data de criação da fatura.
notification obrigatório	Notifications	Objeto Notifications

Objeto Buyer

Parâmetro	Tipo	Descrição
name obrigatório	String	Nome do seu cliente (máximo 60 caracteres)
document obrigatório	Document	Objeto Document
email obrigatório	String	E-mail do seu cliente (máximo 60 caracteres)
type obrigatório	String	Identificação do pagador do boleto como PJ ou PF
address obrigatório	Address	Objeto Address

Objeto Seller

Parâmetro	Tipo	Descrição
business_id obrigatório	String	Dia do mês que será incluído em todas as parcelas
name obrigatório	String	Nome do beneficiário do boleto
document obrigatório	String	Documento de identificação do beneficiário do boleto. Apenas números, sem pontos ou hífens
type obrigatório	String	Identificação do beneficiário do boleto como PJ ou PF

Objeto BankSlipInstallment

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.
our_number obrigatório	String	Nosso número. Número do convênio concatenado com a sequência do documento.
registered obrigatório	Boolean	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)
fine obrigatório	Int	Será definido como 0 no momento da criação do carnê.
interest obrigatório	Int	Será definido como 0 no momento da criação do carnê.
document_sequence obrigatório	Int	Número da sequência do documento
interest_monthly_percent obrigatório	Double	Taxa percentual de juros a ser cobrada
fine_percent obrigatório	Double	Porcentagem do valor total a ser cobrada quando o pagamento é atrasado ou não realizado dentro do prazo estipulado
fine_value obrigatório	Int	Valor fixo a ser cobrado quando o pagamento não é realizado dentro do prazo estipulado
discount_percent obrigatório	Double	Porcentagem 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	Int	Valor 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.