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

El tipo también fija las fuentes por lado. Un contexto 1:1 necesita exactamente una fuente LEFT y una fuente RIGHT, un contexto 1:N necesita exactamente una fuente LEFT, y un contexto N:M necesita al menos una fuente en cada lado. Una ejecución de coincidencia falla cuando las fuentes no se ajustan al tipo.

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	Descripción de la transacción
`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
`direction`	No	Object	`{column, debit, credit}`: la columna que marca cada fila como débito o crédito. Una fila de débito se importa con un monto negativo, una de crédito con uno positivo. Solo CSV, JSON y XML

El vocabulario canónico se mantiene cerrado. Matcher rechaza un mapa de campos que declare cualquier otra clave. Cuando mapeas direction, usa una columna de monto sin signo. Matcher rechaza una fila con un monto con signo, una celda de dirección vacía o un valor de dirección desconocido. Cuando cargas un archivo con el formato camt053, Matcher usa su mapeo ISO 20022 incorporado e ignora el mapa de campos. La activación trata como mapeada una fuente que declara opciones camt053.

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. La moneda y la referencia también deben coincidir de forma predeterminada. Las tolerancias de monto omitidas y dateWindowDays tienen 0 como valor predeterminado, así que la regla no 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). DATE_LAG solo propone. Nunca autoconfirma.
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). `percentTolerance` es una fracción: `0.005` es 0.5%. La diferencia permitida es el mayor entre `absTolerance` y `percentTolerance` por el mayor monto absoluto, con el `percentageBase` predeterminado. 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 ambos límites. Los montos deben ser iguales, a menos que definas `feeTolerance`.
FUZZY	`minSimilarity`: umbral de referencia normalizada de `0` a `1` (`0.80` de forma predeterminada), más verificaciones de monto, moneda y fecha, activas de forma predeterminada.

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 `UNMATCHED`

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. Omite un bucket de candidatos que tenga más de 40 transacciones en un lado.

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. El monto es el valor absoluto del monto base de la transacción o, cuando no tiene monto base, de su monto. Para una partida abierta vencida, es el valor absoluto del saldo abierto.

Severidad	Criterios predeterminados
Crítica	Monto ≥ 100,000 o antigüedad ≥ 120 horas
Alta	Monto ≥ 10,000 o antigüedad ≥ 72 horas
Media	Monto ≥ 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. Matcher limita una excepción con motivo FEE_DATA_MISSING a Media, sin importar su monto o su antigüedad.

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 y notas 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%	Peso total cuando los montos coinciden según la regla o la regla no verifica montos; si no, `0`
Coincidencia de moneda	30%	Peso total cuando las monedas coinciden; si no, `0`
Tolerancia de fecha	20%	Peso total cuando las fechas están dentro de la ventana de la regla o la regla no verifica fechas; si no, `0`
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 para las coincidencias EXACT y TOLERANCE. Las coincidencias FUZZY y DATE_LAG siempre pasan a revisión
Necesita revisión	60–89	Marcada para revisión manual

El motor fija los pesos de confianza y los umbrales de los niveles. 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. 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

Los registros de auditoría son solo por adición. El archivado exporta las particiones mensuales antiguas al almacenamiento de objetos y luego las elimina de la base de datos.

Resumen

Guías

Console

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