> This page is for BaaS.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.api.corpx.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.api.corpx.com/_mcp/server.

# Guia de Emissão de Boleto

Emite um boleto em nome da conta. A conta é o beneficiário e um terceiro paga. O caminho inverso, pagar um boleto de terceiro, é [Boleto Pay](/baas/guias/pagar/boleto-pay).

A feature `boleto_charge` **nasce desligada para todos os tenants**, inclusive os criados depois do lançamento. Enquanto estiver off, toda rota em `/v1/accounts/{accountId}/boleto/charge` responde **403** `feature_disabled`. Com a feature ligada, a emissão ainda exige `boletoCharge.enabled = true` na policy do tenant (todas as contas) ou na policy da conta. Sem isso a rota responde **403** `boleto_charge_account_disabled`. `enabled = false` na conta tira essa conta de um tenant habilitado. A CorpX liga os dois pelo painel administrativo. Desligar a feature depois não cancela boleto já emitido.

Escopo da credencial: `boleto_charge.manage`. É entrada de dinheiro, não cashout. A leitura também aceita `read`. Emissão avulsa e lotes são **BaaS**; credenciais de Internet Banking continuam somente com as leituras de boleto.

## Credenciar o beneficiário

O titular precisa estar cadastrado como beneficiário no liquidante antes da primeira emissão. O cadastro usa os dados da conta (nome, documento e, quando há mais de uma conta ativa, agência e conta). **Não envie corpo.** Qualquer JSON que não seja vazio ou `{}` responde **400** `invalid_payload`.

```
POST /v1/accounts/{accountId}/boleto/charge/beneficiary
```

| Situação                                      | HTTP                                                | O que acontece                                                                                                                                                          |
| --------------------------------------------- | --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Sem beneficiário, ou relacionamento encerrado | 202 `boleto_charge_beneficiary_pending`             | A facade cadastra e para. Header `Retry-After: 300`. Nada foi emitido.                                                                                                  |
| Já `PENDING`                                  | 202, o mesmo código                                 | Não há um segundo cadastro.                                                                                                                                             |
| `ELIGIBLE` com relacionamento `ACTIVE`        | 200                                                 | Devolve o beneficiário. Não recadastra.                                                                                                                                 |
| `INELIGIBLE` ou `UNDER_REVIEW`                | 422 `boleto_charge_beneficiary_ineligible`          | A mensagem traz o status.                                                                                                                                               |
| O liquidante recusa na hora                   | 502 `boleto_charge_beneficiary_registration_failed` | A mensagem traz a descrição do liquidante. Nada foi emitido.                                                                                                            |
| Cadastro rejeitado nas últimas 24 horas       | Conforme as linhas acima                            | Este `POST` cadastra de novo mesmo assim: é por ele que você recadastra depois de corrigir os dados da conta. Só o recadastro automático da emissão espera as 24 horas. |

```
GET /v1/accounts/{accountId}/boleto/charge/beneficiary
```

Consulta ao vivo. **404** `boleto_charge_beneficiary_not_found` quando a conta nunca foi cadastrada. **422** `boleto_charge_account_holder_not_found` quando o liquidante não reconhece o titular no módulo de boletos: isso não é ausência de beneficiário.

