Regras de match

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

cURL

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

matchAmount

Boolean

padrão:"true"

Requer match exato de valor

matchCurrency

Boolean

padrão:"true"

Requer match exato de moeda

matchDate

Boolean

padrão:"true"

Requer match exato de data

matchReference

Boolean

padrão:"true"

Requer match exato de referência

datePrecision

String

padrão:"DAY"

Precisão da comparação de data: DAY ou TIMESTAMP

caseInsensitive

Boolean

padrão:"true"

Comparação de referência sem distinção de maiúsculas/minúsculas

referenceMustSet

Boolean

padrão:"false"

Requer que a referência esteja presente em ambos os lados

matchBaseAmount

Boolean

padrão:"false"

Comparar pelo valor base (convertido) em vez do original

matchBaseCurrency

Boolean

padrão:"false"

Comparar pela moeda base em vez da original

matchScore

Integer

padrão:"100"

Aceito e validado, mas reservado/inerte — não altera o score de confiança calculado (veja a nota abaixo)

matchBaseScore

Integer

padrão:"90"

Aceito e validado, mas reservado/inerte — não altera o score de confiança calculado (veja a nota abaixo)

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.

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

Referência da API: Criar regra de match

Regra tolerance

cURL

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

percentTolerance

Decimal

padrão:"0.005"

Variância percentual máxima permitida (0.005 = 0,5%)

absTolerance

Decimal

padrão:"0.50"

Variância absoluta máxima de valor permitida

dateWindowDays

Integer

Número de dias permitidos entre as datas das transações

roundingScale

Integer

Casas decimais para arredondamento

roundingMode

String

Estratégia de arredondamento: HALF_UP, BANKERS, FLOOR, CEIL ou TRUNCATE

percentageBase

String

Base para cálculo percentual: MAX, MIN, AVERAGE, LEFT ou RIGHT

matchCurrency

Boolean

padrão:"true"

Requer match de moeda

matchReference

Boolean

padrão:"true"

Requer match de referência

caseInsensitive

Boolean

padrão:"true"

Comparação de referência sem distinção de maiúsculas/minúsculas

referenceMustSet

Boolean

padrão:"false"

Requer que a referência esteja presente em ambos os lados

matchBaseAmount

Boolean

padrão:"false"

Comparar pelo valor base (convertido)

matchBaseCurrency

Boolean

padrão:"false"

Comparar pela moeda base

matchScore

Integer

padrão:"85"

Aceito e validado, mas reservado/inerte — não altera o score de confiança calculado

matchBaseScore

Integer

padrão:"80"

Aceito e validado, mas reservado/inerte — não altera o score de confiança calculado

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

cURL

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

minSimilarity

Decimal

padrão:"0.80"

Similaridade de referência normalizada mínima (0–1) exigida para validar como correspondência

matchAmount

Boolean

padrão:"true"

Requer match exato de valor

matchCurrency

Boolean

padrão:"true"

Requer match exato de moeda

matchDate

Boolean

padrão:"true"

Requer match exato de data

datePrecision

String

padrão:"DAY"

Precisão da comparação de data: DAY ou TIMESTAMP

referenceMustSet

Boolean

padrão:"true"

Requer uma referência não vazia em ambos os lados

matchScore

Integer

padrão:"70"

Teto nominal de pontuação (o avaliador de similaridade graduado determina a confiança real)

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.

Regra date lag

cURL

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

maxDays

Integer

Número máximo de dias de diferença permitido

minDays

Integer

padrão:"0"

Número mínimo de dias de diferença requerido

inclusive

Boolean

padrão:"true"

Se os dias limítrofes são inclusivos

direction

String

padrão:"ABS"

Como medir o atraso: ABS (absoluto), LEFT_BEFORE_RIGHT ou RIGHT_BEFORE_LEFT

feeTolerance

Decimal

padrão:"0"

Diferença de valor permitida para considerar taxas

matchScore

Integer

padrão:"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

matchCurrency

Boolean

padrão:"true"

Requer match de moeda

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:

cURL

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

Referência da API: Reordenar regras de match

Testando regras

Teste as regras em modo dry-run antes de confirmar as correspondências.

cURL

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

cURL

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.

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

Referência da API: Listar regras de match

Atualizar uma regra

cURL

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
   }
 }'

Referência da API: Atualizar regra de match

Excluir uma regra

cURL

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

Referência da API: Excluir regra de match

Boas práticas

Comece estrito, depois relaxe

Comece com regras exatas. Adicione regras de tolerância apenas para a variância que você pode justificar e explicar.

Deixe espaço nas prioridades

Use gaps (1, 10, 20, 50) para que você possa inserir regras sem renumerar todo o seu conjunto.

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.

Escreva descrições que expliquem a intenção

Uma regra deve documentar a variância que cobre e o risco que introduz.

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.

Mantenha regras flexíveis com baixa prioridade

Alta tolerância aumenta falsos positivos. Use como fallback e revise os resultados cuidadosamente.

Próximos passos

Roteamento de exceções

Configure classificação, atribuição e escalonamento para transações não conciliadas.

Score de confiança

Entenda como os scores são calculados e como os limites impactam a automação.

Visão geral

Guias

Matcher UI

Servidor MCP

Operações

Regras de match

Como as regras funcionam

Tipos de regra

Exact

Tolerance

Date lag

Fuzzy

Criando regras de match

Regra exact

Referência de configuração

Regra tolerance

Referência de configuração

Regra fuzzy

Referência de configuração

Regra date lag

Referência de configuração

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

Prioridade de regras

Estratégia de prioridade

Reordenar regras

Testando regras

Gerenciando regras

Listar regras

Response

Atualizar uma regra

Excluir uma regra

Boas práticas

Próximos passos

Roteamento de exceções

Score de confiança

​Como as regras funcionam

​Tipos de regra

​Exact

​Tolerance

​Date lag

​Fuzzy

​Criando regras de match

​Regra exact

​Referência de configuração

​Regra tolerance

​Referência de configuração

​Regra fuzzy

​Referência de configuração

​Regra date lag

​Referência de configuração

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

​Prioridade de regras

​Estratégia de prioridade

​Reordenar regras

​Testando regras

​Gerenciando regras

​Listar regras

​Response

​Atualizar uma regra

​Excluir uma regra

​Boas práticas

​Próximos passos

Roteamento de exceções

Score de confiança

Como as regras funcionam

Tipos de regra

Exact

Tolerance

Date lag

Fuzzy

Criando regras de match

Regra exact

Referência de configuração

Regra tolerance

Referência de configuração

Regra fuzzy

Referência de configuração

Regra date lag

Referência de configuração

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

Prioridade de regras

Estratégia de prioridade

Reordenar regras

Testando regras

Gerenciando regras

Listar regras

Response

Atualizar uma regra

Excluir uma regra

Boas práticas

Próximos passos