Billing Packages: cobrança por volume e manutenção
Os Billing Packages permitem definir como sua plataforma cobra os clientes pelo uso. O Fees Engine agora suporta dois tipos de cobrança:
- Cobrança por volume — encargos baseados na contagem de transações dentro de um período, com suporte para preços escalonados, cotas gratuitas e faixas de desconto
- Cobrança por manutenção — encargos baseados no número de contas ativas em um segment ou portfolio
O que há de novo
- Nova Referência de API de Billing Packages — endpoints CRUD completos para criar, listar, obter, atualizar e excluir billing packages
- Novo Endpoint de Billing Calculation — POST /v1/billing/calculate calcula os encargos para um ledger e período determinados
- Nova página de Exemplos de Billing Packages com quatro cenários reais: preços escalonados de boleto, 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
- Atualizada Visão geral do Fees Engine com conceitos de billing packages, formato de período (ISO 8601 YYYY-MM e YYYY-Www) e regras de validação
- Atualizado o guia de Fee Calculation 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
- Atualizado Usando o Fees Engine com o fluxo de configuração de billing packages
- Atualizadas as Melhores práticas com orientação específica para cobrança sobre seleção de períodos, isenções baseadas em segments e estratégia de faixas de desconto
Por que isso importa
Se você está construindo uma plataforma que precisa cobrar clientes com base no volume de transações ou contas ativas, os Billing Packages oferecem uma forma declarativa de definir modelos de preços — incluindo preços escalonados com aplicação automática de descontos. O endpoint de cálculo retorna um transactionPayload pronto para executar que você pode enviar diretamente ao Ledger, mantendo a cobrança totalmente integrada com 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 a FEE-0070) cobrindo 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 segments, dependências de serviços)
- Validação de contas alvo (segmentId, portfolioId ou aliases — exatamente um obrigatório)
Especificação OpenAPI atualizada para v3.1.0
A especificação OpenAPI do Fees Engine foi atualizada 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/ — Obter um billing package
- PATCH /v1/billing-packages/ — Atualizar um billing package
- DELETE /v1/billing-packages/ — Excluir um billing package
- POST /v1/billing/calculate — Calcular cobrança para um ledger e período