> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# FAQ

> Respuestas a preguntas comunes de Lerian y Midaz sobre límites de paginación de la API, aislamiento de datos en SaaS, alcance del tenant en el JWT y configuración de plataformas multiorganización.

## APIs de Lerian

***

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

<Accordion title="¿Hay un número máximo de registros por página en los listados de la API? ¿Puedo aumentar este límite?">
  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.
</Accordion>

## 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.

<AccordionGroup>
  <Accordion title="¿Mis datos están aislados de otros clientes en SaaS?">
    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](/es/platform/multi-tenancy).
  </Accordion>

  <Accordion title="¿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.
  </Accordion>

  <Accordion title="¿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.
  </Accordion>

  <Accordion title="¿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.
  </Accordion>
</AccordionGroup>

## Midaz

***

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

### Organizations

<AccordionGroup>
  <Accordion title="¿Las diferentes Organizations se comunican entre sí?">
    No. Cada Organization opera de forma independiente y no se comunica con las demás.
  </Accordion>

  <Accordion title="¿Puedo usar una sola licencia en varias Organizations?">
    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.
  </Accordion>

  <Accordion title="¿Una Organization puede tener varios Plugins?">
    Sí. Una Organization puede tener más de un Plugin.
  </Accordion>

  <Accordion title="¿Una Organization puede tener varios Ledgers?">
    Sí. Una Organization puede administrar varios Ledgers.
  </Accordion>

  <Accordion title="¿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. Las transacciones no pueden mover valor directamente entre ledgers. Orquestas la transferencia con estos pasos:

    <Steps>
      <Step>
        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.
      </Step>

      <Step>
        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).
      </Step>
    </Steps>

    Este patrón mueve valor entre ledgers de diferentes Organizations.
  </Accordion>
</AccordionGroup>

### Ledgers

<AccordionGroup>
  <Accordion title="¿Los diferentes Ledgers se comunican entre sí?">
    No. Los Ledgers no se comunican directamente. Las transferencias entre Ledgers requieren orquestación.
  </Accordion>

  <Accordion title="¿Cómo puedo hacer transacciones entre Ledgers?">
    Debes orquestar el proceso y mover el monto a través de una External Account. Esto implica dos pasos:

    <Steps>
      <Step>
        Ledger A -> External Account.
      </Step>

      <Step>
        External Account -> Ledger B.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="¿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.
  </Accordion>
</AccordionGroup>

### Assets

<AccordionGroup>
  <Accordion title="¿Un Asset puede vincularse a varias Accounts?">
    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.
  </Accordion>

  <Accordion title="¿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.
    * *commodities*: bienes tangibles como oro, soja y petróleo.
    * *others*: Assets personalizados, incluidos puntos de fidelidad y valores tokenizados.
  </Accordion>
</AccordionGroup>

### Portfolios

<Accordion title="¿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 `segment_id` tiene dos valores de `account_id` correspondientes. Creas un Portfolio para ese CPF para vincular ambas cuentas bajo una sola estructura.
</Accordion>

### Accounts

<AccordionGroup>
  <Accordion title="¿Una Account puede asociarse con varios Assets?">
    No. Cada Account se vincula a un solo Asset. No puedes cambiar este vínculo.
  </Accordion>

  <Accordion title="¿Qué es una External Account?">
    Una External Account recibe fondos desde fuera del Ledger. Trae dinero hacia el sistema.
  </Accordion>

  <Accordion title="¿Cómo puedo crear una External Account?">
    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.
  </Accordion>

  <Accordion title="¿Una Account puede vincularse a varios Segments?">
    No. Cada account (`account_id`) se vincula a un solo Segment (`segment_id`).
  </Accordion>

  <Accordion title="¿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.
  </Accordion>

  <Accordion title="¿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í:

    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.
  </Accordion>
</AccordionGroup>

### Transactions

<AccordionGroup>
  <Accordion title="¿Cuál es la estructura mínima de una Transaction?">
    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.
  </Accordion>

  <Accordion title="¿Es posible generar un recibo de transferencia en PDF con los detalles de una transacción completada?">
    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.
  </Accordion>
</AccordionGroup>

### Entities

<Accordion title="¿Cómo puedo crear una Entity?">
  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.
</Accordion>

### Idempotencia

<AccordionGroup>
  <Accordion title="¿Qué sucede si no envío una clave de idempotencia?">
    Midaz trata la solicitud como nueva cada vez. Los reintentos pueden entonces crear operaciones duplicadas.
  </Accordion>

  <Accordion title="¿Puedo reutilizar una clave de idempotencia en varios endpoints?">
    No. Delimita cada clave a una sola operación y endpoint.
  </Accordion>

  <Accordion title="¿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.
  </Accordion>

  <Accordion title="¿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`.
  </Accordion>

  <Accordion title="¿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.
  </Accordion>
</AccordionGroup>

