> ## 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 de 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 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                                              |

<Note>
  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.
</Note>

## 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          |

### 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
   }
 }'
```

<Note>
  `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).
</Note>

## 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"
 }'
```

<Tip>Referencia de API: [Crear contexto](/es/reference/matcher/create-context)</Tip>

## 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, deshaz el emparejamiento. Esto rechaza el grupo con un motivo y revierte todas sus transacciones a `UNMATCHED`. 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"
 }'
```

## 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

***

<AccordionGroup>
  <Accordion title="Comienza con 1:N antes de N:M">
    La coincidencia muchos a muchos es compleja. Comienza con patrones más simples y habilita N:M solo cuando sea necesario.
  </Accordion>

  <Accordion title="Usa tolerancia de asignación para redondeos">
    Las pequeñas diferencias de redondeo son comunes en pagos divididos. Configura allocationToleranceValue en unos pocos centavos para evitar excepciones falsas.
  </Accordion>

  <Accordion title="Habilita asignación parcial deliberadamente">
    Solo configura allowPartial como true cuando se esperan coincidencias parciales. Esto previene coincidencias falsas de datos incompletos.
  </Accordion>

  <Accordion title="Ejecuta dry-run antes de confirmar">
    Siempre prueba la coincidencia dividida y agregada en modo DRY\_RUN primero para verificar los resultados de asignación.
  </Accordion>

  <Accordion title="Monitorea los residuos">
    Rastrea los montos residuales a lo largo del tiempo. Los residuos crecientes pueden indicar problemas sistemáticos de coincidencia.
  </Accordion>
</AccordionGroup>

## Próximos pasos

***

<Card title="Reglas de coincidencia" icon="scale-balanced" href="/es/matcher/configuration/matcher-match-rules" horizontal>
  Configura reglas y configuraciones de asignación.
</Card>

<Card title="Seguridad" icon="shield-halved" href="/es/matcher/reference/matcher-security" horizontal>
  Seguridad y control de acceso.
</Card>