FAQ

APIs de Lerian

Esta sección responde preguntas comunes sobre las APIs de Lerian.

¿Hay un número máximo de registros por página en los listados de la API? ¿Puedo aumentar este límite?

Sí. En Midaz, el máximo predeterminado es 100 registros por página. Este límite mantiene el rendimiento constante y controla el volumen de datos en cada solicitud. Para aumentarlo, define la variable de entorno MAX_PAGINATION_LIMIT en la configuración de tu despliegue. La mayoría de los listados acepta tamaños de página mayores después de que reinicies la aplicación.Importante: un tamaño de página mayor puede hacer más lentos los tiempos de respuesta, sobre todo con volúmenes de datos grandes. Prueba en staging antes de cambiar producción.

Tenants en Lerian Cloud

Estas preguntas cubren el aislamiento de datos y el alcance del tenant en Lerian Cloud.

¿Mis datos están aislados de otras instituciones en SaaS?

Sí. Tus datos están aislados de todos los demás tenants, con sus propias credenciales. La plataforma resuelve tu tenant a partir del JWT en cada solicitud. No hay forma de acceder a los datos de otro tenant a través de la API.

¿Necesito enviar un ID de tenant en mis solicitudes a la API?

No. El token de acceso JWT que recibes durante la autenticación lleva el contexto de tu tenant. La plataforma lo resuelve automáticamente. No necesitas incluir un identificador de tenant en los headers ni en los cuerpos de las solicitudes.

¿Puedo tener varias Organizations bajo un mismo tenant?

Sí. Un tenant puede contener varias Organizations. Cada Organization tiene sus propios Ledgers, cuentas y transacciones. La plataforma delimita todas ellas a tu tenant automáticamente.

¿La API es diferente entre los despliegues SaaS y self-hosted?

No. La superficie de la API es idéntica: los mismos endpoints, los mismos payloads, las mismas respuestas. SaaS exige autenticación en cada solicitud, y tu token delimita todas las operaciones a tu tenant.

Midaz

Estas preguntas cubren Organizations, Ledgers, Accounts, Transactions y más en Midaz.

Organizations

¿Las diferentes Organizations se comunican entre sí?

Cada Organization opera de forma independiente. Una transacción cross-ledger puede mover valor entre Ledgers de distintas Organizations en el mismo tenant.

¿Puedo usar una sola licencia en varias Organizations?

Consulta La licencia de Lerian para saber cómo se aplica cada licencia a las Organizations.

¿Una Organization puede tener varios Plugins?

Sí. Una Organization puede tener más de un Plugin.

¿Una Organization puede tener varios Ledgers?

Sí. Una Organization puede administrar varios Ledgers.

¿Puedo crear transacciones entre una Organization padre y una Organization hija?

Puedes crear una Organization padre y una Organization hija. Cada Organization conserva su propio Ledger y opera de forma independiente. Para mover valor entre sus Ledgers, envía una transacción cross-ledger. Cada Ledger participante debe definir settings.crossLedger.enabled como true, y ninguno puede tener accounting.validateRoutes definido como true. También puedes orquestar la transferencia con estos pasos:

En el ledger de origen, crea una transacción desde la cuenta original (origen) hacia la cuenta externa del asset (distribuir). Esto retira el valor del ledger de origen.

En el ledger de destino, crea una segunda transacción. El origen ahora es la cuenta externa del asset, y el destino es la cuenta receptora (distribuir).

Este patrón mueve valor entre ledgers de diferentes Organizations.

Ledgers

¿Los diferentes Ledgers se comunican entre sí?

Los Ledgers llevan libros separados. Una transacción cross-ledger mueve valor entre Ledgers que definen settings.crossLedger.enabled como true.

¿Cómo puedo hacer transacciones entre Ledgers?

Envía una solicitud POST /v2/transactions/direct o POST /v2/transactions/hold con tramos en cada Ledger. Cada Ledger participante debe definir settings.crossLedger.enabled como true. Midaz crea una transacción balanceada por Ledger. También puedes mover el monto a través de una External Account en dos pasos:

Ledger A -> External Account.

External Account -> Ledger B.

¿Necesito un Ledger separado para cada Plugin?

No. Un solo Ledger puede admitir varios Plugins. Por ejemplo, un Ledger puede manejar tanto el Plugin de Exchange como el de Pix.

Assets

