Reglas de coincidencia

Las reglas de coincidencia son donde defines tu política de conciliación: qué tan estricto o flexible debe ser Matcher al decidir que dos transacciones son la misma. Reglas ajustadas implican más revisión manual pero menos coincidencias falsas; reglas más flexibles automatizan más pero requieren una supervisión cuidadosa. Puedes exigir coincidencias exactas, permitir variaciones controladas, tolerar diferencias de tiempo o comparar referencias de texto libre por similitud.

Cómo funcionan las reglas

Cuando se inicia una ejecución de coincidencia, Matcher evalúa las reglas según su prioridad.

Las reglas se evalúan desde el número de prioridad más bajo hasta el más alto.
La primera regla que produce una coincidencia determina el resultado.
Si ninguna regla coincide, la transacción se convierte en una excepción.

Este enfoque garantiza una conciliación determinista, al tiempo que permite reglas progresivamente más flexibles como respaldo.

Tipos de reglas

Exact

Requiere una coincidencia estricta en los campos configurados.

Ideal para: coincidencias deterministas donde los valores deben alinearse 1:1.

Tolerance

Permite una variación controlada en la comparación de montos.

Ideal para: patrones de variación conocidos, como comisiones, redondeos o diferencias de tipo de cambio (FX).

Date lag

Permite diferencias de fecha entre transacciones.

Ideal para: retrasos de contabilización entre sistemas.

Fuzzy

Reemplaza la igualdad exacta de referencia por una puntuación de similitud de cadenas normalizada, manteniendo exactas las comprobaciones financieras (monto, moneda, fecha). FUZZY siempre propone una coincidencia para revisión y nunca la confirma automáticamente.

Ideal para: memos de texto libre o referencias truncadas donde la referencia varía pero el monto, la moneda y la fecha siguen alineados.

Creación de reglas de coincidencia

Regla Exact

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

matchAmount

Boolean

predeterminado:"true"

Requiere coincidencia exacta de monto

matchCurrency

Boolean

predeterminado:"true"

Requiere coincidencia exacta de moneda

matchDate

Boolean

predeterminado:"true"

Requiere coincidencia exacta de fecha

matchReference

Boolean

predeterminado:"true"

Requiere coincidencia exacta de referencia

datePrecision

String

predeterminado:"DAY"

Precisión de comparación de fecha: DAY o TIMESTAMP

caseInsensitive

Boolean

predeterminado:"true"

Comparación de referencia sin distinción de mayúsculas/minúsculas

referenceMustSet

Boolean

predeterminado:"false"

Requiere que la referencia esté presente en ambos lados

matchBaseAmount

Boolean

predeterminado:"false"

Comparar monto base (convertido) en lugar del original

matchBaseCurrency

Boolean

predeterminado:"false"

Comparar moneda base en lugar de la original

matchScore

Integer

predeterminado:"100"

Aceptado y validado, pero reservado/inerte — no altera la puntuación de confianza calculada (consulta la nota más abajo)

matchBaseScore

Integer

predeterminado:"90"

Aceptado y validado, pero reservado/inerte — no altera la puntuación de confianza calculada (consulta la nota más abajo)

matchScore y matchBaseScore actualmente 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 cada componente (monto 40, moneda 30, fecha 20, referencia 10). Estos campos están reservados para uso futuro y establecerlos no modifica la puntuación de confianza ni el comportamiento de confirmación automática. Consulta Puntuación de confianza.

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

API Reference: Create match rule

Regla Tolerance

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

percentTolerance

Decimal

predeterminado:"0.005"

Variación porcentual máxima permitida (0.005 = 0.5%)

absTolerance

Decimal

predeterminado:"0.50"

Variación absoluta máxima de monto permitida

dateWindowDays

Integer

Número de días permitidos entre fechas de transacción

roundingScale

Integer

Decimales para redondeo

roundingMode

String

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

percentageBase

String

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

matchCurrency

Boolean

predeterminado:"true"

Requiere coincidencia de moneda

matchReference

Boolean

predeterminado:"true"

Requiere coincidencia de referencia

caseInsensitive

Boolean

predeterminado:"true"

Comparación de referencia sin distinción de mayúsculas/minúsculas

referenceMustSet

Boolean

predeterminado:"false"

Requiere que la referencia esté presente en ambos lados

matchBaseAmount

Boolean

predeterminado:"false"

Comparar monto base (convertido)

matchBaseCurrency

Boolean

predeterminado:"false"

Comparar moneda base

matchScore

Integer

predeterminado:"85"

Aceptado y validado, pero reservado/inerte — no altera la puntuación de confianza calculada

matchBaseScore

Integer

predeterminado:"80"

Aceptado y validado, pero reservado/inerte — no altera la puntuación de confianza calculada

Ejemplo:

Transacción A: $1,000.00
Transacción B: $1,005.00
Variación: 0.5% → Coinciden (dentro de la tolerancia de 0.5% y tolerancia absoluta de $0.50)

Regla Fuzzy

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

minSimilarity

Decimal

predeterminado:"0.80"

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

matchAmount

Boolean

predeterminado:"true"

Requiere coincidencia exacta de monto

matchCurrency

Boolean

predeterminado:"true"

Requiere coincidencia exacta de moneda

matchDate

Boolean

predeterminado:"true"

Requiere coincidencia exacta de fecha

