14 de abril de 2026 Atualização de documentação Revisão recomendadaDocumentation Index
Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
Use this file to discover all available pages before exploring further.
Afeta
Times usando billing packages ou billing calculation do Fees Engine. Esta atualização se aplica ao portal público de documentação. Não altera 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 introduz documentação abrangente para duas novas capacidades do Fees Engine: Billing Packages e Billing Calculation. Esses recursos permitem que você configure modelos de cobrança recorrente — baseados em volume e em manutenção — e calcule cobranças automaticamente a partir da atividade do ledger.
Billing Packages: cobrança por volume e por manutenção
Os Billing Packages permitem definir como sua plataforma cobra dos clientes pelo uso. O Fees Engine agora suporta dois tipos de cobrança:
- Volume billing — cobranças baseadas em contagem de transações dentro de um período, com suporte a precificação em faixas (tiered), cotas gratuitas e faixas de desconto
- Maintenance billing — cobranças baseadas no número de contas ativas em um segmento ou portfólio
Novidades
- Nova Billing Packages API reference — endpoints CRUD completos para criar, listar, recuperar, atualizar e excluir billing packages
- Novo endpoint de Billing Calculation — POST /v1/billing/calculate calcula cobranças para um ledger e período
- Nova página Billing Package Examples com quatro cenários reais: precificação tiered de boleto, cobrança por volume de Pix com faixas de desconto, cobrança por manutenção de conta e cobrança combinada de volume + manutenção
- Atualizada Fees Engine Overview com conceitos de billing package, formato de período (ISO 8601 YYYY-MM e YYYY-Www) e regras de validação
- Atualizado guia de Fee Calculation com o fluxo de cálculo de cobrança: freeQuota → tiers → discountTiers, semântica do countMode (perRoute vs perAccount), comportamento all-or-nothing e metadados de auditoria
- Atualizado Using Fees Engine com o workflow de configuração de billing package
- Atualizado Best Practices com orientações específicas de cobrança sobre escolha de período, isenções por segmento e estratégia de faixas de desconto
Por que importa
Se você está construindo uma plataforma que precisa cobrar clientes com base em volume de transações ou contas ativas, os Billing Packages oferecem uma forma declarativa de definir modelos de precificação — incluindo precificação tiered com aplicação automática de desconto. O endpoint de cálculo retorna um transactionPayload pronto para executar, que você pode enviar diretamente ao Ledger, mantendo a cobrança totalmente integrada aos seus registros financeiros.Catálogo de erros atualizado
A Fees Engine Error List foi expandida com 19 novos códigos de erro (FEE-0052 até 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, thresholds 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)
Spec 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 — Create a billing package
- GET /v1/billing-packages — List billing packages
- GET /v1/billing-packages/ — Retrieve a billing package
- PATCH /v1/billing-packages/ — Update a billing package
- DELETE /v1/billing-packages/ — Delete a billing package
- POST /v1/billing/calculate — Calculate billing for a ledger and period
Impacto
Esta é uma atualização de documentação. Integrações existentes não precisam migrar apenas com base nesta release note.