> ## 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.
# Primeros pasos con Matcher
> Recorre el ciclo de vida de conciliación de cinco etapas en Matcher. Define un contexto, conecta fuentes, configura reglas, ejecuta la coincidencia y resuelve excepciones paso a paso.
Esta guía recorre el ciclo de vida de conciliación en Matcher, desde la configuración inicial hasta la revisión de resultados. Se enfoca en los conceptos y las decisiones de cada etapa.
Para instrucciones paso a paso de la API con ejemplos de solicitud y respuesta, consulta el [inicio rápido de la API de Matcher](/es/reference/products/matcher/matcher-developer-quick-start).
## El ciclo de vida de la conciliación
***
Cada conciliación en Matcher sigue el mismo ciclo de vida de cinco etapas:
Crea un contexto que describa qué concilias y registre su intervalo de conciliación.
Registra los sistemas cuyas transacciones quieres comparar.
Configura los criterios que Matcher usa para emparejar transacciones.
Sube los datos y deja que Matcher encuentre pares, empezando por una vista previa antes de confirmar.
Revisa las transacciones no conciliadas y decide cómo tratarlas.
Las secciones de abajo explican cada etapa.
## Define el alcance con un contexto
***
Un **contexto** es el contenedor de nivel superior de un workflow de conciliación. Responde tres preguntas:
* **¿Qué concilias?** Por ejemplo, una cuenta bancaria contra tu ledger general.
* **¿Qué tipo de emparejamiento?** Uno a uno, uno a muchos o muchos a muchos.
* **¿Qué etiqueta de intervalo describe el período de conciliación?** Por ejemplo, `daily`, `weekly` o `on-demand`.
El valor obligatorio `interval` es metadato de texto libre. No programa la ejecución. Las ejecuciones automáticas usan un `ReconciliationSchedule` aparte, respaldado por cron, con una cadencia mínima de cinco minutos.
| Tipo de emparejamiento | Cuándo usarlo | Ejemplo |
| ---------------------- | ------------------------------------------------------ | ----------------------------------------- |
| `1:1` | Cada transacción tiene exactamente una contraparte | Extracto bancario vs. asientos del ledger |
| `1:N` | Un registro corresponde a varios del otro lado | Una sola factura pagada en cuotas |
| `N:M` | Varios registros de ambos lados se relacionan entre sí | Pagos en lote divididos entre cuentas |
La mayoría de las conciliaciones empiezan con `1:1`. Puedes cambiar el tipo de emparejamiento más adelante, conforme tu proceso evoluciona.
Referencia de API:
* [Crear contexto](/es/reference/products/matcher/create-context)
* [Actualizar contexto](/es/reference/products/matcher/update-context)
## Conecta fuentes de datos
***
Cada contexto necesita al menos **dos fuentes**: los sistemas cuyos datos de transacciones quieres comparar. Una fuente representa un único flujo de datos, como un extracto bancario, una exportación del ledger o un archivo de un gateway de pago.
### Tipos de fuente
| Tipo | Uso típico |
| --------- | --------------------------------------------------- |
| `BANK` | Extractos bancarios y extractos de cuenta |
| `LEDGER` | Exportaciones del ledger general o del ERP |
| `GATEWAY` | Datos de procesadores de pago (Stripe, Adyen, etc.) |
| `FETCHER` | Datos extraídos mediante Discovery |
| `CUSTOM` | Cualquier otro dato estructurado |
### Mapeo de campos
Los archivos de transacciones de sistemas distintos rara vez usan los mismos nombres de columna. Los **mapas de campos** traducen las columnas de tu fuente al esquema estándar de Matcher para que las transacciones se puedan comparar.
Por ejemplo, un archivo bancario puede llamar "Post Date" a la fecha de la transacción, mientras tu ledger la llama "posting\_date". Los mapas de campos normalizan ambas al campo `date` de Matcher.
Cada transacción debe aportar al menos cuatro campos después del mapeo:
| Campo | Descripción |
| ------------- | ------------------------------------------------- |
| `external_id` | Identificador único dentro de la fuente |
| `amount` | Valor de la transacción |
| `currency` | Código de moneda ISO 4217 (por ejemplo, USD, BRL) |
| `date` | Fecha de la transacción |
Referencia de API: [Crear fuente](/es/reference/products/matcher/create-source) | [Crear mapa de campos](/es/reference/products/matcher/create-field-map)
## Configura reglas de coincidencia
***
Las reglas definen **cómo Matcher decide si dos transacciones son la misma**. Puedes apilar varias reglas con prioridades distintas. Matcher las evalúa en orden: solo las transacciones que la primera regla deja sin conciliar pasan a la siguiente.
### Tipos de regla
| Regla | Qué hace | Cuándo usarla |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| **Exacta** | Exige valores idénticos en los campos seleccionados | Cuando los datos están limpios y los sistemas están sincronizados |
| **Tolerancia** | Permite pequeñas diferencias numéricas o de fecha | Cuando comisiones bancarias, redondeos o demoras de procesamiento causan discrepancias menores |
| **Difusa** | Usa la similitud de cadenas normalizadas para las referencias. El monto, la moneda y la fecha deben coincidir de forma predeterminada, pero puedes configurar cada control por separado. | Cuando las referencias de texto libre o truncadas varían entre fuentes |
| **Desfase de fecha** | Permite una ventana de fechas configurable | Cuando las fechas de liquidación difieren entre sistemas |
### Configuración inicial recomendada
1. **Prioridad 1: regla exacta** sobre monto, moneda y fecha. Esto captura primero todas las coincidencias perfectas.
2. **Prioridad 10: regla de tolerancia** con una tolerancia pequeña de monto (por ejemplo, 1%) y una ventana de fechas de 2 días. Esto captura las coincidencias cercanas causadas por comisiones o tiempos.
A medida que observas los resultados con el tiempo, ajusta las reglas o agrega nuevas para mejorar tu tasa de coincidencia.
Referencia de API: [Crear regla de coincidencia](/es/reference/products/matcher/create-match-rule)
## Ejecuta la coincidencia
***
Una vez que las fuentes están configuradas y los datos subidos, puedes ejecutar el motor de coincidencia.
### Primero la vista previa, después la confirmación
Matcher admite dos modos de ejecución:
| Modo | Comportamiento |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Dry run** | Calcula las coincidencias y genera una vista previa sin persistir artefactos de coincidencia ni excepciones. Crea y completa un registro `MatchRun`. |
| **Commit** | Persiste los resultados: coincidencias confirmadas, puntuaciones de confianza y excepciones. |
Empieza siempre con un dry run. Revisa la vista previa para verificar la calidad de las coincidencias antes de confirmar.
### Entender las puntuaciones de confianza
Cada coincidencia recibe una puntuación de confianza de 0 a 100:
| Rango de puntuación | Significado | Acción requerida |
| ------------------- | --------------- | ---------------------------------------------------------------------------------------------------------- |
| 90–100 | Confianza alta | Apta para confirmación automática, excepto los grupos `FUZZY` y `DATE_LAG`, que siempre requieren revisión |
| 60–89 | Confianza media | Marcada para revisión manual |
| Menos de 60 | Confianza baja | No conciliada — se convierte en excepción |
Las puntuaciones derivan de los componentes que coinciden y de sus pesos configurados. Las reglas exactas y de tolerancia usan el mismo esquema de pesos. Ningún tipo de regla produce puntuaciones más altas por sí mismo.
Referencia de API: [Ejecutar coincidencia](/es/reference/products/matcher/run-match) | [Listar grupos de una ejecución](/es/reference/products/matcher/list-match-run-groups)
## Resuelve las excepciones
***
Las excepciones son transacciones que Matcher no pudo emparejar de forma automática. Representan los ítems que necesitan atención humana.
### Severidad de las excepciones
Matcher clasifica cada excepción por severidad según el monto de la transacción y cuánto tiempo lleva sin conciliar:
| Severidad | Criterio | SLA sugerido |
| ----------- | --------------------------------------------- | ------------ |
| **Crítica** | Monto >= 100,000 o sin conciliar >= 120 horas | 24 horas |
| **Alta** | Monto >= 10,000 o sin conciliar >= 72 horas | 72 horas |
| **Media** | Monto >= 1,000 o sin conciliar >= 24 horas | 5 días |
| **Baja** | Todas las demás | 7 días |
### Opciones de resolución
* **Coincidencia forzada**: empareja a mano la transacción con una contraparte cuando sabes que van juntas.
* **Crear un ajuste**: registra un asiento de corrección para dar cuenta de la diferencia.
* **Deshacer la coincidencia**: si una coincidencia confirmada es incorrecta, deshazla para que ambas transacciones vuelvan al conjunto no conciliado.
* **Despachar**: envía la excepción por su ruta configurada de JIRA o webhook. Esta acción dirigida por quien llama no cambia su estado.
Referencia de API:
* [Listar excepciones](/es/reference/products/matcher/list-exceptions)
* [Deshacer la coincidencia de un grupo](/es/reference/products/matcher/unmatch-group)
## Escenario de ejemplo
***
Una empresa fintech concilia su extracto bancario diario contra los registros de su ledger interno.
**Configuración:**
* Contexto: "Daily Bank Reconciliation", tipo `1:1`, intervalo `daily`
* Dos fuentes: extracto de Chase Bank (`BANK`) y ledger general (`LEDGER`)
* Dos reglas: coincidencia exacta (prioridad 1) y coincidencia por tolerancia con 1% y ventana de 2 días (prioridad 10)
**Flujo diario:**
1. El equipo de finanzas sube el extracto bancario y la exportación del ledger.
2. Matcher ejecuta un dry run. La vista previa muestra 95% de las transacciones conciliadas con confianza alta.
3. El equipo revisa la vista previa y confirma los resultados.
4. Quedan cinco transacciones como excepciones: dos tienen pequeñas diferencias de comisiones, tres no tienen contraparte.
5. El equipo resuelve las excepciones de comisiones creando ajustes. Las tres transacciones faltantes se escalan para investigación.
## Próximos pasos
***
Guía completa para configurar contextos de conciliación.
Análisis a fondo de todos los tipos de regla y las opciones de configuración.
Mapea distintos formatos de archivo al esquema estándar de Matcher.
Estrategias para tratar transacciones no conciliadas.