Coincidencias divididas y agregadas

La conciliación del mundo real a menudo involucra transacciones que no coinciden 1:1. Un solo pago puede cubrir múltiples facturas, o varios depósitos pueden consolidarse en una sola entrada bancaria. Matcher maneja estos escenarios complejos a través de coincidencias divididas y agregadas.

Descripción general

La cardinalidad de la coincidencia se controla mediante el tipo de contexto. Matcher soporta tres tipos de contexto:

Tipo de contexto	Descripción	Ejemplo
1:1 — Uno a uno	Un origen a un destino	Pago de factura única
1:N — Uno a muchos / muchos a uno	Un origen a muchos destinos (división) o muchos orígenes a un destino (agregación)	Pago masivo cubriendo facturas; depósitos consolidados en un banco
N:M — Muchos a muchos	Cualquier combinación de orígenes y destinos	Compensación compleja

No existe un tipo de contexto N:1 separado. La coincidencia agregada (muchos orígenes a un destino) es simplemente el tipo de contexto 1:N aplicado en la dirección de agregación: el mismo tipo de contexto cubre tanto la división como la agregación.

Cómo funciona

El comportamiento de división y agregación se controla mediante dos mecanismos:

Tipo de contexto — determina la cardinalidad de la coincidencia (1:1, 1:N o N:M).
Flags de asignación en la regla — controlan cómo se distribuyen los montos dentro de un grupo de coincidencia.

No existe una configuración separada de “split” o “aggregate” en el contexto. El tipo de contexto define qué patrones están permitidos, y la configuración de la regla controla el comportamiento de asignación.

Mapeo de tipo de contexto

Tipo de contexto	Patrones permitidos
`1:1`	Solo un origen a un destino
`1:N`	Un origen a muchos destinos (split), o muchos orígenes a un destino (aggregate)
`N:M`	Cualquier combinación de orígenes y destinos

Configuraciones de asignación en reglas

Todos los tipos de regla aceptan flags de asignación en su config:

Campo	Tipo	Descripción
`allowPartial`	Boolean	Permitir asignación parcial de montos de transacción
`allocationDirection`	String	Orden de asignación: `LEFT_TO_RIGHT` o `RIGHT_TO_LEFT`
`allocationToleranceMode`	String	Cómo se mide la tolerancia: `ABS` (absoluta) o `PERCENT`
`allocationToleranceValue`	Decimal	Umbral de tolerancia para residuos de asignación
`allocationUseBaseAmount`	Boolean	Usar monto base (convertido) para la asignación

Ejemplo: regla de tolerancia con asignación

cURL

curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/rules" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "type": "TOLERANCE",
   "priority": 2,
   "config": {
     "percentTolerance": 0.01,
     "absTolerance": 5.0,
     "matchCurrency": true,
     "allowPartial": true,
     "allocationDirection": "LEFT_TO_RIGHT",
     "allocationToleranceMode": "ABS",
     "allocationToleranceValue": 10.0,
     "matchScore": 85,
     "matchBaseScore": 80
   }
 }'

matchScore y matchBaseScore se aceptan y validan pero son reservados/inertes — no cambian la puntuación de confianza calculada. La confianza siempre se calcula a partir de los pesos de componentes internos fijos (monto 40, moneda 30, fecha 20, referencia 10). Consulta Puntuación de confianza.

Creando un contexto 1:N

Para habilitar coincidencia dividida o agregada, crea un contexto con tipo 1:N:

cURL

curl -X POST "https://api.matcher.example.com/v1/contexts" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "name": "Payment Reconciliation",
   "type": "1:N",
   "interval": "daily"
 }'

Referencia de API: Crear contexto

Coincidencia dividida 1:N

Una transacción de origen coincide con múltiples transacciones de destino.

Casos de uso comunes

Pago masivo: Una transferencia cubriendo múltiples facturas
Nómina: Un débito bancario para múltiples pagos de salario
Liquidación: Un pago de pasarela para múltiples órdenes

Ejemplo: pago masivo de facturas

Origen (Extracto bancario):

