> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.
# 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
```bash cURL theme={null}
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](/es/matcher/reference/matcher-confidence-scoring).
## Creando un contexto 1:N
***
Para habilitar coincidencia dividida o agregada, crea un contexto con tipo `1:N`:
```bash cURL theme={null}
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](/es/reference/matcher/create-context)
## 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`:
```bash cURL theme={null}
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
```bash cURL theme={null}
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
```bash cURL theme={null}
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.
```bash cURL theme={null}
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.
```bash cURL theme={null}
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
***
La coincidencia muchos a muchos es compleja. Comienza con patrones más simples y habilita N:M solo cuando sea necesario.
Las pequeñas diferencias de redondeo son comunes en pagos divididos. Configura allocationToleranceValue en unos pocos centavos para evitar excepciones falsas.
Solo configura allowPartial como true cuando se esperan coincidencias parciales. Esto previene coincidencias falsas de datos incompletos.
Siempre prueba la coincidencia dividida y agregada en modo DRY\_RUN primero para verificar los resultados de asignación.
Rastrea los montos residuales a lo largo del tiempo. Los residuos crecientes pueden indicar problemas sistemáticos de coincidencia.
## Próximos pasos
***
Configura reglas y configuraciones de asignación.
Seguridad y control de acceso.