Conceitos do Matcher

Os cinco conceitos centrais do Matcher: contextos, fontes, mapas de campos, regras e correspondências.

Contexto

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

Um contexto responde: o que corresponde ao quê?

Você pode começar com um rascunho vazio. Para ativá-lo, configure pelo menos uma fonte LEFT e uma fonte RIGHT, mapeie cada fonte (ou declare opções camt053 válidas, que se automapeiam) e adicione uma regra de correspondência. Se você habilitar a normalização de tarifas, 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 várias faturas
N:M	Conciliação muitos para muitos	Cenários de netting ou de agregação

Exemplo

Um contexto chamado “Chase Bank vs ERP System” faria o seguinte:

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

Fonte

Uma fonte é de onde as transações vêm. Um contexto em rascunho pode começar sem fontes. Um contexto ativável precisa de pelo menos uma fonte em cada lado da correspondência.

Tipos de fonte

LEDGER: categoria de fonte ledger
BANK: categoria de fonte bancária
GATEWAY: categoria de fonte de gateway de pagamento
CUSTOM: categoria de fonte personalizada
FETCHER: uma categoria de fonte do Discovery

Configuração da fonte

Cada fonte exige:

Nome: rotule a fonte (por exemplo, “Chase Checking”)
Tipo: categoria (LEDGER, BANK, GATEWAY, CUSTOM ou FETCHER)
Lado: qual lado da correspondência ela alimenta (LEFT ou RIGHT)

Config é opcional. Se você omitir, o Matcher guarda uma config vazia e usa os padrões do parser para as 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 chama as coisas de um jeito. Os 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 ou descrição externa
`fee_amount`	Não	Decimal	Coluna opcional de valor da tarifa
`fee_currency`	Não	String	Coluna opcional de moeda da tarifa

O vocabulário canônico permanece fechado. O Matcher rejeita um mapa de campos que declare qualquer outra chave. Quando a config de uma fonte declara opções camt053, o Matcher usa o mapeamento ISO 20022 embutido e ignora o mapa de campos. A ativação trata essa fonte como mapeada.

Exemplo de mapeamento

Você mapeia um extrato bancário que expõe TXN_ID, VALUE, CCY e POST_DATE assim:

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

Regra de correspondência

Uma regra de correspondência diz ao Matcher como comparar transações. As regras rodam em ordem crescente de prioridade. Uma transação reivindicada por uma regra anterior fica indisponível para as regras seguintes, que ainda avaliam as transações restantes.

Tipos de regra

EXACT: compara exatamente os campos configurados. Valor, moeda, data (por dia) e referência vêm habilitados por padrão.
TOLERANCE: corresponde valores dentro da tolerância absoluta e/ou percentual configurada. As tolerâncias de valor omitidas e dateWindowDays têm padrão 0, então nenhuma variação nem janela de data é permitida até você configurar uma.
DATE_LAG: corresponde dentro de uma faixa configurada de diferença de dias. minDays e maxDays têm ambos o padrão 0 (mesmo dia), não ±3. Como FUZZY, as correspondências DATE_LAG nunca se autoconfirmam. Elas sempre vão para revisão manual.
FUZZY: gradua as referências normalizadas das transações. Usa Reference, preenchido a partir do ExternalID da transação; um description do mapa de campos não é entrada para FUZZY. FUZZY apenas propõe. Nunca autoconfirma, então uma pessoa revisa cada ligação difusa.

Ordem de prioridade

Números menores rodam primeiro. Uma regra reivindica as transações que ela corresponde; as regras seguintes continuam com as transações restantes.

Prioridade	Regra	Descrição
1	Correspondência exata	Valor, data e referência devem coincidir
2	Tolerância no mesmo dia	Mesma data, valor dentro de 0,5%
3	Tolerância de uma semana	Dentro de 7 dias, valor dentro de 1%

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

Parâmetros das regras

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

Correspondência

Uma correspondência acontece quando transações de fontes diferentes são conciliadas juntas.

Status da correspondência

Status	Descrição
`PROPOSED`	O Matcher encontrou, aguardando confirmação
`CONFIRMED`	Aprovada automaticamente ou manualmente
`REJECTED`	Rejeitada manualmente
`REVOKED`	Uma correspondência antes confirmada foi desfeita, devolvendo suas transações para revisão

Padrões de correspondência

Correspondência 1:1

