Regras de correspondência

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

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"

Exige correspondência exata de valor

Boolean

padrão:"true"

Exige correspondência exata de moeda

Boolean

padrão:"true"

Exige correspondência exata de data

Boolean

padrão:"true"

Exige correspondência exata 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 diferenciar maiúsculas

Boolean

padrão:"false"

Exige que a referência esteja presente nos dois lados

Boolean

padrão:"false"

Corresponde pelo valor base (convertido) em vez do original

Boolean

padrão:"false"

Corresponde pela moeda base em vez da original

Integer

padrão:"100"

Aceito e validado, mas reservado/inerte. Ele não muda a pontuação de confiança calculada (veja a nota abaixo)

Integer

padrão:"90"

Aceito e validado, mas reservado/inerte. Ele não muda a pontuação de confiança calculada (veja a nota abaixo)

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.

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

Referência da API: Criar regra de correspondência

Regra de tolerância

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

Limiar percentual aplicado a percentageBase (0,005 = 0,5%). O padrão é 0. O Matcher compara esse limiar com absTolerance e usa o maior

Decimal

Limiar de valor absoluto. O padrão é 0. O Matcher o compara com o limiar percentual e usa o maior

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

Integer

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

Integer

Casas decimais para o arredondamento

String

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

String

padrão:"MAX"

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

Boolean

padrão:"true"

Exige correspondência de moeda

Boolean

padrão:"true"

Exige correspondência de referência

Boolean

padrão:"true"

Comparação de referência sem diferenciar maiúsculas

Boolean

padrão:"false"

Exige que a referência esteja presente nos dois lados

Boolean

padrão:"false"

Corresponde pelo valor base (convertido)

Boolean

padrão:"false"

Corresponde pela moeda base

Integer

padrão:"85"

Aceito e validado, mas reservado/inerte. Ele não muda a pontuação de confiança calculada

Integer

padrão:"80"

Aceito e validado, mas reservado/inerte. Ele não muda a pontuação de confiança calculada

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

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 mínima normalizada da referência (0–1) exigida para filtrar como correspondência

Boolean

padrão:"true"

Quando true, exige correspondência exata de valor

Boolean

padrão:"true"

Quando true, exige correspondência exata de moeda

Boolean

padrão:"true"

Quando true, exige correspondência exata de data

String

padrão:"DAY"

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

Boolean

padrão:"true"

Exige uma referência não vazia nos dois lados

Integer

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

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.

Regra de defasagem de data

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 exigido

Boolean

padrão:"true"

Se os dias de fronteira são inclusivos

String

padrão:"ABS"

Como medir a defasagem: ABS (absoluta), LEFT_BEFORE_RIGHT ou RIGHT_BEFORE_LEFT

Decimal

padrão:"0"

Diferença de valor permitida para considerar tarifas

Integer

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

Boolean

padrão:"true"

Exige correspondência de moeda

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:

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 correspondência

Como testar regras

Teste as regras no modo dry run antes de efetivar 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 o evento de conclusão dele.

Como gerenciar regras

Como listar regras

cURL

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.

{
  "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 correspondência

Como 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 correspondência

Como 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 correspondência

Boas práticas

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.

Deixe espaço nas prioridades

Use intervalos (1, 10, 20, 50) para inserir regras sem renumerar todo o conjunto.

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.

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.

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.

Mantenha as regras frouxas em prioridade baixa

Tolerância alta aumenta os falsos positivos. Use-a como fallback e revise os resultados com cuidado.

Próximos passos

Roteamento de exceções

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

Pontuação de confiança

Entenda como as pontuações são calculadas e como os limiares afetam a automação.

Visão geral

Guias

Matcher UI

Servidor MCP

Operações

Regras de correspondência

Como as regras funcionam

Tipos de regra

Exata

Tolerância

Defasagem de data

Difusa

Como criar regras de correspondência

Regra exata

Referência de configuração

Regra de tolerância

Referência de configuração

Regra difusa

Referência de configuração

Regra de defasagem de data

Referência de configuração

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

Prioridade das regras

Estratégia de prioridade

Como reordenar regras

Como testar regras

Como gerenciar regras

Como listar regras

Resposta

Como atualizar uma regra

Como excluir uma regra

Boas práticas

Próximos passos

Roteamento de exceções

Pontuação de confiança

​Como as regras funcionam

​Tipos de regra

​Exata

​Tolerância

​Defasagem de data

​Difusa

​Como criar regras de correspondência

​Regra exata

​Referência de configuração

​Regra de tolerância

​Referência de configuração

​Regra difusa

​Referência de configuração

​Regra de defasagem de data

​Referência de configuração

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

​Prioridade das regras

​Estratégia de prioridade

​Como reordenar regras

​Como testar regras

​Como gerenciar regras

​Como listar regras

​Resposta

​Como atualizar uma regra

​Como excluir uma regra

​Boas práticas

​Próximos passos

Roteamento de exceções

Pontuação de confiança

Como as regras funcionam

Tipos de regra

Exata

Tolerância

Defasagem de data

Difusa

Como criar regras de correspondência

Regra exata

Referência de configuração

Regra de tolerância

Referência de configuração

Regra difusa

Referência de configuração

Regra de defasagem de data

Referência de configuração

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

Prioridade das regras

Estratégia de prioridade

Como reordenar regras

Como testar regras

Como gerenciar regras

Como listar regras

Resposta

Como atualizar uma regra

Como excluir uma regra

Boas práticas

Próximos passos