Coincidencias divididas y agregadas

La conciliación del mundo real a menudo involucra transacciones que no coinciden 1:1. Un solo pago puede cubrir varias facturas, o varios depósitos pueden consolidarse en un solo asiento bancario. Matcher atiende estos escenarios complejos mediante la coincidencia por división y por agregación.

Resumen

El tipo de contexto controla la cardinalidad de la coincidencia. Matcher admite tres tipos de contexto:

Tipo de contexto	Descripción	Ejemplo
1:1 — uno a uno	Un origen a un destino	Pago de una sola factura
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 que cubre facturas; depósitos consolidados en un banco
N:M — muchos a muchos	Cualquier combinación de orígenes y destinos	Neteo complejo

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

Cómo funciona

Dos mecanismos controlan el comportamiento de división y agregación:

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

No hay un ajuste separado de “split” o “aggregate” en el contexto. El tipo de contexto define los patrones permitidos, y la configuración de la regla controla el comportamiento de asignación.

Mapeo de tipos de contexto

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

Configuración de asignación de la regla

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

Campo	Tipo	Descripción
`allowPartial`	Boolean	Permite la asignación parcial de los montos de las transacciones
`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 los residuos de asignación
`allocationUseBaseAmount`	Boolean	Usa el monto base (convertido) para la asignación
`feeAware`	Boolean	Asignación 1:N consciente de comisiones: consume la parte bruta de cada candidato (neto + comisión) en lugar de solo el neto. Útil para divisiones de marketplace donde el pago es neto de comisiones
`nmDeductionBand`	Decimal	Solo para reglas TOLERANCE. Banda de pago insuficiente para el solucionador N:M, como fracción decimal del valor nominal de la factura corta (`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 deshabilita

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
   }
 }'

Matcher acepta y valida matchScore y matchBaseScore. Ambas claves siguen siendo reservadas/inertes. No cambian la puntuación de confianza calculada. Matcher siempre calcula la confianza a partir de los pesos internos fijos de los componentes (monto 40, moneda 30, fecha 20, referencia 10). Consulta Puntuación de confianza.

Cómo crear un contexto 1:N

Para habilitar la coincidencia por división o por agregación, crea un contexto con el 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 por división 1:N

Una transacción de origen coincide con varias transacciones de destino.

Casos de uso comunes

Pago masivo: una sola transferencia bancaria que cubre varias facturas
Nómina: un solo débito bancario para varios pagos de salario
Liquidación: un solo pago del gateway para varios pedidos

Ejemplo: pago masivo de facturas

Origen (extracto bancario):

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

Destinos (asientos del ledger):

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 por agregación (muchos a uno)

Varias 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: varios cheques depositados como un solo crédito
Liquidaciones de tarjetas: lote diario de transacciones como un solo depósito
Consolidación de efectivo: varios recibos de caja registradora a un solo 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 de muchos a muchos

Varias transacciones de origen coinciden con varias transacciones de destino. Este es el patrón más complejo.

Casos de uso comunes

Neteo intercompañía: varias facturas neteadas contra varios pagos
Liquidaciones de operaciones: compensación compleja con ejecuciones parciales
Reconocimiento de ingresos: varias entregas contra varios anticipos

Ejemplo: neteo intercompañía

Orígenes (cuentas por pagar de la 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 de la 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 en total coincidente Para habilitar la coincidencia N:M, crea un contexto con el 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"
 }'

Cómo ejecutar y revisar las coincidencias

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

Ejecutar la 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 el historial de ejecuciones de coincidencia

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

Debes enviar el parámetro de query string contextId. La respuesta es una lista de grupos de coincidencia paginada por cursor, cada uno con sus transacciones coincidentes (en todas las cardinalidades) y sus puntuaciones de confianza.

cURL

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

Romper (deshacer) un grupo de coincidencia

Para revertir un grupo incorrecto, deshaz la coincidencia. Matcher rechaza un grupo PROPOSED con un motivo, y sus transacciones vuelven a UNMATCHED. Para un grupo CONFIRMED, Matcher además revierte los efectos sobre residuos y partidas abiertas que aplicó la confirmación, de forma atómica junto con la revocación del grupo y la devolución de sus transacciones. Debes enviar el parámetro de query string contextId y 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 a ser WITHDRAWN terminal. Queda como historial, pero no es neteable y ninguna otra ejecución la arrastra. Matcher verifica la reversibilidad antes de cambiar nada. El endpoint devuelve 409 Conflict si un asiento activo posterior todavía se apoya en el residuo. También devuelve ese error si una obligación activa más reciente entraría en conflicto con la restauración de una partida terminal en la misma identidad. En ambos casos deja el grupo, las transacciones y las partidas abiertas sin cambios.

Algoritmo de coincidencia