Uma transação de cada fonte é conciliada.

Bank: $100.00 on Jan 15 → ERP: $100.00 on Jan 15

Correspondência 1:N

Uma transação é conciliada contra várias transações.

Bank: $300.00 → ERP: $100.00 + $100.00 + $100.00

Correspondência N:1

Várias transações são conciliadas contra uma única transação.

Bank: $50.00 + $50.00 + $50.00 → ERP: $150.00

Correspondência N:M

Várias transações de cada lado são conciliadas juntas. A avaliação N:M executa apenas as regras EXACT e TOLERANCE; ela considera até quatro transações por lado em um grupo e limita cada bucket de identidade a 40 candidatos.

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

Itens de correspondência

Cada grupo de correspondência contém itens de correspondência, que registram a participação e a alocação das transações. Isso permite conciliação parcial em cenários de divisão e de 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 variação 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 classifica as exceções automaticamente para você saber o que priorizar.

Severidade	Critérios 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 demais casos

O classificador avalia os critérios de cima para baixo. Quando uma exceção atende aos critérios de mais de uma severidade, vale a severidade mais alta entre as que coincidem.

Workflows de resolução

Resolver: registre um rótulo de resolução e um motivo opcional para fechar uma exceção.
Forçar correspondência: resolva uma exceção forçando uma correspondência com um motivo de substituição depois de revisão manual.
Ajustar lançamento: resolva uma exceção criando um lançamento de ajuste com motivo, notas, valor positivo, moeda e momento de efeito.

Pontuação de confiança

Uma pontuação de confiança indica a confiabilidade de uma correspondência automática em uma escala de 0–100. Pontuações mais altas representam alinhamento mais forte entre as transações.

Cálculo da pontuação

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

Faixas de confiança

Faixa	Intervalo de pontuação	Comportamento do sistema
Aprovada automaticamente	≥ 90	Confirmada automaticamente (apenas regras EXACT e TOLERANCE — FUZZY e DATE_LAG sempre vão para revisão)
Precisa de revisão	60–89	Marcada para revisão manual
Sem correspondência	< 60	Não cria proposta de correspondência

Os pesos de confiança e os limiares das faixas são fixos no motor e não são configuráveis.

Log de auditoria

Um log de auditoria é um registro imutável e append-only criado por um workflow instrumentado. Ele dá rastreabilidade às ações que o Matcher registra.

Eventos registrados

Apenas os workflows 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, de fonte, de mapa de campos e de regra
Workflows de exceção, incluindo forçar correspondência 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 momento da ação auditada
`actorId`	Identificador do ator, quando informado
`action`	Ação executada
`entityType`	Tipo da entidade afetada
`entityId`	Identificador da entidade afetada
`changes`	Dados estruturados do evento em JSON; os eventos emitidos incluem `occurred_at` e quaisquer mudanças informadas
`tenantSeq`	Número de sequência por tenant
`prevHash` / `recordHash`	Cadeia de hash que liga cada entrada à anterior, o que torna a adulteração detectável

Os logs de auditoria são append-only. Ninguém pode alterar ou remover entradas.

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

Tipos de regra

Ordem de prioridade

Parâmetros das regras

Correspondência

Status da correspondência

Padrões de correspondência

Correspondência 1:1

Correspondência 1:N

Correspondência N:1

Correspondência N:M

Itens de correspondência

Exceção

Status da exceção

Severidade

Workflows de resolução

Pontuação de confiança

Cálculo da pontuação

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

​Tipos de regra

​Ordem de prioridade

​Parâmetros das regras

​Correspondência

​Status da correspondência

​Padrões de correspondência

​Correspondência 1:1

​Correspondência 1:N

​Correspondência N:1

​Correspondência N:M

​Itens de correspondência

​Exceção

​Status da exceção

​Severidade

​Workflows de resolução

​Pontuação de confiança

​Cálculo da pontuação

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

Tipos de regra

Ordem de prioridade

Parâmetros das regras

Correspondência

Status da correspondência

Padrões de correspondência

Correspondência 1:1

Correspondência 1:N

Correspondência N:1

Correspondência N:M

Itens de correspondência

Exceção

Status da exceção

Severidade

Workflows de resolução

Pontuação de confiança

Cálculo da pontuação

Faixas de confiança

Log de auditoria

Eventos registrados

Conteúdo da entrada de auditoria

Próximos passos