Simulação

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

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. Em why, os booleanos informam se os dois valores, moedas e datas são iguais, não os componentes da pontuação:

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

Escopo: a simulação lê no máximo 5.000 transações não conciliadas do contexto, e as fontes do contexto precisam se resolver em dois lados. Ela 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, a conversão de câmbio 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, depois da conversão de câmbio, dentro da faixa de câmbio ou por alocação.

Simulação de tarifas

Calcule as tarifas para um valor bruto usando uma tabela de tarifas específica. currency precisa ser igual à moeda da tabela. Use isso para validar as regras de uma tabela antes de anexá-la 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 tarifa total e a composição por item:

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

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.

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.

Códigos de resposta

Status	Significado
`200`	Simulação retornada
`400`	Entrada inválida (regra ambígua ou ausente, lados que não se resolvem, valor bruto inválido)
`404`	Contexto, regra ou tabela de tarifas não encontrada
`422`	Campo malformado, como um id inválido ou um tipo de regra desconhecido
`503`	Simulação de correspondência indisponível

Visão geral

Guias

Console

Operações

Simulação de correspondência

Simulação de tarifas

Quando usar cada uma

Códigos de resposta

​Simulação de correspondência

​Simulação de tarifas

​Quando usar cada uma

​Códigos de resposta

Simulação de correspondência

Simulação de tarifas

Quando usar cada uma

Códigos de resposta