¿Un Asset puede vincularse a varias Accounts?

Sí. Muchas Accounts pueden usar el mismo Asset. Cada Asset también se vincula a una External Account. Midaz crea esa External Account automáticamente cuando creas el Asset.

¿Qué tipos de Assets puedo usar?

Midaz admite varios tipos de Assets:

currency: monedas fiduciarias tradicionales como BRL, USD y EUR.
fiat: un tipo alternativo para monedas fiduciarias; al igual que currency, el código del Asset debe seguir la norma ISO 4217.
crypto: activos digitales como BTC, ETH y otras criptomonedas.
commodity: bienes tangibles como oro, soja y petróleo.
others: Assets personalizados, incluidos puntos de fidelidad y valores tokenizados.

Portfolios

¿Cómo funciona un Portfolio?

Un Portfolio agrupa cuentas que pertenecen a la misma entidad (CPF/CNPJ). Por ejemplo, un CPF con dos valores diferentes de segmentId tiene dos cuentas correspondientes. Creas un Portfolio para ese CPF para vincular ambas cuentas bajo una sola estructura.

Accounts

¿Una Account puede asociarse con varios Assets?

No. Cada Account se vincula a un solo Asset. No puedes cambiar este vínculo.

¿Qué es una External Account?

Una External Account recibe fondos desde fuera del Ledger. Trae dinero hacia el sistema.

¿Cómo puedo crear una External Account?

Midaz crea una External Account automáticamente cuando creas un Asset. También puedes crear una tú mismo: envía type como external con un alias.

¿Una Account puede vincularse a varios Segments?

No. Cada account se vincula a un solo Segment (segmentId).

¿Hay un límite de cuántas Accounts puedo crear en Midaz?

No. Puedes crear tantas Accounts como necesites. Midaz no establece ningún límite en el número de Accounts.

¿Cuál es el proceso para agregar fondos a una cuenta o hacer un cash-in usando dinero que proviene de fuera del entorno del Ledger (Midaz)?

El proceso de recarga de saldo funciona así:

Cuando creas un Asset (por ejemplo, BRL) en el Ledger de Midaz, Midaz también crea una External Account para ese Asset.
Esta External Account refleja los saldos que la institución mantiene fuera de Midaz. Esos saldos pueden estar en una cuenta PI, una cuenta de liquidación, una cuenta de reservas o una cuenta bancaria o de pago tradicional.
Para depositar fondos desde fuera del Ledger de Midaz hacia una cuenta de usuario, sigue estos pasos:
- Crea una transacción con la External Account como origen y las cuentas objetivo como destino.
- Midaz debita la External Account por el monto y acredita las cuentas destino por los valores del payload de la transacción.

Transactions

¿Cuál es la estructura mínima de una Transaction?

Una transferencia directa de R$ 100 de la Cuenta A a la Cuenta B tiene dos operaciones:

Operación 1: debitar R$ 100 de la Cuenta A.
Operación 2: acreditar R$ 100 a la Cuenta B.

¿Es posible generar un recibo de transferencia en PDF con los detalles de una transacción completada?

Lerian ofrece a las instituciones varias formas de acceder a los recibos de transacción:

Mediante las APIs: recupera los datos de la transacción a través de las APIs y luego genera un recibo visual en el formato que elijas.
Con el Reporter: extrae los datos de la transacción y crea recibos visuales personalizados.
A través de la Console: accede a los datos de la transacción directamente en la Console de Lerian.

Entities

¿Cómo puedo crear una Entity?

El campo entityId acepta IDs externos de hasta 256 caracteres. Midaz no valida su formato. Puedes usar los IDs que ya existen en tu base de datos e integrarlos en tu sistema.

Idempotencia

¿Puedo reutilizar una clave de idempotencia en varios endpoints?

No. Delimita cada clave a una sola operación y endpoint.

¿Qué sucede si cambio el TTL en un reintento?

Midaz usa solo el TTL de la primera solicitud. Un cambio posterior no tiene ningún efecto.

¿La respuesta repetida siempre será idéntica?

Sí. Para una solicitud completada, Midaz devuelve el mismo resultado que almacenó de la primera solicitud. También establece el header X-Idempotency-Replayed en true.

¿Cuál es el TTL predeterminado si no envío X-TTL?

El TTL predeterminado es 300 segundos (5 minutos). Envía el header X-TTL para establecer un valor personalizado en segundos.

