Conceitos do Matcher

Os cinco conceitos principais do Matcher: contextos, fontes, mapas de campos, regras e matches. Entenda estes conceitos e você entenderá como todo o sistema funciona.

Contexto

Um contexto define o que você concilia. É o contêiner de configuração de fontes e regras. O Matcher cria um novo contexto em DRAFT, e suas fontes e regras em linha são opcionais.

Um contexto responde: o que estou conciliando contra o quê?

Você pode começar com um rascunho vazio. Para ativá-lo, configure pelo menos uma fonte LEFT e uma RIGHT, mapeie cada fonte (ou declare opções camt053 válidas, que são automapeadas) e adicione uma regra de match. Se a normalização de tarifas estiver habilitada, adicione também uma regra de tarifa.

Tipos de contexto

Tipo	Descrição	Exemplo
1:1	Conciliação um-para-um	Extrato bancário vs registros do ERP
1:N	Conciliação um-para-muitos	Um pagamento cobrindo múltiplas faturas
N:M	Conciliação muitos-para-muitos	Cenários de netting ou agregação

Exemplo

Um contexto chamado “Chase Bank vs ERP System” iria:

Definir o Chase Bank como uma fonte de conciliação
Definir seu sistema ERP como outra fonte
Especificar as regras usadas para conciliar transações entre eles

Fonte

Uma fonte é de onde vêm as transações. Um contexto em rascunho pode começar sem fontes; um contexto que pode ser ativado precisa de pelo menos uma fonte em cada lado do match.

Tipos de fonte

LEDGER: Categoria de fonte de livro-razão
BANK: Categoria de fonte bancária
GATEWAY: Categoria de fonte de gateway de pagamento
CUSTOM: Categoria de fonte personalizada
FETCHER: Categoria de fonte Fetcher

Configuração da fonte

Cada fonte requer:

Nome: Identifique-a (ex: “Chase Checking”)
Tipo: Categoria (LEDGER, BANK, GATEWAY, CUSTOM ou FETCHER)
Lado: Qual lado de match ela alimenta (LEFT ou RIGHT)

A configuração é opcional. Se você a omitir, o Matcher armazena uma configuração vazia e usa os padrões do parser para chaves de política ausentes. Os mapas de campos traduzem os campos de cada fonte para o schema padrão do Matcher.

Mapa de campos

Um mapa de campos traduz nomes de campos externos para o schema padrão do Matcher. Cada sistema nomeia as coisas de forma diferente—mapas de campos normalizam isso.

Campos padrão

Campo	Obrigatório	Tipo	Descrição
`external_id`	Sim	String	Identificador da transação no sistema de origem
`amount`	Sim	Decimal	Valor da transação (positivo ou negativo)
`currency`	Sim	String	Código de moeda ISO 4217
`date`	Sim	DateTime	Data da transação
`description`	Não	String	Referência externa ou descrição
`fee_amount`	Não	Decimal	Coluna opcional de valor de tarifa
`fee_currency`	Não	String	Coluna opcional de moeda de tarifa

O vocabulário canônico é fechado — um mapa de campos que declare qualquer outra chave é rejeitado. Quando a configuração de uma fonte declara opções camt053, o Matcher usa seu mapeamento ISO 20022 incorporado e ignora um mapa de campos; a ativação considera essa fonte mapeada.

Exemplo de mapeamento

Um extrato bancário expondo TXN_ID, VALUE, CCY e POST_DATE seria mapeado como:

{
  "external_id": "TXN_ID",
  "amount": "VALUE",
  "currency": "CCY",
  "date": "POST_DATE"
}

Regra de match

Uma regra de match diz ao Matcher como comparar transações. As regras são executadas em prioridade crescente; uma transação reivindicada por uma regra anterior fica indisponível para as posteriores, que ainda avaliam as transações restantes.

Tipos de regra

EXACT: Compara exatamente os campos configurados. Valor, moeda, data (por dia) e referência são habilitados por padrão.
TOLERANCE: Faz match de valores dentro da tolerância absoluta e/ou percentual configurada. Tolerâncias de valor e dateWindowDays omitidos têm o padrão 0, portanto não há variação nem janela de data permitida até que você os configure.
DATE_LAG: Faz match dentro de uma faixa configurada de diferença em dias. minDays e maxDays têm ambos o padrão 0 (mesmo dia), não ±3. Como FUZZY, matches DATE_LAG nunca são autoconfirmados — sempre vão para revisão manual.
FUZZY: Calcula similaridade graduada de referências normalizadas de transações. Usa Reference, alimentada pelo ExternalID da transação; um description em um mapa de campos não é uma entrada de FUZZY. FUZZY apenas propõe—nunca autoconfirma, então uma pessoa revisa cada vínculo fuzzy.

