# Emissão e Gestão de Boletos e Boletos Híbridos (`/v2/charge`)

O conjunto de endpoints de **Charge** gerencia o ciclo de vida das cobranças por boleto, permitindo criar, consultar, atualizar, cancelar (dar baixa) e imprimir.

Na LURI, o objeto `charge` representa a cobrança gerada. Dependendo da configuração da carteira do _seller_, ao acionar o método de criação, a cobrança pode assumir os seguintes formatos:

- **Boleto Tradicional:** Cobrança padrão via código de barras e linha digitável.
- **Boleto Híbrido (Boleto + Pix):** Um único documento contendo tanto o código de barras quanto o QR Code Pix.

**Comportamento do Boleto Híbrido:**

Esta funcionalidade unifica duas opções de pagamento em uma única cobrança. Independentemente de o cliente pagar via Pix ou código de barras, o sistema registra a liquidação e dá baixa na cobrança automaticamente, invalidando o método que não foi utilizado.

_Para habilitar o Boleto Híbrido na carteira do seller, faça o pedido para o suporte._

> **Convenção de Valores ("Centavos"):** Todos os valores monetários e percentuais da API (como `amount`, `late_fee_amount`, `late_fee_percentage`, `interest_amount`, `interest_percentage`, `abatement_amount` e `discount[].amount`) devem ser informados como **números inteiros representando duas casas decimais** (sem ponto ou vírgula). Exemplo: `15000` = R$ 150,00; `200` = R$ 2,00 (fixo) ou 2,00% (percentual); `100` = R$ 1,00 (fixo) ou 1,00% (percentual).

> *Nota de Compatibilidade:* Parâmetros do formato legado (como `discount_percentage` e `discount_limit_date` diretamente em `billing_instructions`) continuam funcionando normalmente.

<table>
<thead>
<tr><th>Campo</th><th>Tipo</th><th>Obrigatório</th><th>Descrição</th></tr>
</thead>
<tbody>
<tr><td><code>seller</code></td><td>string</td><td>Sim</td><td>ID da loja/conta recebedora (<code>seller_id</code>).</td></tr>
<tr><td><code>amount</code></td><td>integer</td><td>Sim</td><td>Valor nominal do boleto em centavos (mínimo <code>100</code> = R$ 1,00). Ex.: R$ 150,00 = <code>15000</code>.</td></tr>
<tr><td><code>reference_id</code></td><td>string</td><td>Não</td><td>Código de conciliação do seu sistema para identificar a cobrança.</td></tr>
<tr class="grupo"><td><code>installment</code></td><td>object</td><td>Não</td><td>Identificação da parcela e quantidade total de parcelas da venda associada àquele boleto.</td></tr>
<tr><td class="n1"><code>number</code></td><td>integer</td><td>Condicional</td><td>Número da parcela atual (inteiro positivo <code>&gt;= 1</code> e <code>&lt;= total</code>; obrigatório se <code>installment</code> for enviado).</td></tr>
<tr><td class="n1"><code>total</code></td><td>integer</td><td>Condicional</td><td>Quantidade total de parcelas da venda (inteiro positivo <code>&gt;= 1</code>; obrigatório se <code>installment</code> for enviado).</td></tr>
<tr><td><code>tags</code></td><td>array</td><td>Não</td><td>Etiquetas livres para identificar o boleto (pedido, parcela etc.). Ex.: <code>["Parcela 1/12", "Pedido #1234"]</code>.</td></tr>

<tr class="grupo"><td><code>customer</code></td><td>object</td><td>Sim</td><td>Dados do pagador (sacado).</td></tr>
<tr><td class="n1"><code>taxpayer_id</code></td><td>string</td><td>Sim</td><td>CPF ou CNPJ do pagador (somente números).</td></tr>
<tr><td class="n1"><code>name</code></td><td>string</td><td>Sim</td><td>Nome ou Razão Social do pagador.</td></tr>
<tr><td class="n1"><code>email</code></td><td>string</td><td>Não</td><td>E-mail do pagador.</td></tr>
<tr><td class="n1"><code>phone_number</code></td><td>string</td><td>Sim</td><td>Telefone com DDD (somente números). Formato: <code>11912345678</code>.</td></tr>
<tr><td class="n1"><code>street_line</code></td><td>string</td><td>Sim</td><td>Logradouro do pagador (rua e número).</td></tr>
<tr><td class="n1"><code>street_line2</code></td><td>string</td><td>Não</td><td>Complemento do endereço.</td></tr>
<tr><td class="n1"><code>neighborhood</code></td><td>string</td><td>Não</td><td>Bairro.</td></tr>
<tr><td class="n1"><code>city</code></td><td>string</td><td>Sim</td><td>Cidade.</td></tr>
<tr><td class="n1"><code>state</code></td><td>string</td><td>Sim</td><td>Estado (UF com 2 letras, ex.: <code>SP</code>).</td></tr>
<tr><td class="n1"><code>postal_code</code></td><td>string</td><td>Sim</td><td>CEP (somente números). Formato: <code>01310100</code>.</td></tr>

