# Boleto

Cobrança com linha digitável e código de barras.

Cobrança por boleto bancário. Mesma chamada do PIX, trocando o `payment_method`. A resposta traz a **linha digitável** e o **código de barras**.

> ✅ **A API devolve apenas os códigos — não um PDF.** Você recebe a linha digitável e o código de barras e monta o documento no seu layout, com a sua marca. Assim o boleto que o seu cliente recebe é o seu, e a aparência dele não depende de um template nosso.

`POST /v1/charges`

## Criar a cobrança

_Requisição_

```bash
curl -X POST https://novexfinance.com.br/api/v1/charges \
  -H "Authorization: Bearer $NOVEX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: fatura-2026-08-1174" \
  -d '{
    "payment_method": "boleto",
    "amount": 45000,
    "description": "Fatura de agosto/2026",
    "reference": "1174",
    "customer": {
      "name": "Construtora Exemplo LTDA",
      "email": "financeiro@exemplo.com.br",
      "phone": "1133224455",
      "document": "11222333000181"
    }
  }'
```

```php
$charge = $novex->post('/charges', [
    'payment_method' => 'boleto',
    'amount'         => 45000,
    'description'    => 'Fatura de agosto/2026',
    'reference'      => '1174',
    'customer'       => [
        'name'     => 'Construtora Exemplo LTDA',
        'email'    => 'financeiro@exemplo.com.br',
        'phone'    => '1133224455',
        'document' => '11222333000181',
    ],
], 'fatura-2026-08-1174');

$linhaDigitavel = $charge['boleto']['digitable_line'];
$codigoBarras   = $charge['boleto']['barcode'];
```

```js
const charge = await novex.post('/charges', {
  payment_method: 'boleto',
  amount: 45000,
  description: 'Fatura de agosto/2026',
  reference: '1174',
  customer: {
    name: 'Construtora Exemplo LTDA',
    email: 'financeiro@exemplo.com.br',
    phone: '1133224455',
    document: '11222333000181',
  },
}, { idempotencyKey: 'fatura-2026-08-1174' });

const { digitable_line, barcode } = charge.boleto;
```

```python
charge = novex.post('/charges', {
    'payment_method': 'boleto',
    'amount': 45000,
    'description': 'Fatura de agosto/2026',
    'reference': '1174',
    'customer': {
        'name': 'Construtora Exemplo LTDA',
        'email': 'financeiro@exemplo.com.br',
        'phone': '1133224455',
        'document': '11222333000181',
    },
}, idempotency_key='fatura-2026-08-1174')

linha = charge['boleto']['digitable_line']
```

Os campos de entrada são os mesmos do [PIX](https://novexfinance.com.br/docs/pix) — só muda o `payment_method`. CNPJ é aceito normalmente em `customer.document`.

## Resposta

_Resposta 201_

```json
{
  "object": "charge",
  "id": "ch_5e08b3d71fa9426c8b03",
  "status": "pending",
  "amount": 45000,
  "currency": "BRL",
  "payment_method": "boleto",
  "description": "Fatura de agosto/2026",
  "reference": "1174",
  "customer": {
    "name": "Construtora Exemplo LTDA",
    "email": "financeiro@exemplo.com.br",
    "phone": "1133224455",
    "document": "11222333000181",
    "document_type": "cnpj"
  },
  "paid_at": null,
  "created_at": "2026-08-07T14:32:10-03:00",
  "boleto": {
    "digitable_line": "34191.79001 01043.510047 91020.150008 097704500045000",
    "barcode": "34199977000045000000010435100479102015000",
    "expires_at": "2026-08-14T23:59:59-03:00"
  }
}
```

| Campo da resposta | Tipo | Descrição |
| --- | --- | --- |
| `boleto.digitable_line` opcional | string | Linha digitável formatada (47 dígitos). É o que o cliente digita no internet banking. |
| `boleto.barcode` opcional | string | Código de barras (44 dígitos), sem formatação. Use para gerar a imagem do código. |
| `boleto.expires_at` opcional | data | Data de vencimento. |

## Montar o documento

Com a linha digitável e o código de barras você tem tudo. Padrão do mercado para o código de barras de boleto: **Interleaved 2 of 5**, com 44 dígitos.

_Gerar o código de barras_

```php
// picqer/php-barcode-generator, por exemplo
$generator = new BarcodeGeneratorPNG();
$png = $generator->getBarcode(
    $charge['boleto']['barcode'],
    $generator::TYPE_INTERLEAVED_2_5,
    2,
    70
);

echo '<img src="data:image/png;base64,' . base64_encode($png) . '">';
echo '<p>' . $charge['boleto']['digitable_line'] . '</p>';
```

```js
import bwipjs from 'bwip-js';

const png = await bwipjs.toBuffer({
  bcid: 'interleaved2of5',
  text: charge.boleto.barcode,
  height: 12,
  includetext: false,
});
```

> ℹ️ Envie sempre a **linha digitável em texto**, junto com a imagem. Boa parte dos pagamentos de boleto acontece pelo aplicativo do banco, onde copiar e colar é mais rápido — e é o único caminho quando a imagem não carrega no e-mail.

## Ciclo de vida

| Status | Significa |
| --- | --- |
| `pending` | Boleto emitido, aguardando pagamento. |
| `paid` | Pagamento compensado. Chega por webhook `charge.paid`. |
| `refunded` | Valor devolvido ao pagador. |
| `failed` | A cobrança não pôde ser concluída. |

> ⚠️ **Boleto não confirma na hora.** O pagamento é compensado pelo banco e só então o status vira `paid` — normalmente em 1 dia útil. Não libere pedido contra boleto emitido; espere o evento `charge.paid`.

## Liquidação

O valor entra no saldo disponível assim que o pagamento é confirmado. A compensação bancária já aconteceu antes de o status virar `paid`, então não há prazo adicional depois disso.


---

Documentação completa: https://novexfinance.com.br/docs/boleto
Base da API: https://novexfinance.com.br/api/v1