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

> Encuentra respuestas a preguntas frecuentes sobre las APIs de Lerian, multi-tenancy, aislamiento en SaaS, paginación y configuración de la plataforma.

## APIs de Lerian

***

Esta sección responde preguntas frecuentes sobre las APIs de Lerian, cubriendo comportamiento general, configuración y mejores prácticas en todos los servicios.

<Accordion title="¿Existe un número máximo de registros por página en los listados de API? ¿Puedo aumentar este límite?">
  Sí. Por defecto, el número máximo de registros por página es **100**. Este límite garantiza un rendimiento consistente y ayuda a gestionar el volumen de datos transferidos en cada solicitud. Sin embargo, puedes aumentar este valor configurando la variable de entorno `MAX_PAGINATION_LIMIT` en tu configuración de despliegue. Una vez actualizada y reiniciada la aplicación, la API aceptará tamaños de página más grandes.

  **Importante**: Aumentar el tamaño de página puede afectar los tiempos de respuesta, especialmente en entornos que manejan grandes conjuntos de datos. Siempre prueba exhaustivamente en staging antes de aplicar cambios en producción.
</Accordion>

## Multi-tenancy y SaaS

***

Preguntas frecuentes sobre aislamiento de datos, alcance de tenant y cómo funciona multi-tenancy en los despliegues de Lerian.

<AccordionGroup>
  <Accordion title="¿Mis datos están aislados de los de otros clientes en SaaS?">
    Sí. Cada tenant opera en una base de datos separada. La plataforma resuelve tu tenant a partir del JWT en cada solicitud y la dirige a tu base de datos aislada. No hay forma de acceder a los datos de otro tenant a través de la API. Más información sobre [multi-tenancy](/es/multi-tenancy).
  </Accordion>

  <Accordion title="¿Necesito pasar un ID de tenant en mis solicitudes de API?">
    No. El contexto de tu tenant está incluido en el JWT access token que recibes durante la autenticación. La plataforma lo resuelve automáticamente — no necesitas incluir ningún identificador de tenant en headers ni en el cuerpo de la solicitud.
  </Accordion>

  <Accordion title="¿Puedo tener múltiples Organizaciones bajo un solo tenant?">
    Sí. Un tenant puede contener múltiples Organizaciones, cada una con sus propios Ledgers, cuentas y transacciones. Todas están vinculadas a tu tenant automáticamente.
  </Accordion>

  <Accordion title="¿La API es diferente entre SaaS y despliegues autoalojados?">
    No. La superficie de API es idéntica — mismos endpoints, mismos payloads, mismas respuestas. La única diferencia es que SaaS requiere autenticación en cada solicitud, y tu token delimita automáticamente todas las operaciones a tu tenant.
  </Accordion>
</AccordionGroup>

## Midaz

***

Aquí encontrarás respuestas a preguntas comunes sobre Organizaciones, Ledgers, Cuentas, Transacciones y más en Midaz.

### Organizaciones

<AccordionGroup>
  <Accordion title="¿Las diferentes Organizaciones se comunican entre sí?">
    No, cada Organización opera de forma independiente y no se comunica con otras.
  </Accordion>

  <Accordion title="¿Puedo usar una única licencia en múltiples Organizaciones?">
    No, cada licencia está vinculada a una Organización específica. Si necesitas soporte para múltiples Organizaciones, debes adquirir licencias separadas para cada una. La misma regla aplica para los Plugins.
  </Accordion>

  <Accordion title="¿Puede una Organización tener múltiples Plugins?">
    Sí, una Organización puede tener más de un Plugin asociado.
  </Accordion>

  <Accordion title="¿Puede una Organización tener múltiples Ledgers?">
    Sí, una Organización puede gestionar múltiples Ledgers.
  </Accordion>

  <Accordion title="¿Puedo crear transacciones entre una Organización Padre y una Organización Hija?">
    Aunque puedes crear una **Organización Padre** y una **Organización Hija**, cada **Organización** mantiene su propio Ledger, operando independientemente. Dado que las transacciones no pueden mover valor directamente entre Ledgers, necesitas orquestar la transferencia con los siguientes pasos:

    <Steps>
      <Step>
        Inicia una transacción en el Ledger de origen, transfiriendo el monto de la cuenta original (**source**) a la **cuenta externa** del activo (distribute). Esto elimina el valor del Ledger original.
      </Step>

      <Step>
        **Crea una segunda transacción** en el Ledger de destino, donde el **source** es ahora la **cuenta externa** del activo, y el monto se asigna a la cuenta receptora (**distribute**).
      </Step>
    </Steps>

    Este enfoque garantiza transferencias de valor fluidas y controladas entre Ledgers de diferentes organizaciones.
  </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 transferir el monto a una Cuenta Externa. Típicamente, esto involucra dos pasos:

    <Steps>
      <Step>
        Ledger A -> Cuenta Externa.
      </Step>

      <Step>
        Cuenta Externa -> Ledger B.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="¿Necesito un Ledger separado para cada Plugin?">
    No, un único Ledger puede soportar múltiples Plugins. Por ejemplo, un Ledger puede manejar tanto Plugins de Exchange como de Pix simultáneamente.
  </Accordion>
