Afeta
Equipes que usam os Billing Packages ou o Billing Calculation do Fees Engine. Esta atualização se aplica ao portal público de documentação. Ela não muda o comportamento da API em runtime, a menos que a documentação do produto vinculada diga o contrário.
O que mudou
Esta atualização traz documentação completa para duas novas capacidades do Fees Engine: Billing Packages e Billing Calculation. Esses recursos permitem configurar modelos de cobrança recorrente — por volume e por manutenção — e calcular cobranças automaticamente com base na atividade do ledger.
Billing Packages: cobrança por volume e por manutenção
Os Billing Packages permitem definir como sua plataforma cobra os clientes pelo uso. O Fees Engine agora oferece suporte a dois tipos de cobrança:
- Cobrança por volume — cobranças baseadas na contagem de transações dentro de um período, com suporte a precificação por faixas, cotas gratuitas e faixas de desconto
- Cobrança por manutenção — cobranças baseadas no número de contas ativas em um segmento ou portfólio
O que há de novo
- Nova Referência da API de Billing Packages — endpoints CRUD completos para criar, listar, recuperar, atualizar e excluir billing packages
- Novo endpoint de Billing Calculation — POST /v1/billing/calculate calcula as cobranças de um ledger e período
- Nova página Exemplos de Billing Package com quatro cenários reais: precificação de boleto por faixas, cobrança por volume de Pix com faixas de desconto, cobrança por manutenção de contas e cobrança combinada de volume + manutenção
- Visão geral do Fees Engine atualizada com os conceitos de billing package, o formato de período (ISO 8601 YYYY-MM e YYYY-Www) e as regras de validação
- Guia Cálculo de tarifas atualizado com o fluxo de cálculo de cobrança: freeQuota → tiers → discountTiers, semântica de countMode (perRoute vs perAccount), comportamento tudo-ou-nada e metadados de auditoria
- Usando o Fees Engine atualizado com o workflow de configuração de billing package
- Boas práticas atualizadas com orientações específicas de cobrança sobre seleção de período, isenções por segmento e estratégia de faixas de desconto
Por que isso importa
Se você constrói uma plataforma que precisa cobrar clientes com base no volume de transações ou em contas ativas, os Billing Packages dão uma forma declarativa de definir modelos de precificação — incluindo precificação por faixas com aplicação automática de desconto. O endpoint de cálculo retorna um transactionPayload pronto para executar, que você pode enviar direto ao Ledger, mantendo a cobrança totalmente integrada aos seus registros financeiros.Catálogo de erros atualizado
A Lista de erros do Fees Engine foi ampliada com 19 novos códigos de erro (FEE-0052 até FEE-0070) que cobrem validações específicas de cobrança:
- Campos de billing package ausentes ou inválidos (period, type, pricingModel, feeAmount, assetCode)
- Erros de configuração de faixas (faixas sobrepostas, limites ausentes, percentuais de desconto inválidos)
- Falhas de cálculo (resolução de segmento, dependências de serviço)
- Validação do alvo da conta (segmentId, portfolioId ou aliases — exatamente um é obrigatório)
Especificação OpenAPI atualizada para v3.1.0
A especificação OpenAPI do Fees Engine passou de v3.0.0 para v3.1.0, refletindo todos os novos endpoints e schemas:
- POST /v1/billing-packages — Criar um billing package
- GET /v1/billing-packages — Listar billing packages
- GET /v1/billing-packages/ — Recuperar um billing package
- PATCH /v1/billing-packages/ — Atualizar um billing package
- DELETE /v1/billing-packages/ — Excluir um billing package
- POST /v1/billing/calculate — Calcular a cobrança de um ledger e período
Impacto
Esta é uma atualização de documentação. As integrações existentes não precisam de migração apenas por esta nota de release.
O que você precisa fazer
1
Revise a documentação de Billing Packages e Billing Calculation antes de configurar modelos de cobrança recorrente.