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

> Escribe reglas exactas, de tolerancia, de desfase de fecha y difusas en Matcher. Define prioridades, tolerancias y coincidencia de referencias para controlar cómo se emparejan las transacciones.

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 referencias de texto libre 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 corre cada regla, las transacciones que quedan no conciliadas se convierten en excepciones.

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.

* **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**: notas de texto libre o referencias truncadas donde la referencia varía, pero las compuertas financieras habilitadas siguen alineadas.

## Crear reglas de coincidencia

***

### Regla exacta

```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">
  Exige coincidencia exacta de monto
</ParamField>

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

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

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

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

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

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

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

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

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

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

<Note>
  **`matchScore` y `matchBaseScore` son inertes actualmente.** 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). Estos campos están reservados para uso futuro y definirlos **no** altera la puntuación de confianza ni el comportamiento de confirmación automática. Consulta [Puntuación de confianza](/es/products/matcher/reference/matcher-confidence-scoring).
</Note>

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

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

### Regla de tolerancia

```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%). De forma predeterminada es `0`. Matcher compara este umbral con `absTolerance` y usa el mayor
</ParamField>

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

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

<ParamField path="dateWindowDays" type="Integer">
  Cantidad de días permitidos entre las fechas de las transacciones
</ParamField>

<ParamField path="roundingScale" type="Integer">
  Decimales para el 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 el cálculo del porcentaje: `MAX`, `MIN`, `AVERAGE`, `LEFT` o `RIGHT`
</ParamField>

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

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

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

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

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

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

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

<ParamField path="matchBaseScore" type="Integer" default="80">
  Aceptado y validado, pero **reservado/inerte**. No cambia 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 → **Coincide**

### Regla difusa

```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 mínima normalizada de la referencia (0–1) requerida para pasar 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 la comparación de fechas: `DAY` o `TIMESTAMP`
</ParamField>

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

<ParamField path="matchScore" type="Integer" default="70">
  Aceptado y con valor predeterminado `70`, pero **reservado/inerte**. No limita ni cambia la confianza calculada ni el comportamiento de confirmación automática
</ParamField>

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

### Regla de desfase de fecha

```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">
  Cantidad máxima de días de diferencia permitida
</ParamField>

<ParamField path="minDays" type="Integer" default="0">
  Cantidad mínima de días de diferencia requerida
</ParamField>

<ParamField path="inclusive" type="Boolean" default="true">
  Si los días de los límites 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 contabilizar las comisiones
</ParamField>

<ParamField path="matchScore" type="Integer" default="80">
  Aceptado y validado, pero **reservado/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
</ParamField>

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

### 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 |
| `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 | Usa el monto base (convertido) para la asignación                |

## Prioridad de las reglas

***

Las reglas se evalúan por prioridad. Los números más bajos corren primero.

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

```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 API: [Reordenar reglas de coincidencia](/es/reference/products/matcher/reorder-match-rules)
</Tip>

## Probar las reglas

***

Prueba las reglas en modo dry run antes de confirmar 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.

## Gestionar las 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, usa el endpoint de la regla individual 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 API: [Listar reglas de coincidencia](/es/reference/products/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 API: [Actualizar regla de coincidencia](/es/reference/products/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 API: [Eliminar regla de coincidencia](/es/reference/products/matcher/delete-match-rule)
</Tip>

## Mejores prácticas

***

<AccordionGroup>
  <Accordion title="Empieza estricto y luego afloja">
    Pon primero las reglas exactas. Agrega reglas de tolerancia solo para la varianza que puedas justificar y explicar.
  </Accordion>

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

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

  <Accordion title="Escribe descripciones que expliquen la intención">
    Se recomienda que una regla documente la varianza que cubre y el riesgo que introduce.
  </Accordion>

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

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

## Próximos pasos

***

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

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