Reglas de coincidencia

Las reglas de coincidencia son donde defines tu política de conciliación. La política define qué tan estricto o tolerante es Matcher cuando decide que dos transacciones son la misma. Las reglas ajustadas significan más revisión manual, pero menos coincidencias falsas. Las reglas más laxas automatizan más, pero necesitan supervisión cuidadosa. Puedes exigir coincidencias exactas, permitir varianza controlada, tolerar diferencias de tiempo o comparar IDs externos por similitud.

Cómo funcionan las reglas

Cuando empieza una ejecución de coincidencia, Matcher evalúa las reglas en orden de prioridad.

Las reglas se evalúan desde el número de prioridad más bajo hasta el más alto.
Cada regla crea todas las coincidencias que puede a partir de las transacciones que las reglas de mayor prioridad todavía no usaron.
Después de que se ejecutan todas las reglas, cada transacción que sigue sin conciliar se convierte en una excepción.

Este enfoque impide que cualquier regla reutilice una coincidencia de mayor prioridad. Reglas progresivamente más laxas procesan las transacciones que quedan.

Tipos de regla

Exacta

Requiere una coincidencia estricta en los campos configurados.

Mejor para: coincidencias determinísticas donde los valores deben alinearse 1:1.

Tolerancia

Permite varianza controlada en la coincidencia de montos.

Mejor para: patrones de varianza conocidos como comisiones, redondeo o diferencias de FX.

Desfase de fecha

Permite diferencias de fecha entre transacciones. DATE_LAG siempre propone una coincidencia para revisión y nunca la confirma automáticamente, sea cual sea su puntuación.

Mejor para: demoras de contabilización entre sistemas.

Difusa

Reemplaza la igualdad exacta de referencias por una puntuación de similitud de cadenas normalizadas. Las compuertas de monto, moneda y fecha requieren igualdad exacta de forma predeterminada, pero matchAmount, matchCurrency y matchDate controlan de forma independiente si cada compuerta aplica. FUZZY siempre propone una coincidencia para revisión y nunca la confirma automáticamente.

Mejor para: IDs externos truncados o reformateados, donde el ID varía, pero las compuertas financieras habilitadas siguen alineadas.

Crear reglas de coincidencia

Regla exacta

cURL

curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/rules" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "type": "EXACT",
   "priority": 1,
   "config": {
     "matchAmount": true,
     "matchCurrency": true,
     "matchDate": true,
     "matchReference": true,
     "datePrecision": "DAY",
     "caseInsensitive": true,
     "referenceMustSet": false,
     "matchBaseAmount": false,
     "matchBaseCurrency": false,
     "matchScore": 100,
     "matchBaseScore": 90
   }
 }'

Referencia de configuración

Boolean

predeterminado:"true"

Exige coincidencia exacta de monto

Boolean

predeterminado:"true"

Exige coincidencia exacta de moneda

Boolean

predeterminado:"true"

Exige coincidencia exacta de fecha

Boolean

predeterminado:"true"

Exige coincidencia exacta de referencia

String

predeterminado:"DAY"

Precisión de la comparación de fechas: DAY o TIMESTAMP

Boolean

predeterminado:"true"

Comparación de referencias sin distinguir mayúsculas y minúsculas

Boolean

predeterminado:"false"

Exige que la referencia esté presente en ambos lados

Boolean

predeterminado:"false"

Exige montos base (convertidos) iguales, además de la verificación de matchAmount

Boolean

predeterminado:"false"

Exige la misma moneda base, además de la verificación de matchCurrency

String

predeterminado:"same"

Cómo compara Matcher los signos de los dos montos. same compara montos con signo. opposite compara un monto con el monto negado del otro lado, por ejemplo una devolución contra su original. ignore compara solo las magnitudes.

Array

Campos extra que también deben coincidir. Cada elemento tiene field, un mode opcional (required por defecto, conditional u off) y un tolerance opcional.

Integer

predeterminado:"100"

Aceptado y validado, pero inerte. No cambia la puntuación de confianza calculada (ver la nota más abajo)

Integer

predeterminado:"90"

Aceptado y validado, pero inerte. No cambia la puntuación de confianza calculada (ver la nota más abajo)