ID	Monto	Referencia
bank_001	$15,000.00	BULK-PAY-2024-001

Destinos (Asientos contables):

ID	Monto	Factura
inv_001	$5,000.00	INV-2024-001
inv_002	$7,500.00	INV-2024-002
inv_003	$2,500.00	INV-2024-003

Resultado: Coincidencia 1:3 con asignación completa

Coincidencia agregada (muchos a uno)

Múltiples transacciones de origen coinciden con una transacción de destino. Esta es la dirección de agregación del tipo de contexto 1:N: no es un tipo N:1 separado.

Casos de uso comunes

Depósitos bancarios: Múltiples cheques depositados como un crédito
Liquidaciones de tarjeta: Lote diario de transacciones como un depósito
Consolidación de efectivo: Múltiples recibos de caja a un depósito

Ejemplo: depósito consolidado

Orígenes (Punto de venta):

ID	Monto	Caja
pos_001	$1,250.00	REG-01
pos_002	$980.00	REG-02
pos_003	$1,770.00	REG-03

Destino (Extracto bancario):

ID	Monto	Referencia
bank_002	$4,000.00	DEPOSIT-20240120

Resultado: Coincidencia 3:1 con asignación completa

Coincidencia N:M muchos a muchos

Múltiples transacciones de origen coinciden con múltiples transacciones de destino. Este es el patrón más complejo.

Casos de uso comunes

Compensación intercompañía: Múltiples facturas compensadas contra múltiples pagos
Liquidaciones comerciales: Compensación compleja con llenados parciales
Reconocimiento de ingresos: Múltiples entregas contra múltiples anticipos

Ejemplo: compensación intercompañía

Orígenes (Cuentas por pagar Empresa A):

ID	Monto	Referencia
pay_001	$10,000.00	IC-PAY-001
pay_002	$8,000.00	IC-PAY-002

Destinos (Cuentas por cobrar Empresa A):

ID	Monto	Referencia
rec_001	$12,000.00	IC-REC-001
rec_002	$6,000.00	IC-REC-002

Resultado: Coincidencia 2:2, $18,000 total coincidido Para habilitar coincidencia N:M, crea un contexto con tipo N:M:

cURL

curl -X POST "https://api.matcher.example.com/v1/contexts" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "name": "Intercompany Netting",
   "type": "N:M",
   "interval": "weekly"
 }'

Ejecutando y revisando coincidencias

Después de configurar el contexto y las reglas, inicia una ejecución de coincidencia y revisa los grupos resultantes.

Ejecutar coincidencia

cURL

curl -X POST "https://api.matcher.example.com/v1/matching/contexts/{contextId}/run" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "mode": "DRY_RUN"
 }'

Ver historial de ejecuciones

cURL

curl -X GET "https://api.matcher.example.com/v1/matching/contexts/{contextId}/runs" \
 -H "Authorization: Bearer $TOKEN"

Ver los grupos de coincidencia de una ejecución

El parámetro de consulta contextId es obligatorio. La respuesta es una lista paginada por cursor de grupos de coincidencia, cada uno con sus transacciones coincididas (en todas las cardinalidades) y sus puntajes de confianza.

cURL

curl -X GET "https://api.matcher.example.com/v1/matching/runs/{runId}/groups?contextId={contextId}" \
 -H "Authorization: Bearer $TOKEN"

Deshacer (desemparejar) un grupo de coincidencia

Para revertir un grupo incorrecto, deshaz el emparejamiento. Esto rechaza el grupo con un motivo y revierte todas sus transacciones a UNMATCHED. El parámetro de consulta contextId es obligatorio, y se envía un reason en el cuerpo.

cURL

curl -X DELETE "https://api.matcher.example.com/v1/matching/groups/{matchGroupId}?contextId={contextId}" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "reason": "incorrect match - amounts do not match"
 }'

Algoritmo de coincidencia

Para escenarios N:M, Matcher usa asignación secuencial determinista para emparejar transacciones.

Cómo funciona

