Conta e conciliação

Emissão de boletos

Emite um boleto em nome da conta. É o caminho inverso de pagar um boleto: aqui a conta é o beneficiário e um terceiro paga.

A feature bank_slip_issuance nasce desligada para todos os tenants, inclusive os criados depois do lançamento. Enquanto estiver off, POST e GET em /v1/accounts/{accountId}/bank-slips respondem 403 feature_disabled. A CorpX liga pelo painel administrativo. Desligar depois não cancela boleto já emitido.

Escopo da credencial: bank_slip.manage. É entrada de dinheiro, não cashout.

Primeira emissão por conta

O titular ainda não é beneficiário no banco. O primeiro POST cadastra o beneficiário e responde na hora:

{
  "errorCode": "bank_slip_beneficiary_pending",
  "message": "Cadastro do beneficiário desta conta em análise no banco. Isso acontece só na primeira emissão de cada conta; repita a solicitação em alguns minutos.",
  "beneficiary": { "status": "PENDING", "requestedAt": "2026-09-23T18:00:00Z" }
}

HTTP 202, header Retry-After: 300. Nada foi emitido e não existe bankSlipId. Repita o mesmo corpo em alguns minutos. Se o cadastro ainda estiver pendente, a resposta é a mesma, sem um novo cadastro.

ineligible ou underReview responde 422 bank_slip_beneficiary_ineligible. Falha síncrona no cadastro responde 502 bank_slip_beneficiary_registration_failed e nada é emitido.

Emitir

POST /v1/accounts/{accountId}/bank-slips

identifier é a chave de idempotência da conta (se omitido, vale o header Idempotency-Key). dueDate é YYYY-MM-DD. amount.nominal é maior que zero. payer.personType é person ou company.

Resposta 202 com bankSlipId, barcode, digitableLine, ourNumber e registrationCondition: pendingRegistration. O registro na base centralizada chega depois, nos eventos bank_slip.registered ou bank_slip.registration_failed.

Repetir o mesmo identifier devolve 200 com o boleto ao vivo, sem emitir outro.

Consultar

Tudo é lido ao vivo no liquidante. Não há espelho local do boleto.

  • GET /v1/accounts/{accountId}/bank-slips — filtros barcode, payer, dueDate, status, page, pageSize (até 200).
  • GET /v1/accounts/{accountId}/bank-slips/{bankSlipId} — bankSlipId é o id devolvido na emissão.
  • GET /v1/accounts/{accountId}/bank-slips/beneficiary — 404 bank_slip_beneficiary_not_found quando a conta nunca foi cadastrada.

Baixa

Não há como pedir a baixa de um boleto em aberto. DELETE /v1/accounts/{accountId}/bank-slips/{bankSlipId} responde 501 bank_slip_write_off_unavailable. Quando a validade precisar ser previsível, envie expirationPolicy.paymentLimitDate na emissão.

Eventos

bank_slip.registered, bank_slip.registration_failed, bank_slip.settled, bank_slip.overdue, bank_slip.written_off, bank_slip.cancelled, bank_slip.expired. A liquidação também aparece no extrato como BOLETO. bank_slip.failed está no catálogo e não é enviado nesta versão.