Ordem de prioridade

Números menores são executados primeiro. Uma regra reivindica suas transações correspondentes; regras posteriores continuam com as transações restantes.

Prioridade	Regra	Descrição
1	Match exato	Valor, data e referência devem corresponder
2	Tolerância mesmo dia	Mesma data, valor dentro de 0,5%
3	Tolerância semanal	Dentro de 7 dias, valor dentro de 1%

Estas prioridades e valores são regras ilustrativas, não padrões do motor. Configure os valores de acordo com sua política de conciliação.

Parâmetros da regra

Tipo de regra	Parâmetros
EXACT	`matchAmount`, `matchCurrency`, `matchDate`, `matchReference`: quais campos devem corresponder exatamente
TOLERANCE	Valores não negativos `percentTolerance` e/ou `absTolerance` no nível superior (números ou strings decimais); opcionalmente defina `dateWindowDays` (padrão `0`; máximo `3650`). Não envolva esses valores em um objeto `tolerance`.
DATE_LAG	`minDays`, `maxDays`: faixa permitida de diferença em dias. Ambos têm o padrão `0`, devem estar entre `0` e `3650`, e `maxDays` deve ser no mínimo `minDays`; `inclusive` tem o padrão `true` e controla o limite superior.
FUZZY	`minSimilarity`: limite de referência normalizada de `0` a `1` (padrão `0.80`), além de eixos opcionais de valor, moeda e data.

Match

Um match é quando transações de fontes diferentes são conciliadas juntas. É o objetivo final.

Status do match

Status	Descrição
`PROPOSED`	Matcher encontrou, aguardando confirmação
`CONFIRMED`	Aprovado automaticamente ou manualmente
`REJECTED`	Rejeitado manualmente
`REVOKED`	Um match previamente confirmado foi desfeito, devolvendo suas transações para revisão

Padrões de match

Match 1:1

Uma transação de cada fonte é conciliada.

Banco: $100.00 em 15 de jan → ERP: $100.00 em 15 de jan

Match 1:N

Uma transação é conciliada contra múltiplas transações.

Banco: $300.00 → ERP: $100.00 + $100.00 + $100.00

Match N:1

Múltiplas transações são conciliadas contra uma única transação.

Banco: $50.00 + $50.00 + $50.00 → ERP: $150.00

Match N:M

Múltiplas transações de cada lado são conciliadas juntas. A avaliação N:M só executa regras EXACT e TOLERANCE; considera até quatro transações por lado em um grupo e limita cada grupo de identidade a 40 candidatos.

Banco: $100.00 + $200.00 → ERP: $150.00 + $150.00

Itens do match

Cada grupo de match contém itens de match, que registram a participação e alocação das transações. Isso permite conciliação parcial em cenários de split e agregação.

Exceção

Uma exceção registra uma transação que precisa de revisão, incluindo transações não conciliadas e transações conciliadas com condições residuais, como variância de câmbio.

Status da exceção

Status	Descrição
`OPEN`	Aguardando atribuição
`ASSIGNED`	Alguém está investigando
`PENDING_RESOLUTION`	Uma resolução está em andamento, aguardando conclusão
`RESOLVED`	Tratada

Severidade

O Matcher auto-classifica exceções para que você saiba o que priorizar.

Severidade	Critério padrão
Crítica	Valor base absoluto ≥ 100.000, idade ≥ 120 horas ou um tipo de fonte regulatória configurado
Alta	Valor base absoluto ≥ 10.000 ou idade ≥ 72 horas
Média	Valor base absoluto ≥ 1.000 ou idade ≥ 24 horas
Baixa	Todos os outros casos

O classificador avalia os critérios de cima para baixo. Quando uma exceção atende aos critérios de mais de uma severidade, a maior severidade aplicável prevalece.

Fluxos de resolução

Resolver: Registre um rótulo de resolução e um motivo opcional para encerrar uma exceção.
Forçar match: Resolva uma exceção forçando um match com um motivo de substituição após a revisão manual.
Ajustar lançamento: Resolva uma exceção criando um lançamento de ajuste com motivo, notas, valor positivo, moeda e data de vigência.

