Conceptos de Matcher

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í:

{
  "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.

Resumen

Guías

Matcher UI

Servidor MCP

Operaciones

Conceptos de Matcher

Contexto

Tipos de contexto

Ejemplo

Fuente

Tipos de fuente

Configuración de la fuente

Mapa de campos

Campos estándar

Ejemplo de mapeo

Regla de coincidencia

Tipos de regla

Orden de prioridad

Parámetros de regla

Coincidencia

Estado de la coincidencia

Patrones de coincidencia

Coincidencia 1:1

Coincidencia 1:N

Coincidencia N:1

Coincidencia N:M

Ítems de coincidencia

Excepción

Estado de la excepción

Severidad

Workflows de resolución

Puntuación de confianza

Cálculo de la puntuación

Niveles de confianza

Registro de auditoría

Eventos registrados

Contenido de una entrada de auditoría

Próximos pasos

Arquitectura

Inicio rápido

​Contexto

​Tipos de contexto

​Ejemplo

​Fuente

​Tipos de fuente

​Configuración de la fuente

​Mapa de campos

​Campos estándar

​Ejemplo de mapeo

​Regla de coincidencia

​Tipos de regla

​Orden de prioridad

​Parámetros de regla

​Coincidencia

​Estado de la coincidencia

​Patrones de coincidencia

​Coincidencia 1:1

​Coincidencia 1:N

​Coincidencia N:1

​Coincidencia N:M

​Ítems de coincidencia

​Excepción

​Estado de la excepción

​Severidad

​Workflows de resolución

​Puntuación de confianza

​Cálculo de la puntuación

​Niveles de confianza

​Registro de auditoría

​Eventos registrados

​Contenido de una entrada de auditoría

​Próximos pasos

Arquitectura

Inicio rápido

Contexto

Tipos de contexto

Ejemplo

Fuente

Tipos de fuente

Configuración de la fuente

Mapa de campos

Campos estándar

Ejemplo de mapeo

Regla de coincidencia

Tipos de regla

Orden de prioridad

Parámetros de regla

Coincidencia

Estado de la coincidencia

Patrones de coincidencia

Coincidencia 1:1

Coincidencia 1:N

Coincidencia N:1

Coincidencia N:M

Ítems de coincidencia

Excepción

Estado de la excepción

Severidad

Workflows de resolución

Puntuación de confianza

Cálculo de la puntuación

Niveles de confianza

Registro de auditoría

Eventos registrados

Contenido de una entrada de auditoría

Próximos pasos