</AccordionGroup>

### Activos

<AccordionGroup>
  <Accordion title="¿Puede un Activo vincularse a múltiples Cuentas?">
    No, cada Activo está vinculado a una única Cuenta. Sin embargo, cada Activo también estará vinculado a una Cuenta Externa que se crea automáticamente cuando se crea el Activo.
  </Accordion>

  <Accordion title="¿Qué tipos de Activos puedo usar?">
    Midaz está construido para flexibilidad, soportando una amplia gama de Activos:

    * *currency*: Monedas fiduciarias tradicionales como BRL, USD y EUR.
    * *crypto*: Activos digitales como BTC, ETH y otras criptomonedas.
    * *commodities*: Bienes tangibles como oro, soja y petróleo.
    * *others*: Activos personalizados, incluyendo puntos de lealtad y valores tokenizados.
  </Accordion>
</AccordionGroup>

### Portafolios

<Accordion title="¿Cómo funciona un Portafolio?">
  Un **Portafolio** agrupa cuentas que pertenecen a la misma entidad (**CPF/CNPJ**). Por ejemplo, si un único CPF tiene dos valores diferentes de `segment_id`, también tendrá dos valores correspondientes de `account_id`. Para simplificar la recuperación, se crea un Portafolio para ese CPF, vinculando ambas cuentas bajo una única estructura. Esto garantiza un acceso y gestión más fáciles de cuentas relacionadas.
</Accordion>

### Cuentas

<AccordionGroup>
  <Accordion title="¿Puede una Cuenta estar asociada con múltiples Activos?">
    No, cada Cuenta está asociada con un único Activo, y esta asociación no puede cambiarse.
  </Accordion>

  <Accordion title="¿Qué es una Cuenta Externa?">
    Una Cuenta Externa se usa para recibir fondos desde fuera del Ledger, efectivamente trayendo dinero al sistema.
  </Accordion>

  <Accordion title="¿Cómo puedo crear una Cuenta Externa?">
    Midaz configura automáticamente una **Cuenta Externa** cuando creas un Activo, garantizando respaldo continuo para todas las transacciones que fluyen dentro y fuera del Ledger.
  </Accordion>

  <Accordion title="¿Puede una Cuenta estar vinculada a varios Segmentos?">
    No. Cada cuenta (`account_id`) puede estar vinculada solo a un Segmento (`segment_id`).
  </Accordion>

  <Accordion title="¿Existe un límite en cuántas Cuentas puedo crear en Midaz?">
    No. Puedes crear tantas Cuentas como necesite tu configuración. Sin límites, sin restricciones—solo la flexibilidad para escalar a tu manera.
  </Accordion>

  <Accordion title="¿Cuál es el proceso para agregar fondos a una cuenta o realizar un depósito usando dinero que proviene de fuera del entorno del Ledger (Midaz)?">
    Para entender el proceso de recarga de saldo, consideremos los siguientes puntos:

    1. En el Ledger de Midaz, cuando se crea un Activo (por ejemplo, BRL), también se genera una Cuenta Externa asociada con ese activo.
    2. Esta Cuenta Externa actúa como puerta de enlace entre el ecosistema de Lerian y el mundo externo. En otras palabras, sirve como espejo de los saldos mantenidos por la institución en su cuenta PI, cuenta de liquidación, cuenta de reserva, o incluso una cuenta bancaria tradicional o de pago que mantiene los fondos reales.
    3. Para depositar fondos en una cuenta de usuario con un Activo específico proveniente de fuera del Ledger de Midaz, el proceso es el siguiente:
       * Inicia una transacción donde la fuente es la Cuenta Externa y el destino es la(s) cuenta(s) objetivo.
       * Como resultado, la Cuenta Externa se debitará por el monto transferido (volviéndose negativa), mientras que la(s) cuenta(s) destino se acreditarán en consecuencia, según los valores proporcionados en la carga útil de la transacción.
  </Accordion>
