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.

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.

​

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.

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 de la API: Crear fee schedule · Listar fee schedules · Consultar fee schedule · Actualizar fee schedule · Eliminar 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 de la API: Simular cálculo de tarifa

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.

​

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 de la API: Crear fee rule · Listar fee rules · Consultar fee rule · Actualizar fee rule · Eliminar fee rule

​

Flujo de extremo a extremo

---

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

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

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

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

​

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

​

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

Revisa la asignación explícita, el despacho y los callbacks de las excepciones que el manejo de tarifas no cubre.

Referencia de la API de fee schedules

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

Referencia de la API de fee rules

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