<tr class="grupo"><td><code>payment_method</code></td><td>object</td><td>Sim</td><td>Informações e regras de pagamento do boleto.</td></tr>
<tr><td class="n1"><code>expiration_date</code></td><td>string</td><td>Sim</td><td>Data de vencimento no formato <code>AAAA-MM-DD</code>.</td></tr>
<tr><td class="n1"><code>payment_limit_date</code></td><td>string</td><td>Não</td><td>Data limite para pagamento no formato <code>AAAA-MM-DD</code> (deve ser maior que <code>expiration_date</code>). Caso omitida, assume automaticamente <code>+90 dias</code> após o vencimento.</td></tr>
<tr><td class="n1"><code>document_species</code></td><td>integer</td><td>Não</td><td>Código FEBRABAN da espécie do título (padrão <code>2</code> = Duplicata Mercantil; <code>4</code> = Duplicata de Serviço).</td></tr>
<tr><td class="n1"><code>document_number</code></td><td>string</td><td>Não</td><td>Número do documento/título (máx. 15 caracteres). Caso omitido, utiliza <code>reference_id</code>.</td></tr>

<tr class="grupo"><td class="n1"><code>receiver</code></td><td>object</td><td>Não</td><td>Dados do Sacador Avalista do boleto.</td></tr>
<tr><td class="n2"><code>taxpayer_id</code></td><td>string</td><td>Condicional</td><td>CPF ou CNPJ do sacador avalista (obrigatório se <code>receiver</code> for enviado).</td></tr>
<tr><td class="n2"><code>name</code></td><td>string</td><td>Condicional</td><td>Nome ou Razão Social do sacador avalista (obrigatório se <code>receiver</code> for enviado).</td></tr>

<tr class="grupo"><td class="n1"><code>billing_instructions</code></td><td>object</td><td>Não</td><td>Instruções financeiras de cobrança (multa, juros, abatimento e descontos) — todos os valores representados em "centavos" (inteiro com 2 casas decimais).</td></tr>
<tr><td class="n2"><code>late_fee_amount</code></td><td>integer</td><td>Não</td><td>Valor fixo da multa em centavos. Ex.: <code>200</code> = R$ 2,00. (Mutuamente exclusivo com <code>late_fee_percentage</code>).</td></tr>
<tr><td class="n2"><code>late_fee_percentage</code></td><td>integer</td><td>Não</td><td>Percentual da multa em base centesimal. Ex.: <code>200</code> = 2,00%. Máx.: <code>10000</code> (100,00%).</td></tr>
<tr><td class="n2"><code>late_fee_date</code></td><td>string</td><td>Não</td><td>Data de início da multa (<code>AAAA-MM-DD</code>, posterior ao vencimento). Padrão: <code>expiration_date + 1 dia</code>.</td></tr>
<tr><td class="n2"><code>interest_amount</code></td><td>integer</td><td>Não</td><td>Valor fixo de juros ao dia (dias corridos) em centavos. Ex.: <code>100</code> = R$ 1,00/dia. (Mutuamente exclusivo com <code>interest_percentage</code>).</td></tr>
<tr><td class="n2"><code>interest_percentage</code></td><td>integer</td><td>Não</td><td>Percentual de juros ao mês (dias corridos) em base centesimal. Ex.: <code>100</code> = 1,00%/mês.</td></tr>
<tr><td class="n2"><code>interest_date</code></td><td>string</td><td>Não</td><td>Data de início dos juros (<code>AAAA-MM-DD</code>, posterior ao vencimento). Padrão: <code>expiration_date + 1 dia</code>.</td></tr>
<tr><td class="n2"><code>abatement_amount</code></td><td>integer</td><td>Não</td><td>Valor de abatimento concedido no título em centavos. Ex.: <code>500</code> = R$ 5,00.</td></tr>
<tr><td class="n2"><code>discount</code></td><td>array</td><td>Não</td><td>Lista de até 3 faixas de desconto para pagamento antecipado. Cada item do array contém:<ul><li><code>limit_date</code> (string, obrigatório): Data limite do desconto (<code>AAAA-MM-DD</code>, menor ou igual a <code>expiration_date</code>).</li><li><code>mode</code> (string, obrigatório): <code>"fixed"</code> (valor fixo) ou <code>"percentage"</code> (percentual).</li><li><code>amount</code> (integer, obrigatório): Valor em centavos/base centesimal (ex.: <code>1000</code> = R$ 10,00 ou 10,00%).</li></ul></td></tr>

<tr class="grupo"><td><code>body_instructions</code></td><td>object</td><td>Não</td><td>Instruções impressas no corpo do boleto.</td></tr>
<tr><td class="n1"><code>line1</code></td><td>string</td><td>Não</td><td>Texto impresso na primeira linha (limite de 80 caracteres).</td></tr>
<tr><td class="n1"><code>line2</code></td><td>string</td><td>Não</td><td>Texto impresso na segunda linha (limite de 80 caracteres).</td></tr>
<tr><td class="n1"><code>line3</code></td><td>string</td><td>Não</td><td>Texto impresso na terceira linha (limite de 80 caracteres).</td></tr>
</tbody>
</table>