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

# Regras de correspondência

> Escreva regras exatas, de tolerância, de defasagem de data e difusas no Matcher. Defina prioridades, tolerâncias e correspondência de referência para controlar como as transações se emparelham.

As regras de correspondência são onde você define a sua política de conciliação. A política define o quanto o Matcher é rígido ou tolerante quando decide que duas transações são a mesma. Regras apertadas significam mais revisão manual, mas menos correspondências falsas. Regras mais frouxas automatizam mais, mas exigem supervisão cuidadosa. Você pode exigir correspondências exatas, permitir variação controlada, tolerar diferenças de tempo ou comparar referências de texto livre por similaridade.

## Como as regras funcionam

***

Quando uma execução de correspondência começa, o Matcher avalia as regras em ordem de prioridade.

* As regras são avaliadas do menor número de prioridade para o maior.
* Cada regra cria todas as correspondências que consegue a partir de transações ainda não usadas por regras de prioridade mais alta.
* Depois que cada regra roda, as transações que continuam não conciliadas viram exceções.

Essa abordagem impede que qualquer regra reuse uma correspondência de prioridade mais alta. Regras progressivamente mais frouxas processam as transações que sobram.

## Tipos de regra

***

### Exata

Exige correspondência estrita nos campos configurados.

* **Melhor para**: correspondências determinísticas em que se recomenda que os valores alinhem 1:1.

### Tolerância

Permite variação controlada na correspondência de valores.

* **Melhor para**: padrões de variação conhecidos, como tarifas, arredondamento ou diferenças de câmbio.

### Defasagem de data

Permite diferenças de data entre transações.

* **Melhor para**: atrasos de lançamento entre sistemas.

### Difusa

Substitui a igualdade exata de referência por uma pontuação de similaridade de string normalizada. Por padrão, os filtros de valor, moeda e data exigem igualdade exata, mas `matchAmount`, `matchCurrency` e `matchDate` controlam de forma independente se cada filtro se aplica. FUZZY sempre propõe uma correspondência para revisão e nunca confirma automaticamente.

* **Melhor para**: memorandos de texto livre ou referências truncadas em que a referência varia, mas os filtros financeiros habilitados ainda se alinham.

## Como criar regras de correspondência

***

### Regra exata

```bash cURL theme={null}
curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/rules" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "type": "EXACT",
   "priority": 1,
   "config": {
     "matchAmount": true,
     "matchCurrency": true,
     "matchDate": true,
     "matchReference": true,
     "datePrecision": "DAY",
     "caseInsensitive": true,
     "referenceMustSet": false,
     "matchBaseAmount": false,
     "matchBaseCurrency": false,
     "matchScore": 100,
     "matchBaseScore": 90
   }
 }'
```

#### Referência de configuração

<ParamField path="matchAmount" type="Boolean" default="true">
  Exige correspondência exata de valor
</ParamField>

<ParamField path="matchCurrency" type="Boolean" default="true">
  Exige correspondência exata de moeda
</ParamField>

<ParamField path="matchDate" type="Boolean" default="true">
  Exige correspondência exata de data
</ParamField>

<ParamField path="matchReference" type="Boolean" default="true">
  Exige correspondência exata de referência
</ParamField>

<ParamField path="datePrecision" type="String" default="DAY">
  Precisão da comparação de data: `DAY` ou `TIMESTAMP`
</ParamField>

<ParamField path="caseInsensitive" type="Boolean" default="true">
  Comparação de referência sem diferenciar maiúsculas
</ParamField>

<ParamField path="referenceMustSet" type="Boolean" default="false">
  Exige que a referência esteja presente nos dois lados
</ParamField>

<ParamField path="matchBaseAmount" type="Boolean" default="false">
  Corresponde pelo valor base (convertido) em vez do original
</ParamField>

<ParamField path="matchBaseCurrency" type="Boolean" default="false">
  Corresponde pela moeda base em vez da original
</ParamField>

<ParamField path="matchScore" type="Integer" default="100">
  Aceito e validado, mas **reservado/inerte**. Ele não muda a pontuação de confiança calculada (veja a nota abaixo)
</ParamField>

<ParamField path="matchBaseScore" type="Integer" default="90">
  Aceito e validado, mas **reservado/inerte**. Ele não muda a pontuação de confiança calculada (veja a nota abaixo)
</ParamField>

