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

# Planes de tarifas

> Asigna un plan de tarifas a una cuenta, con una cuota gratuita por comisión y mes calendario, y cobra sus comisiones de servicio.

Un **plan de tarifas** es un conjunto de comisiones que asignas a una cuenta. Cada comisión tiene una cuota gratuita: un número de unidades en cada mes calendario que no cuestan nada. Un plan de tarifas tiene dos tipos de comisión:

* Las **comisiones de transacción** se aplican a las transacciones `/v2` que envía la cuenta.
* Las **comisiones de servicio** se aplican cuando cobras un servicio a la cuenta, por ejemplo un extracto en papel. Las cobras con un [cobro de comisiones](#service-fees-and-fee-charges).

Creas planes de tarifas y los asignas mediante la API. Cada cuenta tiene como máximo un plan de tarifas activo.

## Planes de tarifas y paquetes de comisiones

***

Un plan de tarifas y un [paquete de comisiones](https://docs.lerian.studio/es/products/midaz/fees/fees-engine-overview.md#fee-packages) son entidades diferentes.

* Una cuenta con un plan de tarifas activo paga las comisiones de su plan en las transacciones `/v2` que envía. En esas transacciones, un paquete de comisiones nunca cobra a esa cuenta, también cuando ninguna comisión del plan coincide. Entonces la cuenta no paga comisión.
* Un paquete de comisiones no cobra los asientos de comisión que agrega un plan de tarifas.

| | Paquetes de comisiones | Planes de tarifas |
| - | - | - |
| **Selecciona** | Transacciones, por ruta, segmento, metadatos y monto | Las cuentas que asignas al plan |
| **Cuota gratuita** | No | Sí, por comisión y mes calendario |
| **Comisiones de servicio** | No | Sí, mediante cobros de comisiones |
| **Comisiones deducibles** | Sí (`isDeductibleFrom`) | No |
| **Comisiones diferibles** | Sí (`deferrable`) | No |
| **Redondeo** | Sí (`rounding`) | No |

## Crea un plan de tarifas

***

Crea un plan con [Crear un plan de tarifas](https://docs.lerian.studio/es/reference/products/midaz/v2/create-an-account-plan.md). El plan tiene estos campos:

* `label`: el nombre del plan. Dos planes de un ledger que no se eliminaron no pueden tener el mismo label (`0543`).
* `description`: opcional.
* `enable`: `true` permite asignar el plan a cuentas.
* `timezone`: la zona horaria IANA en la que el plan cuenta sus meses. El valor predeterminado es `America/Sao_Paulo`.
* `fees`: al menos una comisión, por clave de comisión. Una clave de comisión empieza con una letra minúscula, seguida solo de letras y dígitos ASCII (`^[a-z][a-zA-Z0-9]*$`).

Cada comisión tiene estos campos:

* `feeLabel`: el nombre de la comisión.
* `trigger`: lo que hace que la comisión se aplique. Consulta [Disparadores](#triggers).
* `calculationModel`: `flatFee`, `percentual` o `maxBetweenTypes`, como en un [paquete de comisiones](https://docs.lerian.studio/es/products/midaz/fees/fee-engine-calculation.md#fee-calculation-rules). Una comisión de servicio acepta solo `flatFee` (`0555`).
* `creditAccount`: el alias de la cuenta del ledger que recibe la comisión. Midaz verifica que la cuenta exista cuando creas o actualizas el plan.
* `accounting`: el `transactionRoute`, el `operationRouteFrom` y el `operationRouteTo` de la comisión. Consulta [Rutas contables](#accounting-routes).
* `freeQuota`: el número de unidades gratuitas por mes. El valor predeterminado es `0`.
* `period`: solo `monthly`, el valor predeterminado.
* `referenceAmount`: solo `originalAmount`, el valor predeterminado.

### Disparadores

Un disparador con `type: transaction` acepta estos campos:

* `direction`: obligatorio. El único valor es `sent`: la comisión se aplica a la cuenta que envía la transacción.
* `schemes`: los esquemas de transacción con los que coincide la comisión, por ejemplo `TED` o `PIX`.
* `metadata`: pares opcionales que los metadatos de la transacción deben llevar todos. Un par coincide solo con un valor de metadato de tipo string igual a él.

Un disparador con `type: service` acepta solo `serviceCode`, por ejemplo `PAPER_STATEMENT`.

Midaz almacena los esquemas y los códigos de servicio sin espacios en los extremos y en mayúsculas. Cada uno tiene de 1 a 50 letras, dígitos, guiones bajos o guiones. Un código no puede ser el esquema de una comisión y el código de servicio de otra comisión del plan (`0558`).

### Rutas contables

Las reglas dependen de si el ledger valida las rutas contables (`accounting.validateRoutes` en la [configuración del ledger](https://docs.lerian.studio/es/products/midaz/ledgers.md)):

| Regla | Ledger sin validación de rutas | Ledger con validación de rutas |
| - | - | - |
| Comisión de transacción | Lista al menos un esquema (`0556`). | Una comisión sin esquemas coincide con cada esquema de su ruta de transacción. |
| `accounting` | Opcional. | Obligatorio en cada comisión, con un `transactionRoute` (`0547`) que existe (`0105`) y las dos rutas de operación (`0557`). |
| Rutas de operación | No se verifican. | Las dos están vinculadas a la ruta de transacción de la comisión. En una comisión de transacción, las dos son vínculos opcionales (`optionalOperationRoutes`) (`0557`). |

Dos comisiones de transacción de un plan con los mismos `metadata` no pueden seleccionar las mismas transacciones (`0544`). En un ledger sin validación de rutas, no pueden compartir un esquema. En un ledger con validación de rutas, no pueden compartir una ruta de transacción y un esquema, y una comisión sin esquemas ocupa cada esquema de su ruta. Dos comisiones de servicio no pueden compartir un código de servicio (`0544`).

Si activas la validación de rutas después de crear un plan, da antes a cada comisión una ruta de transacción y las dos rutas de operación. Una comisión sin ruta de transacción rechaza con `0547` cada transacción con la que coincidiría, y cada cobro de comisiones que la nombra.

## Versiones

***

Las comisiones de un plan viven en versiones. Una versión nunca cambia.

* La creación genera la versión 1, vigente desde el instante de la creación.
* Una [actualización](https://docs.lerian.studio/es/reference/products/midaz/v2/update-an-account-plan.md) que envía `fees` genera una nueva versión con el conjunto completo de comisiones resultante.
* `effectiveFrom` define el instante desde el que se aplica la nueva versión, en RFC 3339. El valor predeterminado es el instante de la solicitud. No puede ser anterior al `effectiveFrom` de la versión más reciente (`0553`). Envíalo solo con `fees`.
* `label`, `description`, `enable` y `timezone` cambian el plan, no una versión.

En los `fees` de una actualización:

* Una entrada con la clave de una comisión almacenada cambia los campos que envía y conserva los demás. `trigger`, `calculationModel` y `accounting` cambian completos.
* Una entrada vacía (`{}`) elimina esa comisión.
* Una entrada con una clave nueva agrega una comisión, con cada campo obligatorio.
* La nueva versión parte de las comisiones de la versión más reciente. Conserva al menos una comisión.

Cuando dos actualizaciones crean una versión del mismo plan al mismo tiempo, una de ellas recibe `0559` y no crea ninguna versión. Lee el plan de nuevo y envía la actualización de nuevo.

[Obtener un plan de tarifas](https://docs.lerian.studio/es/reference/products/midaz/v2/get-an-account-plan.md) devuelve la versión vigente en el instante de la solicitud. `currentVersion` es la versión más alta creada, que puede empezar después. [Listar las versiones de un plan de tarifas](https://docs.lerian.studio/es/reference/products/midaz/v2/list-the-versions-of-an-account-plan.md) devuelve cada versión.

## Asigna un plan a una cuenta

***

[Asignar un plan de tarifas a una cuenta](https://docs.lerian.studio/es/reference/products/midaz/v2/assign-an-account-plan-to-an-account.md) envía el `accountPlanId` del plan.

* El plan debe pertenecer al ledger, existir y estar habilitado (`0545`).
* Si la cuenta tiene una asignación activa de otro plan, termina en el instante en que empieza la nueva asignación, en un solo paso.
* Si la cuenta ya tiene el mismo plan, Midaz devuelve la asignación activa y no cambia nada.
* Cuando otra asignación de la misma cuenta ocurre al mismo tiempo, Midaz puede responder `0560` y no cambiar nada. Envía la solicitud de nuevo.

[Obtener la asignación de plan de tarifas de una cuenta](https://docs.lerian.studio/es/reference/products/midaz/v2/get-the-account-plan-assignment-of-an-account.md) devuelve la asignación activa, o `null`, y el historial de la cuenta. [Listar las cuentas asignadas a un plan de tarifas](https://docs.lerian.studio/es/reference/products/midaz/v2/list-the-accounts-assigned-to-an-account-plan.md) devuelve las asignaciones activas de un plan.

[Terminar la asignación de plan de tarifas de una cuenta](https://docs.lerian.studio/es/reference/products/midaz/v2/end-the-account-plan-assignment-of-an-account.md) termina la asignación activa. Los paquetes de comisiones vuelven entonces a aplicarse a la cuenta. Una cuenta sin asignación activa responde `0554`.

### Deshabilita o elimina un plan

* Un plan deshabilitado (`enable: false`) no se puede asignar. Sigue cobrando a las cuentas que ya tiene.
* Midaz rechaza eliminar un plan asignado a una cuenta (`0546`). Termina antes sus asignaciones.
* Cuando eliminas una cuenta, Midaz termina su asignación activa. El historial de la cuenta sigue legible.

## Cómo un plan cobra una transacción

***

Midaz aplica los planes de tarifas a estas transacciones `/v2`: direct, hold, block, unblock y cada elemento de un lote. Una transacción `/v1`, una anotación, una reversión y una transacción que omite las comisiones con `skip.fees` no usan planes de tarifas.

Midaz toma una decisión para cada cuenta de origen de la transacción que tiene un plan activo, excepto las cuentas `@external`. Toma una decisión por cuenta, también cuando la cuenta envía desde varios saldos.

### Coincidencia

Las comisiones de la versión vigente se comparan con la transacción:

* En un ledger sin validación de rutas, una comisión de transacción coincide cuando sus `schemes` contienen el `scheme` de la transacción. Una transacción sin `scheme` no coincide con ninguna comisión.
* En un ledger con validación de rutas, una comisión de transacción coincide cuando su `transactionRoute` es el `routeId` de la transacción y sus `schemes` están vacíos o contienen el `scheme` de la transacción.
* En los dos casos, los metadatos de la transacción deben llevar cada par de `metadata` de la comisión.
* Cuando varias comisiones coinciden, se aplica la comisión con más pares de `metadata`. Cuando dos o más comisiones tienen ese número de pares, Midaz rechaza la transacción con `0548`.

### Resultado

La decisión tiene uno de estos resultados:

| Resultado | Qué ocurre |
| - | - |
| `quota` | Una comisión coincidió, y la unidad está dentro de la cuota gratuita. La cuenta no paga comisión. |
| `charged` | Una comisión coincidió, y la unidad superó la cuota gratuita. Midaz agrega la comisión por encima de lo que envía la cuenta y la acredita en `creditAccount`. |
| `no_match` | Ninguna comisión coincidió. La cuenta no paga comisión, y no se cuenta ninguna unidad. |

Midaz calcula una comisión cobrada sobre el monto que envía la cuenta en la transacción. En un ledger con validación de rutas, los asientos de comisión usan las rutas de operación de la comisión.

La respuesta de creación tiene `accountPlanFees`, con un elemento para cada cuenta que tiene un plan activo: `accountId`, `accountAlias`, `accountPlanId`, `accountPlanVersion`, `feeKey`, `outcome`, `unit`, `freeQuota` y `amount`. Solo las respuestas de creación lo devuelven. Las lecturas, los commits, las cancelaciones y las reversiones no. Las claves de metadatos de la transacción `packageAppliedID`, `feeApplied` y `feeExemption` describen solo paquetes de comisiones.

### Holds, cancelaciones y reversiones

* Un hold cuenta la unidad cuando lo creas. El commit no cuenta nada.
* Una cancelación o una reversión devuelve la unidad solo en el mismo mes del plan. La reversión también revierte los asientos de comisión.

## Cuota gratuita

***

Una unidad es una decisión con el resultado `quota` o `charged`, o un código de servicio de un cobro de comisiones con los mismos resultados.

* Midaz cuenta unidades por cuenta, clave de comisión y mes calendario en la zona horaria del plan.
* El conteo pertenece a la cuenta y a la clave de comisión, no al plan. Una cuenta que pasa a otro plan con la misma clave de comisión conserva su conteo del mes.
* Una comisión de transacción cuenta cada esquema por separado. En un ledger con validación de rutas, una comisión sin esquemas tiene un conteo para todos los esquemas de su ruta. Una comisión de servicio tiene un conteo.
* Cuando cambias una comisión, su conteo se conserva. Una comisión con una clave nueva empieza en cero.
* El mes es el mes en que Midaz procesa la transacción, no su `transactionDate`.

## Comisiones de servicio y cobros de comisiones

***

[Cobrar comisiones de servicio a una cuenta](https://docs.lerian.studio/es/reference/products/midaz/v2/charge-service-fees-to-an-account.md) envía `serviceCodes`, con 1 a 100 códigos, y `description` y `metadata` opcionales. La solicitud necesita el header `X-Idempotency` (`0552`).

Cada código de la lista es una unidad. Su resultado es uno de estos:

* `quota`: la unidad está dentro de la cuota gratuita de su comisión. No cuesta nada.
* `charged`: la unidad superó la cuota gratuita. Cuesta el monto fijo de la comisión.
* `not_covered`: el plan de la cuenta no tiene comisión de servicio para el código, o la cuenta no tiene plan activo. No cuesta nada y no cuenta unidad.

Midaz rechaza la solicitud antes de cobrar nada cuando:

* Ningún plan de tarifas del ledger tiene una comisión de servicio para un código (`0549`).
* Un código pertenece solo a comisiones de transacción (`0550`).
* En un ledger con validación de rutas, las comisiones de los códigos tienen rutas de transacción diferentes (`0551`), o una comisión no tiene ruta de transacción (`0547`).

Midaz registra las unidades cobradas como una transacción de comisión en el activo de la cuenta. Debita la cuenta y acredita el `creditAccount` de cada comisión. En un ledger con validación de rutas, la transacción usa la ruta de transacción y las rutas de operación de las comisiones. La `description` y los `metadata` del cobro van a la transacción de comisión. Ningún paquete de comisiones, plan de tarifas ni validación de Tracer se aplica a la transacción de comisión. Cuando Midaz rechaza la transacción de comisión, por ejemplo por fondos insuficientes, rechaza el cobro con el mismo error y no cuenta unidad.

Un cobro sin unidad cobrada no tiene transacción de comisión, y su `feeTransactionIds` queda vacío. Nada deshace ese cobro, y sus unidades siguen contadas.

* Un reintento con la misma clave y el mismo cuerpo devuelve el cobro registrado con el header `X-Idempotency-Replayed`. Un cuerpo diferente con la misma clave responde `0084`. Las claves son únicas por cuenta.
* Para deshacer un cobro, revierte su transacción de comisión. Una reversión en el mismo mes devuelve cada unidad del cobro.
* La transacción de comisión no tiene referencia a su cobro. El `feeTransactionIds` del cobro los vincula.

[Listar los cobros de comisiones de una cuenta](https://docs.lerian.studio/es/reference/products/midaz/v2/list-the-fee-charges-of-an-account.md) devuelve primero el cobro más reciente, y `period` (`YYYY-MM`) filtra la lista. [Obtener un cobro de comisiones de una cuenta](https://docs.lerian.studio/es/reference/products/midaz/v2/get-a-fee-charge-of-an-account.md) devuelve un cobro.

## Uso

***

[Obtener el uso del plan de tarifas de una cuenta](https://docs.lerian.studio/es/reference/products/midaz/v2/get-the-account-plan-usage-of-an-account.md) devuelve las unidades de la cuenta en un mes. `period` (`YYYY-MM`, en la zona horaria del plan) selecciona el mes. El valor predeterminado es el mes actual. Un `period` futuro o mal formado responde `0082`, y una cuenta sin plan activo responde `0554`.

La respuesta tiene un elemento para cada conteo de cada comisión: `feeKey`, `trigger`, `period`, `freeQuota`, `used`, `remaining` y `charged`. `trigger` es una clave del conteo: lee `feeKey` en lugar de interpretarla. `remaining` nunca es negativo.

El uso lista las comisiones y las cuotas gratuitas de la versión vigente ahora, también para un mes pasado. Para la conciliación, usa el `accountPlanFees` de las respuestas de creación y los cobros de comisiones.

## Estimaciones y eventos

***

* Una [estimación de comisiones](https://docs.lerian.studio/es/reference/products/midaz/v2/estimate-fee-calculation.md) calcula el precio del paquete de comisiones que nombras. No lee las asignaciones de planes de tarifas.
* El evento `fee_charge.applied` cubre solo paquetes de comisiones. Una comisión de un plan de tarifas o un cobro de comisiones no lo emite.

## Permisos

***

Las rutas usan estos recursos de permiso de Midaz:

| Recurso | Acción | Uso |
| - | - | - |
| `account-plans` | `get` | Leer planes, versiones, cuentas asignadas, asignaciones y uso. |
| `account-plans` | `post` | Crear un plan. |
| `account-plans` | `patch` | Actualizar un plan. |
| `account-plans` | `put` | Asignar un plan a una cuenta. |
| `account-plans` | `delete` | Eliminar un plan, o terminar la asignación de una cuenta. |
| `fee-charges` | `get` | Leer cobros de comisiones. |
| `fee-charges` | `post` | Cobrar comisiones de servicio. |

## Próximos pasos

***

> [card] [Usar planes de tarifas](https://docs.lerian.studio/es/products/midaz/fees/using-account-plans.md)
>
> Crea un plan, asígnalo y cobra comisiones paso a paso.

> [card] [Lista de errores de Midaz](https://docs.lerian.studio/es/reference/products/midaz/error-list.md)
>
> Consulta los códigos de `0543` a `0560`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.