> ## 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 y de desfase de fecha para controlar cómo Matcher compara transacciones entre fuentes.

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

```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>API Reference: [Create match rule](/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" default="0.005">
  Variación porcentual máxima permitida (0.005 = 0.5%)
</ParamField>

<ParamField path="absTolerance" type="Decimal" default="0.50">
  Variación absoluta máxima de monto permitida
</ParamField>

<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">
  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
* Variación: 0.5% → **Coinciden** (dentro de la tolerancia de 0.5% y tolerancia absoluta de \$0.50)

### 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">
  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="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">
  Tope nominal de puntuación (el evaluador de similitud gradual determina la confianza real)
</ParamField>

<Note>
  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.
</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>API Reference: [Reorder match rules](/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 muestra coincidencias potenciales sin persistir los resultados.

## 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>API Reference: [List match rules](/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>API Reference: [Update match rule](/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>API Reference: [Delete match rule](/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="Exception routing" 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="Confidence scoring" 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>