<Note>
  **`matchScore` e `matchBaseScore` estão inertes atualmente.** Eles são aceitos e validados na configuração da regra, mas o motor de pontuação os ignora: a confiança é sempre calculada a partir dos pesos internos fixos dos componentes (valor 40, moeda 30, data 20, referência 10). Esses campos são reservados para uso futuro e defini-los **não** altera a pontuação de confiança nem o comportamento de confirmação automática. Veja [Pontuação de confiança](/pt/products/matcher/reference/matcher-confidence-scoring).
</Note>

A resposta devolve a regra persistida com o `id` atribuído e os timestamps.

<Tip>
  Referência da API: [Criar regra de correspondência](/pt/reference/products/matcher/create-match-rule)
</Tip>

### Regra de tolerância

```bash cURL theme={null}
curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/rules" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "type": "TOLERANCE",
   "priority": 2,
   "config": {
     "percentTolerance": 0.005,
     "absTolerance": 0.50,
     "dateWindowDays": 3,
     "roundingScale": 2,
     "roundingMode": "HALF_UP",
     "percentageBase": "MAX",
     "matchCurrency": true,
     "matchReference": true,
     "caseInsensitive": true,
     "referenceMustSet": false,
     "matchBaseAmount": false,
     "matchBaseCurrency": false,
     "matchScore": 85,
     "matchBaseScore": 80
   }
 }'
```

#### Referência de configuração

<ParamField path="percentTolerance" type="Decimal">
  Limiar percentual aplicado a `percentageBase` (0,005 = 0,5%). O padrão é `0`. O Matcher compara esse limiar com `absTolerance` e usa o maior
</ParamField>

<ParamField path="absTolerance" type="Decimal">
  Limiar de valor absoluto. O padrão é `0`. O Matcher o compara com o limiar percentual e usa o maior
</ParamField>

Os dois limiares têm zero como padrão, então você deve configurar explicitamente qualquer variação de valor permitida.

<ParamField path="dateWindowDays" type="Integer">
  Número de dias permitido entre as datas das transações
</ParamField>

<ParamField path="roundingScale" type="Integer">
  Casas decimais para o arredondamento
</ParamField>

<ParamField path="roundingMode" type="String">
  Estratégia de arredondamento: `HALF_UP`, `BANKERS`, `FLOOR`, `CEIL` ou `TRUNCATE`
</ParamField>

<ParamField path="percentageBase" type="String" default="MAX">
  Base para o cálculo percentual: `MAX`, `MIN`, `AVERAGE`, `LEFT` ou `RIGHT`
</ParamField>

<ParamField path="matchCurrency" type="Boolean" default="true">
  Exige correspondência de moeda
</ParamField>

<ParamField path="matchReference" type="Boolean" default="true">
  Exige correspondência de referência
</ParamField>

<ParamField path="caseInsensitive" type="Boolean" default="true">
  Comparação de referência sem diferenciar maiúsculas
</ParamField>

<ParamField path="referenceMustSet" type="Boolean" default="false">
  Exige que a referência esteja presente nos dois lados
</ParamField>

<ParamField path="matchBaseAmount" type="Boolean" default="false">
  Corresponde pelo valor base (convertido)
</ParamField>

<ParamField path="matchBaseCurrency" type="Boolean" default="false">
  Corresponde pela moeda base
</ParamField>

<ParamField path="matchScore" type="Integer" default="85">
  Aceito e validado, mas **reservado/inerte**. Ele não muda a pontuação de confiança calculada
</ParamField>

<ParamField path="matchBaseScore" type="Integer" default="80">
  Aceito e validado, mas **reservado/inerte**. Ele não muda a pontuação de confiança calculada
</ParamField>

**Exemplo:**

* Transação A: US\$ 1.000,00
* Transação B: US\$ 1.005,00
* Diferença de valor: US\$ 5,00
* Limiar percentual: US$ 1.005,00 × 0,5% = US$ 5,025 (`percentageBase: MAX`)
* Limiar absoluto: US\$ 0,50
* Limiar efetivo: `MAX($5.025, $0.50)` = US\$ 5,025 → **Corresponde**

### Regra difusa

```bash cURL theme={null}
curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/rules" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "type": "FUZZY",
   "priority": 4,
   "config": {
     "minSimilarity": 0.85,
     "matchAmount": true,
     "matchCurrency": true,
     "matchDate": true,
     "datePrecision": "DAY",
     "referenceMustSet": true,
     "matchScore": 70
   }
 }'
```

#### Referência de configuração

<ParamField path="minSimilarity" type="Decimal" default="0.80">
  Similaridade mínima normalizada da referência (0–1) exigida para filtrar como correspondência