Contabilidad en Midaz

¿Cómo puedo reflejar mi propio Chart of Accounts en Midaz?

Midaz permite reflejar en la plataforma el Chart of Accounts oficial de tu organización. Configuras dos funciones principales:

Account Types: crea las categorías lógicas a partir de tu plan de cuentas, como Activos, Pasivos, Ingresos y Gastos. Asígnalas a las cuentas de tu ledger. Cuando habilitas la validación de tipo de cuenta (validateAccountType), el campo type en la API de Accounts debe coincidir con un valor registrado.
Accounting Routes: usa Operation Routes para validar cada tramo de una transacción. Por ejemplo, un débito debe provenir de una cuenta del tipo user_wallet. Usa Accounting Routes (el recurso transactionRoute en la API) para definir patrones de transacción completos que coincidan con tu lógica contable.

Account Types y Accounting Routes en conjunto aplican tus reglas contables en el nivel del ledger. Midaz valida cada transacción frente a tu Chart of Accounts cuando habilitas la validación de rutas (validateRoutes). No necesitas codificar reglas de forma fija en tu lógica de negocio.

Plugins

Los Plugins extienden Midaz con integración y orquestación de procesos. Aportan abstracciones para que puedas enfocarte en tu modelo de negocio en lugar de en la lógica de sistemas fuera de tu dominio. Las siguientes preguntas cubren cómo funcionan los plugins, cómo los despliegas y las opciones disponibles.

¿Qué son los Plugins?

Los Plugins son tecnologías que se integran en el ledger de Midaz. Simplifican la integración y orquestación de procesos. Aportan abstracciones para que las instituciones puedan enfocarse en su modelo de negocio. Las instituciones no construyen ni administran lógica de sistemas fuera de su dominio.

¿Cómo se distribuyen los plugins?

Después de que contratas un plugin, Lerian te lo provee. En el modelo BYOC, el plugin se ejecuta en tu infraestructura, junto a tu instancia de Midaz. Las aplicaciones se conectan a cada plugin según su función.

¿Qué opciones de plugins ofrece Lerian?

Lerian ofrece dos tipos de plugins, agrupados por origen:

Native Plugins: Lerian desarrolla e integra estos plugins en el ledger de Midaz. Lerian les da soporte completo.
Marketplace Plugins: los socios de Lerian crean estos plugins para nichos de mercado específicos. Lerian ayuda a integrarlos en Midaz. Los socios los proveen y les dan soporte directamente.

Fees Engine

Estas preguntas cubren Fees Engine. Fees Engine es una capacidad licenciada de Midaz que corre dentro del proceso unificado del ledger.

Conceptos generales

¿Qué es Fees Engine?

Fees Engine es parte de Midaz. Corre en el proceso del ledger de Midaz para calcular las comisiones de las transacciones financieras. Se configura y despliega junto con Midaz. Obtén más información en Fees Engine overview. Trabaja en cuatro dominios principales:

Fee Packages (/v2/organizations/{organization_id}/ledgers/{ledger_id}/packages): define las reglas de cobro por transacción (comisión fija, porcentaje, o el mayor entre ambos).
Billing Packages (/v2/organizations/{organization_id}/ledgers/{ledger_id}/billing-packages): define cobros periódicos basados en el volumen de transacciones o el mantenimiento de cuentas.
Planes de tarifas (/v2/organizations/{organization_id}/ledgers/{ledger_id}/account-plans): define comisiones que asignas a cuentas, con una cuota gratuita por mes calendario. Consulta Planes de tarifas.
Cálculo y estimación: el Ledger evalúa las comisiones durante el flujo de la transacción. Usa POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/estimates para una vista previa específica de un package y POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing/calculate para la facturación periódica.

¿Cómo encaja Fees Engine en el ecosistema de Lerian?

Fees Engine corre dentro del proceso del ledger de Midaz. Cuando se aplica un fee package configurado, Midaz incorpora sus cálculos de comisión en la transacción. Usa casos de uso de consulta del ledger en lugar de una conexión HTTP externa hacia Midaz.

¿Qué necesito enviar en cada solicitud a Fees Engine?

Los endpoints de Fees se delimitan por organización a través del ID de la organización en la ruta de la URL /v2. La plataforma resuelve el contexto del tenant a partir de la solicitud autenticada; envía el material de autorización que exija la configuración de tu Access Manager.

