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

# Conceptos de Matcher

> Comprende los cinco conceptos clave que dan vida a Matcher: contextos, fuentes, mapeos de campos, reglas y coincidencias.

Los cinco conceptos principales en Matcher: **contextos**, **fuentes**, **mapeos de campos**, **reglas** y **coincidencias**. Entiende estos y entenderás cómo funciona todo el sistema.

## Contexto

***

Un **contexto** define qué estás conciliando. Es el contenedor que mantiene tus fuentes, reglas y resultados.

<Info>
  Un contexto responde: *¿qué estoy conciliando contra qué?*
</Info>

### Tipos de contexto

| Tipo    | Descripción                  | Ejemplo                                 |
| ------- | ---------------------------- | --------------------------------------- |
| **1:1** | Conciliación uno a uno       | Extracto bancario vs registros ERP      |
| **1:N** | Conciliación uno a muchos    | Un pago cubriendo múltiples facturas    |
| **N:M** | Conciliación muchos a muchos | Escenarios de compensación o agregación |

### Ejemplo

Un contexto llamado **"Chase Bank vs ERP System"** podría:

* Definir Chase Bank como una fuente de conciliación
* Definir tu sistema ERP como otra fuente
* Especificar las reglas usadas para conciliar transacciones entre ellos

## Fuente

***

Una **fuente** es de donde vienen las transacciones. Cada contexto necesita al menos dos fuentes—eso es lo que estás conciliando.

### Tipos de fuente

* **LEDGER**: Sistemas de libro contable interno (incluyendo Midaz)
* **BANK**: Feeds de extractos bancarios
* **GATEWAY**: Liquidaciones de pasarelas de pago (Stripe, Adyen, PayPal)
* **CUSTOM**: Feeds personalizados definidos por el usuario
* **FETCHER**: Fuentes obtenidas automáticamente por el motor de descubrimiento (conexiones de agregadores)

### Configuración de fuente

Cada fuente requiere:

* **Name**: Etiquétala (ej., "Chase Checking")
* **Type**: Categoría (`LEDGER`, `BANK`, `GATEWAY`, `CUSTOM` o `FETCHER`)
* **Side**: Qué lado de coincidencia alimenta (`LEFT` o `RIGHT`)
* **Config**: Ajustes de conexión y parsing específicos de la fuente

Los mapeos de campos traducen los campos de cada fuente al esquema estándar de Matcher.

## Mapeo de campos

***

Un **mapeo de campos** traduce nombres de campos externos al esquema estándar de Matcher. Cada sistema llama las cosas de manera diferente—los mapeos de campos normalizan eso.

### Campos estándar

| Campo            | Tipo     | Descripción                                     |
| ---------------- | -------- | ----------------------------------------------- |
| `transaction_id` | String   | Identificador de transacción del sistema fuente |
| `amount`         | Decimal  | Monto de la transacción (positivo o negativo)   |
| `currency`       | String   | Código de moneda ISO 4217                       |
| `date`           | DateTime | Fecha de la transacción                         |
| `reference`      | String   | Referencia externa o descripción                |
| `metadata`       | Object   | Atributos específicos de la fuente              |

### Ejemplo de mapeo

Un extracto bancario que expone `TXN_ID`, `VALUE`, `CCY` y `POST_DATE` se mapearía como:

```json theme={null}
{
  "transaction_id": "TXN_ID",
  "amount": "VALUE",
  "currency": "CCY",
  "date": "POST_DATE"
}
```

## Regla de conciliación

***

Una **regla de conciliación** le dice a Matcher cómo comparar transacciones. Las reglas se ejecutan en orden de prioridad—la primera coincidencia gana.

### Tipos de regla

* **EXACT**: Los campos deben coincidir exactamente (monto, fecha, referencia)
* **TOLERANCE**: Permite pequeñas diferencias (0.5% de variación, \$10 absolutos)
* **DATE\_LAG**: Concilia dentro de una ventana de fechas (±3 días)
* **FUZZY**: Similitud graduada en referencias/descripciones (normalizada, subcadena o puntuada por similitud). FUZZY solo propone—nunca auto-confirma, por lo que un humano revisa cada vínculo difuso.

### Orden de prioridad

Los números más bajos se ejecutan primero. Matcher se detiene en la primera regla que coincide.

| Prioridad | Regla                | Descripción                               |
| --------- | -------------------- | ----------------------------------------- |
| 1         | Coincidencia exacta  | Monto, fecha y referencia deben coincidir |
| 2         | Tolerancia mismo día | Misma fecha, monto dentro del 0.5%        |
| 3         | Tolerancia semanal   | Dentro de 7 días, monto dentro del 1%     |

### Parámetros de regla

| Tipo de regla | Parámetros                                                                          |
| ------------- | ----------------------------------------------------------------------------------- |
| EXACT         | `fields`: lista de campos a comparar                                                |
| TOLERANCE     | `percent`: variación porcentual, `absolute`: monto de variación fijo                |
| DATE\_LAG     | `days_before`, `days_after`: desplazamiento permitido desde la fecha de transacción |

## Coincidencia

***

Una **coincidencia** es cuando transacciones de diferentes fuentes se reconcilian juntas. Es el objetivo final.

