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

Matcher permite cuatro patrones de coincidencia:

Patrón	Descripción	Ejemplo
1:1	Uno a uno	Pago de factura única
1:N	Uno a muchos	Pago masivo cubriendo facturas
N:1	Muchos a uno	Depósitos consolidados en banco
N:M	Muchos a muchos	Compensación compleja

Habilitando coincidencia compleja

Configuración de contexto

Habilite la coincidencia dividida y agregada a nivel de contexto:

cURL

curl -X PATCH "https://api.matcher.example.com/v1/contexts/ctx_abc123" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "settings": {
     "matching": {
       "allow_split": true,
       "allow_aggregate": true,
       "allow_many_to_many": false,
       "max_transactions_per_group": 20,
       "require_full_allocation": true
     }
   }
 }'

Respuesta

{
  "id": "ctx_abc123",
  "name": "Payment Reconciliation",
  "settings": {
    "matching": {
      "allow_split": true,
      "allow_aggregate": true,
      "allow_many_to_many": false,
      "max_transactions_per_group": 20,
      "require_full_allocation": true
    }
  }
}

Configuración de coincidencia

Configuración	Tipo	Por defecto	Descripción
`allow_split`	Boolean	false	Habilitar coincidencia 1:N
`allow_aggregate`	Boolean	false	Habilitar coincidencia N:1
`allow_many_to_many`	Boolean	false	Habilitar coincidencia N:M
`max_transactions_per_group`	Integer	10	Máximo de transacciones en un grupo
`require_full_allocation`	Boolean	true	Requerir asignación del 100%
`partial_match_threshold`	Decimal	0.95	Asignación mínima para parcial (95%)

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

API: crear coincidencia dividida

cURL

curl -X POST "https://api.matcher.example.com/v1/contexts/ctx_abc123/matches" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "type": "SPLIT",
   "source_transactions": [
     {
       "transaction_id": "bank_001",
       "amount": 15000.0
     }
   ],
   "target_transactions": [
     {
       "transaction_id": "inv_001",
       "allocated_amount": 5000.0
     },
     {
       "transaction_id": "inv_002",
       "allocated_amount": 7500.0
     },
     {
       "transaction_id": "inv_003",
       "allocated_amount": 2500.0
     }
   ]
 }'

Respuesta

{
  "match_id": "match_split_001",
  "type": "SPLIT",
  "status": "PROPOSED",
  "confidence": 95,
  "source": {
    "transaction_count": 1,
    "total_amount": 15000.0,
    "allocated_amount": 15000.0,
    "allocation_percent": 100.0
  },
  "targets": {
    "transaction_count": 3,
    "total_amount": 15000.0,
    "allocated_amount": 15000.0,
    "allocation_percent": 100.0
  },
  "residual": 0.0,
  "transactions": [
    {
      "id": "bank_001",
      "role": "SOURCE",
      "amount": 15000.0,
      "allocated": 15000.0
    },
    {
      "id": "inv_001",
      "role": "TARGET",
      "amount": 5000.0,
      "allocated": 5000.0
    },
    {
      "id": "inv_002",
      "role": "TARGET",
      "amount": 7500.0,
      "allocated": 7500.0
    },
    {
      "id": "inv_003",
      "role": "TARGET",
      "amount": 2500.0,
      "allocated": 2500.0
    }
  ],
  "created_at": "2024-01-20T10:00:00Z"
}

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):

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

API: crear coincidencia agregada

cURL

curl -X POST "https://api.matcher.example.com/v1/contexts/ctx_abc123/matches" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "type": "AGGREGATE",
   "source_transactions": [
     {
       "transaction_id": "pos_001",
       "allocated_amount": 1250.0
     },
     {
       "transaction_id": "pos_002",
       "allocated_amount": 980.0
     },
     {
       "transaction_id": "pos_003",
       "allocated_amount": 1770.0
     }
   ],
   "target_transactions": [
     {
       "transaction_id": "bank_002",
       "amount": 4000.0
     }
   ]
 }'

Respuesta

