> ## 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 comisión

> Configura tablas de comisiones y reglas con predicados que usa la normalización NET o GROSS cuando el lado de coincidencia y las monedas son compatibles.

El manejo de comisiones en Matcher se divide en dos entidades:

* Una **tabla de comisiones** define *cuánta* comisión calcular: la moneda, el redondeo y uno o más ítems de comisión (fijo, porcentual, escalonado o basado en expresión).
* Una **regla de comisión** decide *cuándo* aplica una tabla de comisiones. 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 tabla de comisiones.

Modelar las comisiones esperadas de esta forma permite que Matcher contabilice los cargos predecibles antes de comparar transacciones. Esto aplica cuando habilitas la normalización de comisiones y las monedas de la transacción y de la tabla coinciden.

## Qué resuelve el manejo de comisiones

***

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

Sin comisiones modeladas, Matcher trata estas diferencias como discrepancias de monto y genera excepciones, incluso cuando esperas y documentas la diferencia. Las tablas de comisiones describen el cargo, y las reglas de comisión seleccionan cuándo usarlo durante la normalización de comisiones habilitada.

## Cómo encajan las reglas y las tablas

***

Una regla de comisión no contiene el monto de la comisión ni el cálculo en sí. Referencia una tabla de comisiones por ID y la aplica a las transacciones que seleccionan sus predicados.

1. Creas una **tabla de comisiones** una vez en el nivel del tenant. Muchas reglas de muchos contextos pueden reutilizarla.
2. Creas una **regla de comisión** dentro de un contexto. Define un `side`, un `feeScheduleId`, un `priority` y una lista de `predicates`.
3. Cuando Matcher procesa un contexto con la normalización de comisiones habilitada, evalúa las reglas de comisión del lado relevante en orden de `priority` (el más bajo primero). La primera regla que coincide selecciona la tabla referenciada.

Esta separación significa que cambias *cómo* una tabla de comisiones calcula una comisión editando la tabla. Cambias *cuándo* aplica la comisión editando la regla. Ninguna edición toca a la otra.

<Note>
  Una regla de comisión por sí sola no cambia los montos de comparación. La evaluación de reglas de comisión afecta la conciliación de comisiones solo cuando el contexto pone `feeNormalization` en `NET` o `GROSS`, el lado relevante tiene reglas y las monedas de la transacción y de la tabla coinciden.
</Note>

## Estructura de la regla de comisión

***

Una regla de comisión pertenece a un contexto y tiene los siguientes campos.

| Campo           | Tipo    | Descripción                                                                                                                                                                        |
| --------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `side`          | Enum    | A qué lado de coincidencia aplica la regla: `LEFT`, `RIGHT` o `ANY`. `ANY` coincide con transacciones de cualquiera de los dos lados.                                              |
| `feeScheduleId` | UUID    | La tabla de comisiones que esta regla aplica cuando sus predicados coinciden.                                                                                                      |
| `name`          | String  | Nombre legible de la regla de comisión.                                                                                                                                            |
| `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 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 prueba el predicado (por ejemplo, `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 distinguir mayúsculas y minúsculas con un solo `value`.                                                                                    |
| `NEQ`                       | Para un campo presente, desigualdad numérica cuando ambos valores se convierten a decimales; si no, desigualdad de cadenas sin distinguir mayúsculas y minúsculas. |
| `IN`                        | Coincide con cualquier entrada de `values`.                                                                                                                        |
| `EXISTS`                    | Afirma que el campo está presente (no necesita valor).                                                                                                             |
| `GT` / `GTE` / `LT` / `LTE` | Comparación numérica del campo contra un solo `value` decimal.                                                                                                     |
| `BETWEEN`                   | Pertenencia numérica inclusiva en `values` = `[lo, hi]` (con `lo <= hi`).                                                                                          |

Los campos ausentes se evalúan como `false` para cada operador excepto `EXISTS`.

## Estructura de la tabla de comisiones

***

Una tabla de comisiones es una entidad en el nivel del tenant que calcula una comisión a partir de un monto bruto.

