Billing Packages: facturación por volumen y mantenimiento
Los Billing Packages te permiten definir cómo tu plataforma cobra a los clientes por el uso. El Fees Engine ahora soporta dos tipos de facturación:
- Facturación por volumen — cargos basados en el conteo de transacciones dentro de un período, con soporte para precios escalonados, cuotas gratuitas y niveles de descuento
- Facturación por mantenimiento — cargos basados en el número de cuentas activas en un segmento o portafolio
Qué hay de nuevo
- Nueva Referencia de API de Billing Packages — endpoints CRUD completos para crear, listar, obtener, actualizar y eliminar billing packages
- Nuevo Endpoint de Billing Calculation — POST /v1/billing/calculate calcula los cargos para un ledger y período determinados
- Nueva página de Ejemplos de Billing Packages con cuatro escenarios reales: precios escalonados de boleto, facturación por volumen de Pix con niveles de descuento, facturación por mantenimiento de cuentas, y facturación combinada de volumen + mantenimiento
- Actualizada Descripción general del Fees Engine con conceptos de billing packages, formato de período (ISO 8601 YYYY-MM y YYYY-Www) y reglas de validación
- Actualizada la guía de Fee Calculation con el flujo de cálculo de facturación: freeQuota → tiers → discountTiers, semántica de countMode (perRoute vs perAccount), comportamiento todo-o-nada y metadatos de auditoría
- Actualizado Usando Fees Engine con el flujo de configuración de billing packages
- Actualizadas las Mejores prácticas con orientación específica para facturación sobre selección de períodos, exenciones basadas en segmentos y estrategia de niveles de descuento
Por qué es importante
Si estás construyendo una plataforma que necesita cobrar a los clientes basándose en volumen de transacciones o cuentas activas, los Billing Packages te brindan una forma declarativa de definir modelos de precios —incluyendo precios escalonados con aplicación automática de descuentos. El endpoint de cálculo devuelve un transactionPayload listo para ejecutar que puedes enviar directamente al Ledger, manteniendo la facturación completamente integrada con tus registros financieros.Catálogo de errores actualizado
La Lista de errores del Fees Engine ha sido ampliada con 19 nuevos códigos de error (FEE-0052 a FEE-0070) que cubren validaciones específicas de facturación:
- Campos de billing package faltantes o inválidos (period, type, pricingModel, feeAmount, assetCode)
- Errores de configuración de niveles (niveles superpuestos, umbrales faltantes, porcentajes de descuento inválidos)
- Fallos de cálculo (resolución de segmentos, dependencias de servicios)
- Validación de cuentas objetivo (segmentId, portfolioId o aliases — exactamente uno requerido)
Especificación OpenAPI actualizada a v3.1.0
La especificación OpenAPI del Fees Engine ha sido actualizada de v3.0.0 a v3.1.0, reflejando todos los nuevos endpoints y esquemas:
- POST /v1/billing-packages — Crear un billing package
- GET /v1/billing-packages — Listar billing packages
- GET /v1/billing-packages/ — Obtener un billing package
- PATCH /v1/billing-packages/ — Actualizar un billing package
- DELETE /v1/billing-packages/ — Eliminar un billing package
- POST /v1/billing/calculate — Calcular facturación para un ledger y período