{
  "match_id": "match_agg_001",
  "type": "AGGREGATE",
  "status": "PROPOSED",
  "confidence": 92,
  "source": {
    "transaction_count": 3,
    "total_amount": 4000.0,
    "allocated_amount": 4000.0,
    "allocation_percent": 100.0
  },
  "targets": {
    "transaction_count": 1,
    "total_amount": 4000.0,
    "allocated_amount": 4000.0,
    "allocation_percent": 100.0
  },
  "residual": 0.0
}

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 y requiere el solucionador de grafos.

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

API: crear coincidencia N:M

curl -X POST "https://api.matcher.example.com/v1/contexts/ctx_abc123/matches" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "type": "MANY_TO_MANY",
   "source_transactions": [
     {
       "transaction_id": "pay_001",
       "allocated_amount": 10000.0
     },
     {
       "transaction_id": "pay_002",
       "allocated_amount": 8000.0
     }
   ],
   "target_transactions": [
     {
       "transaction_id": "rec_001",
       "allocated_amount": 12000.0
     },
     {
       "transaction_id": "rec_002",
       "allocated_amount": 6000.0
     }
   ]
 }'

Seguimiento de asignación

Matcher rastrea cuánto de cada transacción ha sido asignado a coincidencias.

Estado de asignación de transacción

Estado	Descripción
`UNALLOCATED`	Sin asignación (0%)
`PARTIALLY_ALLOCATED`	Algo de asignación (1-99%)
`FULLY_ALLOCATED`	Asignación completa (100%)

Ver asignación de transacción

curl -X GET "https://api.matcher.example.com/v1/transactions/bank_001/allocation" \
 -H "Authorization: Bearer $TOKEN"

Respuesta

{
  "transaction_id": "bank_001",
  "total_amount": 15000.0,
  "currency": "USD",
  "allocation_status": "FULLY_ALLOCATED",
  "allocations": [
    {
      "match_id": "match_split_001",
      "allocated_amount": 15000.0,
      "allocation_percent": 100.0,
      "status": "CONFIRMED"
    }
  ],
  "available_amount": 0.0,
  "available_percent": 0.0
}

Ejemplo de asignación parcial

Transacción con monto no asignado restante:

{
  "transaction_id": "bank_003",
  "total_amount": 10000.0,
  "allocation_status": "PARTIALLY_ALLOCATED",
  "allocations": [
    {
      "match_id": "match_002",
      "allocated_amount": 7500.0,
      "allocation_percent": 75.0,
      "status": "CONFIRMED"
    }
  ],
  "available_amount": 2500.0,
  "available_percent": 25.0
}

Coincidencias parciales

Por defecto, Matcher requiere asignación completa. Habilite la coincidencia parcial para escenarios donde la coincidencia completa no es posible.

Habilitar coincidencia parcial

{
  "settings": {
    "matching": {
      "require_full_allocation": false,
      "partial_match_threshold": 0.9,
      "partial_match_behavior": "propose_with_residual"
    }
  }
}

Comportamientos de coincidencia parcial

Comportamiento	Descripción
`propose_with_residual`	Crear coincidencia, rastrear residuo
`create_exception`	Crear excepción para porción no coincidente
`hold_for_review`	Retener hasta que lleguen transacciones adicionales

Respuesta de coincidencia parcial

{
  "match_id": "match_partial_001",
  "type": "SPLIT",
  "status": "PROPOSED",
  "confidence": 78,
  "source": {
    "total_amount": 10000.0,
    "allocated_amount": 9500.0,
    "allocation_percent": 95.0
  },
  "targets": {
    "total_amount": 9500.0,
    "allocated_amount": 9500.0,
    "allocation_percent": 100.0
  },
  "residual": {
    "amount": 500.0,
    "percent": 5.0,
    "status": "UNALLOCATED",
    "exception_id": "exc_residual_001"
  }
}

Solucionador de grafos

Para escenarios N:M complejos, Matcher usa un solucionador de grafos bipartitos para encontrar coincidencias óptimas.

Cómo funciona

Construir grafo: Crear grafo bipartito con orígenes y destinos como nodos
Pesos de aristas: Calcular confianza de coincidencia como pesos de aristas
Resolver: Encontrar coincidencia de máximo peso
Asignar: Distribuir montos entre pares coincidentes

Configuración del solucionador de grafos

{
  "settings": {
    "graph_solver": {
      "enabled": true,
      "algorithm": "hungarian",
      "max_nodes": 100,
      "min_edge_confidence": 50,
      "optimization_goal": "maximize_allocation"
    }
  }
}