</AccordionGroup>

### Transacciones

<AccordionGroup>
  <Accordion title="¿Cuál es la estructura mínima de una Transacción?">
    Una Transacción debe tener al menos dos Operaciones. Por ejemplo, transferir R\$ 100 de la Cuenta A a la Cuenta B consiste en:

    * **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 que contenga los detalles de una transacción completada?">
    Lerian proporciona a los clientes múltiples opciones para acceder a recibos de transacciones:

    1. **Vía APIs** – Recupera datos de transacciones a través de nuestras APIs, permitiéndote generar un recibo visual en el formato de tu elección.
    2. **Usando el Reporter** – Extrae datos de transacciones y crea recibos visuales personalizados.
    3. **A través de Lerian Console** – Accede a información de transacciones directamente desde Lerian Console.
  </Accordion>
</AccordionGroup>

### Entidades

<Accordion title="¿Cómo puedo crear una Entidad?">
  Actualmente, la Entidad (`entity_id`) está abierta para IDs externos, sin validación impuesta por Midaz. Esto significa que puedes usar los IDs que ya existen en tu base de datos, integrándolos sin problemas 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. Esto significa que los reintentos pueden resultar en operaciones duplicadas.
  </Accordion>

  <Accordion title="¿Puedo reutilizar una clave de idempotencia en diferentes endpoints?">
    No. Las claves deben estar limitadas a una única operación y endpoint.
  </Accordion>

  <Accordion title="¿Qué sucede si cambio el TTL en un reintento?">
    Solo se usa el TTL de la primera solicitud. Cambiarlo posteriormente no tiene efecto.
  </Accordion>

  <Accordion title="¿La respuesta reproducida siempre será idéntica?">
    Sí. Midaz reproduce la respuesta completa, incluyendo encabezados y cuerpo, para solicitudes completadas.
  </Accordion>

  <Accordion title="¿Cuál es el TTL predeterminado si no envío X-TTL?">
    La ventana predeterminada es **300 segundos** (5 minutos), pero puedes personalizarla hasta tu límite permitido por endpoint.
  </Accordion>
</AccordionGroup>

### Contabilidad en Midaz

<Accordion title="¿Cómo puedo reflejar mi propio Plan de Cuentas en Midaz?">
  R: Midaz te permite reflejar el **Plan de Cuentas** oficial de tu organización directamente en la plataforma configurando dos características principales:

  * [Tipos de Cuenta](/es/midaz/accounts) – Crea las categorías lógicas de tu plan (por ejemplo, Activos, Pasivos, Ingresos, Gastos) y asígnalas a cuentas en tu Ledger. Cuando la función de Tipos de Cuenta está habilitada, el campo tipo en la API de Cuentas se vuelve obligatorio y debe coincidir con uno de los valores que has registrado.
  * [Rutas Contables](/es/midaz/transaction-routing-entities) – Usa Rutas de Operación para validar cada "pierna" de una transacción (por ejemplo, el débito debe provenir de un tipo de cuenta `user_wallet`) y Rutas Contables (el recurso `transactionRoute` en la API) para definir patrones completos de transacción que se alineen con tu lógica contable.

  Al combinar Tipos de Cuenta y Rutas Contables, puedes hacer cumplir tus reglas contables a nivel de Ledger — garantizando que cada transacción sea validada y categorizada según tu Plan de Cuentas, sin codificar reglas en tu lógica de negocio.
</Accordion>

## Plugins

***

Los plugins extienden las capacidades de Midaz, habilitando integración fluida y orquestación de procesos. Diseñados para eliminar complejidad, proporcionan abstracciones poderosas que te permiten enfocarte en tu modelo de negocio mientras garantizan eficiencia y escalabilidad.

Explora las preguntas más comunes sobre cómo funcionan los plugins, su despliegue y las opciones disponibles para mejorar tus operaciones.

