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 | Customer | Objeto Customer |
service obrigatório | Service | Objeto Service |
payment_terms opcional | PaymentTermsInstallment | Objeto PaymentTermsInstallment |
installment obrigatório | Installment | Objeto Installment |
notification opcional | Notification | Objeto Notification |
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: - 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. |
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 |