Skip to navigation

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.

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çãoHTTPO que acontece
Sem beneficiário, ou relacionamento encerrado202 boleto_charge_beneficiary_pendingA facade cadastra e para. Header Retry-After: 300. Nada foi emitido.
Já PENDING202, o mesmo códigoNão há um segundo cadastro.
ELIGIBLE com relacionamento ACTIVE200Devolve o beneficiário. Não recadastra.
INELIGIBLE ou UNDER_REVIEW422 boleto_charge_beneficiary_ineligibleA mensagem traz o status.
O liquidante recusa na hora502 boleto_charge_beneficiary_registration_failedA mensagem traz a descrição do liquidante. Nada foi emitido.
Cadastro rejeitado nas últimas 24 horasConforme as linhas acimaEste 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.

CampoValores
statusELIGIBLE apto, PENDING em análise, UNDER_REVIEW em revisão, INELIGIBLE inapto
relationshipStatusACTIVE ou CLOSED
relationshipActivetrue quando o relacionamento está ativo
lastEventÚltimo aviso do liquidante sobre o beneficiário, quando houver. Veja 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.

EventoQuando
boleto.charge.beneficiary.approvedO cadastro (ou a reativação) foi confirmado. A conta já pode emitir.
boleto.charge.beneficiary.rejectedO liquidante recusou uma operação. operation diz qual: INCLUSION, UPDATE, STATUS_UPDATE ou TERMINATION. rejectionCode e rejectionReason dizem por quê.
boleto.charge.beneficiary.updatedAtualização cadastral (UPDATE) ou de elegibilidade (STATUS_UPDATE, com previousStatus e currentStatus) aplicada.
boleto.charge.beneficiary.closedRelacionamento 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):

CotaPadrãoConfiguração
Tenant100 emissões/mêsboletoCharge.maxIssuesPerMonth na policy do tenant
Conta PF5 emissões/mêspolicy da conta
Conta PJ10 emissões/mêspolicy 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.

CampoObrigatórioO que é
identifierSimIdempotência desta conta. Único por conta; não há fallback para header.
dueDateSimVencimento, YYYY-MM-DD. Não pode ser anterior a issueDate.
issueDateNãoData de emissão, YYYY-MM-DD.
amount.nominalSimValor de face, maior que zero.
amount.currencyNãoBRL.
payer.nameSimNome do pagador.
payer.personTypeSimperson ou company.
payer.taxNumberSimCPF se person, CNPJ se company. Só dígitos.
payer.emailNãoE-mail do pagador.
payer.addressStreet, addressNumber, addressComplement, addressDistrict, addressCity, addressState, addressZipCodeNãoEndereço do pagador. CEP com 8 dígitos.
interestNãoJuros após o vencimento. startDate tem de ser posterior a dueDate.
fineNãoMulta após o vencimento. Mesma regra de startDate.
discountNãoDesconto por antecipação. Cada groups[].limitDate tem de ser anterior a dueDate.
abatement.amountNãoAbatimento fixo, não negativo. Somado aos descontos, não pode atingir amount.nominal.
allowPartialPaymentNãoAceita pagamento menor que o valor.
allowDivergentPaymentNãoAceita valor diferente do nominal, dentro de minPaymentAmount e maxPaymentAmount.
divergentPaymentModeNãoanyValue, minMax ou minOnly.
expirationPolicy.allowPaymentAfterDueDateNãoSe o título pode ser pago depois do vencimento.
expirationPolicy.paymentLimitDateNã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.blockPaymentAfterLimitNãoRecusa pagamento depois de paymentLimitDate.
expirationPolicy.decursoGraceDaysNãoDias 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.

EncargotypeKey aceitos
interestexempt, 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
fineexempt, 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

CampoO que é
chargeIdId do boleto no liquidante. É o que vai na URL de consulta e nos webhooks.
identifierO seu.
barcodeCódigo de barras, 44 dígitos, quando o liquidante já devolveu.
digitableLineLinha digitável.
ourNumberNosso número.
statusOPEN, SETTLED, OVERDUE, WRITTEN_OFF, CANCELLED, EXPIRED. OVERDUE não encerra o boleto.
statusReasonMotivo, quando o liquidante manda: termExpiration, settlement, manualWriteOff, cancellation, other.
registrationConditionPENDING aguardando a base centralizada, REGISTERED, REJECTED.
dueDate, paymentLimitDateDatas YYYY-MM-DD.
amount.nominalValor de face.
amount.updatedAmountValor atualizado, se o liquidante já calculou juros, multa e desconto.
amount.currencyBRL.
payer.name, payer.taxNumber, payer.personTypeQuem deve pagar.
payment.amount, payment.settledAtPreenchidos 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:

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 é:

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.