> ## 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–100 a partir das verificações de valor, moeda, data e referência, e como as regras EXACT, TOLERANCE, DATE_LAG e FUZZY pontuam.

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

## Visão geral

***

Quando o Matcher identifica uma correspondência possível, ele atribui uma pontuação de confiança com base em vários fatores.

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

* Pontuações altas (90+) são aprovadas automaticamente
* Pontuações médias (60 – 89) exigem 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/vdBt8wfgjsNRO1rf/images/pt/d2/matcher-confidence-scoring.svg?fit=max&auto=format&n=vdBt8wfgjsNRO1rf&q=85&s=6304db02d012f3a0e340ad6eef3abd50" alt="Pontuação de confiança do Matcher" width="707" height="1026" data-path="images/pt/d2/matcher-confidence-scoring.svg" />
</Frame>

## Componentes da pontuação

***

O Matcher usa um **sistema de pontuação binária com pesos** e quatro componentes. Cada componente resulta em correspondência total (1.0) ou nenhuma correspondência (0.0). Não existe pontuação parcial dentro de um componente.

| Componente                    | Peso | Pontos (corresponde / não corresponde) |
| ----------------------------- | ---- | -------------------------------------- |
| 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 diferenças de valor costumam indicar transações distintas.

| Condição                                             | Pontuação |
| ---------------------------------------------------- | --------- |
| Os valores coincidem (dentro da tolerância da regra) | 40 pontos |
| Os valores não coincidem                             | 0 pontos  |

A correspondência de valor depende do tipo de regra ativo. Uma regra EXACT exige valores idênticos. Uma regra TOLERANCE permite variação dentro dos `percentTolerance` e `absTolerance` configurados.

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

A verificação de moeda é binária. As moedas coincidem ou não coincidem.

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

### Proximidade de data (20%)

A pontuação de data confere se as datas das transações caem 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 exige a mesma data e respeita `datePrecision`. Uma regra DATE\_LAG aceita uma diferença de dias dentro da faixa `[minDays, maxDays]` dela. A flag `inclusive` controla se o próprio `maxDays` conta.

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

Para regras EXACT, a comparação de referência é binária. As regras TOLERANCE pontuam esse componente apenas quando você habilita `matchReference`. Fora isso, a pontuação de referência delas é `0`.

| Condição                                                       | Pontuação                                                                                                |
| -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| As referências coincidem (exata ou sem diferenciar maiúsculas) | 10 pontos                                                                                                |
| Ambas as referências ausentes                                  | 10 pontos (a menos que a regra defina `referenceMustSet`, que pontua qualquer referência ausente como 0) |
| As referências não coincidem, ou apenas uma está ausente       | 0 pontos                                                                                                 |

