> ## 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 > Conoce los cinco conceptos principales de Matcher que dan forma a cada conciliación que construyes: contextos, fuentes, mapas de campos, reglas de coincidencia y coincidencias. Los cinco conceptos principales de Matcher: **contextos**, **fuentes**, **mapas de campos**, **reglas** y **coincidencias**. ## Contexto *** Un **contexto** define qué concilias. Es el contenedor de configuración de las fuentes y las reglas. Matcher crea un contexto nuevo en `DRAFT`, y sus fuentes y reglas en línea son opcionales. Un contexto responde: *¿qué concilio contra qué?* Puedes empezar con un borrador vacío. Para activarlo, configura al menos una fuente `LEFT` y una fuente `RIGHT`, mapea cada fuente (o declara opciones `camt053` válidas, que se mapean solas) y agrega una regla de coincidencia. Si habilitas la normalización de comisiones, agrega también una regla de comisiones. ### Tipos de contexto | Tipo | Descripción | Ejemplo | | ------- | ---------------------------- | -------------------------------------- | | **1:1** | Conciliación uno a uno | Extracto bancario vs registros del ERP | | **1:N** | Conciliación uno a muchos | Un pago que cubre varias facturas | | **N:M** | Conciliación muchos a muchos | Escenarios de netting o de agregación | ### Ejemplo Un contexto llamado **"Chase Bank vs ERP System"** haría lo siguiente: * Definir Chase Bank como una fuente de conciliación * Definir tu sistema ERP como otra fuente * Especificar las reglas que se usan para conciliar transacciones entre ambas ## Fuente *** Una **fuente** es el origen de las transacciones. Un contexto en borrador puede empezar sin fuentes. Un contexto activable necesita al menos una fuente en cada lado de la coincidencia. ### Tipos de fuente * **LEDGER**: categoría de fuente de ledger * **BANK**: categoría de fuente bancaria * **GATEWAY**: categoría de fuente de gateway de pago * **CUSTOM**: categoría de fuente personalizada * **FETCHER**: una categoría de fuente de Discovery ### Configuración de la fuente Cada fuente requiere: * **Nombre**: etiquétala (por ejemplo, "Chase Checking") * **Tipo**: categoría (`LEDGER`, `BANK`, `GATEWAY`, `CUSTOM` o `FETCHER`) * **Lado**: a qué lado de la coincidencia alimenta (`LEFT` o `RIGHT`) **Config** es opcional. Si lo omites, Matcher almacena una configuración vacía y usa los valores predeterminados del parser para las claves de política ausentes. Los mapas de campos traducen los campos de cada fuente al esquema estándar de Matcher. ## Mapa de campos *** Un **mapa de campos** traduce los nombres de campos externos al esquema estándar de Matcher. Cada sistema nombra las cosas de otra manera. Los mapas de campos normalizan eso. ### Campos estándar | Campo | Obligatorio | Tipo | Descripción | | -------------- | ----------- | -------- | ------------------------------------------------------- | | `external_id` | Sí | String | Identificador de la transacción en el sistema de origen | | `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 o descripción externa | | `fee_amount` | No | Decimal | Columna opcional del monto de la comisión | | `fee_currency` | No | String | Columna opcional de la moneda de la comisión | El vocabulario canónico se mantiene cerrado. Matcher rechaza un mapa de campos que declare cualquier otra clave. Cuando la configuración de una fuente declara opciones `camt053`, Matcher usa su mapeo ISO 20022 incorporado e ignora el mapa de campos. La activación trata esa fuente como mapeada. ### Ejemplo de mapeo Mapeas un extracto bancario que expone `TXN_ID`, `VALUE`, `CCY` y `POST_DATE` así: ```json theme={null} { "external_id": "TXN_ID", "amount": "VALUE", "currency": "CCY", "date": "POST_DATE" } ``` ## Regla de coincidencia *** Una **regla de coincidencia** le indica a Matcher cómo comparar transacciones. Las reglas se ejecutan en orden ascendente de prioridad. Una transacción reclamada por una regla anterior no queda disponible para las reglas posteriores, que de todos modos evalúan las transacciones restantes. ### Tipos de regla * **EXACT**: compara de forma exacta los campos configurados. El monto, la moneda, la fecha (por día) y la referencia están habilitados de forma predeterminada. * **TOLERANCE**: hace coincidir montos dentro de la tolerancia absoluta y/o porcentual configurada. Las tolerancias de monto omitidas y `dateWindowDays` tienen `0` como valor predeterminado, así que no se permite ninguna desviación ni ventana de fechas hasta que configures una. * **DATE\_LAG**: hace coincidir dentro de una banda configurada de diferencia de días. `minDays` y `maxDays` tienen ambos `0` como valor predeterminado (el mismo día), no ±3. Igual que FUZZY, las coincidencias DATE\_LAG nunca se autoconfirman. Siempre pasan a revisión manual. * **FUZZY**: califica las referencias normalizadas de las transacciones. Usa `Reference`, que se completa desde el `ExternalID` de la transacción; un `description` del mapa de campos no es una entrada de FUZZY. FUZZY solo propone. Nunca autoconfirma, así que una persona revisa cada vínculo difuso. ### Orden de prioridad Los números más bajos se ejecutan primero. Una regla reclama las transacciones que le coinciden; las reglas posteriores continúan con las transacciones restantes. | Prioridad | Regla | Descripción | | --------- | ------------------------ | -------------------------------------------------- | | 1 | Coincidencia exacta | El monto, la fecha y la referencia deben coincidir | | 2 | Tolerancia del mismo día | La misma fecha, el monto dentro de 0.5% | | 3 | Tolerancia semanal | Dentro de 7 días, el monto dentro de 1% | Estas prioridades y estos 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 de forma exacta | | TOLERANCE | Valores `percentTolerance` y/o `absTolerance` no negativos en el nivel superior (números o cadenas decimales); de forma opcional, define `dateWindowDays` (`0` de forma predeterminada; máximo `3650`). No envuelvas estos valores en un objeto `tolerance`. | | DATE\_LAG | `minDays`, `maxDays`: banda permitida de diferencia de días. Ambos tienen `0` como valor predeterminado, deben ir de `0` a `3650`, y `maxDays` debe ser al menos `minDays`; `inclusive` tiene `true` como valor predeterminado y controla el límite superior. | | FUZZY | `minSimilarity`: umbral de referencia normalizada de `0` a `1` (`0.80` de forma predeterminada), más ejes opcionales de monto, moneda y fecha. | ## Coincidencia *** Una **coincidencia** ocurre cuando se concilian juntas transacciones de fuentes distintas. ### Estado de la coincidencia | Estado | Descripción | | ----------- | ------------------------------------------------------------------------------------ | | `PROPOSED` | Matcher la encontró, en espera de confirmación | | `CONFIRMED` | Aprobada de forma automática o manual | | `REJECTED` | Rechazada de forma manual | | `REVOKED` | Una coincidencia confirmada antes se deshizo y devolvió sus transacciones a revisión | ### Patrones de coincidencia #### Coincidencia 1:1 Se concilia una transacción de cada fuente. ``` Bank: $100.00 on Jan 15 → ERP: $100.00 on Jan 15 ``` #### Coincidencia 1:N Una transacción se concilia contra varias transacciones. ``` Bank: $300.00 → ERP: $100.00 + $100.00 + $100.00 ``` #### Coincidencia N:1 Varias transacciones se concilian contra una sola transacción. ``` Bank: $50.00 + $50.00 + $50.00 → ERP: $150.00 ``` #### Coincidencia N:M Varias 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 bucket de identidad a 40 candidatos. ``` Bank: $100.00 + $200.00 → ERP: $150.00 + $150.00 ``` ### Ítems de coincidencia Cada grupo de coincidencia contiene **ítems de coincidencia**, que registran la participación y la asignación de las transacciones. Esto habilita la conciliación parcial en escenarios de división y de agregación. ## Excepción *** Una **excepción** registra una transacción que necesita revisión, incluidas las transacciones no conciliadas y las transacciones conciliadas con condiciones residuales, como la variación de la tasa de cambio. ### Estado de la excepción | Estado | Descripción | | -------------------- | ------------------------------------------------------- | | `OPEN` | En espera de asignación | | `ASSIGNED` | Alguien está investigando | | `PENDING_RESOLUTION` | Hay una resolución en curso, a la espera de completarse | | `RESOLVED` | Atendida | ### Severidad Matcher clasifica las excepciones de forma automática para que sepas qué priorizar. | Severidad | Criterios predeterminados | | ----------- | -------------------------------------------------------------------------------------------------- | | **Crítica** | Monto base absoluto ≥ 100,000, antigüedad ≥ 120 horas, o un tipo de fuente regulatorio 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 coincidente más alta. ### Workflows 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 la revisión manual. * **Ajustar asiento**: resuelve una excepción creando un asiento de ajuste con un motivo, notas, un monto positivo, una moneda y una hora efectiva. ## Puntuación de confianza *** Una **puntuación de confianza** indica la fiabilidad de una coincidencia automática en una escala de 0–100. Las puntuaciones más altas representan una alineación más fuerte entre las transacciones. ### Cálculo de la puntuación | Componente | Peso | Descripción | | ---------------------- | ---- | --------------------------------------------------------------------------------- | | Coincidencia de monto | 40% | Grado de alineación de los montos | | Coincidencia de moneda | 30% | Consistencia de la moneda | | Tolerancia de fecha | 20% | Proximidad de las fechas de las transacciones | | Referencia | 10% | Alineación de la referencia normalizada (calificada de 0–1 para las reglas FUZZY) | ### Niveles de confianza | Nivel | Rango de puntuación | Comportamiento del sistema | | -------------------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------ | | **Aprobada de forma automática** | ≥ 90 | Se confirma de forma automática (solo reglas EXACT y TOLERANCE — FUZZY y DATE\_LAG siempre pasan a revisión) | | **Necesita revisión** | 60–89 | Marcada para revisión manual | | **Sin coincidencia** | \< 60 | No crea una propuesta de coincidencia | Los pesos de confianza y los umbrales de los niveles los fija el motor y no son configurables. ## Registro de auditoría *** Un **registro de auditoría** es un registro inmutable y solo por adición que crea un workflow instrumentado. Provee trazabilidad para las acciones que Matcher registra. ### Eventos registrados Solo los workflows instrumentados para emitir un evento de auditoría crean entradas. Cuando la publicación de auditoría está configurada, los productores verificados incluyen: * Las mutaciones de contexto, de fuente, de mapa de campos y de regla * Los workflows de excepción, incluidos forzar coincidencia y ajustar asiento ### Contenido de una 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 ejecutada | | `entityType` | Tipo de la entidad afectada | | `entityId` | Identificador de la entidad afectada | | `changes` | Datos estructurados del evento en JSON; los eventos emitidos incluyen `occurred_at` y los cambios proporcionados | | `tenantSeq` | Número de secuencia por tenant | | `prevHash` / `recordHash` | Cadena de hashes que vincula cada entrada con la anterior y hace detectable la manipulación | Los registros de auditoría son solo por adición. Nadie puede modificar ni eliminar entradas. ## Próximos pasos *** Mira cómo los contextos delimitados implementan estos conceptos. Aplica estos conceptos en un flujo guiado y práctico.