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

# Reglas de tarifas

> Configura fee schedules y reglas de predicados que usa la normalización NET o GROSS cuando el lado y las monedas son compatibles.

El manejo de tarifas en Matcher se divide en dos entidades que trabajan juntas:

* Un **fee schedule** define *cuánto* calcular de tarifa — la moneda, el redondeo y uno o más fee items (fijo, porcentaje, escalonado o basado en expresión).
* Una **fee rule** decide *cuándo* se aplica un fee schedule. Pertenece a un contexto de conciliación, apunta a un lado de coincidencia y lleva predicados que los metadatos de una transacción deben satisfacer. Cuando los predicados coinciden, la regla selecciona su fee schedule.

Cuando la normalización de tarifas está habilitada y las monedas de la transacción y el schedule coinciden, modelar las tarifas esperadas de esta forma permite que Matcher tenga en cuenta cargos predecibles antes de comparar transacciones.

## Qué resuelve el manejo de tarifas

***

La conciliación falla cuando un lado de una transacción incluye tarifas o cargos que el otro lado no registra. Un gateway de pagos deduce una comisión de procesamiento antes de liquidar. Un banco cobra una comisión por transferencia bancaria. Un adquirente descuenta comisiones de los pagos.

Sin tarifas modeladas, Matcher trata estas diferencias como discrepancias de monto y genera excepciones — incluso cuando la diferencia es esperada y documentada. Los fee schedules describen el cargo, y las fee rules seleccionan cuándo usarlo durante la normalización de tarifas habilitada.

## Cómo encajan las reglas y los schedules

***

Una fee rule no contiene el monto de la tarifa ni el cálculo en sí. **Referencia** un fee schedule por ID y lo aplica a las transacciones que seleccionan sus predicados.

1. Un **fee schedule** se crea una vez a nivel de tenant y puede ser reutilizado por muchas reglas en muchos contextos.
2. Una **fee rule** se crea dentro de un contexto. Establece un `side`, un `feeScheduleId`, una `priority` y una lista de `predicates`.
3. Cuando Matcher procesa un contexto con la normalización de tarifas habilitada, evalúa las fee rules del lado relevante en orden de `priority` (primero el más bajo). La primera regla que coincide selecciona el schedule referenciado.

Esta separación significa que cambias *cómo* se calcula una tarifa editando el schedule, y cambias *cuándo* se aplica editando la regla — sin tocar la otra.

<Note>
  Una fee rule por sí sola no cambia los montos de comparación. La evaluación de fee rules solo afecta la conciliación de tarifas cuando el contexto establece `feeNormalization` en `NET` o `GROSS`, el lado relevante tiene reglas y las monedas de la transacción y el schedule coinciden.
</Note>

## Estructura de una fee rule

***

Una fee rule pertenece a un contexto y tiene los siguientes campos.

| Campo           | Tipo    | Descripción                                                                                                                                                                        |
| --------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `side`          | Enum    | A qué lado de coincidencia se aplica la regla: `LEFT`, `RIGHT` o `ANY`. `ANY` coincide con transacciones en cualquiera de los lados.                                               |
| `feeScheduleId` | UUID    | El fee schedule que esta regla aplica cuando sus predicados coinciden.                                                                                                             |
| `name`          | String  | Nombre legible de la fee rule.                                                                                                                                                     |
| `priority`      | Integer | Prioridad de evaluación; los números más bajos se evalúan primero. Debe ser único dentro del contexto. Las reglas `LEFT`, `RIGHT` y `ANY` comparten el mismo espacio de prioridad. |
| `predicates`    | Array   | Predicados (unidos con AND) que los metadatos de una transacción deben satisfacer para que esta regla se aplique.                                                                  |

### Predicados

Cada predicado prueba un campo de metadatos de la transacción con un operador.

