Saltar al contenido principal
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

Matcher soporta cuatro patrones de coincidencia:
PatrónDescripciónEjemplo
1:1Uno a unoPago de factura única
1:NUno a muchosPago masivo cubriendo facturas
N:1Muchos a unoDepósitos consolidados en banco
N:MMuchos a muchosCompensación compleja

​
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 contextoPatrones permitidos
1:1Solo un origen a un destino
1:NUn origen a muchos destinos (split), o muchos orígenes a un destino (aggregate)
N:MCualquier 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:
CampoTipoDescripción
allowPartialBooleanPermitir asignación parcial de montos de transacción
allocationDirectionStringOrden de asignación: LEFT_TO_RIGHT o RIGHT_TO_LEFT
allocationToleranceModeStringCómo se mide la tolerancia: ABS (absoluta) o PERCENT
allocationToleranceValueDecimalUmbral de tolerancia para residuos de asignación
allocationUseBaseAmountBooleanUsar monto base (convertido) para la asignación

​
Ejemplo: regla de tolerancia con asignación

cURL
curl -X POST "https://api.matcher.example.com/v1/config/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
   }
 }'

​
Creando un contexto 1:N

Para habilitar coincidencia dividida o agregada, cree un contexto con tipo 1:N:
cURL
curl -X POST "https://api.matcher.example.com/v1/config/contexts" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "name": "Payment Reconciliation",
   "type": "1:N",
   "interval": "daily"
 }'
API Reference: 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):
IDMontoReferencia
bank_001$15,000.00BULK-PAY-2024-001
Destinos (Asientos contables):
IDMontoFactura
inv_001$5,000.00INV-2024-001
inv_002$7,500.00INV-2024-002
inv_003$2,500.00INV-2024-003
Resultado: Coincidencia 1:3 con asignación completa

​
Coincidencia agregada N:1

Múltiples transacciones de origen coinciden con una transacción de destino.

​
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):
IDMontoCaja
pos_001$1,250.00REG-01
pos_002$980.00REG-02
pos_003$1,770.00REG-03
Destino (Extracto bancario):
IDMontoReferencia
bank_002$4,000.00DEPOSIT-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):
IDMontoReferencia
pay_001$10,000.00IC-PAY-001
pay_002$8,000.00IC-PAY-002
Destinos (Cuentas por cobrar Empresa A):
IDMontoReferencia
rec_001$12,000.00IC-REC-001
rec_002$6,000.00IC-REC-002
Resultado: Coincidencia 2:2, $18,000 total coincidido Para habilitar coincidencia N:M, cree un contexto con tipo N:M:
cURL
curl -X POST "https://api.matcher.example.com/v1/config/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, inicie una ejecución de coincidencia y revise 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 grupos de coincidencia

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

​
Ver detalles del grupo

cURL
curl -X GET "https://api.matcher.example.com/v1/matching/groups/{groupId}" \
 -H "Authorization: Bearer $TOKEN"

​
Confirmar un grupo de coincidencia

cURL
curl -X POST "https://api.matcher.example.com/v1/matching/groups/{groupId}/confirm" \
 -H "Authorization: Bearer $TOKEN"

​
Rechazar un grupo de coincidencia

cURL
curl -X POST "https://api.matcher.example.com/v1/matching/groups/{groupId}/reject" \
 -H "Authorization: Bearer $TOKEN"

​
Revocar un grupo de coincidencia confirmado

cURL
curl -X POST "https://api.matcher.example.com/v1/matching/groups/{groupId}/revoke" \
 -H "Authorization: Bearer $TOKEN"

​
Algoritmo de coincidencia

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

​
Cómo funciona

  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, se crean coincidencias parciales; de lo contrario, las transacciones no asignadas se convierten en excepciones.

​
Mejores prácticas

La coincidencia muchos a muchos es compleja. Comience con patrones más simples y habilite N:M solo cuando sea necesario.
Las pequeñas diferencias de redondeo son comunes en pagos divididos. Configure allocationToleranceValue en unos pocos centavos para evitar excepciones falsas.
Solo configure allowPartial como true cuando se esperan coincidencias parciales. Esto previene coincidencias falsas de datos incompletos.
Siempre pruebe la coincidencia dividida y agregada en modo DRY_RUN primero para verificar los resultados de asignación.
Rastree los montos residuales a lo largo del tiempo. Los residuos crecientes pueden indicar problemas sistemáticos de coincidencia.

​
Próximos pasos

Reglas de coincidencia

Configure reglas y configuraciones de asignación.

Seguridad

Seguridad y control de acceso.