matchScore y matchBaseScore son inertes. Se aceptan y validan en la configuración de la regla, pero el motor de puntuación los ignora: la confianza siempre se calcula a partir de los pesos internos fijos de los componentes (monto 40, moneda 30, fecha 20, referencia 10). Definirlos no altera la puntuación de confianza ni el comportamiento de confirmación automática. Consulta Puntuación de confianza.

La respuesta devuelve la regla persistida con su id asignado y sus marcas de tiempo.

Referencia de API: Crear regla de coincidencia

Regla de tolerancia

cURL

curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/rules" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "type": "TOLERANCE",
   "priority": 2,
   "config": {
     "percentTolerance": 0.005,
     "absTolerance": 0.50,
     "dateWindowDays": 3,
     "roundingScale": 2,
     "roundingMode": "HALF_UP",
     "percentageBase": "MAX",
     "matchCurrency": true,
     "matchReference": true,
     "caseInsensitive": true,
     "referenceMustSet": false,
     "matchBaseAmount": false,
     "matchBaseCurrency": false,
     "matchScore": 85,
     "matchBaseScore": 80
   }
 }'

Referencia de configuración

Decimal

Umbral porcentual aplicado a percentageBase (0.005 = 0.5%). De forma predeterminada es 0. Matcher compara este umbral con absTolerance y usa el mayor

Decimal

Umbral de monto absoluto. De forma predeterminada es 0. Matcher lo compara con el umbral porcentual y usa el mayor

Ambos umbrales son cero de forma predeterminada, así que debes configurar de forma explícita cualquier varianza de monto permitida.

Integer

Cantidad de días permitidos entre las fechas de las transacciones

String

Calendario de días hábiles: BR_ANBIMA o US_FED. Con él, dateWindowDays cuenta días hábiles.

String

Zona horaria IANA. Matcher compara el día civil local de cada fecha.

Integer

Decimales para el redondeo

String

Estrategia de redondeo: HALF_UP, BANKERS, FLOOR, CEIL o TRUNCATE

String

predeterminado:"MAX"

Base para el cálculo del porcentaje: MAX, MIN, AVERAGE, LEFT o RIGHT

Boolean

predeterminado:"true"

Exige coincidencia de moneda

Boolean

predeterminado:"true"

Exige coincidencia de referencia

Boolean

predeterminado:"true"

Comparación de referencias sin distinguir mayúsculas y minúsculas

Boolean

predeterminado:"false"

Exige que la referencia esté presente en ambos lados

Boolean

predeterminado:"false"

Coincide por monto base (convertido)

Boolean

predeterminado:"false"

Coincide por moneda base

String

predeterminado:"same"

Array

Campos extra que también deben coincidir. Cada elemento tiene field, un mode opcional (required por defecto, conditional u off) y un tolerance opcional.

Integer

predeterminado:"85"

Aceptado y validado, pero inerte. No cambia la puntuación de confianza calculada

Integer

predeterminado:"80"

Aceptado y validado, pero inerte. No cambia la puntuación de confianza calculada

Ejemplo:

Transacción A: $1,000.00
Transacción B: $1,005.00
Diferencia de monto: $5.00
Umbral porcentual: $1,005.00 × 0.5% = $5.025 (percentageBase: MAX)
Umbral absoluto: $0.50
Umbral efectivo: MAX($5.025, $0.50) = $5.025 → Coincide

Regla difusa

cURL

curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/rules" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "type": "FUZZY",
   "priority": 4,
   "config": {
     "minSimilarity": 0.85,
     "matchAmount": true,
     "matchCurrency": true,
     "matchDate": true,
     "datePrecision": "DAY",
     "referenceMustSet": true,
     "matchScore": 70
   }
 }'

Referencia de configuración

Decimal

predeterminado:"0.80"

Similitud mínima normalizada de la referencia (0–1) requerida para pasar como coincidencia

Boolean

predeterminado:"true"

Cuando es true, exige una coincidencia exacta de monto

Boolean

predeterminado:"true"

Cuando es true, exige una coincidencia exacta de moneda

Boolean

predeterminado:"true"

Cuando es true, exige una coincidencia exacta de fecha

String

