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)	Una transacción del lado izquierdo a muchas transacciones del lado derecho, para una división o una 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 transacción única siempre está en el lado izquierdo. Para una agregación, pon en el lado izquierdo el origen que trae el asiento consolidado.

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`	Una transacción del lado izquierdo a muchas transacciones del lado derecho
`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. Matcher los aplica en contextos 1:N:

Campo	Tipo	Descripción
`allowPartial`	Boolean	Permite la asignación parcial de los montos de las transacciones
`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	Asigna los montos base (convertidos). En reglas EXACT y TOLERANCE, también activa `matchBaseAmount` y `matchBaseCurrency`.
`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 en contextos `N:M`. 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 división con asignación

En un contexto 1:N, cada transacción del lado derecho debe pasar los controles de la regla contra la transacción del lado izquierdo. Una regla que compara montos solo coincide con tramos iguales al total, así que una regla de división desactiva matchAmount y deja que la asignación verifique el total. Las reglas TOLERANCE siempre comparan montos.

cURL

curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/rules" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "type": "EXACT",
   "priority": 2,
   "config": {
     "matchAmount": false,
     "matchReference": false,
     "allowPartial": true,
     "allocationToleranceMode": "ABS",
     "allocationToleranceValue": 10.0
   }
 }'

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 del lado izquierdo coincide con muchas transacciones del lado derecho.

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

Lado izquierdo (extracto bancario):

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

Lado derecho (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)

Muchas transacciones coinciden con una transacción consolidada. Esto usa el tipo de contexto 1:N con el origen consolidado en el lado izquierdo. No existe 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

Lado derecho (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

Lado izquierdo (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"
 }'

Una ejecución DRY_RUN informa sus estadísticas, pero no guarda grupos de coincidencia. Para listar grupos de coincidencia, ejecuta con COMMIT.

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 y revoca un grupo CONFIRMED. En ambos casos, sus transacciones vuelven a UNMATCHED. Revocar un grupo CONFIRMED también retira sus residuales de partidas abiertas, anula sus variaciones de comisión y retira las excepciones que generó, en la misma transacción. 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"
 }'

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.
Recolectar: para cada transacción del lado izquierdo, Matcher recolecta las transacciones del lado derecho que pasan los controles de la regla contra ella.
Asignar: Matcher asigna las transacciones recolectadas en el orden de clasificación y se detiene cuando el monto restante queda dentro de la tolerancia de asignación. Omite una transacción en otra moneda. Asigna solo transacciones con el signo de liquidación del signConvention del contexto: el signo de la transacción del lado izquierdo con SAME (el predeterminado), el signo opuesto con OPPOSITE.
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í. Un grupo tiene como máximo 4 transacciones por lado. Matcher omite un bucket que tiene más de 40 transacciones en cualquiera de los lados. Solo las reglas EXACT y TOLERANCE se ejecutan en contextos N:M. 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: una transacción liquidó de más una obligación que una ejecución anterior arrastró abierta. 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 y lee las estadísticas de la ejecución. Una ejecución de prueba no guarda grupos de coincidencia.

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

Console

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 división 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 división 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 división 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