</ParamField>

<ParamField path="matchAmount" type="Boolean" default="true">
  Quando `true`, exige correspondência exata de valor
</ParamField>

<ParamField path="matchCurrency" type="Boolean" default="true">
  Quando `true`, exige correspondência exata de moeda
</ParamField>

<ParamField path="matchDate" type="Boolean" default="true">
  Quando `true`, exige correspondência exata de data
</ParamField>

<ParamField path="datePrecision" type="String" default="DAY">
  Precisão da comparação de data: `DAY` ou `TIMESTAMP`
</ParamField>

<ParamField path="referenceMustSet" type="Boolean" default="true">
  Exige uma referência não vazia nos dois lados
</ParamField>

<ParamField path="matchScore" type="Integer" default="70">
  Aceito e com padrão `70`, mas **reservado/inerte**. Ele não limita nem muda a confiança calculada nem o comportamento de confirmação automática
</ParamField>

<Note>
  FUZZY substitui a igualdade de referência por similaridade. Por padrão, ele também exige correspondências exatas de valor, moeda e data. Desabilite cada filtro de forma independente com `matchAmount`, `matchCurrency` ou `matchDate`. FUZZY sempre propõe correspondências para revisão humana e nunca as confirma automaticamente.
</Note>

### Regra de defasagem de data

```bash cURL theme={null}
curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/rules" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "type": "DATE_LAG",
   "priority": 3,
   "config": {
     "maxDays": 3,
     "minDays": 0,
     "inclusive": true,
     "direction": "ABS",
     "feeTolerance": 0,
     "matchScore": 80,
     "matchCurrency": true
   }
 }'
```

#### Referência de configuração

<ParamField path="maxDays" type="Integer">
  Número máximo de dias de diferença permitido
</ParamField>

<ParamField path="minDays" type="Integer" default="0">
  Número mínimo de dias de diferença exigido
</ParamField>

<ParamField path="inclusive" type="Boolean" default="true">
  Se os dias de fronteira são inclusivos
</ParamField>

<ParamField path="direction" type="String" default="ABS">
  Como medir a defasagem: `ABS` (absoluta), `LEFT_BEFORE_RIGHT` ou `RIGHT_BEFORE_LEFT`
</ParamField>

<ParamField path="feeTolerance" type="Decimal" default="0">
  Diferença de valor permitida para considerar tarifas
</ParamField>

<ParamField path="matchScore" type="Integer" default="80">
  Aceito e validado, mas **reservado/inerte**. Ele não muda a pontuação de confiança calculada. Nota: as regras DATE\_LAG sempre pontuam o componente de referência como 0, limitando a pontuação máxima a 90
</ParamField>

<ParamField path="matchCurrency" type="Boolean" default="true">
  Exige correspondência de moeda
</ParamField>

### Ajustes de alocação (todos os tipos de regra)

Todos os tipos de regra aceitam ajustes de alocação adicionais para correspondência dividida e agregada:

| Campo                      | Tipo    | Descrição                                                 |
| -------------------------- | ------- | --------------------------------------------------------- |
| `allowPartial`             | Boolean | Permite alocação parcial dos valores da transação         |
| `allocationDirection`      | String  | Ordem de alocação: `LEFT_TO_RIGHT` ou `RIGHT_TO_LEFT`     |
| `allocationToleranceMode`  | String  | Como a tolerância é medida: `ABS` (absoluta) ou `PERCENT` |
| `allocationToleranceValue` | Decimal | Limiar de tolerância para a alocação                      |
| `allocationUseBaseAmount`  | Boolean | Usa o valor base (convertido) na alocação                 |

## Prioridade das regras

***

As regras são avaliadas por prioridade. Números menores rodam primeiro.

### Estratégia de prioridade

| Prioridade | Tipo de regra | Caso de uso                       |
| ---------- | ------------- | --------------------------------- |
| 1–10       | EXACT         | Correspondências determinísticas  |
| 11–50      | TOLERANCE     | Variação pequena e esperada       |
| 51–100     | DATE\_LAG     | Diferenças de data entre sistemas |

### Como reordenar regras

Você pode reordenar regras fornecendo os IDs das regras na ordem desejada:

```bash cURL theme={null}
curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/rules/reorder" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "ruleIds": [
     "550e8400-e29b-41d4-a716-446655440001",
     "550e8400-e29b-41d4-a716-446655440002",
     "550e8400-e29b-41d4-a716-446655440000"
   ]
 }'
```

