Cobranças (Invoices)

A Banking API expõe a emissão e a gestão de faturas (Pix, boleto registrado ou híbrido) da conta. O contrato é o de invoice — um título da conta, com pagador cadastrado e, se houver boleto, registro na Núclea.

Não confundir com a API de Contas (/api/v2/invoices) nem com a API de QR Codes. Aqui os paths ficam sob /accounts/{accountId}/invoices.

Referência OpenAPI: API Reference.

Pré-requisitos

• mTLS e token OAuth (POST /auth/token). Veja Authentication & mTLS.
• IP da origem na allow-list da credencial.
• Scopes:
  • invoices.read — listar e detalhar
  • invoices.write — criar, emitir e cancelar
• customerId de um pagador já cadastrado na conta (Finance ou API de Contas).
• Para Pix: chave Pix da própria conta em pixKey.
• Para boleto: cobrança por boleto habilitada na conta. Se ainda não houver beneficiário PCR, o backend provisiona o cadastro automaticamente.

Credencial	Quem opera
ACCOUNT	somente a própria conta do token
BAAS	contas do BaaS vinculado (exceto a conta da própria credencial)

Acesso fora do vínculo retorna 403.

Métodos de pagamento

paymentMethod	Valor	Comportamento
Pix	PIX (padrão)	QR Code (copia-e-cola) disponível imediatamente
Boleto registrado	BOLETO	Título na câmara (PCR/Núclea); pagável após a confirmação do registro
Híbrido	PIX_BOLETO	Pix + boleto no mesmo artefato; o primeiro método pago liquida e o outro é cancelado

pixKey é obrigatória quando o método inclui Pix (PIX ou PIX_BOLETO).

Ciclo de vida

DRAFT ──(emit)──► REGISTERING ──(registro confirmado)──► PENDING ──► COMPLETED
  │                    │                                    │
  │                    └──(registro rejeitado)──► FAILED    ├──► OVERDUE ──► COMPLETED
  └──(cancel)──► CANCELED                                   └──(cancel)──► CANCELED

• REGISTERING (só métodos com boleto): o título foi gerado localmente e aguarda confirmação na câmara. boletoBarcode e boletoDigitableLine já vêm preenchidos. O boleto só é pagável após a confirmação (PENDING). No híbrido, o QR Pix já é pagável.
• PENDING: cobrança pagável. Boleto tem código de barras e linha digitável.
• FAILED: recusa PCR. Código de barras não é exposto.
• COMPLETED: paga. No híbrido, o método vencedor liquida e o remanescente é cancelado automaticamente.
• Faturas IMMEDIATE nascem em PENDING/REGISTERING. SCHEDULED com vencimento futuro nascem DRAFT e são emitidas na data (ou via POST .../emit).

Endpoints

Método	Path	Scope	Descrição
POST	/accounts/{accountId}/invoices	invoices.write	Criar
GET	/accounts/{accountId}/invoices	invoices.read	Listar
GET	/accounts/{accountId}/invoices/{invoiceId}	invoices.read	Detalhe
POST	/accounts/{accountId}/invoices/{invoiceId}/emit	invoices.write	Emitir rascunho
DELETE	/accounts/{accountId}/invoices/{invoiceId}	invoices.write	Cancelar

Idempotency-Key é obrigatório na criação (até 160 caracteres). Replay com o mesmo payload devolve a fatura original; payload diferente retorna 409.

Criar fatura

curl -X POST "https://api.bancodigital.com/accounts/123/invoices" \
  --cert client.pem --key client.key \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: invoice-erp-202608-000123" \
  -d '{
    "customerId": 123,
    "paymentMethod": "BOLETO",
    "type": "SCHEDULED",
    "amount": 150.5,
    "dueDate": "2026-08-15",
    "daysToPay": 5,
    "description": "Mensalidade agosto",
    "interest": { "type": 2, "amount": 1.0 },
    "lateFee": { "type": 2, "amount": 2.0 },
    "sendEmail": true,
    "emailTo": "[email protected]"
  }'

Resposta 201 com a fatura (id, status, txId, brCode, boletoBarcode, boletoDigitableLine).