| Campo      | Descripción                                                                           |
| ---------- | ------------------------------------------------------------------------------------- |
| `field`    | El campo de metadatos de la transacción que el predicado prueba (ej., `institution`). |
| `operator` | El operador de comparación (ver abajo).                                               |
| `value`    | Valor único de comparación, usado por `EQUALS`, `NEQ` y los comparadores numéricos.   |
| `values`   | Lista de valores candidatos, usada por `IN` y `BETWEEN`.                              |

**Operadores disponibles:**

| Operador                    | Significado                                                                                                                                                        |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `EQUALS`                    | Igualdad de cadenas sin distinción de mayúsculas con un único `value`.                                                                                             |
| `NEQ`                       | Para un campo presente, desigualdad numérica cuando ambos valores se convierten a decimales; de lo contrario, desigualdad de cadenas sin distinción de mayúsculas. |
| `IN`                        | Coincide con cualquier entrada de `values`.                                                                                                                        |
| `EXISTS`                    | Verifica que el campo está presente (no se necesita valor).                                                                                                        |
| `GT` / `GTE` / `LT` / `LTE` | Comparación numérica del campo contra un único `value` decimal.                                                                                                    |
| `BETWEEN`                   | Pertenencia numérica inclusiva en `values` = `[lo, hi]` (con `lo <= hi`).                                                                                          |

Los campos ausentes se evalúan como `false` para todos los operadores excepto `EXISTS`.

## Estructura de un fee schedule

***

Un fee schedule es una entidad a nivel de tenant que calcula una tarifa a partir de un monto bruto.

| Campo              | Tipo    | Descripción                                                                                                                                                   |
| ------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`             | String  | Nombre legible del schedule.                                                                                                                                  |
| `currency`         | String  | Moneda ISO 4217 en la que se denominan los montos del schedule.                                                                                               |
| `applicationOrder` | Enum    | Cómo se combinan los items: `PARALLEL` aplica cada item a la misma base bruta; `CASCADING` aplica cada item al neto restante después de los items anteriores. |
| `roundingScale`    | Integer | Número de decimales a los que se redondean los montos de tarifa.                                                                                              |
| `roundingMode`     | Enum    | Estrategia de redondeo: `HALF_UP`, `BANKERS`, `FLOOR`, `CEIL` o `TRUNCATE`.                                                                                   |
| `items`            | Array   | Uno o más fee items que componen el schedule (se requiere al menos uno).                                                                                      |

### Fee items

Cada item declara un `name`, una `priority` (orden de aplicación, relevante para `CASCADING`), un `structureType` y una `structure` específica del tipo.

| `structureType` | Forma de `structure`                                       | Notas                                                                                                                                                                                                                                                                                                     |
| --------------- | ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `FLAT`          | `{ "amount": "1.50" }`                                     | Monto fijo.                                                                                                                                                                                                                                                                                               |
| `PERCENTAGE`    | `{ "rate": "0.029" }`                                      | `rate` es una fracción `0..1` de la base (`0.029` = 2.9%), **no** un valor porcentual.                                                                                                                                                                                                                    |
| `TIERED`        | `{ "tiers": [ { "rate": "0.01", "upTo": "1000" }, ... ] }` | La misma semántica de fracción `0..1` por tasa de tramo.                                                                                                                                                                                                                                                  |
| `EXPRESSION`    | `{ "expression": "gross - desconto + multa" }`             | Fórmula sobre identificadores (`+ - * /`, paréntesis y las funciones `days_late`, `days_between`, `max`, `min`, `abs`, `clamp`). `gross` es el monto base suministrado por el motor y reemplaza cualquier clave de metadatos llamada `gross`; los demás identificadores se resuelven desde los metadatos. |

## Gestión de fee schedules

***

Los fee schedules tienen alcance de tenant y se gestionan de forma independiente de cualquier contexto.

| Operación                    | Endpoint                                       |
| ---------------------------- | ---------------------------------------------- |
| Crear un fee schedule        | `POST /v1/fee-schedules`                       |
| Listar fee schedules         | `GET /v1/fee-schedules`                        |
| Obtener un fee schedule      | `GET /v1/fee-schedules/{scheduleId}`           |
| Actualizar un fee schedule   | `PATCH /v1/fee-schedules/{scheduleId}`         |
| Eliminar un fee schedule     | `DELETE /v1/fee-schedules/{scheduleId}`        |
| Simular un cálculo de tarifa | `POST /v1/fee-schedules/{scheduleId}/simulate` |

### Crear un fee schedule

Este schedule calcula una comisión de procesamiento del 2.9% sobre el monto bruto, denominada en BRL.

```bash cURL theme={null}
curl -X POST "https://api.matcher.example.com/v1/fee-schedules" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "name": "Gateway Processing - 2.9%",
   "currency": "BRL",
   "applicationOrder": "PARALLEL",
   "roundingScale": 2,
   "roundingMode": "HALF_UP",
   "items": [
     {
       "name": "processing",
       "priority": 1,
       "structureType": "PERCENTAGE",
       "structure": { "rate": "0.029" }
     }
   ]
 }'