Authorization: Bearer ***

¿Qué base de datos usa Fees Engine para el almacenamiento?

Fees Engine usa MongoDB para el almacenamiento. Las eliminaciones siguen el patrón de soft-delete. Fees Engine no elimina los registros físicamente. En su lugar, los marca con deletedAt. Un registro eliminado no aparece en los listados, pero aún puedes auditarlo.

¿Qué versión de Midaz ofrece el módulo integrado de Fees?

Midaz v4 expone Fees dentro del Ledger unificado en /v2.

Fee Packages

¿Qué es un Fee Package?

Un Fee Package (Package) es un conjunto de reglas de cobro bajo un mismo feeGroupLabel. Cada package se vincula a una Organization + Ledger, y opcionalmente a un Segment. Un package puede contener varias comisiones (objetos Fee), cada una con su propia lógica de cálculo. Obtén más información sobre Fee Packages.

¿Cómo creo un Fee Package?

Envía un POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/packages con el siguiente cuerpo. Consulta la referencia de la API Create Package para ver todos los detalles.

{
  "feeGroupLabel": "Digital Account Fees",
  "segmentId": "{segment_id}",
  "minimumAmount": "100.00",
  "maximumAmount": "50000.00",
  "transactionRoute": "{transaction_route_id}",
  "enable": true,
  "waivedAccounts": ["exempt-account-1", "exempt-account-2"],
  "fees": {
    "adminFee": {
      "feeLabel": "Administrative Fee",
      "calculationModel": {
        "applicationRule": "percentual",
        "calculations": [
          { "type": "percentage", "value": "1.50" }
        ]
      },
      "referenceAmount": "originalAmount",
      "priority": 1,
      "isDeductibleFrom": true,
      "creditAccount": "fee-revenue-account"
    }
  }
}

¿Un package puede deshabilitarse temporalmente?

Sí. Establece el campo enable en false cuando creas o actualizas el package. Fees Engine omite un package deshabilitado durante el cálculo de comisiones, incluso cuando el contexto de la transacción coincide con su alcance.

¿Cómo funciona el alcance del package (minimumAmount / maximumAmount)?

Fees Engine aplica el package solo a transacciones cuyo valor esté dentro del rango [minimumAmount, maximumAmount]. Si el valor de la transacción queda fuera de ese rango, Fees Engine ignora el package.Ejemplo: un package con minimumAmount: 100 y maximumAmount: 5000 cobra comisiones solo en transacciones entre 100 y 5,000.

¿Puedo filtrar un package por ruta de transacción?

Sí. Establece el campo transactionRoute con el ID de una ruta de transacción. Fees Engine entonces considera el package solo para transacciones que llevan ese routeId.

¿Qué son los waivedAccounts?

Son alias de cuenta que el package exime de comisiones. Cuando todas las cuentas de origen de una transacción están en waivedAccounts, Fees Engine no aplica las comisiones del package. Una cuenta exenta no paga comisiones del package.

"waivedAccounts": ["vip-account", "employee-account"]

Este package no cobra a estas cuentas.

¿Los endpoints de listado tienen paginación?

Sí. Los endpoints de listado (GET /v2/organizations/{organization_id}/ledgers/{ledger_id}/packages, GET /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing-packages) admiten los parámetros de consulta limit y page para la paginación.

GET /v2/organizations/{organization_id}/ledgers/{ledger_id}/packages?limit=20&page=2

Modelos de cálculo

¿Qué modelos de cálculo hay disponibles?

El campo applicationRule dentro de calculationModel define cómo calcula Fees Engine la comisión. Consulta Calculation Models para ver todos los detalles. Hay tres opciones:

Regla	Descripción
`flatFee`	Comisión de monto fijo
`percentual`	Comisión porcentual basada en el monto de referencia
`maxBetweenTypes`	Evalúa 2 o más cálculos; aplica el resultado mayor

¿Cómo configuro una comisión fija (flatFee)?

Usa exactamente 1 cálculo de tipo flat:

"calculationModel": {
  "applicationRule": "flatFee",
  "calculations": [
    { "type": "flat", "value": "5.00" }
  ]
}

Esto cobra un monto fijo de 5.00 sin importar el monto de la transacción.

¿Cómo configuro una comisión porcentual (percentual)?

Usa exactamente 1 cálculo de tipo percentage:

"calculationModel": {
  "applicationRule": "percentual",
  "calculations": [
    { "type": "percentage", "value": "2.50" }
  ]
}

Esto cobra el 2.5% del monto de referencia de la transacción.

¿Cómo funciona maxBetweenTypes?

maxBetweenTypes requiere 2 o más cálculos. Fees Engine calcula cada uno y aplica el resultado mayor.Ejemplo: comisión mínima de 3.00 o 1% del valor, lo que sea mayor:

"calculationModel": {
  "applicationRule": "maxBetweenTypes",
  "calculations": [
    { "type": "flat", "value": "3.00" },
    { "type": "percentage", "value": "1.00" }
  ]
}

Para una transacción de 200: 1% = 2.00 frente a 3.00 fijo → cobra 3.00. Para una transacción de 500: 1% = 5.00 frente a 3.00 fijo → cobra 5.00.

¿Puedo mezclar varios porcentajes en maxBetweenTypes?

Sí. Puedes incluir cualquier combinación de flat y percentage. Fees Engine evalúa todos y aplica el mayor. flatFee y percentual requieren exactamente 1 cálculo. Solo maxBetweenTypes acepta 2 o más.

Campos importantes

¿Qué es referenceAmount y cómo afecta el cálculo?

El referenceAmount define sobre qué valor Fees Engine calcula la comisión:

originalAmount: el valor original de la transacción, antes de cualquier comisión.
afterFeesAmount: el valor de la transacción después de que se apliquen comisiones de mayor prioridad.

La comisión con priority: 1 se ejecuta primero, así que debe usar originalAmount. No existen comisiones previas que considerar.

¿Qué es isDeductibleFrom y cuándo se recomienda usarlo?

Cuando isDeductibleFrom: true, Fees Engine deduce la comisión del monto que envía el remitente. El destinatario recibe el monto con el descuento aplicado.Cuando es false, Fees Engine cobra la comisión por separado. El remitente envía el monto completo, y Fees Engine debita la comisión aparte.Restricciones:

isDeductibleFrom: true requiere referenceAmount: originalAmount
Si el tipo es percentage: el valor no puede superar 100
Si el tipo es flat: el valor no puede superar el minimumAmount del package

¿Cómo funciona el campo priority?

El priority define el orden de ejecución de las comisiones dentro de un package. Fees Engine ejecuta primero los valores más bajos.

priority: 1 → se ejecuta primero (debe usar originalAmount)
priority: 2 → se ejecuta después, puede usar afterFeesAmount

Usa las prioridades para encadenar comisiones. Por ejemplo, ejecuta una comisión administrativa sobre el monto original. Luego ejecuta una comisión de IOF sobre el monto que queda después de la comisión administrativa.

¿Qué es creditAccount?

Es el alias de la cuenta del ledger que recibe el ingreso de la comisión. Cada comisión puede tener un creditAccount diferente. Esto ayuda cuando distintas comisiones pertenecen a distintos centros de costo.

"creditAccount": "admin-fee-revenue-account"

¿Qué son routeFrom y routeTo dentro de una comisión?

Estos campos definen las rutas de los tramos contables que genera el cobro de la comisión. Son opcionales. Permiten rastrear el origen y el destino de los movimientos de comisión en el ledger.

Billing Packages

¿Qué son los Billing Packages?

Los Billing Packages son packages de cobro periódico, independientes del cálculo de comisiones por transacción. Consulta Billing Package examples para ver casos de uso. Hay dos tipos:

volume: cobra según el número de transacciones en un período, con precios escalonados.
maintenance: cobra una comisión fija por cuenta en un alcance dado.

¿Cuándo se recomienda usar volume billing?

Usa volume billing para cobrar a los clientes según el número de transacciones procesadas. Este es un modelo común para plataformas de pago con precios basados en volumen. Defines niveles de precio que se aplican a medida que crece el volumen.

{
  "type": "volume",
  "eventFilter": {
    "transactionRoute": "PIX",
    "status": "approved"
  },
  "pricingModel": "tiered",
  "tiers": [
    { "minQuantity": 0, "maxQuantity": 1000, "unitPrice": "0.50" },
    { "minQuantity": 1001, "unitPrice": "0.30" }
  ],
  "assetCode": "BRL",
  "debitAccountAlias": "client-account",
  "creditAccountAlias": "volume-revenue-account"
}

