Boleto Charge | API CorpX

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.

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. A CorpX liga pelo painel administrativo. Desligar 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.

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.

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

Consulta ao vivo. 404 boleto_charge_beneficiary_not_found quando a conta nunca foi cadastrada. O liquidante não devolve um motivo em texto: o que existe é status e relationshipStatus.

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

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

Emitir

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

identifier é a chave de idempotência da conta. Se omitido, vale o header Idempotency-Key. Repetir o mesmo identifier devolve 200 com o boleto ao vivo, sem emitir outro.

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, ou o header	Idempotência desta conta. Único por conta.
`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.

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

Tudo é lido ao vivo no liquidante. Não há espelho local do boleto. A tabela local só guarda o ponteiro para rotear o webhook e a idempotência do identifier.

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

Filtros da lista: barcode (44 dígitos), payer (nome ou documento), dueDate, status, page (mínimo 1) e pageSize (1 a 200, padrão 50). A lista devolve items, page, pageSize, totalItems, totalPages e hasNext.

Ciclo de vida

Credenciamento do beneficiário, se ainda não existir (202, alguns minutos).
Emissão (202). O título nasce OPEN com registro PENDING.
boleto.charge.registered ou boleto.charge.registration_failed.
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.