> ## 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 coincidencia

> Configura reglas exactas, de tolerancia, de desfase de fecha y fuzzy para controlar cómo Matcher compara transacciones entre fuentes de datos distintas.

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.
* Cada regla crea todas las coincidencias posibles con transacciones que no hayan sido usadas por reglas de mayor prioridad.
* Después de ejecutar todas las reglas, las transacciones que siguen sin coincidencia se convierten en excepciones.

Este enfoque evita que se reutilicen las coincidencias de mayor prioridad y permite que reglas progresivamente más flexibles procesen las transacciones restantes.

## 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. Las comprobaciones de monto, moneda y fecha exigen igualdad exacta por defecto, pero `matchAmount`, `matchCurrency` y `matchDate` controlan de forma independiente si se aplica cada comprobación. 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 las comprobaciones financieras habilitadas siguen alineadas.

## Creación de reglas de coincidencia

***

### Regla Exact

```bash cURL theme={null}
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

<ParamField path="matchAmount" type="Boolean" default="true">
  Requiere coincidencia exacta de monto
</ParamField>

<ParamField path="matchCurrency" type="Boolean" default="true">
  Requiere coincidencia exacta de moneda
</ParamField>

<ParamField path="matchDate" type="Boolean" default="true">
  Requiere coincidencia exacta de fecha
</ParamField>

<ParamField path="matchReference" type="Boolean" default="true">
  Requiere coincidencia exacta de referencia
</ParamField>

<ParamField path="datePrecision" type="String" default="DAY">
  Precisión de comparación de fecha: `DAY` o `TIMESTAMP`
</ParamField>

<ParamField path="caseInsensitive" type="Boolean" default="true">
  Comparación de referencia sin distinción de mayúsculas/minúsculas
</ParamField>

<ParamField path="referenceMustSet" type="Boolean" default="false">
  Requiere que la referencia esté presente en ambos lados
</ParamField>

<ParamField path="matchBaseAmount" type="Boolean" default="false">
  Comparar monto base (convertido) en lugar del original
</ParamField>

<ParamField path="matchBaseCurrency" type="Boolean" default="false">
  Comparar moneda base en lugar de la original
</ParamField>

<ParamField path="matchScore" type="Integer" default="100">
  Aceptado y validado, pero **reservado/inerte** — no altera la puntuación de confianza calculada (consulta la nota más abajo)
</ParamField>

<ParamField path="matchBaseScore" type="Integer" default="90">
  Aceptado y validado, pero **reservado/inerte** — no altera la puntuación de confianza calculada (consulta la nota más abajo)
</ParamField>

<Note>
  **`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](/es/matcher/reference/matcher-confidence-scoring).
</Note>

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

<Tip>Referencia de la API: [Crear regla de coincidencia](/es/reference/matcher/create-match-rule)</Tip>

### Regla Tolerance

```bash cURL theme={null}
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

<ParamField path="percentTolerance" type="Decimal">
  Umbral porcentual aplicado a `percentageBase` (0.005 = 0.5%). Su valor predeterminado es `0`; Matcher compara este umbral con `absTolerance` y usa el mayor
</ParamField>

<ParamField path="absTolerance" type="Decimal">
  Umbral absoluto de monto. Su valor predeterminado es `0`; Matcher lo compara con el umbral porcentual y usa el mayor
</ParamField>

Ambos umbrales tienen un valor predeterminado de cero, por lo que debes configurar explícitamente cualquier variación de monto permitida.

<ParamField path="dateWindowDays" type="Integer">
  Número de días permitidos entre fechas de transacción
</ParamField>

<ParamField path="roundingScale" type="Integer">
  Decimales para redondeo
</ParamField>

<ParamField path="roundingMode" type="String">
  Estrategia de redondeo: `HALF_UP`, `BANKERS`, `FLOOR`, `CEIL` o `TRUNCATE`
</ParamField>

<ParamField path="percentageBase" type="String" default="MAX">
  Base para cálculo de porcentaje: `MAX`, `MIN`, `AVERAGE`, `LEFT` o `RIGHT`
</ParamField>

<ParamField path="matchCurrency" type="Boolean" default="true">
  Requiere coincidencia de moneda
</ParamField>

<ParamField path="matchReference" type="Boolean" default="true">
  Requiere coincidencia de referencia
</ParamField>

<ParamField path="caseInsensitive" type="Boolean" default="true">
  Comparación de referencia sin distinción de mayúsculas/minúsculas
</ParamField>

<ParamField path="referenceMustSet" type="Boolean" default="false">
  Requiere que la referencia esté presente en ambos lados
</ParamField>

<ParamField path="matchBaseAmount" type="Boolean" default="false">
  Comparar monto base (convertido)
</ParamField>

<ParamField path="matchBaseCurrency" type="Boolean" default="false">
  Comparar moneda base
</ParamField>

<ParamField path="matchScore" type="Integer" default="85">
  Aceptado y validado, pero **reservado/inerte** — no altera la puntuación de confianza calculada
</ParamField>

<ParamField path="matchBaseScore" type="Integer" default="80">
  Aceptado y validado, pero **reservado/inerte** — no altera la puntuación de confianza calculada
</ParamField>

**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 → **Coinciden**

### Regla Fuzzy

```bash cURL theme={null}
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