Campo	Obrigatório	Descrição
customerId	Sim	Id do pagador da conta
paymentMethod	Não	PIX (padrão), BOLETO ou PIX_BOLETO
pixKey	Se o método inclui Pix	Chave Pix da conta recebedora
dueDate	Sim	Vencimento YYYY-MM-DD
daysToPay	Não	Validade após o vencimento. Padrão 0
amount	Sim	Valor positivo em reais
type	Sim	IMMEDIATE ou SCHEDULED
description	Não	Até 255 caracteres
emailTo	Não	Destinatário do e-mail da cobrança
sendEmail	Não	Enviar e-mail ao criar/emitir. Padrão false
interest	Não	Juros (ignorado em IMMEDIATE)
lateFee	Não	Multa (ignorada em IMMEDIATE)
discount	Não	Desconto

Juros, multa e desconto seguem as modalidades do módulo de invoices (dias corridos). Modalidades em dias úteis não são suportadas para boleto (422).

Listar e detalhar

curl -X GET "https://api.bancodigital.com/accounts/123/invoices?page=1&perPage=20" \
  --cert client.pem --key client.key \
  -H "Authorization: Bearer SEU_TOKEN"

curl -X GET "https://api.bancodigital.com/accounts/123/invoices/42" \
  --cert client.pem --key client.key \
  -H "Authorization: Bearer SEU_TOKEN"

filter busca por descrição ou nome do pagador. Use o detalhe para acompanhar status e obter os dados de pagamento. Para boleto em REGISTERING, código de barras e linha digitável já vêm preenchidos (código local). Recusa PCR (FAILED) oculta o código.

Emitir rascunho

curl -X POST "https://api.bancodigital.com/accounts/123/invoices/42/emit" \
  --cert client.pem --key client.key \
  -H "Authorization: Bearer SEU_TOKEN"

Emite uma fatura DRAFT (gera a cobrança Pix e/ou registra o boleto). A emissão de boleto é idempotente: retries não geram título duplicado.

Cancelar

curl -X DELETE "https://api.bancodigital.com/accounts/123/invoices/42" \
  --cert client.pem --key client.key \
  -H "Authorization: Bearer SEU_TOKEN"

• Boleto: comanda a baixa por instrução na câmara antes do cancelamento local.
• REGISTERING: cancelamento bloqueado até a confirmação do registro (422).
• Fatura já paga (COMPLETED): não pode ser cancelada (409/422).

Webhooks

Cadastre um webhook do tipo INVOICE na gestão de webhooks da conta. Eventos publicados:

Evento	Quando
invoice.registered	Registro do boleto confirmado na câmara (fatura pagável)
invoice.paid	Fatura liquidada (qualquer método)
invoice.settled	Repasse do boleto efetivado na conta (somente quando o boleto foi o método pagador)
invoice.cancelled	Fatura cancelada (manual ou automático)
invoice.overdue	Fatura vencida

Payload: type, data.invoiceId, txId, status, paymentMethod, amount, dueDate, description e customer (documento mascarado). A entrega tem deduplicação por evento — cada evento de cada fatura é notificado uma única vez.

Trate os webhooks como sinal e confirme o estado pelo detalhe (GET /accounts/{accountId}/invoices/{invoiceId}).

Híbrido (PIX_BOLETO)

• A fatura nasce REGISTERING com o QR Pix já pagável; o boleto fica pagável na confirmação do registro.
• O primeiro método pago liquida a fatura (COMPLETED + invoice.paid); o método restante é cancelado automaticamente.
• Pagamentos quase simultâneos pelos dois métodos: o segundo pagamento não altera o estado da fatura e entra em tratamento de devolução.

Erros

Respostas de erro usam RFC 7807 (application/problem+json).

HTTP	Quando
400	Payload inválido (ex.: pixKey ausente com método Pix)
401	Token ausente ou inválido
403	Escopo ausente ou conta fora do vínculo da credencial
404	Fatura inexistente na conta
409	Replay de Idempotency-Key com payload diferente; fatura já paga
422	Regra de negócio (boleto não habilitado, estado inválido, modalidade de juros/multa)
503	Indisponibilidade temporária do serviço de cobranças