El algoritmo depende del tipo de contexto.

Asignación secuencial determinista 1:N

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

Ordenar: Matcher ordena las transacciones de forma determinista para asegurar resultados reproducibles entre ejecuciones.
Iterar: el motor recorre los candidatos en orden de prioridad.
Asignar: Matcher distribuye los montos según el ajuste allocationDirection (LEFT_TO_RIGHT o RIGHT_TO_LEFT).
Seguir los residuos: Matcher hace seguimiento de los montos que quedan sin asignar. Si allowPartial es true, Matcher limita un tramo que se excede al monto restante. Una división con cobertura insuficiente igual expone una excepción de diagnóstico.

Solucionador de coincidencia de conjuntos N:M

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

Motivos de excepción

Las transacciones que Matcher no puede conciliar por completo se exponen como excepciones tipificadas:

SPLIT_INCOMPLETE: existen asignaciones pero no cubren por completo el monto de destino, sin importar allowPartial.
OVER_SETTLED: un tramo liquidó de más. Matcher expone el remanente liquidado de más como una discrepancia tipificada.

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

Mejores prácticas

Empieza con 1:N antes de N:M

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

Usa la tolerancia de asignación para el redondeo

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

Habilita la asignación parcial de forma deliberada

Configura allowPartial en true solo cuando esperas coincidencias parciales. Esto evita coincidencias falsas por datos incompletos.

Haz una ejecución de prueba antes de confirmar

Prueba siempre la coincidencia por división y por agregación primero en modo DRY_RUN para verificar los resultados de asignación.

Monitorea los residuos

Haz seguimiento de los montos residuales en el tiempo. Los residuos crecientes pueden indicar problemas sistemáticos de coincidencia.

Resumen

Guías

Matcher UI

Servidor MCP

Operaciones

Coincidencias divididas y agregadas

Resumen

Cómo funciona

Mapeo de tipos de contexto

Configuración de asignación de la regla

Ejemplo: regla de tolerancia con asignación

Cómo crear un contexto 1:N

Coincidencia por división 1:N

Casos de uso comunes

Ejemplo: pago masivo de facturas

Coincidencia por agregación (muchos a uno)

Casos de uso comunes

Ejemplo: depósito consolidado

Coincidencia N:M de muchos a muchos

Casos de uso comunes

Ejemplo: neteo intercompañía

Cómo ejecutar y revisar las coincidencias

Ejecutar la coincidencia

Ver el historial de ejecuciones de coincidencia

Ver los grupos de coincidencia de una ejecución

Romper (deshacer) un grupo de coincidencia

Algoritmo de coincidencia

Asignación secuencial determinista 1:N

Solucionador de coincidencia de conjuntos N:M

Motivos de excepción

Mejores prácticas

Próximos pasos

Reglas de coincidencia

Seguridad

​Resumen

​Cómo funciona

​Mapeo de tipos de contexto

​Configuración de asignación de la regla

​Ejemplo: regla de tolerancia con asignación

​Cómo crear un contexto 1:N

​Coincidencia por división 1:N

​Casos de uso comunes

​Ejemplo: pago masivo de facturas

​Coincidencia por agregación (muchos a uno)

​Casos de uso comunes

​Ejemplo: depósito consolidado

​Coincidencia N:M de muchos a muchos

​Casos de uso comunes

​Ejemplo: neteo intercompañía

​Cómo ejecutar y revisar las coincidencias

​Ejecutar la coincidencia

​Ver el historial de ejecuciones de coincidencia

​Ver los grupos de coincidencia de una ejecución

​Romper (deshacer) un grupo de coincidencia

​Algoritmo de coincidencia

​Asignación secuencial determinista 1:N

​Solucionador de coincidencia de conjuntos N:M

​Motivos de excepción

​Mejores prácticas

​Próximos pasos

Reglas de coincidencia

Seguridad

Resumen

Cómo funciona

Mapeo de tipos de contexto

Configuración de asignación de la regla

Ejemplo: regla de tolerancia con asignación

Cómo crear un contexto 1:N

Coincidencia por división 1:N

Casos de uso comunes

Ejemplo: pago masivo de facturas

Coincidencia por agregación (muchos a uno)

Casos de uso comunes

Ejemplo: depósito consolidado

Coincidencia N:M de muchos a muchos

Casos de uso comunes

Ejemplo: neteo intercompañía

Cómo ejecutar y revisar las coincidencias

Ejecutar la coincidencia

Ver el historial de ejecuciones de coincidencia

Ver los grupos de coincidencia de una ejecución

Romper (deshacer) un grupo de coincidencia

Algoritmo de coincidencia

Asignación secuencial determinista 1:N

Solucionador de coincidencia de conjuntos N:M

Motivos de excepción

Mejores prácticas

Próximos pasos