Gere um boleto parcelado através desta API
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 | Objeto Customer | |
service\ obrigatório | Objeto Service | |
payment_terms\ opcional | Objeto PaymentTermsInstallment | |
installment\ obrigatório | Objeto Installment | |
notifications\ opcional | 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
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:
- 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 | 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 | Object Buyer | |
seller\ obrigatório | Object Seller | |
bank_slip\ obrigatório | Object BankSlipInstallment | |
pix\ obrigatório | Objeto Pix | |
services\ obrigatório | Lista de Services | Lista de objetos Services |
payment_terms\ obrigatório | Objeto PaymentTerms | |
payments\ obrigatório | 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 | Objeto Notifications |
Objeto Buyer
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 |
