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

# Simulação

> Execute em modo dry-run uma regra de match contra um contexto e previsualize o cálculo de taxas de um programa de taxas — ambas somente leitura, para que você possa validar a configuração antes de confirmar qualquer coisa.

O Matcher expõe dois endpoints de simulação somente leitura para que você possa responder "o que aconteceria?" antes de confirmar a configuração: **simulação de match** (esta regra realmente fará match?) e **simulação de taxas** (quais taxas este programa de taxas cobraria?). Nenhuma persiste nada.

## Simulação de match

***

Previsualize como uma única regra — uma regra existente já configurada (`ruleId`) **ou** uma regra candidata inline (`rule`) — faria match com as transações não conciliadas de um contexto, sem 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
  }'
```

Forneça **exatamente um** de:

* `ruleId` — previsualiza uma regra existente já configurada do contexto.
* `rule` — previsualiza uma definição candidata não persistida (`type` é um de `EXACT`, `TOLERANCE`, `DATE_LAG`, `FUZZY`, mais seu `config`).

Fornecer ambos, ou nenhum, retorna `400`. `sampleLimit` (1–200, padrão 25) limita os pares de possível match retornados.

A resposta informa quantos grupos 1:1 a regra formaria, uma amostra limitada de pares de possível match (cada um com uma pontuação de confiança e uma justificativa por componente) e as contagens de não 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>Escopo: a simulação pontua por meio do motor de regras determinístico sobre os valores **originais** da transação. **Não** aplica a normalização de taxas em tempo de execução nem a banda de variação de câmbio, e previsualiza apenas o agrupamento por pares 1:1 (sem alocação 1:N/N:M). Um par que só faz match após a normalização de taxas, dentro da banda de câmbio ou por alocação não é contado aqui.</Note>

## Simulação de taxas

***

Calcule as taxas para um valor bruto informado usando um programa de taxas específico. Use-a para validar as regras de um programa de taxas antes de anexá-lo a um 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" }'
```

A resposta retorna o valor líquido, a taxa total e um detalhamento por item:

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

<Note>A simulação de taxas não tem metadados de transação, portanto os itens de taxa baseados em expressão que exigem um identificador de transação retornam seu erro de identificador ausente como um `4xx`. Um programa de taxas inexistente retorna `404`.</Note>

## Quando usar cada uma

***

| Uso                                                             | Quando                                                                                                                                             |
| --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Simulação de match** (`/matching/simulate`)                   | Você está criando ou revisando uma regra de match e quer ver quantas transações ela agruparia, e quais pares, antes de confirmá-la.                |
| **Simulação de taxas** (`/fee-schedules/{scheduleId}/simulate`) | Você está configurando um programa de taxas e quer verificar o detalhamento de líquido/taxa que ele produziria para um valor bruto representativo. |

Ambas são estritamente somente leitura: nunca persistem uma execução, grupo, item, regra ou transação, e o tenant é sempre obtido do JWT.

## Códigos de resposta

***

| Status | Significado                                                                   |
| ------ | ----------------------------------------------------------------------------- |
| `200`  | Simulação retornada                                                           |
| `400`  | Entrada inválida (regra ambígua/ausente, ids inválidos, valor bruto inválido) |
| `404`  | Contexto, regra ou programa de taxas não encontrado                           |
| `503`  | Simulação de match indisponível                                               |