Algoritmos del solucionador

Algoritmo	Mejor para	Complejidad
`hungarian`	Grafos pequeños (<100 nodos)	O(n³)
`auction`	Grafos medianos (<1000 nodos)	O(n² log n)
`greedy`	Grafos grandes (>1000 nodos)	O(n log n)

Ejecutar solucionador de grafos

cURL

curl -X POST "https://api.matcher.example.com/v1/contexts/ctx_abc123/solve" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "source_transactions": [
     "pay_001",
     "pay_002",
     "pay_003"
   ],
   "target_transactions": [
     "rec_001",
     "rec_002",
     "rec_003"
   ],
   "options": {
     "algorithm": "hungarian",
     "allow_partial": true,
     "min_confidence": 60
   }
 }'

Respuesta

{
  "solver_id": "solve_001",
  "status": "COMPLETED",
  "algorithm": "hungarian",
  "execution_time_ms": 45,
  "results": {
    "proposed_matches": [
      {
        "match_id": "match_proposed_001",
        "type": "MANY_TO_MANY",
        "confidence": 88,
        "allocations": [
          {
            "source": "pay_001",
            "target": "rec_001",
            "amount": 10000.0
          },
          {
            "source": "pay_002",
            "target": "rec_001",
            "amount": 2000.0
          },
          {
            "source": "pay_002",
            "target": "rec_002",
            "amount": 6000.0
          }
        ]
      }
    ],
    "unmatched_sources": [],
    "unmatched_targets": [],
    "total_matched": 18000.0,
    "match_rate": 100.0
  }
}

Reglas de tolerancia

Configure cómo se aplica la tolerancia a coincidencias divididas y agregadas.

Modos de tolerancia

Modo	Descripción	Caso de uso
`residual`	Aplicar al monto final no coincidente	Por defecto, más común
`per_item`	Aplicar a cada transacción	Coincidencia estricta
`total`	Aplicar a la suma de todas las transacciones	Coincidencia flexible

Configurar modo de tolerancia

{
  "settings": {
    "matching": {
      "tolerance_mode": "residual",
      "tolerance_percent": 1.0,
      "tolerance_absolute": 50.0
    }
  }
}

Ejemplos de tolerancia

Modo residual (por defecto):

Origen: $10,000.00
Destinos: $9,980.00 total
Residuo: $20.00 (0.2%)
Tolerancia: 1% = $100.00
Resultado: Coincidencia (residuo dentro de tolerancia)

Modo por elemento:

Origen: $10,000.00
Destino 1: $5,010.00 (0.2% varianza)
Destino 2: $4,980.00 (0.4% varianza)
Cada uno dentro de 1% de tolerancia
Resultado: Coincidencia (todos los elementos dentro de tolerancia)

Auto-descubrimiento

Matcher puede descubrir automáticamente patrones de división y agregación.

Habilitar auto-descubrimiento

{
  "settings": {
    "auto_discovery": {
      "enabled": true,
      "max_group_size": 10,
      "time_window_days": 7,
      "min_confidence": 75
    }
  }
}

Heurísticas de descubrimiento

Heurística	Descripción
Suma de montos	Encontrar combinaciones que suman al objetivo
Patrones de referencia	Coincidir basado en referencias comunes
Agrupación temporal	Agrupar transacciones por proximidad de fecha
Agrupación por contraparte	Agrupar por misma contraparte

Ver grupos descubiertos

curl -X GET "https://api.matcher.example.com/v1/contexts/ctx_abc123/discoveries" \
 -H "Authorization: Bearer $TOKEN"

Respuesta

{
  "discoveries": [
    {
      "id": "disc_001",
      "type": "AGGREGATE",
      "confidence": 85,
      "heuristic": "amount_summing",
      "source_transactions": [
        "pos_001",
        "pos_002",
        "pos_003"
      ],
      "target_transactions": [
        "bank_002"
      ],
      "source_total": 4000.0,
      "target_total": 4000.0,
      "residual": 0.0
    }
  ]
}

Reportes

Resumen de coincidencias grupales

curl -X GET "https://api.matcher.example.com/v1/contexts/ctx_abc123/reports/group-matches" \
 -H "Authorization: Bearer $TOKEN" \
 -G \
 -d "date_from=2024-01-01" \
 -d "date_to=2024-01-31"

