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

# Pontuação de confiança

> Veja como o Matcher calcula uma pontuação de confiança de 0 a 100 a partir de valor, moeda, data e referência para classificar cada match.

As pontuações de confiança indicam a confiabilidade de uma correspondência automatizada em uma escala de 0-100. Pontuações mais altas significam maior certeza de que duas transações representam o mesmo evento financeiro.

## Visão geral

***

Quando o Matcher identifica uma correspondência potencial, ele atribui uma pontuação de confiança com base em múltiplos fatores.

Esta pontuação define como a correspondência é tratada:

* Pontuações altas (90+) são aprovadas automaticamente
* Pontuações intermediárias (60 – 89) requerem revisão
* Pontuações baixas (\<60) são tratadas como exceções

<Frame caption="Pontuação de confiança do Matcher.">
  <img src="https://mintcdn.com/lerian-49cb71fc/dIivJl2jpQJ0JZcX/images/pt/d2/matcher-confidence-scoring.svg?fit=max&auto=format&n=dIivJl2jpQJ0JZcX&q=85&s=5318304b0739d0bea5d359246b75feea" alt="Pontuação de Confiança do Matcher" width="775" height="1026" data-path="images/pt/d2/matcher-confidence-scoring.svg" />
</Frame>

## Componentes da pontuação

***

O Matcher usa um **sistema de pontuação ponderada binária** com quatro componentes. Cada componente resulta em match completo (1.0) ou sem match (0.0) — não existem pontuações parciais dentro de um componente.

| Componente                    | Peso | Pontos (match / no match) |
| ----------------------------- | ---- | ------------------------- |
| Correspondência de valor      | 40%  | 40 / 0                    |
| Correspondência de moeda      | 30%  | 30 / 0                    |
| Proximidade de data           | 20%  | 20 / 0                    |
| Correspondência de referência | 10%  | 10 / 0                    |

### Correspondência de valor (40%)

O componente de valor tem o maior peso porque discrepâncias de valor frequentemente indicam transações diferentes.

| Condição                                             | Pontuação |
| ---------------------------------------------------- | --------- |
| Valores correspondem (dentro da tolerância da regra) | 40 pontos |
| Valores não correspondem                             | 0 pontos  |

A correspondência de valor depende do tipo de regra ativa. Uma regra EXACT requer valores idênticos; uma regra TOLERANCE permite variância dentro dos limites configurados de `percentTolerance` e `absTolerance`.

### Correspondência de moeda (30%)

A verificação de moeda é binária — as moedas correspondem ou não.

| Condição        | Pontuação |
| --------------- | --------- |
| Mesma moeda     | 30 pontos |
| Moeda diferente | 0 pontos  |

### Proximidade de data (20%)

A pontuação de data verifica se as datas das transações estão dentro da janela configurada.

| Condição                         | Pontuação |
| -------------------------------- | --------- |
| Datas dentro da janela permitida | 20 pontos |
| Datas fora da janela permitida   | 0 pontos  |

A janela permitida depende da regra: uma regra EXACT requer a mesma data (respeitando `datePrecision`), enquanto uma regra DATE\_LAG permite até `maxDays` de diferença.

### Correspondência de referência (10%)

Para regras EXACT e TOLERANCE, a comparação de referência é binária.

| Condição                                                        | Pontuação |
| --------------------------------------------------------------- | --------- |
| Referências correspondem (exata ou sem distinção de maiúsculas) | 10 pontos |
| Referências não correspondem ou estão ausentes                  | 0 pontos  |

