Skip to main content

​
APIs de Lerian

Esta sección responde preguntas comunes sobre las APIs de Lerian.
Sí. 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 API 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.

​
Multi-tenancy y SaaS

Estas preguntas cubren el aislamiento de datos, el alcance del tenant y cómo funciona el multi-tenancy en los despliegues de Lerian.
Sí. Cada tenant opera sobre una base de datos separada. La plataforma resuelve tu tenant a partir del JWT en cada solicitud y la enruta a tu base de datos aislada. No hay forma de acceder a los datos de otro tenant a través de la API. Obtén más información sobre multi-tenancy.
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.
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.
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

No. Cada Organization opera de forma independiente y no se comunica con las demás.
No. Cada licencia se vincula a una Organization. Para admitir varias Organizations, adquiere una licencia separada para cada una. La misma regla se aplica a los Plugins.
Sí. Una Organization puede tener más de un Plugin.
Sí. Una Organization puede administrar varios Ledgers.
Puedes crear una Organization padre y una Organization hija. Cada Organization conserva su propio Ledger y opera de forma independiente. Las transacciones no pueden mover valor directamente entre ledgers. Orquestas la transferencia con estos pasos:
1
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.
2
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

No. Los Ledgers no se comunican directamente. Las transferencias entre Ledgers requieren orquestación.
Debes orquestar el proceso y mover el monto a través de una External Account. Esto implica dos pasos:
1
Ledger A -> External Account.
2
External Account -> Ledger B.
No. Un solo Ledger puede admitir varios Plugins. Por ejemplo, un Ledger puede manejar tanto el Plugin de Exchange como el de Pix.

​
Assets

No. Cada Asset se vincula a una sola Account. Cada Asset también se vincula a una External Account. Midaz crea esa External Account automáticamente cuando creas el Asset.
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.
  • commodities: bienes tangibles como oro, soja y petróleo.
  • others: Assets personalizados, incluidos puntos de fidelidad y valores tokenizados.

​
Portfolios

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

​
Accounts

No. Cada Account se vincula a un solo Asset. No puedes cambiar este vínculo.
Una External Account recibe fondos desde fuera del Ledger. Trae dinero hacia el sistema.
Midaz crea una External Account automáticamente cuando creas un Asset. Esta External Account respalda todas las transacciones que se mueven hacia dentro y fuera del Ledger.
No. Cada account (account_id) se vincula a un solo Segment (segment_id).
No. Puedes crear tantas Accounts como necesites. Midaz no establece ningún límite en el número de Accounts.
El proceso de recarga de saldo funciona así:
  1. Cuando creas un Asset (por ejemplo, BRL) en el Ledger de Midaz, Midaz también crea una External Account para ese Asset.
  2. 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.
  3. 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 (de modo que queda negativa) y acredita las cuentas destino por los valores del payload de la transacción.

​
Transactions

Una Transaction debe tener al menos dos Operations. Por ejemplo, una transferencia 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.
Lerian ofrece a los clientes varias formas de acceder a los recibos de transacción:
  1. 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.
  2. Con el Reporter: extrae los datos de la transacción y crea recibos visuales personalizados.
  3. A través de la Console: accede a los datos de la transacción directamente en la Console de Lerian.

​
Entities

La Entity (entity_id) acepta IDs externos. Midaz no aplica ninguna validación sobre este campo. Puedes usar los IDs que ya existen en tu base de datos e integrarlos en tu sistema.

​
Idempotencia

Midaz trata la solicitud como nueva cada vez. Los reintentos pueden entonces crear operaciones duplicadas.
No. Delimita cada clave a una sola operación y endpoint.
Midaz usa solo el TTL de la primera solicitud. Un cambio posterior no tiene ningún efecto.
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.
El TTL predeterminado es 300 segundos (5 minutos). Envía el header X-TTL para establecer un valor personalizado en segundos.