<ParamField path="minSimilarity" type="Decimal" default="0.80">
  Similitud de referencia normalizada mínima (0–1) requerida para validar como coincidencia
</ParamField>

<ParamField path="matchAmount" type="Boolean" default="true">
  Cuando es `true`, exige una coincidencia exacta de monto
</ParamField>

<ParamField path="matchCurrency" type="Boolean" default="true">
  Cuando es `true`, exige una coincidencia exacta de moneda
</ParamField>

<ParamField path="matchDate" type="Boolean" default="true">
  Cuando es `true`, exige una coincidencia exacta de fecha
</ParamField>

<ParamField path="datePrecision" type="String" default="DAY">
  Precisión de comparación de fecha: `DAY` o `TIMESTAMP`
</ParamField>

<ParamField path="referenceMustSet" type="Boolean" default="true">
  Requiere una referencia no vacía en ambos lados
</ParamField>

<ParamField path="matchScore" type="Integer" default="70">
  Se acepta y su valor predeterminado es `70`, pero está **reservado/inerte**: no limita ni cambia la confianza calculada ni el comportamiento de confirmación automática
</ParamField>

<Note>
  FUZZY reemplaza la igualdad de referencia por similitud. Por defecto, también exige coincidencias exactas de monto, moneda y fecha; desactiva cada comprobación de forma independiente con `matchAmount`, `matchCurrency` o `matchDate`. FUZZY siempre propone coincidencias para revisión humana y nunca las confirma automáticamente.
</Note>

### Regla Date lag

```bash cURL theme={null}
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

<ParamField path="maxDays" type="Integer">
  Número máximo de días de diferencia permitidos
</ParamField>

<ParamField path="minDays" type="Integer" default="0">
  Número mínimo de días de diferencia requeridos
</ParamField>

<ParamField path="inclusive" type="Boolean" default="true">
  Si los días límite son inclusivos
</ParamField>

<ParamField path="direction" type="String" default="ABS">
  Cómo medir el desfase: `ABS` (absoluto), `LEFT_BEFORE_RIGHT` o `RIGHT_BEFORE_LEFT`
</ParamField>

<ParamField path="feeTolerance" type="Decimal" default="0">
  Diferencia de monto permitida para compensar comisiones
</ParamField>

<ParamField path="matchScore" type="Integer" default="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
</ParamField>

<ParamField path="matchCurrency" type="Boolean" default="true">
  Requiere coincidencia de moneda
</ParamField>

### 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:

```bash cURL theme={null}
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"
   ]
 }'
```

<Tip>Referencia de la API: [Reordenar reglas de coincidencia](/es/reference/matcher/reorder-match-rules)</Tip>

## Pruebas de reglas

***

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

```bash cURL theme={null}
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 coincidencias potenciales. No crea excepciones, pero Matcher completa y persiste el `MatchRun` con estadísticas y emite su evento de finalización.

## Gestión de reglas

***

### Listar reglas

```bash cURL theme={null}
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.

```json theme={null}
{
  "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
}
```

<Tip>Referencia de la API: [Listar reglas de coincidencia](/es/reference/matcher/list-match-rules)</Tip>

### Actualizar una regla

```bash cURL theme={null}
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
   }
 }'
```

<Tip>Referencia de la API: [Actualizar regla de coincidencia](/es/reference/matcher/update-match-rule)</Tip>

### Eliminar una regla

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

<Tip>Referencia de la API: [Eliminar regla de coincidencia](/es/reference/matcher/delete-match-rule)</Tip>

## Buenas prácticas

***

<AccordionGroup>
  <Accordion title="Empieza de forma estricta y luego flexibiliza">
    Prioriza reglas exactas. Agrega reglas de tolerancia solo para las variaciones que puedas justificar y explicar.
  </Accordion>

  <Accordion title="Deja espacio en las prioridades">
    Usa intervalos (1, 10, 20, 50) para poder insertar reglas sin renumerar todo el conjunto.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="Escribe descripciones que expliquen la intención">
    Una regla debe documentar la variación que cubre y el riesgo que introduce.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="Mantén las reglas flexibles con baja prioridad">
    Una alta tolerancia incrementa los falsos positivos. Úsala como respaldo y revisa los resultados cuidadosamente.
  </Accordion>
</AccordionGroup>

## Próximos pasos

***

<Card title="Enrutamiento de excepciones" icon="route" href="/es/matcher/configuration/matcher-exception-routing" horizontal>
  Configura la clasificación, asignación y escalamiento de transacciones no conciliadas.
</Card>

<Card title="Puntuación de confianza" icon="chart-simple" href="/es/matcher/reference/matcher-confidence-scoring" horizontal>
  Entiende cómo se calculan los puntajes y cómo los umbrales afectan la automatización.
</Card>