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:

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

---

Arquitectura

Ve cómo estos conceptos se implementan a través de los contextos acotados.

Inicio rápido

Aplica estos conceptos en un flujo guiado y práctico.