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

> Simula una regla de coincidencia y previsualiza los cálculos de un esquema de comisiones en Matcher. Ambos endpoints son de solo lectura, así que puedes validar la configuración antes de comprometer nada.

Matcher expone dos endpoints de simulación de solo lectura para que puedas responder "¿qué pasaría?" antes de comprometer una configuración. Son la **simulación de coincidencia** (¿esta regla va a coincidir?) y la **simulación de comisiones** (¿qué comisiones cobraría este esquema?). Ninguno persiste nada.

## Simulación de coincidencia

***

Previsualiza cómo una sola regla haría coincidir las transacciones no conciliadas de un contexto, sin comprometer nada. Elige una regla configurada existente (`ruleId`) **o** una regla candidata en línea (`rule`).

```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": { "percentTolerance": "0.01" }
    },
    "sampleLimit": 25
  }'
```

Proporciona **exactamente uno** de:

* `ruleId`: previsualiza una regla configurada existente 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, 25 de forma predeterminada) limita los pares candidatos que se devuelven.

La respuesta informa cuántos grupos 1:1 formaría la regla y los conteos de no conciliados por lado. También devuelve una muestra acotada de pares candidatos, cada uno con una puntuación de confianza y una justificación por componente:

```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 con el motor de reglas determinista sobre los montos **brutos** de las transacciones. **No** aplica la normalización de comisiones en tiempo de ejecución ni la banda de variación FX, y previsualiza solo el agrupamiento por pares 1:1 (sin asignación 1:N/N:M). La simulación no cuenta un par que solo coincide después de la normalización de comisiones, dentro de la banda FX o por asignación.</Note>

## Simulación de comisiones

***

Calcula las comisiones de un monto bruto dado con un esquema de comisiones específico. Úsalo para validar las reglas de un esquema 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, así que los ítems de comisión por expresión que requieren un identificador de transacción exponen su error de identificador faltante como un `4xx`. Un esquema que no existe devuelve `404`.</Note>

## Cuándo usar cada una

***

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

Ambos endpoints se mantienen estrictamente de solo lectura. Nunca persisten una ejecución, un grupo, un ítem, una regla ni una transacción. El tenant siempre viene del JWT.

## Códigos de respuesta

***

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