<Note>
  **Regras FUZZY pontuam a referência em uma escala contínua.** Para uma regra FUZZY, o slot de referência de 10% carrega um `ReferenceScore` graduado entre `0.0` e `1.0` (uma medida de similaridade) em vez de um estrito `0`/`1`. Uma referência quase idêntica contribui com quase os 10 pontos completos, enquanto uma que mal ultrapassa o limiar fuzzy contribui proporcionalmente menos. Como resultado, matches FUZZY podem produzir pontuações que não são múltiplos de 10, como 97 ou 99. Veja [Pontuações possíveis](#pontuações-possíveis) abaixo.
</Note>

<Warning>
  **Regras DATE\_LAG não pontuam referências.** Para regras DATE\_LAG, o `ReferenceScore` é sempre `0.0`, então o componente de referência de 10% contribui com `0` pontos independentemente dos valores de referência. A pontuação máxima possível para DATE\_LAG é, portanto, 90 (40 + 30 + 20 + 0), o que, por design, mantém os matches de date-lag no caminho de revisão manual.
</Warning>

## Fórmula de cálculo

***

A fórmula da pontuação de confiança:

```
confidence = round(
  (amountMatch × 0.40 +
   currencyMatch × 0.30 +
   dateMatch × 0.20 +
   referenceScore × 0.10) × 100
)
```

Onde cada fator é `1.0` (match) ou `0.0` (sem match).

Os pesos são constantes fixas no código e não são configuráveis por contexto.

### Pontuações possíveis

Para regras **EXACT**, **TOLERANCE** e **DATE\_LAG**, todos os componentes são binários, então a pontuação de confiança é sempre um destes valores:

**0, 10, 20, 30, 40, 50, 60, 70, 80, 90, 100**

Para esses tipos de regra, valores intermediários (ex: 87, 72, 55) nunca ocorrem. (Para DATE\_LAG o componente de referência é sempre `0`, então suas pontuações nunca incluem os 10 pontos finais.)

Para regras **FUZZY** isso não se aplica. Como o componente de referência é um `ReferenceScore` contínuo (0.0–1.0), matches FUZZY podem produzir pontuações intermediárias como **97** ou **99**. Note que, independentemente da pontuação resultante, um match FUZZY **nunca é confirmado automaticamente** — veja [Matches FUZZY nunca confirmam automaticamente](#matches-fuzzy-nunca-confirmam-automaticamente).

## Exemplos de cálculo

***

### Correspondência exata (pontuação: 100)

Duas transações com valores idênticos no mesmo dia:

| Componente | Comparação                 | Pontos |
| ---------- | -------------------------- | ------ |
| Valor      | $1.000,00 vs $1.000,00 ✓   | 40     |
| Moeda      | USD vs USD ✓               | 30     |
| Data       | 2024-01-15 vs 2024-01-15 ✓ | 20     |
| Referência | PAY-001 vs PAY-001 ✓       | 10     |

**Pontuação Final: 100** → Confirmada automaticamente

### Alta confiança (pontuação: 90)

Todos os campos correspondem exceto referência:

| Componente | Comparação                 | Pontos |
| ---------- | -------------------------- | ------ |
| Valor      | $1.000,00 vs $1.000,00 ✓   | 40     |
| Moeda      | USD vs USD ✓               | 30     |
| Data       | 2024-01-15 vs 2024-01-15 ✓ | 20     |
| Referência | PAY-001 vs — ✗             | 0      |

**Pontuação Final: 90** → Confirmada automaticamente

### Confiança média (pontuação: 70)

Valor e moeda correspondem, mas data e referência não:

| Componente | Comparação                 | Pontos |
| ---------- | -------------------------- | ------ |
| Valor      | $1.000,00 vs $1.000,00 ✓   | 40     |
| Moeda      | USD vs USD ✓               | 30     |
| Data       | 2024-01-15 vs 2024-01-25 ✗ | 0      |
| Referência | PAY-001 vs REC-999 ✗       | 0      |

**Pontuação Final: 70** → Necessita revisão

### Baixa confiança (pontuação: 40)

Apenas o valor corresponde:

| Componente | Comparação                 | Pontos |
| ---------- | -------------------------- | ------ |
| Valor      | $1.000,00 vs $1.000,00 ✓   | 40     |
| Moeda      | USD vs EUR ✗               | 0      |
| Data       | 2024-01-15 vs 2024-01-25 ✗ | 0      |
| Referência | — vs — ✗                   | 0      |

**Pontuação Final: 40** → Exceção (abaixo de 60)

## Níveis de confiança

***

O Matcher categoriza as correspondências em níveis com base na pontuação:

| Tier (pontuação)                     | Comportamento do sistema        | Volume típico |
| ------------------------------------ | ------------------------------- | ------------- |
| **Aprovado Automaticamente** (>= 90) | Confirmado automaticamente      | 70-80%        |
| **Necessita Revisão** (60-89)        | Enfileirado para revisão manual | 15-25%        |
| **Exceção** (\< 60)                  | Tratado como não correspondido  | 5-10%         |

### Como os níveis de confiança são aplicados

Quando o Matcher propõe uma correspondência, ele avalia a pontuação de confiança e aplica os seguintes passos:

1. Se a pontuação for **90 ou superior**, a correspondência é automaticamente confirmada para as regras EXACT e TOLERANCE; correspondências FUZZY e DATE\_LAG sempre requerem revisão manual.
2. Se a pontuação for **entre 60 e 89**, a correspondência é enfileirada para revisão manual.
3. Se a pontuação for **abaixo de 60**, nenhuma correspondência é criada e a transação se torna uma exceção.
4. Correspondências revisadas podem ser confirmadas ou rejeitadas, atualizando seu status final.

Isso garante que correspondências de alta confiança fluam automaticamente, mantendo o controle humano onde é importante.

### Matches FUZZY nunca confirmam automaticamente

O comportamento de confirmação automática acima se aplica às regras EXACT e TOLERANCE, mais as correspondências manuais; correspondências FUZZY e DATE\_LAG sempre requerem revisão manual. Matches produzidos por regras **FUZZY** **nunca são confirmados automaticamente**, independentemente de sua pontuação de confiança — mesmo um match FUZZY com pontuação 90 ou superior é sempre enfileirado para revisão manual.

Isso é por design: uma referência fuzzy contribui apenas com o slot de referência de 10%, então os campos financeiros (valor + moeda + data) sozinhos já podem alcançar o limiar de 90. Limitar FUZZY abaixo da confirmação automática garante que um humano revise a referência fuzzy antes que o match seja confirmado — "fuzzy propõe, nunca confirma."

## Limites de confiança

***

O Matcher usa limites fixos para determinar como as correspondências são tratadas:

| Limite                 | Pontuação | Comportamento                                                  |
| ---------------------- | --------- | -------------------------------------------------------------- |
| Confirmação automática | >= 90     | Correspondência é automaticamente confirmada                   |
| Correspondência        | >= 60     | Correspondência é proposta para revisão manual                 |
| Exceção                | \< 60     | Nenhuma correspondência criada; transação se torna uma exceção |

Esses limites não são configuráveis por contexto.

## Pesos

***

Os pesos dos componentes (40/30/20/10) são constantes fixas no código. Eles não podem ser ajustados por contexto ou por regra.

| Componente | Peso | Justificativa                                                            |
| ---------- | ---- | ------------------------------------------------------------------------ |
| Valor      | 40%  | O valor é o indicador mais forte de uma correspondência válida           |
| Moeda      | 30%  | Moeda diferente geralmente significa transações diferentes               |
| Data       | 20%  | Proximidade de data adiciona confiança mas permite atrasos de liquidação |
| Referência | 10%  | Referências são úteis mas frequentemente ausentes ou inconsistentes      |

## Melhores práticas

***

<AccordionGroup>
  <Accordion title="Monitore a distribuição por níveis">
    Acompanhe a porcentagem de transações em cada nível. Mudanças incomuns podem indicar problemas de qualidade de dados ou configuração incorreta de regras.
  </Accordion>

  <Accordion title="Use modo dry-run para testar regras">
    Como a confiança depende de quais regras fazem match, sempre faça dry-run de mudanças nas regras antes de confirmar. Isso evita aumentos inesperados no volume de revisão manual.
  </Accordion>

  <Accordion title="Revise correspondências próximas ao limite de 60 pontos">
    Periodicamente revise correspondências logo acima do limite de exceção. Estas frequentemente revelam oportunidades para melhorias nas regras.
  </Accordion>

  <Accordion title="Entenda pontuações como resultados de regras">
    Para regras EXACT, TOLERANCE e DATE\_LAG, a pontuação é binária, então uma pontuação de 70 significa exatamente "valor + moeda corresponderam, data + referência não corresponderam." Use isso para diagnosticar problemas de correspondência. Regras FUZZY são a exceção: seu componente de referência graduado pode gerar pontuações intermediárias (ex: 97), então uma pontuação FUZZY deve ser lida como "campos financeiros corresponderam mais uma similaridade parcial de referência."
  </Accordion>
</AccordionGroup>

## Próximos passos

***

<Card title="Regras de Correspondência" icon="scale-balanced" href="/pt/matcher/configuration/matcher-match-rules" horizontal>
  Configure regras que influenciam a pontuação.
</Card>

<Card title="Multi-Moeda" icon="coins" href="/pt/matcher/reference/matcher-multi-currency" horizontal>
  Como FX afeta a pontuação de confiança.
</Card>