<Tip>
  Referência da API: [Reordenar regras de correspondência](/pt/reference/products/matcher/reorder-match-rules)
</Tip>

## Como testar regras

***

Teste as regras no modo dry run antes de efetivar correspondências.

```bash cURL theme={null}
curl -X POST "https://api.matcher.example.com/v1/matching/contexts/{contextId}/run" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "mode": "DRY_RUN"
 }'
```

O modo dry run avalia todas as regras e retorna correspondências potenciais. Ele não cria exceções, mas o Matcher conclui e persiste o `MatchRun` com estatísticas e emite o evento de conclusão dele.

## Como gerenciar regras

***

### Como listar regras

```bash cURL theme={null}
curl -X GET "https://api.matcher.example.com/v1/contexts/{contextId}/rules" \
 -H "Authorization: Bearer $TOKEN"
```

#### Resposta

O endpoint de listagem retorna uma visão resumida das regras. Para ver os detalhes completos de configuração de uma regra específica, use o endpoint da regra individual ou a resposta de criação, que inclui o objeto `config` completo.

```json theme={null}
{
  "items": [
    {
      "id": "019c96a0-2b20-7123-9a1b-2c3d4e5f6a7b",
      "contextId": "019c96a0-2a10-7dfe-b5c1-8a1b2c3d4e5f",
      "type": "EXACT",
      "priority": 1,
      "config": {
        "matchAmount": true,
        "matchCurrency": true,
        "matchDate": true,
        "matchReference": true,
        "datePrecision": "DAY",
        "matchScore": 100,
        "matchBaseScore": 90
      },
      "createdAt": "2026-02-02T16:40:00Z",
      "updatedAt": "2026-02-02T16:40:00Z"
    }
  ],
  "limit": 20,
  "hasMore": false
}
```

<Tip>
  Referência da API: [Listar regras de correspondência](/pt/reference/products/matcher/list-match-rules)
</Tip>

### Como atualizar uma regra

```bash cURL theme={null}
curl -X PATCH "https://api.matcher.example.com/v1/contexts/{contextId}/rules/{ruleId}" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "priority": 5,
   "type": "TOLERANCE",
   "config": {
     "percentTolerance": 0.02,
     "absTolerance": 10.0
   }
 }'
```

<Tip>
  Referência da API: [Atualizar regra de correspondência](/pt/reference/products/matcher/update-match-rule)
</Tip>

### Como excluir uma regra

```bash cURL theme={null}
curl -X DELETE "https://api.matcher.example.com/v1/contexts/{contextId}/rules/{ruleId}" \
 -H "Authorization: Bearer $TOKEN"
```

<Tip>
  Referência da API: [Excluir regra de correspondência](/pt/reference/products/matcher/delete-match-rule)
</Tip>

## Boas práticas

***

<AccordionGroup>
  <Accordion title="Comece rígido, depois afrouxe">
    Comece pelas regras exatas. Adicione regras de tolerância apenas para a variação que você consegue justificar e explicar.
  </Accordion>

  <Accordion title="Deixe espaço nas prioridades">
    Use intervalos (1, 10, 20, 50) para inserir regras sem renumerar todo o conjunto.
  </Accordion>

  <Accordion title="Faça dry run em cada mudança">
    Trate as atualizações de regra como mudanças em produção. Valide as taxas de correspondência e o volume de exceções antes de efetivar.
  </Accordion>

  <Accordion title="Escreva descrições que expliquem a intenção">
    Recomenda-se que uma regra documente a variação que ela cobre e o risco que ela introduz.
  </Accordion>

  <Accordion title="Revise o resultado das regras ao longo do tempo">
    Se uma regra nunca corresponde, ela pode ser desnecessária. Se corresponde com frequência demais, ela pode ser ampla demais.
  </Accordion>

  <Accordion title="Mantenha as regras frouxas em prioridade baixa">
    Tolerância alta aumenta os falsos positivos. Use-a como fallback e revise os resultados com cuidado.
  </Accordion>
</AccordionGroup>

## Próximos passos

***

<Card title="Roteamento de exceções" icon="route" href="/pt/products/matcher/configuration/matcher-exception-routing" horizontal>
  Configure a classificação, a atribuição e o escalonamento das transações não conciliadas.
</Card>

<Card title="Pontuação de confiança" icon="chart-simple" href="/pt/products/matcher/reference/matcher-confidence-scoring" horizontal>
  Entenda como as pontuações são calculadas e como os limiares afetam a automação.
</Card>