Score de confiança

Um score de confiança indica a confiabilidade de um match automatizado em uma escala de 0–100. Scores mais altos representam maior alinhamento entre transações.

Cálculo do score

Componente	Peso	Descrição
Match de valor	40%	Grau de alinhamento do valor
Match de moeda	30%	Consistência da moeda
Tolerância de data	20%	Proximidade das datas das transações
Referência	10%	Alinhamento de referência normalizada (graduado 0–1 para regras FUZZY)

Faixas de confiança

Faixa	Intervalo de score	Comportamento do sistema
Auto-aprovado	≥ 90	Confirmado automaticamente (apenas regras EXACT e TOLERANCE — FUZZY e DATE_LAG sempre vão para revisão)
Precisa revisão	60–89	Sinalizado para revisão manual
Sem match	< 60	Não cria uma proposta de match

Os pesos de confiança e os limites de nível são fixos do motor e não são configuráveis.

Log de auditoria

Um log de auditoria é um registro imutável, somente de acréscimo, criado por um fluxo instrumentado. Ele fornece rastreabilidade para as ações que o Matcher registra.

Eventos registrados

Somente fluxos instrumentados para emitir um evento de auditoria criam entradas. Quando a publicação de auditoria está configurada, os produtores verificados incluem:

Mutações de contexto, fonte, mapa de campos e regra
Fluxos de exceção, incluindo forçar match e ajustar lançamento

Conteúdo da entrada de auditoria

Campo	Descrição
`createdAt`	Timestamp de criação do registro (UTC), que pode diferir do horário da ação auditada
`actorId`	Identificador do ator, quando fornecido
`action`	Ação realizada
`entityType`	Tipo da entidade afetada
`entityId`	Identificador da entidade afetada
`changes`	Dados estruturados do evento em JSON; eventos emitidos incluem `occurred_at` e quaisquer mudanças fornecidas
`tenantSeq`	Número de sequência por tenant
`prevHash` / `recordHash`	Cadeia de hashes que vincula cada entrada à anterior, tornando detectável qualquer adulteração

Os logs de auditoria são apenas append. Entradas não podem ser modificadas ou removidas.

Visão geral

Guias

Matcher UI

Servidor MCP

Operações

Conceitos do Matcher

Contexto

Tipos de contexto

Exemplo

Fonte

Tipos de fonte

Configuração da fonte

Mapa de campos

Campos padrão

Exemplo de mapeamento

Regra de match

Tipos de regra

Ordem de prioridade

Parâmetros da regra

Match

Status do match

Padrões de match

Match 1:1

Match 1:N

Match N:1

Match N:M

Itens do match

Exceção

Status da exceção

Severidade

Fluxos de resolução

Score de confiança

Cálculo do score

Faixas de confiança

Log de auditoria

Eventos registrados

Conteúdo da entrada de auditoria

Próximos passos

Arquitetura

Início rápido

​Contexto

​Tipos de contexto

​Exemplo

​Fonte

​Tipos de fonte

​Configuração da fonte

​Mapa de campos

​Campos padrão

​Exemplo de mapeamento

​Regra de match

​Tipos de regra

​Ordem de prioridade

​Parâmetros da regra

​Match

​Status do match

​Padrões de match

​Match 1:1

​Match 1:N

​Match N:1

​Match N:M

​Itens do match

​Exceção

​Status da exceção

​Severidade

​Fluxos de resolução

​Score de confiança

​Cálculo do score

​Faixas de confiança

​Log de auditoria

​Eventos registrados

​Conteúdo da entrada de auditoria

​Próximos passos

Arquitetura

Início rápido

Contexto

Tipos de contexto

Exemplo

Fonte

Tipos de fonte

Configuração da fonte

Mapa de campos

Campos padrão

Exemplo de mapeamento

Regra de match

Tipos de regra

Ordem de prioridade

Parâmetros da regra

Match

Status do match

Padrões de match

Match 1:1

Match 1:N

Match N:1

Match N:M

Itens do match

Exceção

Status da exceção

Severidade

Fluxos de resolução

Score de confiança

Cálculo do score

Faixas de confiança

Log de auditoria

Eventos registrados

Conteúdo da entrada de auditoria

Próximos passos