14 de abril de 2026 Actualización de documentación Revisión 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.
Afecta
Equipos que usan los billing packages o el billing calculation de Fees Engine. Esta actualización se aplica al portal de documentación pública. No cambia el comportamiento del API en tiempo de ejecución, salvo que la documentación del producto enlazada indique lo contrario.
Qué cambió
Esta actualización introduce documentación completa para dos nuevas capacidades de Fees Engine: Billing Packages y Billing Calculation. Estas funciones permiten configurar modelos de facturación recurrente — basados en volumen y en mantenimiento — y calcular cargos automáticamente según la actividad del ledger.
Billing Packages: facturación por volumen y mantenimiento
Los Billing Packages permiten definir cómo tu plataforma cobra a los clientes por uso. Fees Engine ahora soporta dos tipos de facturación:
- Facturación por volumen — cobros 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 — cobros basados en la cantidad de cuentas activas en un segmento o portafolio
Qué hay de nuevo
- Nueva Referencia API de Billing Packages — endpoints CRUD completos para crear, listar, recuperar, actualizar y eliminar billing packages
- Nuevo Endpoint de Billing Calculation — POST /v1/billing/calculate calcula los cargos para un ledger y período dados
- Nueva página Billing Package Examples con cuatro escenarios reales: precios escalonados de boleto, facturación por volumen de Pix con niveles de descuento, facturación por mantenimiento de cuenta y facturación combinada por volumen + mantenimiento
- Resumen de Fees Engine actualizado con conceptos de billing package, formato de período (ISO 8601 YYYY-MM y YYYY-Www) y reglas de validación
- Guía de Fee Calculation actualizada con el flujo de billing calculation: freeQuota → tiers → discountTiers, semántica de countMode (perRoute vs perAccount), comportamiento all-or-nothing y metadatos de auditoría
- Usando Fees Engine actualizado con el flujo de configuración de billing packages
- Mejores prácticas actualizadas con guía específica de facturación sobre selección de período, exenciones basadas en segmento y estrategia de niveles de descuento
Por qué importa
Si estás construyendo una plataforma que necesita cobrar a los clientes según el volumen de transacciones o las cuentas activas, los Billing Packages te dan una manera 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 publicar directamente en el Ledger, manteniendo la facturación totalmente integrada con tus registros financieros.Catálogo de errores actualizado
La Lista de errores de Fees Engine se expandió con 19 nuevos códigos de error (FEE-0052 hasta 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 tiers (tiers solapados, umbrales faltantes, porcentajes de descuento inválidos)
- Fallos de cálculo (resolución de segmento, dependencias de servicios)
- Validación de cuenta objetivo (segmentId, portfolioId o aliases — exactamente uno requerido)
Especificación OpenAPI actualizada a v3.1.0
La especificación OpenAPI de Fees Engine se actualizó 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/ — Recuperar 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
Impacto
Esta es una actualización de documentación. Las integraciones existentes no necesitan migración solo por esta nota de versión.