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

# Simulación

> Ejecuta en modo dry-run una regla de coincidencia contra un contexto y previsualiza el cálculo de comisiones de un programa de comisiones — ambas de solo lectura, para que puedas validar la configuración antes de confirmar nada.

Matcher expone dos endpoints de simulación de solo lectura para que puedas responder "¿qué pasaría?" antes de confirmar la configuración: **simulación de coincidencia** (¿esta regla realmente coincidirá?) y **simulación de comisiones** (¿qué comisiones cobraría este programa de comisiones?). Ninguna persiste nada.

## Simulación de coincidencia

***

Previsualiza cómo una única regla — una regla existente ya configurada (`ruleId`) **o** una regla candidata en línea (`rule`) — coincidiría con las transacciones no conciliadas de un contexto, sin confirmar nada.

```bash theme={null}
curl -X POST "https://api.matcher.example.com/v1/matching/simulate" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "contextId": "550e8400-e29b-41d4-a716-446655440000",
    "rule": {
      "type": "TOLERANCE",
      "config": { "matchAmount": true, "matchCurrency": true, "tolerance": 0.01 }
    },
    "sampleLimit": 25
  }'
```

Proporciona **exactamente uno** de:

* `ruleId` — previsualiza una regla existente ya configurada del contexto.
* `rule` — previsualiza una definición candidata no persistida (`type` es uno de `EXACT`, `TOLERANCE`, `DATE_LAG`, `FUZZY`, más su `config`).

Proporcionar ambos, o ninguno, devuelve `400`. `sampleLimit` (1–200, por defecto 25) limita los pares de posible coincidencia devueltos.

La respuesta indica cuántos grupos 1:1 formaría la regla, una muestra acotada de pares de posible coincidencia (cada uno con una puntuación de confianza y una justificación por componente) y los recuentos de no conciliados por lado:

```json theme={null}
{
  "ruleType": "TOLERANCE",
  "matchedGroups": 12,
  "unmatchedLeft": 3,
  "unmatchedRight": 5,
  "sampleTruncated": false,
  "sample": [
    {
      "left":  { "id": "...", "amount": "100.00", "currency": "BRL", "date": "2025-06-01T00:00:00Z" },
      "right": { "id": "...", "amount": "100.00", "currency": "BRL", "date": "2025-06-01T00:00:00Z" },
      "score": 90,
      "why": { "amountMatch": true, "currencyMatch": true, "dateMatch": true, "referenceScore": 0 },
      "amountDelta": "0.00",
      "dateDeltaDays": 0
    }
  ]
}
```

<Note>Alcance: la simulación puntúa mediante el motor de reglas determinista sobre los montos **originales** de la transacción. **No** aplica la normalización de comisiones en tiempo de ejecución ni la banda de variación de FX, y solo previsualiza el agrupamiento por pares 1:1 (sin asignación 1:N/N:M). Un par que solo coincide tras la normalización de comisiones, dentro de la banda de FX o mediante asignación no se cuenta aquí.</Note>

## Simulación de comisiones

***

Calcula las comisiones para un monto bruto dado usando un programa de comisiones específico. Úsala para validar las reglas de un programa de comisiones antes de asociarlo a un contexto.

```bash theme={null}
curl -X POST "https://api.matcher.example.com/v1/fee-schedules/{scheduleId}/simulate" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "grossAmount": "100.00", "currency": "USD" }'
```

La respuesta devuelve el monto neto, la comisión total y un desglose por ítem:

```json theme={null}
{
  "grossAmount": "100.00",
  "netAmount": "97.70",
  "totalFee": "2.30",
  "currency": "USD",
  "items": [
    { "name": "interchange", "fee": "1.50", "baseUsed": "100.00" }
  ]
}
```

<Note>La simulación de comisiones no tiene metadatos de transacción, por lo que los ítems de comisión basados en expresiones que requieren un identificador de transacción devuelven su error de identificador faltante como un `4xx`. Un programa de comisiones inexistente devuelve `404`.</Note>

## Cuándo usar cada una

***

| Uso                                                                   | Cuándo                                                                                                                                           |
| --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Simulación de coincidencia** (`/matching/simulate`)                 | Estás creando o revisando una regla de coincidencia y quieres ver cuántas transacciones agruparía, y qué pares, antes de confirmarla.            |
| **Simulación de comisiones** (`/fee-schedules/{scheduleId}/simulate`) | Estás configurando un programa de comisiones y quieres verificar el desglose de neto/comisión que produciría para un monto bruto representativo. |

Ambas son estrictamente de solo lectura: nunca persisten una ejecución, grupo, ítem, regla ni transacción, y el tenant siempre se toma del JWT.

## Códigos de respuesta

***

| Estado | Significado                                                                       |
| ------ | --------------------------------------------------------------------------------- |
| `200`  | Simulación devuelta                                                               |
| `400`  | Entrada no válida (regla ambigua/faltante, ids no válidos, monto bruto no válido) |
| `404`  | Contexto, regla o programa de comisiones no encontrado                            |
| `503`  | Simulación de coincidencia no disponible                                          |