### Contabilidad en Midaz

<Accordion title="¿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](/es/products/midaz/accounts): 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](/es/products/midaz/transaction-routing-entities): 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.
</Accordion>

## 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.

<AccordionGroup>
  <Accordion title="¿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 los clientes puedan enfocarse en su modelo de negocio. Los clientes no construyen ni administran lógica de sistemas fuera de su dominio.
  </Accordion>

  <Accordion title="¿Los plugins pueden usarse sin Midaz?">
    No. Los plugins operan solo con Midaz. Aportan abstracciones específicas y orquestan transacciones según la estructura del ledger.
  </Accordion>

  <Accordion title="¿Cómo se distribuyen los plugins?">
    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.
  </Accordion>

  <Accordion title="¿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.
  </Accordion>
</AccordionGroup>

## 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

<AccordionGroup>
  <Accordion title="¿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](/es/products/midaz/fees/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`.
  </Accordion>

  <Accordion title="¿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.
  </Accordion>

  <Accordion title="¿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 ***
    ```
  </Accordion>

  <Accordion title="¿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.
  </Accordion>

  <Accordion title="¿Qué versión de Midaz ofrece el módulo integrado de Fees?">
    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.
  </Accordion>
</AccordionGroup>

### Fee Packages

<AccordionGroup>
  <Accordion title="¿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](/es/products/midaz/fees/using-fee-engine).
  </Accordion>

  <Accordion title="¿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](/es/reference/products/midaz/v2/create-package) para ver todos los detalles.

    ```json theme={null}
    {
      "feeGroupLabel": "Digital Account Fees",
      "ledgerId": "ldg_abc123",
      "segmentId": "seg_xyz456",
      "minimumAmount": "100.00",
      "maximumAmount": "50000.00",
      "transactionRoute": "PIX",
      "enable": true,
      "waivedAccounts": ["exempt-account-1", "exempt-account-2"],
      "fees": {
        "admin_fee": {
          "feeLabel": "Administrative Fee",
          "calculationModel": {
            "applicationRule": "percentual",
            "calculations": [
              { "type": "percentage", "value": "1.50" }
            ]
          },
          "referenceAmount": "originalAmount",
          "priority": 1,
          "isDeductibleFrom": true,
          "creditAccount": "fee-revenue-account"
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="¿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.
  </Accordion>

  <Accordion title="¿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.

    <Note>Si no defines `maximumAmount`, el package puede aplicarse sin un límite superior. Verifica las reglas de validación de tu versión.</Note>
  </Accordion>

  <Accordion title="¿Puedo filtrar un package por ruta de transacció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"`.
  </Accordion>

  <Accordion title="¿Qué son los waivedAccounts?">
    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.

    ```json theme={null}
    "waivedAccounts": ["vip-account", "employee-account"]
    ```

    Este package no cobra ninguna transacción que provenga de estas cuentas o vaya hacia ellas.
  </Accordion>

  <Accordion title="¿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
    ```
  </Accordion>
</AccordionGroup>

### Modelos de cálculo

<AccordionGroup>
  <Accordion title="¿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](/es/products/midaz/fees/fee-engine-calculation) 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` | Calcula tanto el monto fijo como el porcentual; aplica el resultado **mayor** |
  </Accordion>

  <Accordion title="¿Cómo configuro una comisión fija (flatFee)?">
    Usa exactamente **1 cálculo** de tipo `flat`:

    ```json theme={null}
    "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.
  </Accordion>

  <Accordion title="¿Cómo configuro una comisión porcentual (percentual)?">
    Usa exactamente **1 cálculo** de tipo `percentage`:

    ```json theme={null}
    "calculationModel": {
      "applicationRule": "percentual",
      "calculations": [
        { "type": "percentage", "value": "2.50" }
      ]
    }
    ```

    Esto cobra el 2.5% del monto de referencia de la transacción.
  </Accordion>

  <Accordion title="¿Cómo funciona maxBetweenTypes?">
    `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:

    ```json theme={null}
    "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**.
  </Accordion>

  <Accordion title="¿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.
  </Accordion>
</AccordionGroup>

### Campos importantes

<AccordionGroup>
  <Accordion title="¿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.

    <Note>La comisión con `priority: 1` se ejecuta primero, así que **debe** usar `originalAmount`. No existen comisiones previas que considerar.</Note>
  </Accordion>

  <Accordion title="¿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, 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
  </Accordion>

  <Accordion title="¿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.
  </Accordion>

  <Accordion title="¿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.

    ```json theme={null}
    "creditAccount": "admin-fee-revenue-account"
    ```
  </Accordion>

  <Accordion title="¿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.
  </Accordion>
</AccordionGroup>

### Billing Packages

<AccordionGroup>
  <Accordion title="¿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](/es/products/midaz/fees/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.
  </Accordion>

  <Accordion title="¿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.

    ```json theme={null}
    {
      "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"
    }
    ```

    <Note>El último nivel debe ser **ilimitado** (sin `maxQuantity`). No debe haber vacíos ni superposiciones entre niveles.</Note>
  </Accordion>

  <Accordion title="¿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.

    ```json theme={null}
    {
      "type": "maintenance",
      "feeAmount": "15.00",
      "assetCode": "BRL",
      "maintenanceCreditAccount": "maintenance-revenue-account",
      "accountTarget": {
        "segmentId": "seg_premium_clients"
      }
    }
    ```

    <Note>`accountTarget` debe tener exactamente **uno** de los tres campos: `segmentId`, `portfolioId` o `aliases` (máximo 100 aliases).</Note>
  </Accordion>

  <Accordion title="¿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:

    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:**

    ```json theme={null}
    "tiers": [
      { "minQuantity": 0, "maxQuantity": 500, "unitPrice": "0.80" },
      { "minQuantity": 501, "maxQuantity": 2000, "unitPrice": "0.60" },
      { "minQuantity": 2001, "unitPrice": "0.40" }
    ]
    ```
  </Accordion>

  <Accordion title="¿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.
  </Accordion>

  <Accordion title="¿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.
  </Accordion>

  <Accordion title="¿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.
  </Accordion>
</AccordionGroup>

### Cálculo de comisiones y facturación

<AccordionGroup>
  <Accordion title="¿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. 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.
  </Accordion>

  <Accordion title="¿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`.
  </Accordion>

  <Accordion title="¿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.
  </Accordion>
</AccordionGroup>

### Errores comunes

<AccordionGroup>
  <Accordion title="¿Qué significa &#x22;Priority 1 must use originalAmount&#x22;?">
    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:**

    ```json theme={null}
    {
      "priority": 1,
      "referenceAmount": "originalAmount"
    }
    ```
  </Accordion>

  <Accordion title="¿Cómo corrijo &#x22;isDeductibleFrom requires originalAmount&#x22;?">
    Las comisiones con `isDeductibleFrom: true` solo pueden usar `referenceAmount: "originalAmount"`. Actualiza el campo:

    ```json theme={null}
    {
      "isDeductibleFrom": true,
      "referenceAmount": "originalAmount"
    }
    ```
  </Accordion>

  <Accordion title="¿Por qué obtengo &#x22;Flat fee value cannot exceed minimumAmount&#x22;?">
    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.
  </Accordion>

  <Accordion title="¿Cuándo ocurre &#x22;Percentage value cannot exceed 100&#x22;?">
    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.
  </Accordion>

  <Accordion title="¿Cómo corrijo &#x22;Tiers must be contiguous&#x22;?">
    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.

    ```json theme={null}
    // ❌ 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" }
    ```
  </Accordion>

  <Accordion title="¿Qué significa &#x22;Last tier must be unbounded&#x22;?">
    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.
  </Accordion>

  <Accordion title="&#x22;accountTarget must have exactly one of: segmentId, portfolioId, aliases&#x22;">
    En maintenance billing, el campo `accountTarget` acepta solo **una** de las tres opciones. No combines campos:

    ```json theme={null}
    // ❌ Wrong
    "accountTarget": {
      "segmentId": "seg_abc",
      "portfolioId": "port_xyz"
    }

    // ✅ Correct
    "accountTarget": {
      "segmentId": "seg_abc"
    }
    ```
  </Accordion>

  <Accordion title="¿Hay un límite de aliases en accountTarget?">
    Sí. El campo `aliases` acepta un máximo de **100 aliases** por Billing Package de maintenance.
  </Accordion>

  <Accordion title="&#x22;flatFee requires exactly 1 calculation of type flat&#x22;">
    El `applicationRule: "flatFee"` acepta exactamente 1 cálculo, y debe ser de tipo `flat`. No uses `percentage` con `flatFee`.

    ```json theme={null}
    // ✅ Correct
    "calculationModel": {
      "applicationRule": "flatFee",
      "calculations": [{ "type": "flat", "value": "10.00" }]
    }
    ```
  </Accordion>

  <Accordion title="&#x22;percentual requires exactly 1 calculation of type percentage&#x22;">
    Al igual que `flatFee`, el `applicationRule: "percentual"` acepta exactamente 1 cálculo de tipo `percentage`.
  </Accordion>

  <Accordion title="&#x22;maxBetweenTypes requires 2 or more calculations&#x22;">
    `maxBetweenTypes` requiere al menos 2 cálculos, porque necesita valores para comparar. Proporciona al menos un `flat` y un `percentage`.
  </Accordion>

  <Accordion title="¿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](/es/products/midaz/fees/fees-engine-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?
  </Accordion>

  <Accordion title="¿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 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](/es/reference/products/midaz/v2/estimate-fee-calculation).
  </Accordion>
</AccordionGroup>