<AccordionGroup>
  <Accordion title="¿Qué son los Plugins?">
    Los plugins son tecnologías integradas en el Ledger de Midaz, diseñadas para simplificar la integración y orquestación de procesos. Proporcionan abstracciones que permiten a los clientes enfocarse en su modelo de negocio sin necesidad de construir o gestionar lógica esencial del sistema que cae fuera de su dominio.
  </Accordion>

  <Accordion title="¿Pueden usarse los plugins sin Midaz?">
    No. Los plugins están diseñados para operar exclusivamente con Midaz. Proporcionan abstracciones específicas y orquestan transacciones basándose en la estructura del Ledger, garantizando integración precisa y eficiente.
  </Accordion>

  <Accordion title="¿Cómo se distribuyen los plugins?">
    Una vez contratados, los plugins se proporcionan e instalan dentro de la infraestructura del cliente (modelo on-premise), junto con su instancia de Midaz. Las aplicaciones se conectan según la funcionalidad específica de cada plugin.
  </Accordion>

  <Accordion title="¿Qué opciones de plugins ofrece Lerian?">
    Lerian proporciona dos tipos de plugins, categorizados por su origen:

    * **Plugins Nativos:** Desarrollados e integrados completamente en el Ledger de Midaz por Lerian, estos plugins garantizan soporte completo e integración fluida con la plataforma.
    * **Plugins de Marketplace:** Creados por socios de Lerian para servir nichos de mercado específicos, estos plugins están disponibles en el marketplace. Lerian facilita su integración en Midaz, pero su oferta y soporte son gestionados directamente por los socios respectivos.
  </Accordion>
</AccordionGroup>

## Fees Engine

***

Preguntas frecuentes sobre el Fees Engine — parte de la familia de productos Midaz, un servicio de cálculo de tarifas sobre transacciones financieras, desplegado de forma independiente bajo la licencia Enterprise.

### Conceptos Generales

<AccordionGroup>
  <Accordion title="¿Qué es el Fees Engine?">
    El Fees Engine forma parte de la **familia de productos Midaz**. Es un servicio de cálculo de tarifas sobre transacciones financieras — desplegado de forma independiente y disponible bajo la licencia Enterprise. Más información en la [descripción general del Fees Engine](/es/midaz/fees/fees-engine-overview). Opera en tres dominios principales:

    * **Paquetes de Tarifas (`/v1/packages`):** define las reglas de cobro por transacción (tarifa fija, porcentual, o el mayor entre ambos).
    * **Billing Packages (`/v1/billing-packages`):** define cobros periódicos por volumen de transacciones o por mantenimiento de cuentas.
    * **Cálculo y Estimación (`/v1/fees` y `/v1/estimates`):** endpoints para calcular tarifas en tiempo real o simular antes de confirmar.
  </Accordion>

  <Accordion title="¿Cómo se integra el Fees Engine en el ecosistema Lerian?">
    El Fees Engine forma parte de la familia de productos Midaz, desplegado como un servicio independiente bajo la licencia Enterprise. Es un servicio de cálculo: según las reglas configuradas, determina cuánto debe cobrarse — y a quién — y devuelve el resultado para que tu aplicación lo registre. Lee de Midaz, pero nunca escribe en el ledger.
  </Accordion>

  <Accordion title="¿Qué necesito enviar en cada solicitud al Fees Engine?">
    Todas las solicitudes requieren el header `X-Organization-Id` con el ID de tu organización en Midaz. Este es un header de alcance de organización específico del Fees Engine, no un identificador de tenant — el contexto de tu tenant se resuelve automáticamente desde el JWT. Cuando el plugin de autenticación está activo, también se requiere un Bearer token en el header `Authorization`.

    ```
    X-Organization-Id: <tu-organization-id>
    Authorization: Bearer <tu-token>
    ```
  </Accordion>

  <Accordion title="¿Qué base de datos utiliza el Fees Engine?">
    El Fees Engine usa **MongoDB** como backend de almacenamiento. Las eliminaciones siguen el patrón de **soft-delete** — los registros no se eliminan físicamente, solo se marcan con `deletedAt`. Esto significa que los registros "eliminados" no aparecen en los listados, pero pueden ser auditados.
  </Accordion>

  <Accordion title="¿Cuál es la versión mínima de Midaz necesaria para usar el Fees Engine?">
    **Midaz v3.6.0** o superior. La versión actual del Fees Engine depende de APIs del módulo Transaction que solo están disponibles a partir de la v3.6.0. Versiones anteriores de Midaz no son compatibles.
  </Accordion>
</AccordionGroup>

### Paquetes de Tarifas

