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

> Configure regras exatas, de tolerância e de defasagem de datas para controlar como o Matcher compara transações entre fontes.

As regras de match são onde você define sua política de reconciliação — o quão estrito ou tolerante o Matcher deve ser ao decidir que duas transações são a mesma. Regras rígidas significam mais revisão manual, porém menos correspondências falsas; regras mais flexíveis automatizam mais, mas exigem supervisão cuidadosa. Você pode impor correspondências exatas, permitir variância controlada, tolerar diferenças de timing ou comparar referências de texto livre por similaridade.

## Como as regras funcionam

***

Quando uma execução de matching inicia, o Matcher avalia as regras em ordem de prioridade.

* As regras são avaliadas do menor número de prioridade para o maior.
* A primeira regra que produz uma correspondência determina o resultado.
* Se nenhuma regra faz correspondência, a transação se torna uma exceção.

Esta abordagem garante matching determinístico enquanto permite regras progressivamente mais flexíveis como fallbacks.

## Tipos de regra

***

### Exact

Requer um match estrito nos campos configurados.

* **Melhor para**: Correspondências determinísticas onde os valores devem alinhar 1:1.

### Tolerance

Permite variância controlada no matching de valores.

* **Melhor para**: Padrões de variância conhecidos como taxas, arredondamento ou diferenças de câmbio.

### Date lag

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

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

### Fuzzy

Substitui a igualdade exata de referência por uma pontuação de similaridade de strings normalizada, mantendo exatas as verificações financeiras (valor, moeda, data). FUZZY sempre **propõe** uma correspondência para revisão e nunca confirma automaticamente.

* **Melhor para**: Memos de texto livre ou referências truncadas onde a referência varia, mas o valor, a moeda e a data ainda alinham.

## Criando regras de match

***

### Regra exact

```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">
  Requer match exato de valor
</ParamField>

<ParamField path="matchCurrency" type="Boolean" default="true">
  Requer match exato de moeda
</ParamField>

<ParamField path="matchDate" type="Boolean" default="true">
  Requer match exato de data
</ParamField>

<ParamField path="matchReference" type="Boolean" default="true">
  Requer match exato 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 distinção de maiúsculas/minúsculas
</ParamField>

<ParamField path="referenceMustSet" type="Boolean" default="false">
  Requer que a referência esteja presente em ambos os lados
</ParamField>

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

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

<ParamField path="matchScore" type="Integer" default="100">
  Aceito e validado, mas **reservado/inerte** — não altera o score de confiança calculado (veja a nota abaixo)
</ParamField>

<ParamField path="matchBaseScore" type="Integer" default="90">
  Aceito e validado, mas **reservado/inerte** — não altera o score de confiança calculado (veja a nota abaixo)
</ParamField>

<Note>
  **`matchScore` e `matchBaseScore` estão atualmente inertes.** Eles são aceitos e validados na configuração da regra, mas o mecanismo de scoring os ignora: a confiança é sempre calculada a partir dos pesos fixos internos 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 o score de confiança nem o comportamento de confirmação automática. Consulte [Score de confiança](/pt/matcher/reference/matcher-confidence-scoring).
</Note>

A resposta ecoa a regra persistida com seu `id` atribuído e os timestamps.

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

### Regra tolerance

```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" default="0.005">
  Variância percentual máxima permitida (0.005 = 0,5%)
</ParamField>

<ParamField path="absTolerance" type="Decimal" default="0.50">
  Variância absoluta máxima de valor permitida
</ParamField>

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

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

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

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

<ParamField path="matchCurrency" type="Boolean" default="true">
  Requer match de moeda
</ParamField>

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

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

<ParamField path="referenceMustSet" type="Boolean" default="false">
  Requer que a referência esteja presente em ambos os lados
</ParamField>

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

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

<ParamField path="matchScore" type="Integer" default="85">
  Aceito e validado, mas **reservado/inerte** — não altera o score de confiança calculado
</ParamField>

<ParamField path="matchBaseScore" type="Integer" default="80">
  Aceito e validado, mas **reservado/inerte** — não altera o score de confiança calculado
</ParamField>