Ordenar: Las transacciones se ordenan de forma determinista para asegurar resultados reproducibles entre ejecuciones.
Iterar: El motor recorre los candidatos en orden de prioridad.
Asignar: Los montos se distribuyen según la configuración de allocationDirection (LEFT_TO_RIGHT o RIGHT_TO_LEFT).
Rastrear residuos: Cualquier monto no asignado restante se rastrea. Si allowPartial es true, se crean coincidencias parciales; de lo contrario, las transacciones no asignadas se convierten en excepciones.

Mejores prácticas

Comienza con 1:N antes de N:M

La coincidencia muchos a muchos es compleja. Comienza con patrones más simples y habilita N:M solo cuando sea necesario.

Usa tolerancia de asignación para redondeos

Las pequeñas diferencias de redondeo son comunes en pagos divididos. Configura allocationToleranceValue en unos pocos centavos para evitar excepciones falsas.

Habilita asignación parcial deliberadamente

Solo configura allowPartial como true cuando se esperan coincidencias parciales. Esto previene coincidencias falsas de datos incompletos.

Ejecuta dry-run antes de confirmar

Siempre prueba la coincidencia dividida y agregada en modo DRY_RUN primero para verificar los resultados de asignación.

Monitorea los residuos

Rastrea los montos residuales a lo largo del tiempo. Los residuos crecientes pueden indicar problemas sistemáticos de coincidencia.

Resumen

Guías

Matcher UI

Servidor MCP

Operaciones

Coincidencias divididas y agregadas

Descripción general

Cómo funciona

Mapeo de tipo de contexto

Configuraciones de asignación en reglas

Ejemplo: regla de tolerancia con asignación

Creando un contexto 1:N

Coincidencia dividida 1:N

Casos de uso comunes

Ejemplo: pago masivo de facturas

Coincidencia agregada (muchos a uno)

Casos de uso comunes

Ejemplo: depósito consolidado

Coincidencia N:M muchos a muchos

Casos de uso comunes

Ejemplo: compensación intercompañía

Ejecutando y revisando coincidencias

Ejecutar coincidencia

Ver historial de ejecuciones

Ver los grupos de coincidencia de una ejecución

Deshacer (desemparejar) un grupo de coincidencia

Algoritmo de coincidencia

Cómo funciona

Mejores prácticas

Próximos pasos

Reglas de coincidencia

Seguridad

​Descripción general

​Cómo funciona

​Mapeo de tipo de contexto

​Configuraciones de asignación en reglas

​Ejemplo: regla de tolerancia con asignación

​Creando un contexto 1:N

​Coincidencia dividida 1:N

​Casos de uso comunes

​Ejemplo: pago masivo de facturas

​Coincidencia agregada (muchos a uno)

​Casos de uso comunes

​Ejemplo: depósito consolidado

​Coincidencia N:M muchos a muchos

​Casos de uso comunes

​Ejemplo: compensación intercompañía

​Ejecutando y revisando coincidencias

​Ejecutar coincidencia

​Ver historial de ejecuciones

​Ver los grupos de coincidencia de una ejecución

​Deshacer (desemparejar) un grupo de coincidencia

​Algoritmo de coincidencia

​Cómo funciona

​Mejores prácticas

​Próximos pasos

Reglas de coincidencia

Seguridad

Descripción general

Cómo funciona

Mapeo de tipo de contexto

Configuraciones de asignación en reglas

Ejemplo: regla de tolerancia con asignación

Creando un contexto 1:N

Coincidencia dividida 1:N

Casos de uso comunes

Ejemplo: pago masivo de facturas

Coincidencia agregada (muchos a uno)

Casos de uso comunes

Ejemplo: depósito consolidado

Coincidencia N:M muchos a muchos

Casos de uso comunes

Ejemplo: compensación intercompañía

Ejecutando y revisando coincidencias

Ejecutar coincidencia

Ver historial de ejecuciones

Ver los grupos de coincidencia de una ejecución

Deshacer (desemparejar) un grupo de coincidencia

Algoritmo de coincidencia

Cómo funciona

Mejores prácticas

Próximos pasos