| Campo              | Tipo    | Descripción                                                                                                                                                |
| ------------------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`             | String  | Nombre legible de la tabla.                                                                                                                                |
| `currency`         | String  | Moneda ISO 4217 en la que están denominados los montos de la tabla.                                                                                        |
| `applicationOrder` | Enum    | Cómo se combinan los ítems: `PARALLEL` aplica cada ítem a la misma base bruta; `CASCADING` aplica cada ítem al neto restante después de los ítems previos. |
| `roundingScale`    | Integer | Cantidad de decimales a los que se redondean los montos de comisión.                                                                                       |
| `roundingMode`     | Enum    | Estrategia de redondeo: `HALF_UP`, `BANKERS`, `FLOOR`, `CEIL` o `TRUNCATE`.                                                                                |
| `items`            | Array   | Uno o más ítems de comisión que componen la tabla (se requiere al menos uno).                                                                              |

### Ítems de comisión

Cada ítem declara un `name`, un `priority` (orden de aplicación, relevante para `CASCADING`), un `structureType` y un `structure` específico 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 cada 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 que provee el motor y prevalece sobre cualquier clave de metadatos llamada `gross`; los demás identificadores se resuelven desde los metadatos. Una fórmula que contiene exactamente un `gross` escalado solo por literales numéricos se trata como una tasa porcentual y debe estar dentro de `0..1` (`gross * 0.029` es válida; `gross * 2.9` se rechaza). Las demás fórmulas no tienen límite. |

## Gestionar las tablas de comisiones

***

Las tablas de comisiones tienen alcance de tenant y se gestionan de forma independiente de cualquier contexto.

| Operación                          | Endpoint                                       |
| ---------------------------------- | ---------------------------------------------- |
| Crear una tabla de comisiones      | `POST /v1/fee-schedules`                       |
| Listar tablas de comisiones        | `GET /v1/fee-schedules`                        |
| Recuperar una tabla de comisiones  | `GET /v1/fee-schedules/{scheduleId}`           |
| Actualizar una tabla de comisiones | `PATCH /v1/fee-schedules/{scheduleId}`         |
| Eliminar una tabla de comisiones   | `DELETE /v1/fee-schedules/{scheduleId}`        |
| Simular un cálculo de comisión     | `POST /v1/fee-schedules/{scheduleId}/simulate` |

### Crear una tabla de comisiones

Esta tabla 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 API:

  * [Crear tabla de comisiones](/es/reference/products/matcher/create-fee-schedule)
  * [Listar tablas de comisiones](/es/reference/products/matcher/list-fee-schedules)
  * [Recuperar tabla de comisiones](/es/reference/products/matcher/retrieve-fee-schedule)
  * [Actualizar tabla de comisiones](/es/reference/products/matcher/update-fee-schedule)
  * [Eliminar tabla de comisiones](/es/reference/products/matcher/delete-fee-schedule)
</Tip>

### Simular una tabla de comisiones

Antes de conectar una tabla a una regla, simúlala contra un monto bruto para confirmar la comisión 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 ítem.

<Tip>Referencia de API: [Simular cálculo de comisión](/es/reference/products/matcher/simulate-fee-schedule)</Tip>

<Note>
  Una tabla de comisiones no puede eliminarse mientras una regla de comisión o el historial de variación de comisiones la referencie. La solicitud de eliminación devuelve `409 Conflict` con el código `MTCH-0108` e incluye los contextos que bloquean en `errors`, en `fee-schedule.delete.blocking-contexts`. Primero quita o reapunta las referencias de reglas actuales. Las referencias históricas de variación siguen bloqueando la eliminación.
</Note>

## Gestionar las reglas de comisión

***

Las reglas de comisión se crean dentro de un contexto y referencian una tabla de comisiones.

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

### Crear una regla de comisión

Esta regla aplica la tabla de comisiones creada arriba a las transacciones del lado derecho cuyos metadatos de `institution` son 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 API:

  * [Crear regla de comisión](/es/reference/products/matcher/create-fee-rule)
  * [Listar reglas de comisión](/es/reference/products/matcher/list-fee-rules)
  * [Recuperar regla de comisión](/es/reference/products/matcher/retrieve-fee-rule)
  * [Actualizar regla de comisión](/es/reference/products/matcher/update-fee-rule)
  * [Eliminar regla de comisión](/es/reference/products/matcher/delete-fee-rule)
</Tip>

## Flujo de punta a punta

***

El manejo de comisiones esperadas sigue tres pasos:

<Steps>
  <Step title="Crea la tabla de comisiones">
    Define una vez cómo se calcula la comisión en el nivel del tenant con `POST /v1/fee-schedules`. De forma opcional, valídala con el endpoint de simulación. Anota el `id` devuelto.
  </Step>

  <Step title="Crea la regla de comisión en el contexto">
    Dentro del contexto de conciliación, crea una regla de comisión con `POST /v1/contexts/{contextId}/fee-rules`. Pon `feeScheduleId` en el `id` de la tabla, elige el `side`, define un `priority` único y agrega los `predicates` que seleccionan las transacciones a las que aplica la comisión.
  </Step>

  <Step title="Aplícala durante la coincidencia">
    Pon el `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 que coincide cambia el monto de comparación solo cuando su tabla y la transacción usan la misma moneda.
  </Step>
</Steps>

## Mejores prácticas

***

<AccordionGroup>
  <Accordion title="Reutiliza tablas entre contextos">
    Una tabla de comisiones tiene alcance de tenant y muchas reglas pueden referenciarla. Define una tabla una vez (por ejemplo, "Card Processing - Visa") y apunta a ella reglas de distintos contextos. Editar la tabla actualiza cada regla que la usa.
  </Accordion>

  <Accordion title="Mantén las prioridades únicas e intencionales">
    Las prioridades son únicas dentro de un contexto y se comparten 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="Acota 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 aplica una comisión y evitar atribuciones de comisión no buscadas.
  </Accordion>

  <Accordion title="Simula antes de conectar una tabla a una regla">
    Usa `POST /v1/fee-schedules/{scheduleId}/simulate` para confirmar que una tabla produce la comisión esperada para montos representativos antes de referenciarla desde una regla.
  </Accordion>

  <Accordion title="Reapunta las reglas antes de eliminar una tabla">
    Una tabla referenciada por una regla o por el historial de variación de comisiones no puede eliminarse (`409 MTCH-0108`). La respuesta de conflicto lista los contextos que bloquean en `errors`, en `fee-schedule.delete.blocking-contexts`. Primero actualiza o quita las referencias de reglas actuales; las referencias históricas de variación siguen bloqueando la eliminación.
  </Accordion>
</AccordionGroup>

## Próximos pasos

***

<Card title="Reglas de coincidencia" icon="scale-balanced" href="/es/products/matcher/configuration/matcher-match-rules" horizontal>
  Configura cómo Matcher compara transacciones una vez que contabiliza las comisiones esperadas.
</Card>

<Card title="Enrutamiento de excepciones" icon="route" href="/es/products/matcher/configuration/matcher-exception-routing" horizontal>
  Revisa el comportamiento explícito de asignación, despacho y callback para las excepciones que el manejo de comisiones no cubre.
</Card>

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

<Card title="API de reglas de comisión" icon="code" href="/es/reference/products/matcher/create-fee-rule" horizontal>
  Referencia de API completa de los endpoints de reglas de comisión.
</Card>