datePrecision

String

predeterminado:"DAY"

Precisión de comparación de fecha: DAY o TIMESTAMP

referenceMustSet

Boolean

predeterminado:"true"

Requiere una referencia no vacía en ambos lados

matchScore

Integer

predeterminado:"70"

Tope nominal de puntuación (el evaluador de similitud gradual determina la confianza real)

FUZZY relaja únicamente la comparación de referencia (la igualdad pasa a ser similitud); el monto, la moneda y la fecha se comprueban de forma exacta como en una regla EXACT. Dado que propone en lugar de confirmar automáticamente, sus coincidencias siempre quedan por debajo del umbral de confirmación automática para revisión humana.

Regla Date lag

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

maxDays

Integer

Número máximo de días de diferencia permitidos

minDays

Integer

predeterminado:"0"

Número mínimo de días de diferencia requeridos

inclusive

Boolean

predeterminado:"true"

Si los días límite son inclusivos

direction

String

predeterminado:"ABS"

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

feeTolerance

Decimal

predeterminado:"0"

Diferencia de monto permitida para compensar comisiones

matchScore

Integer

predeterminado:"80"

Aceptado y validado, pero reservado/inerte — no altera la puntuación de confianza calculada. Ten en cuenta que las reglas DATE_LAG siempre puntúan el componente de referencia como 0, limitando la puntuación máxima a 90

matchCurrency

Boolean

predeterminado:"true"

Requiere coincidencia de moneda

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

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

Campo	Tipo	Descripción
`allowPartial`	Boolean	Permitir asignación parcial de montos de transacción
`allocationDirection`	String	Orden de asignación: `LEFT_TO_RIGHT` o `RIGHT_TO_LEFT`
`allocationToleranceMode`	String	Cómo se mide la tolerancia: `ABS` (absoluta) o `PERCENT`
`allocationToleranceValue`	Decimal	Umbral de tolerancia para la asignación
`allocationUseBaseAmount`	Boolean	Usar monto base (convertido) para la asignación

Prioridad de las reglas

Las reglas se evalúan según su prioridad. Los números más bajos se ejecutan primero.

Estrategia de prioridad

Prioridad	Tipo de regla	Caso de uso
1–10	EXACT	Coincidencias deterministas
11–50	TOLERANCE	Variaciones pequeñas y esperadas
51–100	DATE_LAG	Diferencias de fecha entre sistemas

Reordenar reglas

Puedes reordenar las reglas proporcionando 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"
   ]
 }'

API Reference: Reorder match rules

Pruebas de reglas

Prueba las reglas en modo dry-run antes de confirmar las 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 muestra coincidencias potenciales sin persistir los resultados.

Gestión de reglas

Listar reglas

cURL

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

Respuesta

El endpoint de listado devuelve una vista resumida de las reglas. Para ver los detalles completos de configuración de una regla específica, utiliza el endpoint individual de la regla o la respuesta de creación, que incluye el objeto config completo.

{
  "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
}

API Reference: List match rules

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

API Reference: Update match rule

Eliminar una regla

cURL

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

API Reference: Delete match rule

Buenas prácticas

Empieza de forma estricta y luego flexibiliza

Prioriza reglas exactas. Agrega reglas de tolerancia solo para las variaciones que puedas justificar y explicar.

Deja espacio en las prioridades

Usa intervalos (1, 10, 20, 50) para poder insertar reglas sin renumerar todo el conjunto.

Ejecuta dry-run en 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.

Escribe descripciones que expliquen la intención

Una regla debe documentar la variación que cubre y el riesgo que introduce.

Revisa los resultados de las reglas con el tiempo

Si una regla nunca coincide, puede ser innecesaria. Si coincide con demasiada frecuencia, puede ser demasiado amplia.

Mantén las reglas flexibles con baja prioridad

Una alta tolerancia incrementa los falsos positivos. Úsala como respaldo y revisa los resultados cuidadosamente.

Próximos pasos

Exception routing

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

Confidence scoring

Entiende cómo se calculan los puntajes y cómo los umbrales afectan la automatización.

​Cómo funcionan las reglas

​Tipos de reglas

​Exact

​Tolerance

​Date lag

​Fuzzy

​Creación de reglas de coincidencia

​Regla Exact

​Referencia de configuración

​Regla Tolerance

​Referencia de configuración

​Regla Fuzzy

​Referencia de configuración

​Regla Date lag

​Referencia de configuración

​Configuración de asignación (todos los tipos de regla)

​Prioridad de las reglas

​Estrategia de prioridad

​Reordenar reglas

​Pruebas de reglas

​Gestión de reglas

​Listar reglas

​Respuesta

​Actualizar una regla

​Eliminar una regla

​Buenas prácticas

​Próximos pasos

Exception routing

Confidence scoring

Cómo funcionan las reglas

Tipos de reglas

Exact

Tolerance

Date lag

Fuzzy

Creación de reglas de coincidencia

Regla Exact

Referencia de configuración

Regla Tolerance

Referencia de configuración

Regla Fuzzy

Referencia de configuración

Regla Date lag

Referencia de configuración

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

Prioridad de las reglas

Estrategia de prioridad

Reordenar reglas

Pruebas de reglas

Gestión de reglas

Listar reglas

Respuesta

Actualizar una regla

Eliminar una regla

Buenas prácticas

Próximos pasos