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.
Cada regra cria todas as correspondências possíveis com transações que não foram usadas por regras de prioridade mais alta.
Depois que todas as regras são executadas, as transações que continuam sem correspondência se tornam exceções.

Essa abordagem impede a reutilização das correspondências de prioridade mais alta e permite que regras progressivamente mais flexíveis processem as transações restantes.

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 normalizada de similaridade de strings. As verificações de valor, moeda e data exigem igualdade exata por padrão, mas matchAmount, matchCurrency e matchDate controlam de forma independente se cada verificação se aplica. FUZZY sempre propõe uma correspondência para revisão e nunca confirma automaticamente.

Melhor para: Memos de texto livre ou referências truncadas em que a referência varia, mas as verificações financeiras habilitadas ainda correspondem.

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

Boolean

padrão:"true"

Requer match exato de valor

Boolean

padrão:"true"

Requer match exato de moeda

Boolean

padrão:"true"

Requer match exato de data

Boolean

padrão:"true"

Requer match exato de referência

String

padrão:"DAY"

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

Boolean

padrão:"true"

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

Boolean

padrão:"false"

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

Boolean

padrão:"false"

Comparar pelo valor base (convertido) em vez do original

Boolean

padrão:"false"

Comparar pela moeda base em vez da original

Integer

padrão:"100"

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

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

Decimal

Limite percentual aplicado a percentageBase (0.005 = 0,5%). O padrão é 0; o Matcher compara esse limite com absTolerance e usa o maior

Decimal

Limite absoluto de valor. O padrão é 0; o Matcher o compara com o limite percentual e usa o maior

Os dois limites têm padrão zero; portanto, você precisa configurar explicitamente qualquer variação de valor permitida.

Integer

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

Integer

Casas decimais para arredondamento

String

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

String

padrão:"MAX"

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

Boolean

padrão:"true"

Requer match de moeda

Boolean

padrão:"true"

Requer match de referência

Boolean

padrão:"true"

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

Boolean

padrão:"false"

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

Boolean

padrão:"false"

Comparar pelo valor base (convertido)

Boolean

padrão:"false"

Comparar pela moeda base

Integer

padrão:"85"

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

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
Diferença de valor: R$5,00
Limite percentual: R $1.005,00 × 0,5% = R$ 5,025 (percentageBase: MAX)
Limite absoluto: R$0,50
Limite efetivo: MAX(R$5,025, R$0,50) = R$5,025 → Corresponde

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

Decimal

padrão:"0.80"

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

Boolean

padrão:"true"

Quando true, exige match exato de valor

Boolean

padrão:"true"

Quando true, exige match exato de moeda

Boolean

padrão:"true"

Quando true, exige match exato de data

String

padrão:"DAY"

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

Boolean

padrão:"true"

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

Integer

padrão:"70"

Aceito e com padrão 70, mas reservado/inerte — não limita nem altera a confiança calculada ou o comportamento de confirmação automática

FUZZY substitui a igualdade de referência por similaridade. Por padrão, também exige correspondências exatas de valor, moeda e data; desative cada verificação de forma independente com matchAmount, matchCurrency ou matchDate. FUZZY sempre propõe correspondências para revisão humana e nunca as confirma automaticamente.

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

Integer

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

Integer

padrão:"0"

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

Boolean

padrão:"true"

Se os dias limítrofes são inclusivos

String

padrão:"ABS"

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

Decimal

padrão:"0"

Diferença de valor permitida para considerar taxas

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

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 retorna correspondências potenciais. Ele não cria exceções, mas o Matcher conclui e persiste o MatchRun com estatísticas e emite seu evento de conclusão.

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