```

<Tip>Referencia de la API: [Crear fee schedule](/es/reference/matcher/create-fee-schedule) · [Listar fee schedules](/es/reference/matcher/list-fee-schedules) · [Consultar fee schedule](/es/reference/matcher/retrieve-fee-schedule) · [Actualizar fee schedule](/es/reference/matcher/update-fee-schedule) · [Eliminar fee schedule](/es/reference/matcher/delete-fee-schedule)</Tip>

### Simular un fee schedule

Antes de conectar un schedule a una regla, simúlalo contra un monto bruto para confirmar la tarifa calculada.

```bash cURL theme={null}
curl -X POST "https://api.matcher.example.com/v1/fee-schedules/{scheduleId}/simulate" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "grossAmount": "100.00",
   "currency": "BRL"
 }'
```

La respuesta devuelve el `netAmount`, el `totalFee` y un desglose por item.

<Tip>Referencia de la API: [Simular cálculo de tarifa](/es/reference/matcher/simulate-fee-schedule)</Tip>

<Note>
  Un fee schedule no se puede eliminar mientras una fee rule o el historial de variaciones de tarifas lo referencie. La solicitud devuelve `409 Conflict` con el código `MTCH-0108`; el problema de la API no lista los contextos que bloquean la eliminación. Elimina o reapunta primero las referencias de reglas actuales. Las referencias del historial de variaciones continúan bloqueando la eliminación.
</Note>

## Gestión de fee rules

***

Las fee rules se crean dentro de un contexto y referencian un fee schedule.

| Operación                       | Endpoint                                  |
| ------------------------------- | ----------------------------------------- |
| Crear una fee rule              | `POST /v1/contexts/{contextId}/fee-rules` |
| Listar fee rules de un contexto | `GET /v1/contexts/{contextId}/fee-rules`  |
| Obtener una fee rule            | `GET /v1/fee-rules/{feeRuleId}`           |
| Actualizar una fee rule         | `PATCH /v1/fee-rules/{feeRuleId}`         |
| Eliminar una fee rule           | `DELETE /v1/fee-rules/{feeRuleId}`        |

### Crear una fee rule

Esta regla aplica el fee schedule creado arriba a las transacciones del lado derecho cuyos metadatos `institution` sean iguales a `Banco do Brasil`.

```bash cURL theme={null}
curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/fee-rules" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "side": "RIGHT",
   "feeScheduleId": "550e8400-e29b-41d4-a716-446655440000",
   "name": "BB Right-Side Processing Fee",
   "priority": 0,
   "predicates": [
     {
       "field": "institution",
       "operator": "EQUALS",
       "value": "Banco do Brasil"
     }
   ]
 }'
