Afecta a
Equipos que usan Billing Packages o Billing Calculation de Fees Engine. Esta actualización aplica al portal de documentación pública. No cambia el comportamiento de la API en tiempo de ejecución, salvo que la documentación de producto enlazada indique lo contrario.
Qué cambió
Esta actualización agrega documentación completa de dos capacidades nuevas de Fees Engine: Billing Packages y Billing Calculation. Estas funciones permiten configurar modelos de facturación recurrente — por volumen y por mantenimiento — y calcular cargos automáticamente según la actividad del ledger.
Billing Packages: facturación por volumen y por mantenimiento
Billing Packages permite definir cómo tu plataforma cobra a los clientes por el uso. Fees Engine ahora admite dos tipos de facturación:
- Facturación por volumen — cobros según la cantidad de transacciones dentro de un período, que admite precios por tramos, cuotas gratuitas y tramos de descuento
- Facturación por mantenimiento — cobros según la cantidad de cuentas activas en un segmento o portafolio
Novedades
- Nueva referencia de API de Billing Packages — endpoints CRUD completos para crear, listar, consultar, actualizar y eliminar Billing Packages
- Nuevo endpoint de Billing Calculation — POST /v1/billing/calculate calcula los cargos de un ledger y un período determinados
- Nueva página de ejemplos de Billing Package con cuatro escenarios reales: precios por tramos de boleto, facturación por volumen de Pix con tramos de descuento, facturación por mantenimiento de cuentas y facturación combinada por volumen + mantenimiento
- Actualización de Resumen de Fees Engine con los conceptos de Billing Package, el formato de período (ISO 8601 YYYY-MM y YYYY-Www) y las reglas de validación
- Actualización de la guía Cálculo de comisiones con el flujo de Billing Calculation: freeQuota → tiers → discountTiers, la semántica de countMode (perRoute frente a perAccount), el comportamiento de todo o nada y los metadatos de auditoría
- Actualización de Uso de Fees Engine con el flujo de configuración de Billing Package
- Actualización de Mejores prácticas con orientación específica de facturación sobre la elección del período, las exenciones por segmento y la estrategia de tramos de descuento
Por qué importa
Si construyes una plataforma que necesita cobrar a los clientes según el volumen de transacciones o las cuentas activas, Billing Packages te da una forma declarativa de definir modelos de precios — incluidos los precios por tramos con aplicación automática de descuentos. El endpoint de cálculo devuelve un transactionPayload listo para ejecutar que puedes enviar directamente al Ledger, con lo que la facturación queda integrada por completo con tus registros financieros.Catálogo de errores actualizado
La lista de errores de Fees Engine se amplió con 19 códigos de error nuevos (FEE-0052 a FEE-0070) que cubren validaciones específicas de facturación:
- Campos de Billing Package ausentes o inválidos (period, type, pricingModel, feeAmount, assetCode)
- Errores de configuración de tramos (tramos superpuestos, umbrales ausentes, porcentajes de descuento inválidos)
- Fallas de cálculo (resolución de segmento, dependencias de servicio)
- Validación del destino de la cuenta (segmentId, portfolioId o aliases — exactamente uno obligatorio)
Especificación OpenAPI actualizada a v3.1.0
La especificación OpenAPI de Fees Engine pasó de v3.0.0 a v3.1.0, con todos los endpoints y esquemas nuevos:
- POST /v1/billing-packages — Crear un Billing Package
- GET /v1/billing-packages — Listar Billing Packages
- GET /v1/billing-packages/ — Consultar un Billing Package
- PATCH /v1/billing-packages/ — Actualizar un Billing Package
- DELETE /v1/billing-packages/ — Eliminar un Billing Package
- POST /v1/billing/calculate — Calcular la facturación de un ledger y un período
Impacto
Esta es una actualización de documentación. Las integraciones existentes no necesitan una migración solo por esta nota de versión.
Qué debes hacer
1
Revisa la documentación de Billing Packages y Billing Calculation antes de configurar modelos de facturación recurrente.