predeterminado:"DAY"

Precisión de la comparación de fechas: DAY o TIMESTAMP

Boolean

predeterminado:"true"

Exige una referencia no vacía en ambos lados

String

predeterminado:"same"

Integer

predeterminado:"70"

Aceptado y con valor predeterminado 70, pero inerte. No limita ni cambia la confianza calculada ni el comportamiento de confirmación automática

FUZZY reemplaza la igualdad de referencias por similitud. De forma predeterminada, también exige coincidencias exactas de monto, moneda y fecha. Deshabilita cada compuerta de forma independiente con matchAmount, matchCurrency o matchDate. FUZZY siempre propone coincidencias para revisión humana y nunca las confirma automáticamente.

Regla de desfase de fecha

cURL

curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/rules" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "type": "DATE_LAG",
   "priority": 3,
   "config": {
     "maxDays": 3,
     "minDays": 0,
     "inclusive": true,
     "direction": "ABS",
     "feeTolerance": 0,
     "matchScore": 80,
     "matchCurrency": true
   }
 }'

Referencia de configuración

Integer

Cantidad máxima de días de diferencia permitida

Integer

predeterminado:"0"

Cantidad mínima de días de diferencia requerida

Boolean

predeterminado:"true"

Si los días de los límites son inclusivos

String

predeterminado:"ABS"

Cómo medir el desfase: ABS (absoluto), LEFT_BEFORE_RIGHT o RIGHT_BEFORE_LEFT

Decimal

predeterminado:"0"

Diferencia de monto permitida para contabilizar las comisiones

Integer

predeterminado:"80"

Aceptado y validado, pero inerte. No cambia la puntuación de confianza calculada. Las reglas DATE_LAG siempre puntúan el componente de referencia como 0, lo que limita la puntuación máxima a 90

Boolean

predeterminado:"true"

Exige coincidencia de moneda

Boolean

predeterminado:"false"

Cuando es true, empareja solo transacciones con referencias iguales.

Boolean

predeterminado:"true"

Comparación de referencia sin distinguir mayúsculas de minúsculas

Boolean

predeterminado:"false"

Exige una referencia en ambos lados

String

Calendario de días hábiles: BR_ANBIMA o US_FED.

String

Zona horaria IANA. Matcher compara el día civil local de cada fecha.

Boolean

predeterminado:"false"

Cuenta minDays y maxDays en días hábiles de calendar. Requiere calendar.

Ajustes de asignación (todos los tipos de regla)

Todos los tipos de regla aceptan ajustes de asignación adicionales para coincidencia dividida y agregada:

Campo	Tipo	Descripción
`allowPartial`	Boolean	Permite la asignación parcial de los montos de las transacciones
`allocationToleranceMode`	String	Cómo se mide la tolerancia: `ABS` (absoluta) o `PERCENT`
`allocationToleranceValue`	Decimal	Umbral de tolerancia para la asignación
`allocationUseBaseAmount`	Boolean	Usa el monto base (convertido) para la asignación. En reglas EXACT y TOLERANCE, también activa `matchBaseAmount` y `matchBaseCurrency`

Prioridad de las reglas

Las reglas se evalúan por prioridad. Los números más bajos corren primero. Cada prioridad es un entero de 1 a 1000 y es única dentro del contexto. Matcher rechaza una prioridad que otra regla ya usa con 409 (MTCH-0102).

Estrategia de prioridad

Prioridad	Tipo de regla	Caso de uso
1–10	EXACT	Coincidencias determinísticas
11–50	TOLERANCE	Varianza pequeña y esperada
51–100	DATE_LAG	Diferencias de fecha entre sistemas

Reordenar reglas

Puedes reordenar las reglas al entregar los IDs de las reglas en el orden deseado:

cURL

curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/rules/reorder" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "ruleIds": [
     "550e8400-e29b-41d4-a716-446655440001",
     "550e8400-e29b-41d4-a716-446655440002",
     "550e8400-e29b-41d4-a716-446655440000"
   ]
 }'

Luego Matcher renumera todas las reglas del contexto desde 1, en el nuevo orden. Las reglas que dejas fuera de la lista van después de las reglas listadas, en su orden anterior.

