> ## 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 transacción 1:1, 1:N (división y agregación) y N:M con tipos de contexto y flags de asignación en las reglas para controlar cómo se distribuyen los montos.
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:
1. **Tipo de contexto**: determina la cardinalidad de la coincidencia (`1:1`, `1:N` o `N:M`).
2. **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
```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
}
}'
```
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](/es/products/matcher/reference/matcher-confidence-scoring).
## 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`:
```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/products/matcher/create-context)
## 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`:
```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"
}'
```
## 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
```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 el historial de ejecuciones de coincidencia
```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
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.
```bash cURL theme={null}
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.
```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 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:
1. **Ordenar**: Matcher ordena las transacciones de forma determinista para asegurar resultados reproducibles entre ejecuciones.
2. **Iterar**: el motor recorre los candidatos en orden de prioridad.
3. **Asignar**: Matcher distribuye los montos según el ajuste `allocationDirection` (`LEFT_TO_RIGHT` o `RIGHT_TO_LEFT`).
4. **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
***
La coincidencia de muchos a muchos es compleja. Empieza con patrones más simples y habilita N:M solo cuando sea necesario.
Las pequeñas diferencias de redondeo son comunes en los pagos divididos. Configura allocationToleranceValue en unos pocos centavos para evitar excepciones falsas.
Configura allowPartial en true solo cuando esperas coincidencias parciales. Esto evita coincidencias falsas por datos incompletos.
Prueba siempre la coincidencia por división y por agregación primero en modo DRY\_RUN para verificar los resultados de asignación.
Haz seguimiento de los montos residuales en el tiempo. Los residuos crecientes pueden indicar problemas sistemáticos de coincidencia.
## Próximos pasos
***
Configura reglas y ajustes de asignación.
Seguridad y control de acceso.