Coincidencias divididas y agregadas

Concilia patrones de transacciones 1:1, 1:N (división y agregación) y N:M usando tipos de contexto e indicadores de asignación para distribuir montos.

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:

1. Tipo de contexto — determina la cardinalidad de la coincidencia (1:1, 1:N o N:M).
2. 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
feeAware	Boolean	Asignación 1:N consciente de comisiones: consume la participación bruta de cada candidato (neto + comisión) en lugar de solo el neto. Útil para splits de marketplace donde el pago llega neto de comisiones
nmDeductionBand	Decimal	Solo reglas TOLERANCE. Banda de pago corto para el solucionador N:M, como fracción decimal del valor nominal de la factura pagada de menos (0.05 = 5%). Permite que un subconjunto de pagos pague de menos un subconjunto de facturas dentro de la banda. En cero o ausente la desactiva

​

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, usa unmatch. Un grupo PROPOSED se rechaza con un motivo y sus transacciones vuelven a UNMATCHED. Para un grupo CONFIRMED, Matcher también revierte los efectos residuales/de partida abierta que aplicó esa confirmación, de forma atómica con la revocación del grupo y la devolución de sus transacciones. 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"
 }'

Si la reversión del grupo confirmado elimina la última contribución activa detrás de una obligación, esa partida abierta pasa al estado terminal WITHDRAWN: permanece como historial, pero no se puede compensar ni llevar a otra ejecución. Matcher verifica que la reversión sea posible antes de cambiar nada. Si una entrada posterior aún activa sigue sobre el residual, o una obligación más reciente y activa entraría en conflicto con restaurar una partida terminal con la misma identidad, el endpoint devuelve 409 Conflict y deja sin cambios el grupo, las transacciones y las partidas abiertas.

​

Algoritmo de coincidencia

---

El algoritmo depende del tipo de contexto.

​

1:N — asignación secuencial determinista

Para escenarios de split y agregación (1:N), Matcher usa asignación secuencial determinista:

1. Ordenar: Las transacciones se ordenan de forma determinista para asegurar resultados reproducibles entre ejecuciones.
2. Iterar: El motor recorre los candidatos en orden de prioridad.
3. Asignar: Los montos se distribuyen según la configuración de allocationDirection (LEFT_TO_RIGHT o RIGHT_TO_LEFT).
4. Rastrear residuos: Cualquier monto no asignado restante se rastrea. Si allowPartial es true, un tramo que se excede se recorta al monto restante; un split con cobertura incompleta aún genera una excepción de diagnóstico.

​

N:M — solucionador de coincidencia de conjuntos

Para escenarios N:M, Matcher no asigna de forma secuencial. Usa un solucionador acotado de selección de subconjuntos: los candidatos se agrupan por la identidad de coincidencia de la regla, y el solucionador busca un subconjunto de transacciones del lado izquierdo y un subconjunto del lado derecho que se concilien entre sí, con cardinalidad limitada por lado. La selección es determinista sobre la entrada ordenada, cada grupo propuesto debe superar el umbral fijo de confianza (puntuación mínima de 60), y ninguna transacción cae en dos grupos propuestos dentro de una misma ejecución. En reglas TOLERANCE, la clave nmDeductionBand permite al solucionador admitir un subconjunto de pagos que paga de menos un subconjunto de facturas dentro de la banda.

​

Razones de excepción

Las transacciones que no pueden conciliarse por completo aparecen como excepciones tipadas:

• SPLIT_INCOMPLETE — existen asignaciones pero no cubren completamente el monto objetivo, independientemente de allowPartial.
• OVER_SETTLED — un tramo excedió lo que estaba liquidando; el remanente sobreliquidado se registra como una excepción tipada.

Puedes filtrar la lista de excepciones por estos valores de reason.

​

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.

​

Próximos pasos

---

Reglas de coincidencia

Configura reglas y configuraciones de asignación.

Seguridad

Seguridad y control de acceso.