> ## 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. En `why`, los booleanos indican si los dos montos, monedas y fechas son iguales, no los componentes de la puntuación:

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

<Note>Alcance: la simulación lee como máximo 5,000 transacciones no conciliadas del contexto, y los orígenes del contexto deben resolverse en dos lados. 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, la conversión FX 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, después de la conversión FX, 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. `currency` debe ser igual a la moneda del esquema. Ú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",
  "netAmount": "97.7",
  "totalFee": "2.3",
  "currency": "USD",
  "items": [
    { "name": "interchange", "fee": "1.5", "baseUsed": "100" },
    { "name": "processing", "fee": "0.8", "baseUsed": "100" }
  ]
}
```

<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, tipo de regla inválido, lados que no se resuelven, monto bruto inválido) |
| `404` | Contexto, regla o esquema de comisiones no encontrado |
| `422` | Campo con formato incorrecto, como un id inválido |
| `503` | Simulación de coincidencia no disponible |