<AccordionGroup>
  <Accordion title="¿Qué es un Paquete de Tarifas?">
    Un Paquete de Tarifas (`Package`) es un conjunto de reglas de cobro agrupadas bajo un `feeGroupLabel`. Cada paquete está vinculado a una **Organización + Ledger** y, opcionalmente, a un **Segment**. Un paquete puede contener múltiples tarifas individuales (objetos `Fee`), cada una con su propia lógica de cálculo. Más información sobre [Paquetes de Tarifas](/es/midaz/fees/using-fee-engine).
  </Accordion>

  <Accordion title="¿Cómo crear un Paquete de Tarifas?">
    Envía un `POST /v1/packages` con el siguiente cuerpo. Consulta la [referencia de la API Create Package](/es/reference/midaz/plugins/fees-engine/create-package) para detalles completos.

    ```json theme={null}
    {
      "feeGroupLabel": "Tarifas Cuenta Digital",
      "ledgerId": "ldg_abc123",
      "segmentId": "seg_xyz456",
      "minimumAmount": "100.00",
      "maximumAmount": "50000.00",
      "transactionRoute": "PIX",
      "enable": true,
      "waivedAccounts": ["cuenta-exenta-1", "cuenta-exenta-2"],
      "fees": {
        "tarifa_admin": {
          "feeLabel": "Tarifa Administrativa",
          "calculationModel": {
            "applicationRule": "percentual",
            "calculations": [
              { "type": "percentage", "value": "1.50" }
            ]
          },
          "referenceAmount": "originalAmount",
          "priority": 1,
          "isDeductibleFrom": true,
          "creditAccount": "cuenta-ingresos-tarifas"
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="¿Se puede desactivar un paquete temporalmente?">
    Sí. Usa el campo `enable: false` al crear o actualizar el paquete. Un paquete desactivado no se considera en el cálculo de tarifas, incluso si el contexto de la transacción coincide con tu alcance.
  </Accordion>

  <Accordion title="¿Cómo funciona el alcance de un paquete (minimumAmount / maximumAmount)?">
    El paquete solo se aplica a transacciones cuyo valor esté dentro del rango `[minimumAmount, maximumAmount]`. Si la transacción no encaja en este rango, el paquete se ignora.

    **Ejemplo:** Un paquete con `minimumAmount: 100` y `maximumAmount: 5000` solo cobrará tarifas en transacciones entre 100 y 5.000.

    <Note>Si `maximumAmount` no está definido, el paquete puede aplicarse sin límite superior — verifica las reglas de validación de tu versión.</Note>
  </Accordion>

  <Accordion title="¿Puedo filtrar un paquete por ruta de transacción?">
    Sí. Usa el campo `transactionRoute` en el paquete. Cuando está definido, el paquete solo se considerará en transacciones con esa ruta específica (ej: `"PIX"`, `"TED"`, `"BOLETO"`).
  </Accordion>

  <Accordion title="¿Qué son los waivedAccounts?">
    Son aliases de cuentas **exentas** de tarifas dentro de ese paquete. Si el remitente o destinatario de la transacción es una cuenta listada en `waivedAccounts`, las tarifas del paquete no se aplican.

    ```json theme={null}
    "waivedAccounts": ["cuenta-vip", "cuenta-empleado"]
    ```

    Cualquier transacción originada o destinada a estas cuentas no será tarifada por este paquete.
  </Accordion>

  <Accordion title="¿Los endpoints de listado tienen paginación?">
    Sí. Los endpoints de listado (`GET /v1/packages`, `GET /v1/billing-packages`) soportan los parámetros de query `limit` y `page` para paginación.

    ```
    GET /v1/packages?limit=20&page=2
    ```
  </Accordion>
</AccordionGroup>

### Modelos de Cálculo

<AccordionGroup>
  <Accordion title="¿Qué modelos de cálculo están disponibles?">
    El campo `applicationRule` dentro de `calculationModel` define cómo se calcula la tarifa. Consulta [Modelos de Cálculo](/es/midaz/fees/fee-engine-calculation) para detalles completos. Hay tres opciones:

    | Regla             | Descripción                                              |
    | ----------------- | -------------------------------------------------------- |
    | `flatFee`         | Tarifa fija en valor absoluto                            |
    | `percentual`      | Tarifa porcentual sobre el valor de referencia           |
    | `maxBetweenTypes` | Calcula flat y porcentual; aplica el **mayor** resultado |
  </Accordion>

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

    ```json theme={null}
    "calculationModel": {
      "applicationRule": "flatFee",
      "calculations": [
        { "type": "flat", "value": "5.00" }
      ]
    }
    ```

    Esto cobra 5,00 fijos, independientemente del valor de la transacción.
  </Accordion>

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

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

    Esto cobra 2,5% sobre el valor de referencia de la transacción.
  </Accordion>

  <Accordion title="¿Cómo funciona maxBetweenTypes?">
    El `maxBetweenTypes` requiere **2 o más cálculos** (combinando `flat` y `percentage`). El sistema calcula ambos y aplica el **mayor valor resultante**.

    **Ejemplo:** Tarifa mínima de 3,00 o 1% del valor — el 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 vs. 3,00 fijo → cobra **3,00**.
    Para una transacción de 500: 1% = 5,00 vs. 3,00 fijo → cobra **5,00**.
  </Accordion>

  <Accordion title="¿Puedo mezclar múltiples porcentajes en maxBetweenTypes?">
    Sí. Puedes incluir cualquier combinación de `flat` y `percentage` — el sistema evalúa todos y aplica el mayor. Sin embargo, `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** se calcula la tarifa:

    * `originalAmount`: valor original de la transacción, **antes** de que se aplique cualquier tarifa.
    * `afterFeesAmount`: valor de la transacción **después** de que las tarifas de mayor prioridad ya se hayan aplicado.

    <Note>La tarifa con `priority: 1` (la primera en ejecutarse) **debe** usar `originalAmount`. No hay tarifas anteriores que considerar.</Note>
  </Accordion>

  <Accordion title="¿Qué es isDeductibleFrom y cuándo debo usarlo?">
    Cuando `isDeductibleFrom: true`, la tarifa se **deduce del monto enviado por el remitente**. El destinatario recibe el monto ya descontado, y el remitente paga extra para cubrir el cargo.

    Cuando `false`, la tarifa se cobra **por separado** (el remitente envía el monto completo y la tarifa se debita aparte).

    **Restricciones:**

    * `isDeductibleFrom: true` requiere `referenceAmount: originalAmount`
    * Si el tipo es `percentage`: el valor no puede exceder 100
    * Si el tipo es `flat`: el valor no puede exceder el `minimumAmount` del paquete
  </Accordion>

  <Accordion title="¿Cómo funciona el campo priority?">
    El `priority` define el **orden de ejecución** de las tarifas dentro de un paquete. Valores menores se ejecutan primero.

    * `priority: 1` → se ejecuta primero (obligatoriamente usa `originalAmount`)
    * `priority: 2` → se ejecuta después, puede usar `afterFeesAmount`

    Usa prioridades para crear encadenamiento de tarifas — por ejemplo, una tarifa administrativa calculada sobre el valor original, seguida de una tarifa de impuesto calculada sobre el valor con la tarifa administrativa ya aplicada.
  </Accordion>

  <Accordion title="¿Qué es creditAccount?">
    Es el alias de la cuenta en el ledger donde se acreditarán los ingresos de la tarifa. Cada tarifa puede tener un `creditAccount` diferente — útil cuando diferentes tarifas necesitan contabilizarse en centros de costo distintos.

    ```json theme={null}
    "creditAccount": "cuenta-ingresos-tarifas-admin"
    ```
  </Accordion>

  <Accordion title="¿Para qué sirven routeFrom y routeTo dentro de una tarifa?">
    Estos campos definen las rutas de las **patas contables** generadas por el cobro de la tarifa. Son opcionales y permiten rastrear el origen y destino de los movimientos de tarifa en el ledger con granularidad.
  </Accordion>