<Note>
  **As regras FUZZY pontuam a referência em uma escala contínua.** Para uma regra FUZZY, o espaço de 10% da referência carrega um `ReferenceScore` graduado entre `0.0` e `1.0`. Esse valor é uma medida de similaridade, não um `0`/`1` estrito. Uma referência quase idêntica contribui perto dos 10 pontos completos, enquanto uma que mal passa pelo portão difuso contribui proporcionalmente menos. Como resultado, as correspondências FUZZY podem produzir pontuações que não são múltiplos de 10, como 97 ou 99. Veja [Pontuações possíveis](#possible-scores) abaixo.
</Note>

<Warning>
  **As 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, quaisquer que sejam os valores de referência. A pontuação máxima possível de DATE\_LAG é portanto 90 (40 + 30 + 20 + 0), o que por design mantém as correspondências por defasagem de data 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
)
```

Cada fator é `1.0` (corresponde) ou `0.0` (não corresponde).

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

<h3 id="possible-scores">
  Pontuações possíveis
</h3>

Para regras **EXACT**, **TOLERANCE** e **DATE\_LAG**, cada componente é binário, 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 (por exemplo, 87, 72, 55) nunca acontecem. (Para DATE\_LAG o componente de referência é sempre `0`, então as pontuações dele nunca incluem os 10 pontos finais.)

Para regras **FUZZY** isso não vale. Como o componente de referência é um `ReferenceScore` contínuo (0.0–1.0), as correspondências FUZZY podem produzir pontuações intermediárias como **97** ou **99**. Qualquer que seja a pontuação resultante, uma correspondência FUZZY **nunca é autoconfirmada**. Veja [Correspondências FUZZY nunca autoconfirmam](#fuzzy-matches-never-auto-confirm).

## 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** → Autoconfirmada

### Correspondência de alta confiança (pontuação: 90)

Todos os campos coincidem, menos a 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** → Autoconfirmada

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

Valor e moeda coincidem, 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** → Precisa de revisão

### Confiança baixa (pontuação: 40)

Apenas o valor coincide:

| 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 | PAY-001 vs REC-999 ✗       | 0      |

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

## Faixas de confiança

***

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

| Faixa (pontuação)                   | Comportamento do sistema    | Volume típico (ilustrativo) |
| ----------------------------------- | --------------------------- | --------------------------- |
| **Aprovada automaticamente** (≥ 90) | Confirmada automaticamente  | 70-80%                      |
| **Precisa de revisão** (60-89)      | Na fila para revisão manual | 15-25%                      |
| **Exceção** (\< 60)                 | Tratada como não conciliada | 5-10%                       |

### Como as faixas de confiança são aplicadas

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 mais**, a correspondência é confirmada automaticamente para regras EXACT e TOLERANCE; as correspondências FUZZY e DATE\_LAG sempre exigem revisão manual.
2. Se a pontuação estiver **entre 60 e 89**, a correspondência entra na fila para revisão manual.
3. Se a pontuação for **abaixo de 60**, nenhuma correspondência é criada e a transação vira uma exceção.
4. As correspondências revisadas podem ser confirmadas ou rejeitadas, o que atualiza o status final delas.

<h3 id="fuzzy-matches-never-auto-confirm">
  Correspondências FUZZY nunca autoconfirmam
</h3>

O comportamento de autoconfirmação acima vale para regras EXACT e TOLERANCE. As correspondências FUZZY e DATE\_LAG sempre exigem revisão manual. As correspondências produzidas por regras **FUZZY** **nunca são autoconfirmadas**, qualquer que seja a pontuação de confiança delas. Mesmo uma correspondência FUZZY que pontue 90 ou mais entra sempre na fila para revisão manual.

Uma referência difusa contribui apenas com o espaço de 10% da referência, então os campos financeiros (valor + moeda + data) sozinhos já podem alcançar o limiar de 90. Limitar FUZZY abaixo da autoconfirmação garante que uma pessoa revise a referência difusa antes de a correspondência ser gravada.

## Limiares de confiança

***

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

| Limiar          | Pontuação | Comportamento                                                |
| --------------- | --------- | ------------------------------------------------------------ |
| Autoconfirmação | >= 90     | A correspondência é confirmada automaticamente               |
| Correspondência | >= 60     | A correspondência é proposta para revisão manual             |
| Exceção         | \< 60     | Nenhuma correspondência criada; a transação vira uma exceção |

Esses limiares 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 nem por regra.

| Componente | Peso | Justificativa                                                              |
| ---------- | ---- | -------------------------------------------------------------------------- |
| Valor      | 40%  | O valor é o indicador mais forte de uma correspondência válida             |
| Moeda      | 30%  | Moeda diferente normalmente significa transações diferentes                |
| Data       | 20%  | A proximidade de data adiciona confiança, mas admite atrasos de liquidação |
| Referência | 10%  | As referências ajudam, mas costumam estar ausentes ou inconsistentes       |

## Boas práticas

***

<AccordionGroup>
  <Accordion title="Monitore a distribuição por faixa">
    Acompanhe o percentual de transações em cada faixa. Mudanças fora do comum podem indicar problemas de qualidade dos dados ou regras mal configuradas.
  </Accordion>

  <Accordion title="Use o modo de teste a seco para testar regras">
    Como a confiança depende de quais regras correspondem, sempre rode as mudanças de regra em modo de teste a seco antes de gravar. Isso evita aumentos inesperados no volume de revisão manual.
  </Accordion>

  <Accordion title="Revise as correspondências perto do limite de 60 pontos">
    Revise periodicamente as correspondências logo acima do limiar de exceção. Elas costumam revelar oportunidades de melhoria nas regras.
  </Accordion>

  <Accordion title="Entenda as pontuações como resultados das regras">
    Para regras EXACT, TOLERANCE e DATE\_LAG, a pontuação é binária. Uma pontuação de 70 significa exatamente "valor + moeda coincidiram, data + referência não". Use isso para diagnosticar problemas de correspondência. As regras FUZZY são a exceção. O componente de referência graduado delas pode gerar pontuações intermediárias (por exemplo, 97). Leia uma pontuação FUZZY como "os campos financeiros coincidiram mais uma similaridade parcial de referência".
  </Accordion>
</AccordionGroup>

## Próximos passos

***

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

<Card title="Multimoeda" icon="coins" href="/pt/products/matcher/reference/matcher-multi-currency" horizontal>
  Como o câmbio afeta a pontuação de confiança.
</Card>