Regras de match

Regras de match definem como o Matcher compara transações entre fontes. Você pode impor matches estritos, permitir variância controlada ou modelar lógica mais avançada com condições compostas.

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 um match determina o resultado.
Se nenhuma regra faz match, 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: Matches determinísticos onde 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.

Criando regras de match

Regra exact

cURL

curl -X POST "https://api.matcher.example.com/v1/config/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

Campo	Tipo	Padrão	Descrição
`matchAmount`	Boolean	true	Requer match exato de valor
`matchCurrency`	Boolean	true	Requer match exato de moeda
`matchDate`	Boolean	true	Requer match exato de data
`matchReference`	Boolean	true	Requer match exato de referência
`datePrecision`	String	`"DAY"`	Precisão da comparação de data: `DAY` ou `TIMESTAMP`
`caseInsensitive`	Boolean	true	Comparação de referência sem distinção de maiúsculas/minúsculas
`referenceMustSet`	Boolean	false	Requer que a referência esteja presente em ambos os lados
`matchBaseAmount`	Boolean	false	Comparar pelo valor base (convertido) em vez do original
`matchBaseCurrency`	Boolean	false	Comparar pela moeda base em vez da original
`matchScore`	Integer	100	Pontuação de confiança atribuída quando a regra faz match
`matchBaseScore`	Integer	90	Pontuação de confiança atribuída quando a regra faz match pelo valor base

Response

{
  "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",
    "caseInsensitive": true,
    "referenceMustSet": false,
    "matchBaseAmount": false,
    "matchBaseCurrency": false,
    "matchScore": 100,
    "matchBaseScore": 90
  },
  "createdAt": "2026-02-02T16:40:00Z",
  "updatedAt": "2026-02-02T16:40:00Z"
}

Referência da API: Criar regra de match

Regra tolerance

cURL

curl -X POST "https://api.matcher.example.com/v1/config/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

Campo	Tipo	Padrão	Descrição
`percentTolerance`	Decimal	0.005	Variância percentual máxima permitida (0.005 = 0,5%)
`absTolerance`	Decimal	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	true	Requer match de moeda
`matchReference`	Boolean	true	Requer match de referência
`caseInsensitive`	Boolean	true	Comparação de referência sem distinção de maiúsculas/minúsculas
`referenceMustSet`	Boolean	false	Requer que a referência esteja presente em ambos os lados
`matchBaseAmount`	Boolean	false	Comparar pelo valor base (convertido)
`matchBaseCurrency`	Boolean	false	Comparar pela moeda base
`matchScore`	Integer	85	Pontuação de confiança quando a regra faz match
`matchBaseScore`	Integer	80	Pontuação de confiança quando a regra faz match pelo valor base

Exemplo:

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

Regra date lag

cURL

curl -X POST "https://api.matcher.example.com/v1/config/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

Campo	Tipo	Padrão	Descrição
`maxDays`	Integer	—	Número máximo de dias de diferença permitido
`minDays`	Integer	0	Número mínimo de dias de diferença requerido
`inclusive`	Boolean	true	Se os dias limítrofes são inclusivos
`direction`	String	`"ABS"`	Como medir o atraso: `ABS` (absoluto), `LEFT_BEFORE_RIGHT` ou `RIGHT_BEFORE_LEFT`
`feeTolerance`	Decimal	0	Diferença de valor permitida para considerar taxas
`matchScore`	Integer	80	Pontuação de confiança quando a regra faz match
`matchCurrency`	Boolean	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	Matches determinísticos
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/config/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 os matches.

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 matches potenciais sem persistir os resultados.

Gerenciando regras

Listar regras

cURL

curl -X GET "https://api.matcher.example.com/v1/config/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/config/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/config/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 match 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 match, ela pode ser desnecessária. Se faz match 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.

Introdução

Primeiros passos

Configurações

Reconciliação diária

Casos de uso do Matcher

Integrações

Referência

Regras de match

Como as regras funcionam

Tipos de regra

Exact

Tolerance

Date lag

Criando regras de match

Regra exact

Referência de configuração

Response

Regra tolerance

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

Introdução

Primeiros passos

Configurações

Reconciliação diária

Casos de uso do Matcher

Integrações

Referência

​Como as regras funcionam

​Tipos de regra

​Exact

​Tolerance

​Date lag

​Criando regras de match

​Regra exact

​Referência de configuração

​Response

​Regra tolerance

​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

Criando regras de match

Regra exact

Referência de configuração

Response

Regra tolerance

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