</AccordionGroup>

### Billing Packages

<AccordionGroup>
  <Accordion title="¿Qué son los Billing Packages?">
    Son paquetes de cobro **periódico**, independientes del cálculo de tarifas por transacción. Consulta [ejemplos de Billing Packages](/es/midaz/fees/billing-package-examples) para casos de uso detallados. Existen dos tipos:

    * **`volume`:** cobra según la **cantidad de transacciones** en un período, con precios escalonados (tiers).
    * **`maintenance`:** cobra una **tarifa fija por cuenta** en un alcance determinado.
  </Accordion>

  <Accordion title="¿Cuándo usar billing de tipo volume?">
    Úsalo cuando quieras cobrar a clientes según el **número de transacciones procesadas** — modelo común en plataformas de pago con precios por volumen. Define escalones de precio (tiers) que se aplican a medida que el volumen crece.

    ```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": "cuenta-cliente",
      "creditAccountAlias": "cuenta-ingresos-volumen"
    }
    ```

    <Note>El último tier debe ser **ilimitado** (sin `maxQuantity`). No puede haber brechas ni superposiciones entre tiers.</Note>
  </Accordion>

  <Accordion title="¿Cuándo usar billing de tipo maintenance?">
    Úsalo cuando quieras cobrar una **tarifa fija periódica por cuenta** — por ejemplo, una mensualidad por cuenta activa. Especifica el alcance (`segmentId`, `portfolioId` o `aliases`) y el valor de la tarifa.

    ```json theme={null}
    {
      "type": "maintenance",
      "feeAmount": "15.00",
      "assetCode": "BRL",
      "maintenanceCreditAccount": "cuenta-ingresos-mantenimiento",
      "accountTarget": {
        "segmentId": "seg_clientes_premium"
      }
    }
    ```

    <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 tiers en el billing de volumen?">
    Los tiers definen el **precio unitario por escalón** a medida que el volumen aumenta. Reglas obligatorias:

    1. Deben ser **contiguos** — sin brechas entre escalones (`minQuantity` del siguiente = `maxQuantity` del anterior + 1).
    2. No pueden tener **superposición**.
    3. El **último tier debe ser ilimitado** (sin `maxQuantity`).

    **Ejemplo de tiers 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 **cuota gratuita** — un número de transacciones que no se cobran antes de que los tiers comiencen a aplicarse. Útil para modelos de precios con un volumen mínimo incluido.

    **Ejemplo:** `freeQuota: 100` significa que las primeras 100 transacciones del período no se cobran.
  </Accordion>

  <Accordion title="¿Qué son los discountTiers?">
    Son escalones de descuento aplicables al billing de volumen. Permiten reducir el valor cobrado según criterios adicionales, complementando la lógica de los `tiers` principales.
  </Accordion>

  <Accordion title="¿Qué es countMode en el billing de volumen?">
    Define **cómo se cuentan las transacciones**:

    * `perRoute`: cuenta transacciones por ruta (ej: total de PIX aprobados).
    * `perAccount`: cuenta transacciones por cuenta individualmente.
  </Accordion>
