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.
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.
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.
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.
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.
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.
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):
Não existe modo ilimitado. O saldo efetivo é sempre o menor entre tenant e conta. Consulte ambos em:
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
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.
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.
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
Consultar
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) epageSize(1 a 200, padrão 50). A resposta trazitems,page,pageSize,totalItems,totalPagesehasNext. - Detalhe sempre ao vivo. O GET com
{chargeId}consulta o liquidante em toda chamada, atualiza o espelho e devolve o resultado atual com o novoupdatedAt. 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.
POST /v1/accounts/{accountId}/boleto/charge/batchescria um lote vazio emDRAFT. ExigeIdempotency-Key; o JSON opcional aceitaname(até 120 caracteres).PUT .../batches/{batchId}/itemsadiciona de 1 a 50 pedidos JSON por chamada.DELETE .../batches/{batchId}/items/{itemId}remove um item enquanto o lote ainda está emDRAFT.POST .../batches/{batchId}/dispatchreserva a cota e inicia o processamento assíncrono.GET .../batches/{batchId}?page=1&pageSize=50acompanha estatísticas e resultados item a item.GET .../batcheslista 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:
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.
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 é:
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
- Credenciamento do beneficiário, se ainda não existir (202, alguns minutos).
boleto.charge.beneficiary.approvedou.rejectedavisa o desfecho. - Emissão (202). O título nasce
OPENcom registroPENDING. boleto.charge.registeredouboleto.charge.registration_failed.- Daí:
boleto.charge.settled(também entra no extrato comoBOLETO),overdue,written_off,cancelledouexpired.
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.