Simulação

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.

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
  }'

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:

{
  "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
    }
  ]
}

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.

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.

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:

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

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.

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

Visão geral

Guias

Matcher UI

Servidor MCP

Operações

Simulação de match

Simulação de taxas

Quando usar cada uma

Códigos de resposta

​Simulação de match

​Simulação de taxas

​Quando usar cada uma

​Códigos de resposta

Simulação de match

Simulação de taxas

Quando usar cada uma

Códigos de resposta