¿Cuándo se recomienda usar maintenance billing?

Usa maintenance billing para cobrar una comisión periódica fija por cuenta. Por ejemplo, cobra una comisión mensual por cuenta activa. Especificas el alcance (segmentId, portfolioId o aliases) y el monto de la comisión.

{
  "type": "maintenance",
  "feeAmount": "15.00",
  "assetCode": "BRL",
  "maintenanceCreditAccount": "maintenance-revenue-account",
  "accountTarget": {
    "segmentId": "{segment_id}"
  }
}

accountTarget debe tener exactamente uno de los tres campos: segmentId, portfolioId o aliases (máximo 100 aliases).

¿Cómo funcionan los niveles en volume billing?

Los niveles definen el precio unitario por nivel a medida que aumenta el volumen. Las reglas son:

Deben ser contiguos: sin vacíos entre niveles (minQuantity del siguiente = maxQuantity del anterior + 1).
No deben superponerse.
Cuando hay varios niveles, el último debe omitir maxQuantity. Se acepta un único nivel con límite superior. Un conteo facturable positivo fuera de ese nivel hace fallar toda la llamada de cálculo.

Ejemplo de niveles correctos:

"tiers": [
  { "minQuantity": 0, "maxQuantity": 500, "unitPrice": "0.80" },
  { "minQuantity": 501, "maxQuantity": 2000, "unitPrice": "0.60" },
  { "minQuantity": 2001, "unitPrice": "0.40" }
]

¿Qué es freeQuota?

Es una franquicia gratuita. Fees Engine no cobra un número determinado de transacciones antes de que se apliquen los niveles. Esto ayuda a los modelos de precios con un volumen mínimo incluido.Ejemplo: freeQuota: 100 significa que Fees Engine no cobra las primeras 100 transacciones del período.Una comisión de un plan de tarifas tiene su propio freeQuota, contado por cuenta y mes calendario. Consulta Cuota gratuita.

¿Qué son los discountTiers?

Son niveles de descuento para volume billing. Reducen el monto cobrado según criterios adicionales. Complementan la lógica de los tiers principales.

¿Qué es countMode en volume billing?

Define cómo cuenta Fees Engine las transacciones:

perRoute: cuenta las transacciones por ruta (por ejemplo, total de Pix aprobados).
perAccount: cuenta las transacciones por cuenta individual.

Cálculo de comisiones y facturación

¿Cómo se calculan las comisiones de transacción en Midaz v4?

El Ledger evalúa las comisiones en el flujo de la transacción cuando se aplica un package coincidente. Una cuenta de origen con un plan de tarifas activo paga en su lugar las comisiones de su plan. Usa POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/estimates para una vista previa específica de un package.

¿Qué endpoints de v4 configuran las comisiones?

Configura los fee packages de transacción en /v2/organizations/{organization_id}/ledgers/{ledger_id}/packages y los billing packages periódicos en /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing-packages. Configura los planes de tarifas en /v2/organizations/{organization_id}/ledgers/{ledger_id}/account-plans, y asigna uno a una cuenta en /v2/organizations/{organization_id}/ledgers/{ledger_id}/accounts/{account_id}/account-plan.

¿Cómo calculo la facturación periódica?

Llama a POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing/calculate después de configurar los billing packages. Procesa las reglas configuradas para ese Ledger.

Errores comunes

¿Qué significa el error 0188 "originalAmount is required when priority is one"?

La comisión con priority: 1 debe tener referenceAmount: "originalAmount". Es la primera comisión en ejecutarse, así que no existen comisiones previas en las que basar el cálculo.Solución:

{
  "priority": 1,
  "referenceAmount": "originalAmount"
}

¿Cómo corrijo el error 0205 "originalAmount is required when isDeductibleFrom is true"?

Las comisiones con isDeductibleFrom: true solo pueden usar referenceAmount: "originalAmount". Actualiza el campo:

{
  "isDeductibleFrom": true,
  "referenceAmount": "originalAmount"
}

¿Por qué obtengo el error 0208 "calculation value flat invalid"?

Cuando isDeductibleFrom: true y el tipo es flat, el valor de la comisión no puede superar el minimumAmount del package. Esto evita una comisión mayor que el valor mínimo de la transacción.Ejemplo: si minimumAmount: 100, la comisión fija no puede superar 100.