| Campo                | Valores                                                                                                                                                   |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `status`             | `ELIGIBLE` apto, `PENDING` em análise, `UNDER_REVIEW` em revisão, `INELIGIBLE` inapto                                                                     |
| `relationshipStatus` | `ACTIVE` ou `CLOSED`                                                                                                                                      |
| `relationshipActive` | `true` quando o relacionamento está ativo                                                                                                                 |
| `lastEvent`          | Último aviso do liquidante sobre o beneficiário, quando houver. Veja [Acompanhando o beneficiário por webhook](#acompanhando-o-beneficiário-por-webhook). |

```
PATCH /v1/accounts/{accountId}/boleto/charge/beneficiary
```

Atualiza os dados cadastrais. A facade descobre o beneficiário da conta; não envie o id. PF aceita `name` e `socialName`. PJ aceita `legalName` e `tradeName`. E-mail, telefone e representante valem para os dois. Pelo menos um campo. Resposta **202** com `operationId`.

```
PATCH /v1/accounts/{accountId}/boleto/charge/beneficiary/status
```

`targetStatus` é `ELIGIBLE`, `UNDER_REVIEW` ou `INELIGIBLE`. Transições: apto vai para em análise ou inapto; em análise vai para apto ou inapto; inapto só volta para em análise. Qualquer outra é **409** `boleto_charge_beneficiary_transition_invalid` e não chega ao liquidante. `reason` é obrigatório. `documentId` é obrigatório quando o destino é `INELIGIBLE`.

```
DELETE /v1/accounts/{accountId}/boleto/charge/beneficiary/relationship
```

Encerra o relacionamento. Depois da confirmação, a conta não emite novos boletos. Para voltar, credencie de novo. `reason` é obrigatório. `terminationDate` é opcional, `YYYY-MM-DD`, hoje ou depois no fuso de Brasília. **202** traz o `operationId`.

```
GET /v1/boleto/charge/beneficiaries
```

Lista os beneficiários do liquidante e fica só com os documentos das contas do tenant. A página é a do liquidante, então pode voltar mais curta. `hasNext` indica que o liquidante tem outra página.

A primeira `POST /boleto/charge` também cadastra sozinha, com o mesmo 202, se você não tiver chamado o credenciamento antes.

### Acompanhando o beneficiário por webhook

Cadastro, atualização, mudança de elegibilidade e encerramento são confirmados pelo liquidante depois da resposta **202**. Assine os eventos abaixo para saber o desfecho sem repetir a chamada a cada `Retry-After`. O formato de cada um está em [Webhooks](/baas/guias/conta/webhooks).

| Evento                               | Quando                                                                                                                                                               |
| ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `boleto.charge.beneficiary.approved` | O cadastro (ou a reativação) foi confirmado. A conta já pode emitir.                                                                                                 |
| `boleto.charge.beneficiary.rejected` | O liquidante recusou uma operação. `operation` diz qual: `INCLUSION`, `UPDATE`, `STATUS_UPDATE` ou `TERMINATION`. `rejectionCode` e `rejectionReason` dizem por quê. |
| `boleto.charge.beneficiary.updated`  | Atualização cadastral (`UPDATE`) ou de elegibilidade (`STATUS_UPDATE`, com `previousStatus` e `currentStatus`) aplicada.                                             |
| `boleto.charge.beneficiary.closed`   | Relacionamento encerrado. A conta não emite novos boletos até ser credenciada de novo.                                                                               |

`data.operationId` é o mesmo `operationId` da resposta 202 do `PATCH` ou do `DELETE`. Deduplique pelo `id` do envelope: o mesmo aviso pode chegar mais de uma vez.

O `GET .../beneficiary` traz o último aviso em `lastEvent`, com `eventType`, `operation`, `result` (`CONFIRMED` ou `REJECTED`), `operationId`, `rejectionCode`, `rejectionReason` e `occurredAt`. Quando a conta ainda não tem beneficiário, o **404** traz o mesmo objeto em `details.lastEvent`.

Um cadastro rejeitado segura o recadastro automático da emissão por 24 horas, contadas do aviso de recusa. Nesse prazo, a `POST /boleto/charge` e o disparo de lote respondem **502** `boleto_charge_beneficiary_registration_failed` com o motivo e `details.lastEvent`, sem enviar outro cadastro. O header `Retry-After` traz os segundos que faltam. Repetir a emissão antes disso não adianta: corrija os dados da conta e chame `POST .../beneficiary`, que cadastra de novo na hora e responde o **202** de sempre. Fora desse caso, o **202** com `Retry-After` continua igual: o webhook só avisa antes.

## Cotas mensais

As emissões passam por duas cotas simultâneas no mês civil de Brasília (`America/Sao_Paulo`):

| Cota     |           Padrão | Configuração                                         |
| -------- | ---------------: | ---------------------------------------------------- |
| Tenant   | 100 emissões/mês | `boletoCharge.maxIssuesPerMonth` na policy do tenant |
| Conta PF |   5 emissões/mês | policy da conta                                      |
| Conta PJ |  10 emissões/mês | policy da conta                                      |

Não existe modo ilimitado. O saldo efetivo é sempre o menor entre tenant e conta. Consulte ambos em:

```
GET /v1/accounts/{accountId}/boleto/charge/quota
```

A resposta traz `periodStart`, `resetsAt`, `effectiveRemaining` e os blocos `tenant` e `account` (`limit`, `used`, `remaining`, `source`). `account.personType` informa `PF` ou `PJ`; `source` diz se o limite veio de `default`, `tenant` ou `account`.

Uma emissão só consome cota depois de o beneficiário ser validado e a operação ser admitida. Repetição idempotente do mesmo boleto, beneficiário pendente/inapto e recusa por falta de cota não contam. Recusa definitiva do liquidante (4xx, boleto não criado) **devolve** a vaga. Timeout e resposta ambígua não devolvem: o boleto pode ter sido emitido.

## Emitir

```
POST /v1/accounts/{accountId}/boleto/charge
```

`identifier` é obrigatório no JSON e é a única chave de idempotência desta operação. O header `Idempotency-Key` **não** substitui o campo. Repetir o mesmo boleto devolve **200** sem emitir outro nem consumir cota novamente.

Resposta **202** com `chargeId` (o id do liquidante), `barcode`, `digitableLine`, `ourNumber` e `registrationCondition: PENDING`. O registro na base centralizada chega depois, em `boleto.charge.registered` ou `boleto.charge.registration_failed`.

### Campos do pedido

Dinheiro é `number` em BRL com duas casas. Nunca centavos, nunca string.

| Campo                                                                                                                           | Obrigatório | O que é                                                                                                                       |
| ------------------------------------------------------------------------------------------------------------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `identifier`                                                                                                                    | Sim         | Idempotência desta conta. Único por conta; não há fallback para header.                                                       |
| `dueDate`                                                                                                                       | Sim         | Vencimento, `YYYY-MM-DD`. Não pode ser anterior a `issueDate`.                                                                |
| `issueDate`                                                                                                                     | Não         | Data de emissão, `YYYY-MM-DD`.                                                                                                |
| `amount.nominal`                                                                                                                | Sim         | Valor de face, maior que zero.                                                                                                |
| `amount.currency`                                                                                                               | Não         | `BRL`.                                                                                                                        |
| `payer.name`                                                                                                                    | Sim         | Nome do pagador.                                                                                                              |
| `payer.personType`                                                                                                              | Sim         | `person` ou `company`.                                                                                                        |
| `payer.taxNumber`                                                                                                               | Sim         | CPF se `person`, CNPJ se `company`. Só dígitos.                                                                               |
| `payer.email`                                                                                                                   | Não         | E-mail do pagador.                                                                                                            |
| `payer.addressStreet`, `addressNumber`, `addressComplement`, `addressDistrict`, `addressCity`, `addressState`, `addressZipCode` | Não         | Endereço do pagador. CEP com 8 dígitos.                                                                                       |
| `interest`                                                                                                                      | Não         | Juros após o vencimento. `startDate` tem de ser posterior a `dueDate`.                                                        |
| `fine`                                                                                                                          | Não         | Multa após o vencimento. Mesma regra de `startDate`.                                                                          |
| `discount`                                                                                                                      | Não         | Desconto por antecipação. Cada `groups[].limitDate` tem de ser anterior a `dueDate`.                                          |
| `abatement.amount`                                                                                                              | Não         | Abatimento fixo, não negativo. Somado aos descontos, não pode atingir `amount.nominal`.                                       |
| `allowPartialPayment`                                                                                                           | Não         | Aceita pagamento menor que o valor.                                                                                           |
| `allowDivergentPayment`                                                                                                         | Não         | Aceita valor diferente do nominal, dentro de `minPaymentAmount` e `maxPaymentAmount`.                                         |
| `divergentPaymentMode`                                                                                                          | Não         | `anyValue`, `minMax` ou `minOnly`.                                                                                            |
| `expirationPolicy.allowPaymentAfterDueDate`                                                                                     | Não         | Se o título pode ser pago depois do vencimento.                                                                               |
| `expirationPolicy.paymentLimitDate`                                                                                             | Não         | Último dia de pagamento, `YYYY-MM-DD`, não anterior a `dueDate`. É o que limita a validade: não há baixa de boleto em aberto. |
| `expirationPolicy.blockPaymentAfterLimit`                                                                                       | Não         | Recusa pagamento depois de `paymentLimitDate`.                                                                                |
| `expirationPolicy.decursoGraceDays`                                                                                             | Não         | Dias de decurso de prazo depois do limite.                                                                                    |

`interest` e `fine` compartilham a forma do encargo: `calculationModel`, `typeId`, `typeKey`, `value` e `startDate`. `discount.groups[]` traz `sequence`, `typeId`, `typeKey`, `value` e `limitDate`. `typeKey` com `percentage` trata `value` como percentual do nominal; os demais, como valor em BRL. `typeId` é opcional: sem ele, preenchemos a partir do `typeKey`; se vier, tem de corresponder.

| Encargo             | `typeKey` aceitos                                                                                                                                                                                                                                        |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `interest`          | `exempt`, `fixed-value-calendar-day`, `fixed-value-business-day`, `percentage-calendar-day`, `percentage-business-day`, `percentage-month-calendar-day`, `percentage-month-business-day`, `percentage-year-calendar-day`, `percentage-year-business-day` |
| `fine`              | `exempt`, `fixed-value`, `percentage`                                                                                                                                                                                                                    |
| `discount.groups[]` | `exempt`, `fixed-value-until-date`, `percentage-until-date`, `fixed-value-anticipation-calendar-day`, `fixed-value-anticipation-business-day`, `percentage-anticipation-calendar-day`, `percentage-anticipation-business-day`                            |

`calculationModel`, quando enviado, é `receiver-calculates-all`, `recipient-calculates-overdue` ou `recipient-calculates-all`. `value` é obrigatório e maior que zero, exceto em `exempt`. Desconto `-until-date` exige `limitDate`; desconto por antecipação não aceita `limitDate`. `typeKey` ou `calculationModel` fora dessas listas responde **400** `invalid_payload`.

Encargo incompatível com o modelo responde **422** `boleto_charge_rules_inconsistent`. Desconto com data inválida responde **422** `boleto_charge_discount_invalid`. Abatimento mais descontos que zeram o título respondem **422** `boleto_charge_reductions_exceed_amount`. `identifier` já ativo responde **409** `boleto_charge_identifier_in_use`. Código de barras já ativo responde **409** `boleto_charge_barcode_active`.

### O que a resposta traz

| Campo                                               | O que é                                                                                                       |
| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `chargeId`                                          | Id do boleto no liquidante. É o que vai na URL de consulta e nos webhooks.                                    |
| `identifier`                                        | O seu.                                                                                                        |
| `barcode`                                           | Código de barras, 44 dígitos, quando o liquidante já devolveu.                                                |
| `digitableLine`                                     | Linha digitável.                                                                                              |
| `ourNumber`                                         | Nosso número.                                                                                                 |
| `status`                                            | `OPEN`, `SETTLED`, `OVERDUE`, `WRITTEN_OFF`, `CANCELLED`, `EXPIRED`. `OVERDUE` não encerra o boleto.          |
| `statusReason`                                      | Motivo, quando o liquidante manda: `termExpiration`, `settlement`, `manualWriteOff`, `cancellation`, `other`. |
| `registrationCondition`                             | `PENDING` aguardando a base centralizada, `REGISTERED`, `REJECTED`.                                           |
| `dueDate`, `paymentLimitDate`                       | Datas `YYYY-MM-DD`.                                                                                           |
| `amount.nominal`                                    | Valor de face.                                                                                                |
| `amount.updatedAmount`                              | Valor atualizado, se o liquidante já calculou juros, multa e desconto.                                        |
| `amount.currency`                                   | `BRL`.                                                                                                        |
| `payer.name`, `payer.taxNumber`, `payer.personType` | Quem deve pagar.                                                                                              |
| `payment.amount`, `payment.settledAt`               | Preenchidos quando o boleto foi liquidado.                                                                    |

## Consultar

```
GET /v1/accounts/{accountId}/boleto/charge
GET /v1/accounts/{accountId}/boleto/charge/{chargeId}
```

As duas leituras têm garantias diferentes:

* **Lista local.** O primeiro GET pagina o espelho local e não chama o liquidante. Cada item traz `updatedAt`, instante da última sincronização bem-sucedida. Filtros: `barcode` (44 dígitos), `payer` (nome ou documento), `dueDate`, `status`, `page` (mínimo 1) e `pageSize` (1 a 200, padrão 50). A resposta traz `items`, `page`, `pageSize`, `totalItems`, `totalPages` e `hasNext`.
* **Detalhe sempre ao vivo.** O GET com `{chargeId}` consulta o liquidante em toda chamada, atualiza o espelho e devolve o resultado atual com o novo `updatedAt`. Se o liquidante falhar, a API devolve erro; **nunca** responde com cache antigo.

Não há backfill histórico. A lista começa com as emissões novas da v2.85.0. Um boleto anterior entra no espelho depois de uma consulta de detalhe bem-sucedida.

## Emitir em lote

As rotas de lote são somente BaaS e exigem `boleto_charge.manage`.

1. `POST /v1/accounts/{accountId}/boleto/charge/batches` cria um lote vazio em `DRAFT`. Exige `Idempotency-Key`; o JSON opcional aceita `name` (até 120 caracteres).
2. `PUT .../batches/{batchId}/items` adiciona de 1 a 50 pedidos JSON por chamada.
3. `DELETE .../batches/{batchId}/items/{itemId}` remove um item enquanto o lote ainda está em `DRAFT`.
4. `POST .../batches/{batchId}/dispatch` reserva a cota e inicia o processamento assíncrono.
5. `GET .../batches/{batchId}?page=1&pageSize=50` acompanha estatísticas e resultados item a item. `GET .../batches` lista os lotes da conta.

Cada item usa exatamente o corpo da emissão avulsa, inclusive `identifier` obrigatório. O upload de um chunk é **atômico**: se um item for inválido ou conflitar, nenhum dos 1–50 é salvo. O lote aceita no máximo **5.000** itens. `boleto_charge_batch_chunk_invalid` indica um chunk fora do intervalo de 1–50; `boleto_charge_batch_too_large`, total acima de 5.000; e `boleto_charge_batch_item_conflict`, o mesmo `identifier` com outro payload no lote.

Só `DRAFT` é editável. Os estados são:

```text
DRAFT → QUEUED → PROCESSING → COMPLETED | PARTIAL_FAILED | FAILED
```

O dispatch é atômico também: todos os itens precisam caber ao mesmo tempo nos saldos do tenant **e** da conta. Se um saldo não bastar, a API responde **429** `boleto_charge_monthly_limit_exceeded`, não reserva nada, não inicia nenhuma emissão e mantém o lote em `DRAFT`. Depois que o lote é admitido, a reserva cobre os itens. Item recusado em definitivo pelo liquidante devolve a vaga dele. Item com timeout ou resposta ambígua fica com a vaga.

> **Dispatch gera emissões cobradas**
>
> Cada boleto enviado para emissão pode gerar cobrança conforme as condições comerciais negociadas com a CorpX. Revise os itens e a cota antes do dispatch. O Portal pede uma confirmação explícita na tela; ela é uma proteção da interface, não um campo que a API recebe.

### Estatísticas do lote

`statistics.generation` acompanha `total`, `pending`, `processing`, `issued`, `failed` e `progressPercentage`. O lote termina quando todas as **tentativas de emissão** acabarem; registro, pagamento e expiração seguem no ciclo individual.

`statistics.payment` acompanha `issued`, `paid`, `unpaid`, `overdue`, `paidAmount` e `conversionRate`. A conversão é:

```text
paid / issued × 100
```

Falhas de emissão não entram no denominador. Por isso as estatísticas de pagamento continuam mudando depois que o lote chega ao estado terminal.

Ao terminar as tentativas, a API envia `boleto.charge.batch.completed` com o estado final e o resumo de geração (`total`, `issued`, `failed`). Consulte o lote para a conversão de pagamento atualizada. Com assinatura HMAC, valide `X-Signature` sobre os bytes brutos e deduplique pelo `id` do envelope.

## Ciclo de vida

1. Credenciamento do beneficiário, se ainda não existir (202, alguns minutos). `boleto.charge.beneficiary.approved` ou `.rejected` avisa o desfecho.
2. Emissão (202). O título nasce `OPEN` com registro `PENDING`.
3. `boleto.charge.registered` ou `boleto.charge.registration_failed`.
4. Daí: `boleto.charge.settled` (também entra no extrato como `BOLETO`), `overdue`, `written_off`, `cancelled` ou `expired`.

`boleto.charge.failed` está no catálogo e não é enviado nesta versão.

Não há como pedir a baixa de um boleto em aberto. O liquidante ainda não oferece essa operação; o `DELETE` existe no código e responde 501, fora deste contrato. Quando a validade precisar ser previsível, envie `expirationPolicy.paymentLimitDate` na emissão.