Referencia de API: Reordenar reglas de coincidencia

Probar las reglas

Prueba las reglas en modo dry run antes de confirmar coincidencias.

cURL

curl -X POST "https://api.matcher.example.com/v1/matching/contexts/{contextId}/run" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "mode": "DRY_RUN"
 }'

El modo dry run evalúa todas las reglas y devuelve solo runId y status. No crea excepciones, pero Matcher completa y persiste el MatchRun con estadísticas y emite su evento de finalización. Lee las estadísticas con GET /v1/matching/runs/{runId}.

Gestionar las reglas

Listar reglas

cURL

curl -X GET "https://api.matcher.example.com/v1/contexts/{contextId}/rules" \
 -H "Authorization: Bearer $TOKEN"

Respuesta

Cada elemento es la regla completa, con la misma forma que la respuesta de creación, incluido config.

{
  "items": [
    {
      "id": "019c96a0-2b20-7123-9a1b-2c3d4e5f6a7b",
      "contextId": "019c96a0-2a10-7dfe-b5c1-8a1b2c3d4e5f",
      "type": "EXACT",
      "priority": 1,
      "config": {
        "matchAmount": true,
        "matchCurrency": true,
        "matchDate": true,
        "matchReference": true,
        "datePrecision": "DAY",
        "matchScore": 100,
        "matchBaseScore": 90
      },
      "createdAt": "2026-02-02T16:40:00Z",
      "updatedAt": "2026-02-02T16:40:00Z"
    }
  ],
  "limit": 20,
  "hasMore": false
}

Referencia de API: Listar reglas de coincidencia

Actualizar una regla

cURL

curl -X PATCH "https://api.matcher.example.com/v1/contexts/{contextId}/rules/{ruleId}" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "priority": 5,
   "type": "TOLERANCE",
   "config": {
     "percentTolerance": 0.02,
     "absTolerance": 10.0
   }
 }'

config reemplaza toda la configuración almacenada. Matcher no la combina con la anterior, así que una clave que omites vuelve a su valor predeterminado.

Referencia de API: Actualizar regla de coincidencia

Eliminar una regla

cURL

curl -X DELETE "https://api.matcher.example.com/v1/contexts/{contextId}/rules/{ruleId}" \
 -H "Authorization: Bearer $TOKEN"

Matcher rechaza la eliminación con 409 (MTCH-0118) mientras un grupo de coincidencia confirmado que creó esta regla todavía tenga una excepción adjunta.

Referencia de API: Eliminar regla de coincidencia

Mejores prácticas

Empieza estricto y luego afloja

Pon primero las reglas exactas. Agrega reglas de tolerancia solo para la varianza que puedas justificar y explicar.

Haz dry run de cada cambio

Trata las actualizaciones de reglas como cambios de producción. Valida las tasas de coincidencia y el volumen de excepciones antes de confirmar.

Revisa el resultado de las reglas con el tiempo

Si una regla nunca coincide, puede ser innecesaria. Si coincide demasiado seguido, puede ser demasiado amplia.

Mantén las reglas laxas en prioridad baja

Una tolerancia alta aumenta los falsos positivos. Úsala como respaldo y revisa los resultados con cuidado.

Próximos pasos

Enrutamiento de excepciones

Configura la clasificación, la asignación y el escalamiento de las transacciones no conciliadas.

Puntuación de confianza

Entiende cómo se calculan las puntuaciones y cómo los umbrales impactan la automatización.

Resumen

Guías

Console

Operaciones

Reglas de coincidencia

Cómo funcionan las reglas

Tipos de regla

Exacta

Tolerancia

Desfase de fecha

Difusa

Crear reglas de coincidencia

Regla exacta

Referencia de configuración

Regla de tolerancia

Referencia de configuración

Regla difusa

Referencia de configuración

Regla de desfase de fecha

Referencia de configuración

Ajustes de asignación (todos los tipos de regla)

Prioridad de las reglas

Estrategia de prioridad

Reordenar reglas

Probar las reglas

Gestionar las reglas

Listar reglas

Respuesta

Actualizar una regla

Eliminar una regla

Mejores prácticas

Próximos pasos

Enrutamiento de excepciones

Puntuación de confianza