### Estado de coincidencia

| Estado      | Descripción                                                                                    |
| ----------- | ---------------------------------------------------------------------------------------------- |
| `PROPOSED`  | Matcher la encontró, esperando confirmación                                                    |
| `CONFIRMED` | Auto-aprobada o aprobada manualmente                                                           |
| `REJECTED`  | Rechazada manualmente                                                                          |
| `REVOKED`   | Una coincidencia previamente confirmada fue deshecha, devolviendo sus transacciones a revisión |

### Patrones de coincidencia

#### Coincidencia 1:1

Una transacción de cada fuente se concilia.

```
Bank: $100.00 on Jan 15 → ERP: $100.00 on Jan 15
```

#### Coincidencia 1:N

Una transacción se concilia contra múltiples transacciones.

```
Bank: $300.00 → ERP: $100.00 + $100.00 + $100.00
```

#### Coincidencia N:1

Múltiples transacciones se concilian contra una sola transacción.

```
Bank: $50.00 + $50.00 + $50.00 → ERP: $150.00

```

### Elementos de coincidencia

Cada grupo de coincidencia contiene **elementos de coincidencia**, que registran la participación y asignación de transacciones.
Esto permite la conciliación parcial en escenarios de división y agregación.

## Excepción

***

Una **excepción** es una transacción que no coincidió. Necesita revisión manual.

### Estado de excepción

| Estado               | Descripción                                                |
| -------------------- | ---------------------------------------------------------- |
| `OPEN`               | Esperando asignación                                       |
| `ASSIGNED`           | Alguien está investigando                                  |
| `PENDING_RESOLUTION` | Una resolución está en progreso, esperando su finalización |
| `RESOLVED`           | Manejada                                                   |

### Severidad

Matcher auto-clasifica las excepciones para que sepas qué priorizar.

| Severidad   | Criterio por defecto                                            |
| ----------- | --------------------------------------------------------------- |
| **Crítica** | Monto ≥ \$100K, antigüedad ≥ 5 días, o marcada regulatoriamente |
| **Alta**    | Monto ≥ \$10K o antigüedad ≥ 3 días                             |
| **Media**   | Monto ≥ 1,000 o antigüedad ≥ 1 día                              |
| **Baja**    | Todos los demás casos                                           |

### Tipos de resolución

* **Force match**: Conciliar transacciones manualmente
* **Adjustment**: Registrar un ajuste compensatorio
* **Write-off**: Cerrar la excepción con justificación

## Puntaje de confianza

***

Un **puntaje de confianza** indica la confiabilidad de una conciliación automatizada en una escala de 0–100.
Puntajes más altos representan mayor alineación entre transacciones.

### Cálculo del puntaje

| Componente             | Peso | Descripción                                                           |
| ---------------------- | ---- | --------------------------------------------------------------------- |
| Coincidencia de monto  | 40%  | Grado de alineación de monto                                          |
| Coincidencia de moneda | 30%  | Consistencia de moneda                                                |
| Tolerancia de fecha    | 20%  | Proximidad de fechas de transacción                                   |
| Referencia/descripción | 10%  | Alineación de referencia/descripción (graduada 0–1 para reglas FUZZY) |

### Niveles de confianza

| Nivel                 | Rango de puntaje | Comportamiento del sistema   |
| --------------------- | ---------------- | ---------------------------- |
| **Auto-aprobado**     | ≥ 90             | Confirmado automáticamente   |
| **Necesita revisión** | 60–89            | Marcado para revisión manual |
| **Sin coincidencia**  | \< 60            | Tratado como excepción       |

<Tip>
  Los umbrales de confianza pueden personalizarse por tenant para reflejar diferentes tolerancias al riesgo.
</Tip>

## Log de auditoría

***

Un **log de auditoría** es un registro inmutable de todas las acciones del sistema.
Proporciona trazabilidad completa para revisión operacional, auditorías y cumplimiento regulatorio.

### Eventos registrados

Las entradas de auditoría se crean para:

* Cambios de contexto, fuente y regla
* Ingesta y procesamiento de archivos
* Confirmaciones y rechazos de coincidencias
* Resolución de excepciones y anulaciones

### Contenido de entrada de auditoría

| Campo           | Descripción                        |
| --------------- | ---------------------------------- |
| `timestamp`     | Marca de tiempo de la acción (UTC) |
| `user_id`       | Actor responsable de la acción     |
| `action`        | Acción realizada                   |
| `resource_type` | Tipo de recurso afectado           |
| `resource_id`   | Identificador del recurso afectado |
| `before_state`  | Estado antes de la acción          |
| `after_state`   | Estado después de la acción        |
| `notes`         | Justificación, cuando aplica       |

<Warning>
  Los logs de auditoría son de solo adición. Las entradas no pueden ser modificadas o eliminadas.
</Warning>

## Próximos pasos

***

<Card title="Arquitectura" icon="sitemap" href="/es/matcher/matcher-architecture" horizontal>
  Ve cómo estos conceptos se implementan a través de los contextos acotados.
</Card>

<Card title="Inicio rápido" icon="rocket" href="/es/matcher/getting-started/matcher-quick-start" horizontal>
  Aplica estos conceptos en un flujo guiado y práctico.
</Card>