Emissão de carnê

{`

`}

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.

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

  <th>
    Tipo
  </th>

  <th>
    Descrição
  </th>
</tr>

  <td>
    String
  </td>

  <td>
    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.
  </td>
</tr>

<tr>
  <td>
    customer\ <span class="tag tag-inline background-light-negative">obrigatório</span>
  </td>

  <td>
    [Customer](https://cora-api.readme.io/reference/emiss%C3%A3o-de-boleto-registrado-v2#objeto-customer)
  </td>

  <td>
    Objeto [Customer](https://cora-api.readme.io/reference/emiss%C3%A3o-de-boleto-registrado-v2#objeto-customer)
  </td>
</tr>

<tr>
  <td>
    service\ <span class="tag tag-inline background-light-negative">obrigatório</span>
  </td>

  <td>
    [Service](https://cora-api.readme.io/reference/emiss%C3%A3o-de-boleto-registrado-v2#objeto-services)
  </td>

  <td>
    Objeto [Service](https://cora-api.readme.io/reference/emiss%C3%A3o-de-boleto-registrado-v2#objeto-services)
  </td>
</tr>

<tr>
  <td>
    payment\_terms\ <span class="tag tag-inline background-light-info">opcional</span>
  </td>

  <td>
    [PaymentTermsInstallment](https://cora-api.readme.io/reference/emiss%C3%A3o-de-boleto-parcelado-v2#objeto-paymenttermsinstallment)
  </td>

  <td>
    Objeto [PaymentTermsInstallment](https://cora-api.readme.io/reference/emiss%C3%A3o-de-boleto-parcelado-v2#objeto-paymenttermsinstallment)
  </td>
</tr>

<tr>
  <td>
    installment\ <span class="tag tag-inline background-light-negative">obrigatório</span>
  </td>

  <td>
    [Installment](https://cora-api.readme.io/reference/emiss%C3%A3o-de-boleto-parcelado-v2#objeto-installment)
  </td>

  <td>
    Objeto [Installment](https://cora-api.readme.io/reference/emiss%C3%A3o-de-boleto-parcelado-v2#objeto-installment)
  </td>
</tr>

<tr>
  <td>
    notification\ <span class="tag tag-inline background-light-info">opcional</span>
  </td>

  <td>
    [Notification](https://cora-api.readme.io/reference/emiss%C3%A3o-de-boleto-registrado-v2#objeto-notification)
  </td>

  <td>
    Objeto [Notification](https://cora-api.readme.io/reference/emiss%C3%A3o-de-boleto-registrado-v2#objeto-notification)
  </td>
</tr>

<tr>
  <td>
    payment\_forms\ <span class="tag tag-inline background-light-info">opcional</span>
  </td>

  <td>
    Lista de strings
  </td>

  <td>
    Lista de Strings que representam as formas de pagamento escolhidas. Hoje o parâmetro aceita apenas "BANK\_SLIP"
  </td>
</tr>

Parâmetros da resposta

  <th>
    Tipo
  </th>

  <th>
    Descrição
  </th>
</tr>

  <td>
    String
  </td>

  <td>
    Link que permite download do carnê em formato PDF
  </td>
</tr>

<tr>
  <td>
    result\ <span class="tag tag-inline background-light-negative">obrigatório</span>
  </td>

  <td>
    Lista de [Result](https://cora-api.readme.io/reference/emiss%C3%A3o-de-boleto-parcelado-v2#objeto-result)
  </td>

  <td>
    Lista de Objetos [Result](https://cora-api.readme.io/reference/emiss%C3%A3o-de-boleto-parcelado-v2#objeto-result)
  </td>
</tr>

{`

`}

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

  <th>
    Descrição
  </th>
</tr>

  <td>
    O token de acesso está inválido ou expirado. Erro comum no momento de trocas de ambientes (Stage/Production).
  </td>
</tr>

<tr>
  <td>
    400 (Bad Request)
  </td>

  <td>
    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)
  </td>
</tr>

<tr>
  <td>
    415 (Unsupported Media Type)
  </td>

  <td>
    Falta do Content-Type **application/json** no header da requisição.
  </td>
</tr>

<tr>
  <td>
    422 (Unprocessable Entity)
  </td>

  <td>
    Ambos os campos dentro do objeto **due\_date** estão definidos como null.
  </td>
</tr>

Tipos de Objetos

Objeto Installment

  <th>
    Tipo
  </th>

  <th>
    Descrição
  </th>
</tr>

  <td>
    Int
  </td>

  <td>
    Número de parcelas do carnê
  </td>
</tr>

<tr>
  <td>
    due\_date\ <span class="tag tag-inline background-light-negative">obrigatório</span>
  </td>

  <td>
    [DueDateInstallment](https://cora-api.readme.io/reference/emiss%C3%A3o-de-boleto-parcelado-v2#objeto-duedateinstallment)
  </td>

  <td>
    Objeto [DueDateInstallment](https://cora-api.readme.io/reference/emiss%C3%A3o-de-boleto-parcelado-v2#objeto-duedateinstallment)
  </td>
</tr>

---

Objeto DueDateInstallment

  <th>
    Tipo
  </th>

  <th>
    Descrição
  </th>
</tr>

  <td>
    Int
  </td>

  <td>
    Dia do mês que será incluído em todas as parcelas
  </td>
</tr>

<tr>
  <td>
    dates\ <span class="tag tag-inline background-light-info">opcional</span>
  </td>

  <td>
    Lista de Strings
  </td>

  <td>
    Lista de datas de vencimento customizadas
  </td>
</tr>

---

Objeto PaymentTermsInstallment

  <th>
    Tipo
  </th>

  <th>
    Descrição
  </th>
</tr>

  <td>
    Double
  </td>

  <td>
    Taxa percentual de juros a ser cobrada
  </td>
</tr>

<tr>
  <td>
    fine\_percent\ <span class="tag tag-inline background-light-info">opcional</span>
  </td>

  <td>
    Double
  </td>

  <td>
    Porcentagem do valor total a ser cobrada quando o pagamento é atrasado ou não realizado dentro do prazo estipulado
  </td>
</tr>

<tr>
  <td>
    fine\_value\ <span class="tag tag-inline background-light-info">opcional</span>
  </td>

  <td>
    Int
  </td>

  <td>
    Valor fixo a ser cobrado quando o pagamento não é realizado dentro do prazo estipulado
  </td>
</tr>

<tr>
  <td>
    discount\_percent\ <span class="tag tag-inline background-light-info">opcional</span>
  </td>

  <td>
    Double
  </td>

  <td>
    Porcentagem do valor total a ser reduzido em forma de desconto caso o pagamento seja realizado um dia antes da data de vencimento definida
  </td>
</tr>

<tr>
  <td>
    discount\_value\ <span class="tag tag-inline background-light-info">opcional</span>
  </td>

  <td>
    Int
  </td>

  <td>
    Valor fixo a ser reduzido em forma de desconto caso o pagamento seja realizado um dia antes da data de vencimento definida
  </td>
</tr>

---

Objeto Result

  <th>
    Tipo
  </th>

  <th>
    Descrição
  </th>
</tr>

  <td>
    String
  </td>

  <td>
    Identificador da fatura na Cora. Esse id poderá ser usado para consultar os detalhes da fatura.
  </td>
</tr>

<tr>
  <td>
    amount\_total\ <span class="tag tag-inline background-light-negative">obrigatório</span>
  </td>

  <td>
    Int
  </td>

  <td>
    Valor total em centavos da parcela. Equivale ao valor informado no parâmetro amount dividido pela quantidade de parcelas indicada
  </td>
</tr>

<tr>
  <td>
    status\ <span class="tag tag-inline background-light-negative">obrigatório</span>
  </td>

  <td>
    String
  </td>

  <td>
    Indica qual é o estado da fatura. Os status possíveis estão na Tabela de status da fatura Tabela de status da fatura
  </td>
</tr>

<tr>
  <td>
    document\_url\ <span class="tag tag-inline background-light-negative">obrigatório</span>
  </td>

  <td>
    String
  </td>

  <td>
    Link que permite download da parcela do carnê em formato PDF
  </td>
</tr>

<tr>
  <td>
    buyer\ <span class="tag tag-inline background-light-negative">obrigatório</span>
  </td>

  <td>
    [Buyer](https://cora-api.readme.io/reference/emiss%C3%A3o-de-boleto-parcelado-v2#objeto-buyer)
  </td>

  <td>
    Object [Buyer](https://cora-api.readme.io/reference/emiss%C3%A3o-de-boleto-parcelado-v2#objeto-buyer)
  </td>
</tr>

<tr>
  <td>
    seller\ <span class="tag tag-inline background-light-negative">obrigatório</span>
  </td>

  <td>
    [Seller](https://cora-api.readme.io/reference/emiss%C3%A3o-de-boleto-parcelado-v2#objeto-seller)
  </td>

  <td>
    Object [Seller](https://cora-api.readme.io/reference/emiss%C3%A3o-de-boleto-parcelado-v2#objeto-seller)
  </td>
</tr>

<tr>
  <td>
    bank\_slip\ <span class="tag tag-inline background-light-negative">obrigatório</span>
  </td>

  <td>
    [BankSlipInstallment](https://cora-api.readme.io/reference/emiss%C3%A3o-de-boleto-parcelado-v2#objeto-bankslipinstallment)
  </td>

  <td>
    Object [BankSlipInstallment](https://cora-api.readme.io/reference/emiss%C3%A3o-de-boleto-parcelado-v2#objeto-bankslipinstallment)
  </td>
</tr>

<tr>
  <td>
    pix\ <span class="tag tag-inline background-light-negative">obrigatório</span>
  </td>

  <td>
    [Pix](https://cora-api.readme.io/reference/emiss%C3%A3o-de-boleto-registrado-v2#objeto-pix)
  </td>

  <td>
    Objeto [Pix](https://cora-api.readme.io/reference/emiss%C3%A3o-de-boleto-registrado-v2#objeto-pix)
  </td>
</tr>

<tr>
  <td>
    services\ <span class="tag tag-inline background-light-negative">obrigatório</span>
  </td>

  <td>
    Lista de [Services](https://cora-api.readme.io/reference/emiss%C3%A3o-de-boleto-registrado-v2#objeto-services)
  </td>

  <td>
    Lista de objetos [Services](https://cora-api.readme.io/reference/emiss%C3%A3o-de-boleto-registrado-v2#objeto-services)
  </td>
</tr>

<tr>
  <td>
    payment\_terms\ <span class="tag tag-inline background-light-negative">obrigatório</span>
  </td>

  <td>
    [PaymentTerms](https://cora-api.readme.io/reference/emiss%C3%A3o-de-boleto-registrado#objeto-paymentterms)
  </td>

  <td>
    Objeto [PaymentTerms](https://cora-api.readme.io/reference/emiss%C3%A3o-de-boleto-registrado#objeto-paymentterms)
  </td>
</tr>

<tr>
  <td>
    payments\ <span class="tag tag-inline background-light-negative">obrigatório</span>
  </td>

  <td>
    [Payments](https://cora-api.readme.io/reference/emiss%C3%A3o-de-boleto-registrado#objeto-payments)
  </td>

  <td>
    Lista de objetos [Payments](https://cora-api.readme.io/reference/emiss%C3%A3o-de-boleto-registrado#objeto-payments). Caso o pagamento ainda não tenha sido feito o array será vazio
  </td>
</tr>

<tr>
  <td>
    payment\_forms\ <span class="tag tag-inline background-light-negative">obrigatório</span>
  </td>

  <td>
    Lista de Strings
  </td>

  <td>
    Lista de Strings que representam as formas de pagamento escolhidas ao gerar carnê
  </td>
</tr>

<tr>
  <td>
    created\_at\ <span class="tag tag-inline background-light-negative">obrigatório</span>
  </td>

  <td>
    String
  </td>

  <td>
    Data de criação da fatura.
  </td>
</tr>

---

Objeto Buyer

  <th>
    Tipo
  </th>

  <th>
    Descrição
  </th>
</tr>

  <td>
    String
  </td>

  <td>
    Nome do seu cliente (máximo 60 caracteres)
  </td>
</tr>

<tr>
  <td>
    document\ <span class="tag tag-inline background-light-negative">obrigatório</span>
  </td>

  <td>
    [Document](https://cora-api.readme.io/reference/emiss%C3%A3o-de-boleto-registrado-v2#objeto-document)
  </td>

  <td>
    Objeto [Document](https://cora-api.readme.io/reference/emiss%C3%A3o-de-boleto-registrado-v2#objeto-document)
  </td>
</tr>

<tr>
  <td>
    email\ <span class="tag tag-inline background-light-negative">obrigatório</span>
  </td>

  <td>
    String
  </td>

  <td>
    E-mail do seu cliente (máximo 60 caracteres)
  </td>
</tr>

<tr>
  <td>
    type\ <span class="tag tag-inline background-light-negative">obrigatório</span>
  </td>

  <td>
    String
  </td>

  <td>
    Identificação do pagador do boleto como PJ ou PF
  </td>
</tr>

<tr>
  <td>
    address\ <span class="tag tag-inline background-light-negative">obrigatório</span>
  </td>

  <td>
    [Address](https://cora-api.readme.io/reference/emiss%C3%A3o-de-boleto-registrado-v2#objeto-address)
  </td>

  <td>
    Objeto [Address](https://cora-api.readme.io/reference/emiss%C3%A3o-de-boleto-registrado-v2#objeto-address)
  </td>
</tr>

---

Objeto Seller

  <th>
    Tipo
  </th>

  <th>
    Descrição
  </th>
</tr>

  <td>
    String
  </td>

  <td>
    Dia do mês que será incluído em todas as parcelas
  </td>
</tr>

<tr>
  <td>
    name\ <span class="tag tag-inline background-light-negative">obrigatório</span>
  </td>

  <td>
    String
  </td>

  <td>
    Nome do beneficiário do boleto
  </td>
</tr>

<tr>
  <td>
    document\ <span class="tag tag-inline background-light-negative">obrigatório</span>
  </td>

  <td>
    String
  </td>

  <td>
    Documento de identificação do beneficiário do boleto. Apenas números, sem pontos ou hífens
  </td>
</tr>

<tr>
  <td>
    type\ <span class="tag tag-inline background-light-negative">obrigatório</span>
  </td>

  <td>
    String
  </td>

  <td>
    Identificação do beneficiário do boleto como PJ ou PF
  </td>
</tr>

---

Objeto BankSlipInstallment

  <th>
    Tipo
  </th>

  <th>
    Descrição
  </th>
</tr>

  <td>
    String
  </td>

  <td>
    Código de barras do boleto.
  </td>
</tr>

<tr>
  <td>
    digitable\ <span class="tag tag-inline background-light-negative">obrigatório</span>
  </td>

  <td>
    String
  </td>

  <td>
    Linha digitável do boleto. Número que deverá ser utilizado para pagamento.
  </td>
</tr>

<tr>
  <td>
    our\_number\ <span class="tag tag-inline background-light-negative">obrigatório</span>
  </td>

  <td>
    String
  </td>

  <td>
    Nosso número. Número do convênio concatenado com a sequência do documento.
  </td>
</tr>

<tr>
  <td>
    registered\ <span class="tag tag-inline background-light-negative">obrigatório</span>
  </td>

  <td>
    Boolean
  </td>

  <td>
    Informa se o boleto foi registrado ou não.
  </td>
</tr>

<tr>
  <td>
    url\ <span class="tag tag-inline background-light-negative">obrigatório</span>
  </td>

  <td>
    String
  </td>

  <td>
    URL do PDF do boleto (os boletos são disponibilizados apenas em PDF, não há versão HTML)
  </td>
</tr>

<tr>
  <td>
    fine\ <span class="tag tag-inline background-light-negative">obrigatório</span>
  </td>

  <td>
    Int
  </td>

  <td>
    Será definido como 0 no momento da criação do carnê.
  </td>
</tr>

<tr>
  <td>
    interest\ <span class="tag tag-inline background-light-negative">obrigatório</span>
  </td>

  <td>
    Int
  </td>

  <td>
    Será definido como 0 no momento da criação do carnê.
  </td>
</tr>

<tr>
  <td>
    document\_sequence\ <span class="tag tag-inline background-light-negative">obrigatório</span>
  </td>

  <td>
    Int
  </td>

  <td>
    Número da sequência do documento
  </td>
</tr>

<tr>
  <td>
    interest\_monthly\_percent\ <span class="tag tag-inline background-light-negative">obrigatório</span>
  </td>

  <td>
    Double
  </td>

  <td>
    Taxa percentual de juros a ser cobrada
  </td>
</tr>

<tr>
  <td>
    fine\_percent\ <span class="tag tag-inline background-light-negative">obrigatório</span>
  </td>

  <td>
    Double
  </td>

  <td>
    Porcentagem do valor total a ser cobrada quando o pagamento é atrasado ou não realizado dentro do prazo estipulado
  </td>
</tr>

<tr>
  <td>
    fine\_value\ <span class="tag tag-inline background-light-negative">obrigatório</span>
  </td>

  <td>
    Int
  </td>

  <td>
    Valor fixo a ser cobrado quando o pagamento não é realizado dentro do prazo estipulado
  </td>
</tr>

<tr>
  <td>
    discount\_percent\ <span class="tag tag-inline background-light-negative">obrigatório</span>
  </td>

  <td>
    Double
  </td>

  <td>
    Porcentagem do valor total a ser reduzido em forma de desconto caso o pagamento seja realizado um dia antes da data de vencimento definida
  </td>
</tr>

<tr>
  <td>
    discount\_value\ <span class="tag tag-inline background-light-negative">obrigatório</span>
  </td>

  <td>
    Int
  </td>

  <td>
    Valor fixo a ser reduzido em forma de desconto caso o pagamento seja realizado um dia antes da data de vencimento definida
  </td>
</tr>

---