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

> Rode uma regra de correspondência em modo de teste e veja antes os cálculos de uma tabela de tarifas no Matcher. Os dois endpoints são somente leitura, então você valida a configuração antes de gravar qualquer coisa.

O Matcher expõe dois endpoints de simulação somente leitura para você responder "o que aconteceria?" antes de gravar a configuração. São a **simulação de correspondência** (esta regra vai corresponder?) e a **simulação de tarifas** (que tarifas esta tabela cobraria?). Nenhum dos dois persiste nada.

## Simulação de correspondência

***

Veja antes como uma única regra corresponderia às transações não conciliadas de um contexto, sem gravar nada. Escolha uma regra configurada existente (`ruleId`) **ou** uma regra candidata inline (`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
  }'
```

Informe **exatamente um** destes:

* `ruleId`: pré-visualize uma regra configurada existente do contexto.
* `rule`: pré-visualize uma definição candidata não persistida (`type` é um entre `EXACT`, `TOLERANCE`, `DATE_LAG`, `FUZZY`, mais a `config` dela).

Informar os dois, ou nenhum, retorna `400`. `sampleLimit` (1–200, padrão 25) limita os pares de correspondência potencial retornados.

A resposta informa quantos grupos 1:1 a regra formaria e as contagens de não conciliados de cada lado. Ela também retorna uma amostra limitada de pares de correspondência potencial, cada um com uma pontuação de confiança e a justificativa 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>Escopo: a simulação pontua pelo motor determinístico de regras sobre os valores **brutos** das transações. Ela **não** aplica a normalização de tarifas em tempo de execução nem a faixa de variação de câmbio, e pré-visualiza apenas o agrupamento par a par 1:1 (sem alocação 1:N/N:M). A simulação não conta um par que apenas corresponde depois da normalização de tarifas, dentro da faixa de câmbio ou por alocação.</Note>

## Simulação de tarifas

***

Calcule as tarifas para um valor bruto usando uma tabela de tarifas específica. Use isso para validar as regras de uma tabela antes de anexá-la 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 tarifa total e a composição 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 tarifas não tem metadados de transação, então os itens de tarifa por expressão que exigem um identificador de transação mostram o erro de identificador ausente como `4xx`. Uma tabela inexistente retorna `404`.</Note>

## Quando usar cada uma

***

| Uso                                                               | Quando                                                                                                                                               |
| ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Simulação de correspondência** (`/matching/simulate`)           | Você está escrevendo ou revisando uma regra de correspondência e quer ver quantas transações ela agruparia, e quais pares, antes de gravá-la.        |
| **Simulação de tarifas** (`/fee-schedules/{scheduleId}/simulate`) | Você está configurando uma tabela de tarifas e quer conferir a composição de líquido e tarifa que ela produziria para um valor bruto representativo. |

Os dois endpoints continuam estritamente somente leitura. Eles nunca persistem uma execução, um grupo, um item, uma regra ou uma transação. O tenant sempre vem do JWT.

## Códigos de resposta

***

| Status | Significado                                                                      |
| ------ | -------------------------------------------------------------------------------- |
| `200`  | Simulação retornada                                                              |
| `400`  | Entrada inválida (regra ambígua ou ausente, ids inválidos, valor bruto inválido) |
| `404`  | Contexto, regra ou tabela de tarifas não encontrada                              |
| `503`  | Simulação de correspondência indisponível                                        |