**Exemplo:**

* Transação A: R\$1.000,00
* Transação B: R\$1.005,00
* Variância: 0,5% → **Corresponde** (dentro da tolerância de 0,5% e tolerância absoluta de R\$0,50)

### Regra fuzzy

```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 de referência normalizada mínima (0–1) exigida para validar como correspondência
</ParamField>

<ParamField path="matchAmount" type="Boolean" default="true">
  Requer match exato de valor
</ParamField>

<ParamField path="matchCurrency" type="Boolean" default="true">
  Requer match exato de moeda
</ParamField>

<ParamField path="matchDate" type="Boolean" default="true">
  Requer match exato 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">
  Requer uma referência não vazia em ambos os lados
</ParamField>

<ParamField path="matchScore" type="Integer" default="70">
  Teto nominal de pontuação (o avaliador de similaridade graduado determina a confiança real)
</ParamField>

<Note>
  FUZZY relaxa apenas a comparação de referência (a igualdade passa a ser similaridade); o valor, a moeda e a data são verificados de forma exata como em uma regra EXACT. Como propõe em vez de confirmar automaticamente, suas correspondências sempre ficam abaixo do limite de confirmação automática para revisão humana.
</Note>

### Regra date lag

```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 requerido
</ParamField>

<ParamField path="inclusive" type="Boolean" default="true">
  Se os dias limítrofes são inclusivos
</ParamField>

<ParamField path="direction" type="String" default="ABS">
  Como medir o atraso: `ABS` (absoluto), `LEFT_BEFORE_RIGHT` ou `RIGHT_BEFORE_LEFT`
</ParamField>

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

<ParamField path="matchScore" type="Integer" default="80">
  Aceito e validado, mas **reservado/inerte** — não altera o score de confiança calculado. Observe que regras DATE\_LAG sempre pontuam o componente de referência como 0, limitando o score máximo a 90
</ParamField>

<ParamField path="matchCurrency" type="Boolean" default="true">
  Requer match de moeda
</ParamField>

### Configurações de alocação (todos os tipos de regra)

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

| Campo                      | Tipo    | Descrição                                                 |
| -------------------------- | ------- | --------------------------------------------------------- |
| `allowPartial`             | Boolean | Permitir alocação parcial dos valores das transações      |
| `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 | Limite de tolerância para alocação                        |
| `allocationUseBaseAmount`  | Boolean | Usar valor base (convertido) para alocação                |

## Prioridade de regras

***

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

### Estratégia de prioridade

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

### 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 match](/pt/reference/matcher/reorder-match-rules)</Tip>

## Testando regras

***

Teste as regras em modo dry-run antes de confirmar as 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 mostra correspondências potenciais sem persistir os resultados.

## Gerenciando regras

***

### Listar regras

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

#### Response

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 individual da regra 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 match](/pt/reference/matcher/list-match-rules)</Tip>

### 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 match](/pt/reference/matcher/update-match-rule)</Tip>

### 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 match](/pt/reference/matcher/delete-match-rule)</Tip>

## Boas práticas

***

<AccordionGroup>
  <Accordion title="Comece estrito, depois relaxe">
    Comece com regras exatas. Adicione regras de tolerância apenas para a variância que você pode justificar e explicar.
  </Accordion>

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

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

  <Accordion title="Escreva descrições que expliquem a intenção">
    Uma regra deve documentar a variância que cobre e o risco que introduz.
  </Accordion>

  <Accordion title="Revise a saída das regras ao longo do tempo">
    Se uma regra nunca faz correspondência, ela pode ser desnecessária. Se faz correspondência com muita frequência, pode ser muito ampla.
  </Accordion>

  <Accordion title="Mantenha regras flexíveis com baixa prioridade">
    Alta tolerância aumenta falsos positivos. Use como fallback e revise os resultados cuidadosamente.
  </Accordion>
</AccordionGroup>

## Próximos passos

***

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

<Card title="Score de confiança" icon="chart-simple" href="/pt/matcher/reference/matcher-confidence-scoring" horizontal>
  Entenda como os scores são calculados e como os limites impactam a automação.
</Card>