</AccordionGroup>

### Cálculo y Estimación de Tarifas

<AccordionGroup>
  <Accordion title="¿Cuál es la diferencia entre /v1/fees y /v1/estimates?">
    | Endpoint             | Cuándo usar                                                                                                                                                                                                                                                          |
    | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | `POST /v1/fees`      | Calcular la tarifa **real** de una transacción en curso. El sistema busca automáticamente los paquetes aplicables según el ledger, segment, ruta y valor. Consulta la [referencia de la API Calculate Fees](/es/reference/midaz/plugins/fees-engine/calculate-fees). |
    | `POST /v1/estimates` | **Simular** la tarifa de un paquete específico antes de confirmar la transacción. Útil para mostrar al usuario final el costo antes de ejecutar. Consulta la [referencia de la API Simulate Fees](/es/reference/midaz/plugins/fees-engine/simulate-fees).            |
  </Accordion>

  <Accordion title="¿Cómo funciona /v1/fees?">
    El endpoint recibe los datos de la transacción y el sistema **busca automáticamente** los paquetes aplicables, considerando:

    * `ledgerId` — obligatorio
    * `segmentId` — opcional
    * `transactionRoute` — opcional
    * Valor de la transacción — comparado con `minimumAmount`/`maximumAmount` del paquete

    Las tarifas de todos los paquetes correspondientes se calculan y retornan.
  </Accordion>

  <Accordion title="¿Cómo funciona /v1/estimates?">
    El `/v1/estimates` permite simular la tarifa de un **paquete específico** (`packageId`), sin necesitar una transacción real. Ideal para:

    * Mostrar el costo estimado al usuario antes de confirmar.
    * Probar configuraciones de paquetes recién creados.
    * Construir simuladores de tarifas en tu producto.
  </Accordion>

  <Accordion title="¿Puedo usar /v1/estimates en producción para mostrar tarifas al usuario final?">
    Sí. El `/v1/estimates` es un endpoint de solo lectura — no altera estado ni registra transacciones. Es seguro usarlo en flujos de UX para mostrar el costo antes de la confirmación.
  </Accordion>

  <Accordion title="¿Cómo calcular el billing?">
    Después de configurar los Billing Packages, usa el endpoint:

    ```
    POST /v1/billing/calculate
    ```

    Este endpoint procesa las reglas configuradas y genera los cobros para el período informado. Consulta la [referencia de la API Calculate Billing](/es/reference/midaz/plugins/fees-engine/calculate-billing).
  </Accordion>