```

<Tip>Referencia de la API: [Crear fee rule](/es/reference/matcher/create-fee-rule) · [Listar fee rules](/es/reference/matcher/list-fee-rules) · [Consultar fee rule](/es/reference/matcher/retrieve-fee-rule) · [Actualizar fee rule](/es/reference/matcher/update-fee-rule) · [Eliminar fee rule](/es/reference/matcher/delete-fee-rule)</Tip>

## Flujo de extremo a extremo

***

Poniéndolo todo junto, el manejo de tarifas esperadas sigue tres pasos:

<Steps>
  <Step title="Crea el fee schedule">
    Define cómo se calcula la tarifa una vez a nivel de tenant con `POST /v1/fee-schedules`. Opcionalmente valídalo con el endpoint de simulación. Anota el `id` devuelto.
  </Step>

  <Step title="Crea la fee rule en el contexto">
    Dentro del contexto de conciliación, crea una fee rule con `POST /v1/contexts/{contextId}/fee-rules`. Establece `feeScheduleId` al `id` del schedule, elige el `side`, define una `priority` única y agrega los `predicates` que seleccionan las transacciones a las que se aplica la tarifa.
  </Step>

  <Step title="Aplica durante la coincidencia">
    Establece `feeNormalization` del contexto en `NET` o `GROSS`. Durante la coincidencia, Matcher evalúa las reglas de cada lado relevante en orden de `priority`. Una regla coincidente solo cambia el monto de comparación cuando su schedule y la transacción usan la misma moneda.
  </Step>
</Steps>

## Mejores prácticas

***

<AccordionGroup>
  <Accordion title="Reutiliza schedules entre contextos">
    Un fee schedule tiene alcance de tenant y puede ser referenciado por muchas reglas. Define un schedule una vez (ej., "Card Processing - Visa") y apunta reglas de distintos contextos hacia él. Editar el schedule actualiza todas las reglas que lo usan.
  </Accordion>

  <Accordion title="Mantén las prioridades únicas e intencionales">
    Las prioridades son únicas dentro de un contexto y compartidas entre las reglas `LEFT`, `RIGHT` y `ANY`. Ordénalas de la más específica a la más general para que una regla estrecha gane antes que un respaldo amplio.
  </Accordion>

  <Accordion title="Delimita las reglas con predicados precisos">
    Los predicados se unen con AND y se prueban contra los metadatos de la transacción. Combina operadores (`EQUALS`, `IN`, `BETWEEN`, `EXISTS`) para apuntar exactamente a las transacciones a las que se aplica una tarifa y evitar la atribución de tarifas no deseada.
  </Accordion>

  <Accordion title="Simula antes de conectar un schedule a una regla">
    Usa `POST /v1/fee-schedules/{scheduleId}/simulate` para confirmar que un schedule produce la tarifa esperada para montos representativos antes de referenciarlo desde una regla.
  </Accordion>

  <Accordion title="Reapunta las reglas antes de eliminar un schedule">
    Un schedule referenciado por una regla o por el historial de variaciones de tarifas no se puede eliminar (`409 MTCH-0108`). La respuesta de conflicto no lista los contextos que lo bloquean. Actualiza o elimina primero las referencias de reglas actuales; las referencias históricas de variaciones continúan bloqueando la eliminación.
  </Accordion>
</AccordionGroup>

## Próximos pasos

***

<Card title="Reglas de conciliación" icon="scale-balanced" href="/es/matcher/configuration/matcher-match-rules" horizontal>
  Configura cómo se comparan las transacciones una vez que se tienen en cuenta las tarifas esperadas.
</Card>

<Card title="Enrutamiento de excepciones" icon="route" href="/es/matcher/configuration/matcher-exception-routing" horizontal>
  Revisa la asignación explícita, el despacho y los callbacks de las excepciones que el manejo de tarifas no cubre.
</Card>

<Card title="Referencia de la API de fee schedules" icon="code" href="/es/reference/matcher/create-fee-schedule" horizontal>
  Referencia completa de la API para los endpoints de fee schedules.
</Card>

<Card title="Referencia de la API de fee rules" icon="code" href="/es/reference/matcher/create-fee-rule" horizontal>
  Referencia completa de la API para los endpoints de fee rules.
</Card>