> ## 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 que dan vida a Matcher: contextos, fuentes, mapeos de campos, reglas y coincidencias que impulsan cada ejecución. 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é concilias. Es el contenedor de configuración de fuentes y reglas. Matcher crea un contexto nuevo en `DRAFT`, y sus fuentes y reglas en línea son opcionales. Un contexto responde: *¿qué estoy conciliando contra qué?* Puedes empezar con un borrador vacío. Para activarlo, configura al menos una fuente `LEFT` y una `RIGHT`, mapea cada fuente (o declara opciones `camt053` válidas, que se mapean internamente) y agrega una regla de conciliación. Si la normalización de tarifas está habilitada, agrega también una regla de tarifas. ### 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 provienen las transacciones. Un contexto en borrador puede empezar sin fuentes; un contexto que se puede activar necesita al menos una fuente en cada lado de coincidencia. ### Tipos de fuente * **LEDGER**: Categoría de fuente de libro contable * **BANK**: Categoría de fuente bancaria * **GATEWAY**: Categoría de fuente de pasarela de pago * **CUSTOM**: Categoría de fuente personalizada * **FETCHER**: Categoría de fuente de Fetcher ### Configuración de fuente Cada fuente requiere: * **Nombre**: Etiquétala (ej., "Chase Checking") * **Tipo**: Categoría (`LEDGER`, `BANK`, `GATEWAY`, `CUSTOM` o `FETCHER`) * **Lado**: Qué lado de coincidencia alimenta (`LEFT` o `RIGHT`) La **configuración** es opcional. Si la omites, Matcher almacena una configuración vacía y usa los valores predeterminados de los parsers para las claves de política ausentes. 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 | Obligatorio | Tipo | Descripción | | -------------- | ----------- | -------- | ----------------------------------------------- | | `external_id` | Sí | String | Identificador de transacción del sistema fuente | | `amount` | Sí | Decimal | Monto de la transacción (positivo o negativo) | | `currency` | Sí | String | Código de moneda ISO 4217 | | `date` | Sí | DateTime | Fecha de la transacción | | `description` | No | String | Referencia externa o descripción | | `fee_amount` | No | Decimal | Columna opcional de monto de tarifa | | `fee_currency` | No | String | Columna opcional de moneda de tarifa | El vocabulario canónico es cerrado — un mapeo de campos que declare cualquier otra clave es rechazado. Cuando la configuración de una fuente declara opciones `camt053`, Matcher usa su mapeo ISO 20022 incorporado e ignora un mapa de campos; la activación considera mapeada esa fuente. ### Ejemplo de mapeo Un extracto bancario que expone `TXN_ID`, `VALUE`, `CCY` y `POST_DATE` se mapearía como: ```json theme={null} { "external_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 prioridad ascendente; una transacción reclamada por una regla anterior no está disponible para las siguientes, que aún evalúan las transacciones restantes. ### Tipos de regla * **EXACT**: Compara exactamente los campos configurados. Monto, moneda, fecha (por día) y referencia están habilitados de forma predeterminada. * **TOLERANCE**: Concilia montos dentro de la tolerancia absoluta y/o porcentual configurada. Las tolerancias de monto omitidas y `dateWindowDays` tienen como valor predeterminado `0`, así que no se permite ninguna variación ni ventana de fecha hasta que las configures. * **DATE\_LAG**: Concilia dentro de una banda de diferencia de días configurada. `minDays` y `maxDays` tienen como valor predeterminado `0` (el mismo día), no ±3. Como FUZZY, las coincidencias DATE\_LAG nunca se auto-confirman — siempre van a revisión manual. * **FUZZY**: Calcula similitud graduada de referencias de transacciones normalizadas. Usa `Reference`, alimentada por el `ExternalID` de la transacción; un `description` de un mapa de campos no es una entrada de FUZZY. FUZZY solo propone—nunca auto-confirma, por lo que una persona revisa cada vínculo difuso. ### Orden de prioridad Los números más bajos se ejecutan primero. Una regla reclama sus transacciones coincidentes; las reglas posteriores continúan con las transacciones restantes. | 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% | Estas prioridades y valores son reglas ilustrativas, no valores predeterminados del motor. Configura los valores según tu política de conciliación. ### Parámetros de regla | Tipo de regla | Parámetros | | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | EXACT | `matchAmount`, `matchCurrency`, `matchDate`, `matchReference`: qué campos deben coincidir exactamente | | TOLERANCE | Valores no negativos `percentTolerance` y/o `absTolerance` de nivel superior (números o cadenas decimales); opcionalmente configura `dateWindowDays` (`0` de forma predeterminada; máximo `3650`). No envuelvas estos valores en un objeto `tolerance`. | | DATE\_LAG | `minDays`, `maxDays`: banda permitida de diferencia en días. Ambos tienen como valor predeterminado `0`, deben estar entre `0` y `3650`, y `maxDays` debe ser al menos `minDays`; `inclusive` tiene como valor predeterminado `true` y controla el límite superior. | | FUZZY | `minSimilarity`: umbral de referencia normalizada entre `0` y `1` (valor predeterminado `0.80`), más ejes opcionales de monto, moneda y fecha. | ## 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. ``` Banco: $100.00 el 15 de ene → ERP: $100.00 el 15 de ene ``` #### Coincidencia 1:N Una transacción se concilia contra múltiples transacciones. ``` Banco: $300.00 → ERP: $100.00 + $100.00 + $100.00 ``` #### Coincidencia N:1 Múltiples transacciones se concilian contra una sola transacción. ``` Banco: $50.00 + $50.00 + $50.00 → ERP: $150.00 ``` #### Coincidencia N:M Múltiples transacciones de cada lado se concilian juntas. La evaluación N:M solo ejecuta reglas `EXACT` y `TOLERANCE`; considera hasta cuatro transacciones por lado en un grupo y limita cada grupo de identidad a 40 candidatos. ``` Banco: $100.00 + $200.00 → ERP: $150.00 + $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** registra una transacción que necesita revisión, incluidas transacciones sin conciliar y transacciones conciliadas con condiciones residuales como varianza de tipo de cambio. ### 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 base absoluto ≥ 100.000, antigüedad ≥ 120 horas o un tipo de fuente regulatoria configurado | | **Alta** | Monto base absoluto ≥ 10.000 o antigüedad ≥ 72 horas | | **Media** | Monto base absoluto ≥ 1.000 o antigüedad ≥ 24 horas | | **Baja** | Todos los demás casos | El clasificador evalúa los criterios de arriba hacia abajo. Cuando una excepción cumple los criterios de más de una severidad, se aplica la severidad más alta que coincida. ### Flujos de resolución * **Resolver**: Registra una etiqueta de resolución y un motivo opcional para cerrar una excepción. * **Forzar coincidencia**: Resuelve una excepción forzando una coincidencia con un motivo de anulación después de una revisión manual. * **Ajustar entrada**: Resuelve una excepción creando una entrada de ajuste con un motivo, notas, monto positivo, moneda y fecha de vigencia. ## 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 | 10% | Alineación de referencia normalizada (graduada 0–1 para reglas FUZZY) | ### Niveles de confianza | Nivel | Rango de puntaje | Comportamiento del sistema | | --------------------- | ---------------- | ----------------------------------------------------------------------------------------------------- | | **Auto-aprobado** | ≥ 90 | Confirmado automáticamente (solo reglas EXACT y TOLERANCE — FUZZY y DATE\_LAG siempre van a revisión) | | **Necesita revisión** | 60–89 | Marcado para revisión manual | | **Sin coincidencia** | \< 60 | No crea una propuesta de coincidencia | Los pesos de confianza y los umbrales de nivel son fijos del motor y no son configurables. ## Log de auditoría *** Un **log de auditoría** es un registro inmutable, de solo adición, creado por un flujo instrumentado. Proporciona trazabilidad para las acciones que Matcher registra. ### Eventos registrados Solo los flujos instrumentados para emitir un evento de auditoría crean entradas. Cuando la publicación de auditoría está configurada, los productores verificados incluyen: * Mutaciones de contexto, fuente, mapa de campos y regla * Flujos de excepción, incluidos forzar coincidencia y ajustar entrada ### Contenido de entrada de auditoría | Campo | Descripción | | ------------------------- | -------------------------------------------------------------------------------------------------------------------- | | `createdAt` | Marca de tiempo de creación del registro (UTC), que puede diferir de la hora de la acción auditada | | `actorId` | Identificador del actor, cuando se proporciona | | `action` | Acción realizada | | `entityType` | Tipo de entidad afectada | | `entityId` | Identificador de la entidad afectada | | `changes` | Datos estructurados del evento en JSON; los eventos emitidos incluyen `occurred_at` y cualquier cambio proporcionado | | `tenantSeq` | Número de secuencia por tenant | | `prevHash` / `recordHash` | Cadena de hashes que vincula cada entrada con la anterior, haciendo detectable cualquier manipulación | Los logs de auditoría son de solo adición. Las entradas no pueden ser modificadas o eliminadas. ## Próximos pasos *** Ve cómo estos conceptos se implementan a través de los contextos acotados. Aplica estos conceptos en un flujo guiado y práctico.