{
  "period": {
    "from": "2024-01-01",
    "to": "2024-01-31"
  },
  "summary": {
    "total_matches": 1250,
    "by_type": {
      "one_to_one": 980,
      "split": 150,
      "aggregate": 100,
      "many_to_many": 20
    },
    "avg_group_size": {
      "split": 3.2,
      "aggregate": 4.5,
      "many_to_many": 6.1
    },
    "partial_matches": 45,
    "total_residual": 12500.0
  }
}

Mejores prácticas

Comience con 1:N y N:1 antes de N:M

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

Establezca límites razonables de tamaño de grupo

Los grupos grandes son más difíciles de verificar. Limite el tamaño del grupo según sus requisitos de auditoría.

Use auto-descubrimiento con revisión

Habilite el auto-descubrimiento para encontrar patrones, pero requiera revisión humana antes de confirmar coincidencias complejas.

Monitoree los residuos

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

Documente las reglas de asignación

Cuando son posibles múltiples estrategias de asignación, documente por qué se eligieron asignaciones específicas.

Pruebe el solucionador de grafos con datos de muestra

Antes de habilitar el solucionador de grafos en producción, pruebe con datos representativos para verificar los resultados.

Introduction

Primeros pasos

Configuración

Reconciliación diaria

Integraciones

Referencia

​Descripción general

​Habilitando coincidencia compleja

​Configuración de contexto

​Respuesta

​Configuración de coincidencia

​Coincidencia dividida 1:N

​Casos de uso comunes

​Ejemplo: pago masivo de facturas

​API: crear coincidencia dividida

​Respuesta

​Coincidencia agregada N:1

​Casos de uso comunes

​Ejemplo: depósito consolidado

​API: crear coincidencia agregada

​Respuesta

​Coincidencia N:M muchos a muchos

​Casos de uso comunes

​Ejemplo: compensación intercompañía

​API: crear coincidencia N:M

​Seguimiento de asignación

​Estado de asignación de transacción

​Ver asignación de transacción

​Respuesta

​Ejemplo de asignación parcial

​Coincidencias parciales

​Habilitar coincidencia parcial

​Comportamientos de coincidencia parcial

​Respuesta de coincidencia parcial

​Solucionador de grafos

​Cómo funciona

​Configuración del solucionador de grafos

​Algoritmos del solucionador

​Ejecutar solucionador de grafos

​Respuesta

​Reglas de tolerancia

​Modos de tolerancia

​Configurar modo de tolerancia

​Ejemplos de tolerancia

​Auto-descubrimiento

​Habilitar auto-descubrimiento

​Heurísticas de descubrimiento

​Ver grupos descubiertos

​Respuesta

​Reportes

​Resumen de coincidencias grupales

​Mejores prácticas

​Próximos pasos

Reglas de coincidencia

Seguridad

Descripción general

Habilitando coincidencia compleja

Configuración de contexto

Respuesta

Configuración de coincidencia

Coincidencia dividida 1:N

Casos de uso comunes

Ejemplo: pago masivo de facturas

API: crear coincidencia dividida

Respuesta

Coincidencia agregada N:1

Casos de uso comunes

Ejemplo: depósito consolidado

API: crear coincidencia agregada

Respuesta

Coincidencia N:M muchos a muchos

Casos de uso comunes

Ejemplo: compensación intercompañía

API: crear coincidencia N:M

Seguimiento de asignación

Estado de asignación de transacción

Ver asignación de transacción

Respuesta

Ejemplo de asignación parcial

Coincidencias parciales

Habilitar coincidencia parcial

Comportamientos de coincidencia parcial

Respuesta de coincidencia parcial

Solucionador de grafos

Cómo funciona

Configuración del solucionador de grafos

Algoritmos del solucionador

Ejecutar solucionador de grafos

Respuesta

Reglas de tolerancia

Modos de tolerancia

Configurar modo de tolerancia

Ejemplos de tolerancia

Auto-descubrimiento

Habilitar auto-descubrimiento

Heurísticas de descubrimiento

Ver grupos descubiertos

Respuesta

Reportes

Resumen de coincidencias grupales

Mejores prácticas

Próximos pasos