Reglas de tarifas

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 enruta la transacción a su fee schedule.

Modelar las tarifas esperadas de esta forma permite que Matcher tenga en cuenta los cargos predecibles antes de comparar transacciones, de modo que una diferencia de tarifa conocida se resuelve limpiamente en lugar de convertirse en una excepción.

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 le indican a Matcher cuándo anticiparlo, para que pueda conciliar correctamente a pesar de la diferencia de monto.

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.

Un fee schedule se crea una vez a nivel de tenant y puede ser reutilizado por muchas reglas en muchos contextos.
Una fee rule se crea dentro de un contexto. Establece un side, un feeScheduleId, una priority y una lista de predicates.
Cuando Matcher procesa un contexto, evalúa las fee rules en orden de priority (primero el más bajo). La primera regla cuyos predicados coinciden con una transacción enruta esa transacción al schedule referenciado, que calcula la tarifa.

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.

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`	Coincide con un único `value`. Numérico cuando ambos lados se interpretan como decimales, de lo contrario cadena sin distinción de mayúsculas.
`NEQ`	Negación de `EQUALS`.
`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`).

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 campos de metadatos (`+ - * /`, paréntesis y las funciones `days_late`, `days_between`, `max`, `min`, `abs`, `clamp`).

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.

cURL

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" }
     }
   ]
 }'

Referencia API: Create fee schedule · List fee schedules · Retrieve fee schedule · Update fee schedule · Delete fee schedule

Simular un fee schedule

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

cURL

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.

Referencia API: Simulate fee calculation

Un fee schedule que todavía está referenciado por una o más fee rules no se puede eliminar. La solicitud de eliminación devuelve 409 Conflict con el código fee_schedule_in_use y lista los contextos cuyas reglas bloquean la eliminación. Elimina o reapunta esas reglas primero.

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.

cURL

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"
     }
   ]
 }'

Referencia API: Create fee rule · List fee rules · Retrieve fee rule · Update fee rule · Delete fee rule

Flujo de extremo a extremo

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

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.

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.

Aplica durante la coincidencia

Cuando se procesa el contexto, Matcher evalúa las fee rules en orden de priority. La primera regla cuyos predicados coinciden con una transacción la enruta al schedule referenciado, que calcula la tarifa esperada para que la coincidencia la tenga en cuenta.

Mejores prácticas

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.

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.

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.

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.

Reapunta las reglas antes de eliminar un schedule

Un schedule referenciado por cualquier regla no se puede eliminar (409 fee_schedule_in_use). Actualiza o elimina primero las reglas que lo referencian, usando los contextos listados en la respuesta de conflicto.

Próximos pasos

Reglas de conciliación

Configura cómo se comparan las transacciones una vez que se tienen en cuenta las tarifas esperadas.

Enrutamiento de excepciones

Enruta a los equipos correctos las excepciones que el manejo de tarifas no cubre.

Fee schedules API

Referencia completa de la API para los endpoints de fee schedules.

Fee rules API

Referencia completa de la API para los endpoints de fee rules.

​Qué resuelve el manejo de tarifas

​Cómo encajan las reglas y los schedules

​Estructura de una fee rule

​Predicados

​Estructura de un fee schedule

​Fee items

​Gestión de fee schedules

​Crear un fee schedule

​Simular un fee schedule

​Gestión de fee rules

​Crear una fee rule

​Flujo de extremo a extremo

​Mejores prácticas

​Próximos pasos

Reglas de conciliación

Enrutamiento de excepciones

Fee schedules API

Fee rules API

Qué resuelve el manejo de tarifas

Cómo encajan las reglas y los schedules

Estructura de una fee rule

Predicados

Estructura de un fee schedule

Fee items

Gestión de fee schedules

Crear un fee schedule

Simular un fee schedule

Gestión de fee rules

Crear una fee rule

Flujo de extremo a extremo

Mejores prácticas

Próximos pasos