¿Cuándo ocurre el error 0207 "calculation value percentage invalid"?

Este error ocurre cuando isDeductibleFrom: true, el tipo es percentage, y el valor supera 100. Una comisión porcentual deducible del 100% dejaría la transacción en cero. Los valores por encima de 100 no son válidos.

¿Cómo corrijo el error 0218 "tiers have a gap"?

Los niveles de volume billing deben cubrir todos los rangos sin vacíos. Verifica que el minQuantity de cada nivel sea exactamente maxQuantity + 1 del nivel anterior.

// ❌ Wrong — gap between 500 and 600
{ "minQuantity": 0, "maxQuantity": 500, "unitPrice": "0.80" },
{ "minQuantity": 600, "unitPrice": "0.40" }

// ✅ Correct
{ "minQuantity": 0, "maxQuantity": 500, "unitPrice": "0.80" },
{ "minQuantity": 501, "unitPrice": "0.40" }

Error 0229: "Exactly one of segmentId, portfolioId, or aliases must be provided"

En maintenance billing, el campo accountTarget acepta solo una de las tres opciones. No combines campos:

// ❌ Wrong
"accountTarget": {
  "segmentId": "{segment_id}",
  "portfolioId": "{portfolio_id}"
}

// ✅ Correct
"accountTarget": {
  "segmentId": "{segment_id}"
}

¿Hay un límite de aliases en accountTarget?

Sí. El campo aliases acepta un máximo de 100 aliases por Billing Package de maintenance.

Errores 0189 y 0191: flatFee necesita exactamente 1 cálculo de tipo flat

El applicationRule: "flatFee" acepta exactamente 1 cálculo, y debe ser de tipo flat. No uses percentage con flatFee.

// ✅ Correct
"calculationModel": {
  "applicationRule": "flatFee",
  "calculations": [{ "type": "flat", "value": "10.00" }]
}

Errores 0189 y 0190: percentual necesita exactamente 1 cálculo de tipo percentage

Al igual que flatFee, el applicationRule: "percentual" acepta exactamente 1 cálculo de tipo percentage.

Error 0201: "applicationRule maxBetweenTypes must have more than 1 calculation"

maxBetweenTypes requiere al menos 2 cálculos, porque necesita valores para comparar.

¿Qué se recomienda verificar cuando el package no se aplica a la transacción?

Lista de verificación de diagnóstico (consulta también Best Practices):

enable: ¿el package está activo (enable: true)?
Ledger: ¿creaste el package en el ledger de la transacción?
minimumAmount / maximumAmount: ¿el valor de la transacción está dentro del rango?
transactionRoute: si el package tiene transactionRoute, ¿la transacción usa la misma ruta?
segmentId: si el package está delimitado a un segmento, ¿la cuenta pertenece a él?
waivedAccounts: ¿la cuenta está listada como exenta?

¿Se puede recuperar un registro eliminado?

Fees Engine hace soft-delete de los registros. Los marca con deletedAt y no los elimina de la base de datos. La API no tiene un endpoint de restauración. Contacta al equipo de Lerian si necesitas recuperar un registro eliminado.

Midaz Core

CRM

Fees

APIs de Lerian

Tenants en Lerian Cloud

Midaz

Organizations

Ledgers

Assets

Portfolios

Accounts

Transactions

Entities

Idempotencia

Contabilidad en Midaz

Plugins

Fees Engine

Conceptos generales

Fee Packages

Modelos de cálculo

Campos importantes

Billing Packages

Cálculo de comisiones y facturación

Errores comunes

​APIs de Lerian

​Tenants en Lerian Cloud

​Midaz

​Organizations

​Ledgers

​Assets

​Portfolios

​Accounts

​Transactions

​Entities

​Idempotencia

​Contabilidad en Midaz

​Plugins

​Fees Engine

​Conceptos generales

​Fee Packages

​Modelos de cálculo

​Campos importantes

​Billing Packages

​Cálculo de comisiones y facturación

​Errores comunes

APIs de Lerian

Tenants en Lerian Cloud

Midaz

Organizations

Ledgers

Assets

Portfolios

Accounts

Transactions

Entities

Idempotencia

Contabilidad en Midaz

Plugins

Fees Engine

Conceptos generales

Fee Packages

Modelos de cálculo

Campos importantes

Billing Packages

Cálculo de comisiones y facturación

Errores comunes