</AccordionGroup>

### Errores Comunes

<AccordionGroup>
  <Accordion title="&#x22;Priority 1 must use originalAmount&#x22; — ¿qué significa?">
    La tarifa con `priority: 1` debe obligatoriamente tener `referenceAmount: "originalAmount"`. Esto ocurre porque es la primera en calcularse — no hay tarifas anteriores sobre las cuales basar el cálculo.

    **Corrección:**

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

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

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

  <Accordion title="&#x22;Flat fee value cannot exceed minimumAmount&#x22; — ¿por qué?">
    Cuando `isDeductibleFrom: true` y el tipo es `flat`, el valor de la tarifa no puede ser mayor que el `minimumAmount` del paquete. Esto evita escenarios donde la tarifa supera el valor mínimo de la propia transacción.

    **Ejemplo:** Si `minimumAmount: 100`, la tarifa flat no puede exceder 100.
  </Accordion>

  <Accordion title="&#x22;Percentage value cannot exceed 100&#x22; — ¿cuándo ocurre?">
    Este error ocurre cuando `isDeductibleFrom: true` y el tipo es `percentage` con un valor superior a 100. Una tarifa porcentual deducible del 100% anularía el valor de la transacción — valores superiores son inválidos.
  </Accordion>

  <Accordion title="&#x22;Tiers must be contiguous&#x22; — ¿cómo corregir?">
    Los tiers de billing de volumen deben cubrir todos los rangos sin brechas. Verifica que el `minQuantity` de cada tier sea exactamente `maxQuantity + 1` del tier anterior.

    ```json theme={null}
    // ❌ Incorrecto — brecha entre 500 y 600
    { "minQuantity": 0, "maxQuantity": 500, "unitPrice": "0.80" },
    { "minQuantity": 600, "unitPrice": "0.40" }

    // ✅ Correcto
    { "minQuantity": 0, "maxQuantity": 500, "unitPrice": "0.80" },
    { "minQuantity": 501, "unitPrice": "0.40" }
    ```
  </Accordion>

  <Accordion title="&#x22;Last tier must be unbounded&#x22; — ¿qué significa?">
    El último tier en el billing de volumen debe ser **sin límite superior** (sin `maxQuantity`). Esto garantiza que las transacciones por encima del mayor rango definido aún sean tarifadas.
  </Accordion>

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

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

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

  <Accordion title="¿El campo aliases en accountTarget tiene algún límite?">
    Sí. El campo `aliases` acepta un máximo de **100 aliases** por Billing Package de tipo `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}
    // ✅ Correcto
    "calculationModel": {
      "applicationRule": "flatFee",
      "calculations": [{ "type": "flat", "value": "10.00" }]
    }
    ```
  </Accordion>

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

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

  <Accordion title="El paquete no se está aplicando a la transacción — ¿qué verificar?">
    Lista de verificación — consulta también [Mejores Prácticas](/es/midaz/fees/fees-engine-best-practices):

    * **`enable`:** ¿el paquete está activo (`enable: true`)?
    * **`ledgerId`:** ¿el paquete está vinculado al ledger correcto?
    * **`minimumAmount` / `maximumAmount`:** ¿el valor de la transacción está dentro del rango?
    * **`transactionRoute`:** si el paquete tiene `transactionRoute`, ¿la transacción usa la misma ruta?
    * **`segmentId`:** si el paquete está vinculado a un segmento específico, ¿la cuenta pertenece a él?
    * **`waivedAccounts`:** ¿la cuenta está listada como exenta?
  </Accordion>

  <Accordion title="¿Se puede recuperar un registro eliminado?">
    Técnicamente, los registros son soft-deleted (marcados con `deletedAt`) y no se eliminan de la base de datos. Sin embargo, la API no expone endpoints de restauración por defecto. Contacta al equipo de Lerian si necesitas recuperar un registro eliminado accidentalmente. Para la lista completa de códigos de error, consulta la [referencia de Códigos de Error](/es/reference/midaz/plugins/fees-engine/fee-engine-error-list).
  </Accordion>
</AccordionGroup>