post
https://api.stage.cora.com.br/v2/invoices/installments
Gere um boleto parcelado através desta API
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. 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\ 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:
|
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 |