​
Contabilidad 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 función de Account Types, el campo type en la API de Accounts pasa a ser obligatorio y 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 y clasifica cada transacción frente a tu Chart of Accounts. 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.
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 los clientes puedan enfocarse en su modelo de negocio. Los clientes no construyen ni administran lógica de sistemas fuera de su dominio.
No. Los plugins operan solo con Midaz. Aportan abstracciones específicas y orquestan transacciones según la estructura del ledger.
Después de que contratas un plugin, Lerian lo provee y lo instala en tu infraestructura (modelo on-premise), junto a tu instancia de Midaz. Las aplicaciones se conectan a cada plugin según su función.
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

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 tres 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.
  • 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. Midaz v4 no tiene un endpoint de nivel superior /v2/fees ni /v2/estimates.
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.
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.
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.
Midaz v4 expone Fees dentro del Ledger unificado en /v2. Las versiones independientes anteriores de plugin-fees siguen su propia matriz de compatibilidad heredada y no son el modelo de despliegue de v4.

​
Fee Packages

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.
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.
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.
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.
Si no defines maximumAmount, el package puede aplicarse sin un límite superior. Verifica las reglas de validación de tu versión.
Sí. Establece el campo transactionRoute en el package. Fees Engine entonces considera el package solo para transacciones con esa ruta, como "PIX", "TED" o "BOLETO".
Son alias de cuenta que el package exime de comisiones. Si el remitente o el destinatario de una transacción es una cuenta en waivedAccounts, Fees Engine no le aplica las comisiones del package.
Este package no cobra ninguna transacción que provenga de estas cuentas o vaya hacia ellas.
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.

​
Modelos de cálculo

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:
Usa exactamente 1 cálculo de tipo flat:
Esto cobra un monto fijo de 5.00 sin importar el monto de la transacción.
Usa exactamente 1 cálculo de tipo percentage:
Esto cobra el 2.5% del monto de referencia de la transacción.
maxBetweenTypes requiere 2 o más cálculos que combinen flat y percentage. Fees Engine calcula ambos y aplica el resultado mayor.Ejemplo: comisión mínima de 3.00 o 1% del valor, lo que sea mayor:
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.
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

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.
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, y el remitente paga de más para cubrir el cargo.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
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.
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.
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

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.
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.
El último nivel debe ser ilimitado (sin maxQuantity). No debe haber vacíos ni superposiciones entre niveles.
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.
accountTarget debe tener exactamente uno de los tres campos: segmentId, portfolioId o aliases (máximo 100 aliases).
Los niveles definen el precio unitario por nivel a medida que aumenta el volumen. Las reglas son:
  1. Deben ser contiguos: sin vacíos entre niveles (minQuantity del siguiente = maxQuantity del anterior + 1).
  2. No deben superponerse.
  3. El último nivel debe ser ilimitado (sin maxQuantity).
Ejemplo de niveles correctos:
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.
Son niveles de descuento para volume billing. Reducen el monto cobrado según criterios adicionales. Complementan la lógica de los tiers principales.
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

El Ledger evalúa las comisiones en el flujo de la transacción cuando se aplica un package coincidente. Midaz v4 no tiene un endpoint de nivel superior /v2/fees ni /v2/estimates. El endpoint delimitado al ledger POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/estimates sigue disponible para una vista previa específica de un package.
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.
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

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:
Las comisiones con isDeductibleFrom: true solo pueden usar referenceAmount: "originalAmount". Actualiza el campo:
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.
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.
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.
El último nivel en volume billing no debe tener límite superior (sin maxQuantity). Esto mantiene un precio para las transacciones por encima del rango más alto definido.
En maintenance billing, el campo accountTarget acepta solo una de las tres opciones. No combines campos:
Sí. El campo aliases acepta un máximo de 100 aliases por Billing Package de maintenance.
El applicationRule: "flatFee" acepta exactamente 1 cálculo, y debe ser de tipo flat. No uses percentage con flatFee.
Al igual que flatFee, el applicationRule: "percentual" acepta exactamente 1 cálculo de tipo percentage.
maxBetweenTypes requiere al menos 2 cálculos, porque necesita valores para comparar. Proporciona al menos un flat y un percentage.
Lista de verificación de diagnóstico (consulta también Best Practices):
  • enable: ¿el package está activo (enable: true)?
  • ledgerId: ¿el package está vinculado al ledger correcto?
  • 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?
Fees Engine hace soft-delete de los registros. Los marca con deletedAt y no los elimina de la base de datos. La API no expone endpoints de restauración por defecto. Contacta al equipo de Lerian si necesitas recuperar un registro eliminado. Para ver la lista completa de códigos de error, consulta la referencia de Error Codes.