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. 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

O tipo também fixa as fontes por lado. Um contexto 1:1 precisa de exatamente uma fonte LEFT e uma fonte RIGHT, um contexto 1:N precisa de exatamente uma fonte LEFT, e um contexto N:M precisa de pelo menos uma fonte em cada lado. Uma execução de correspondência falha quando as fontes não se encaixam no tipo.

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	Descrição da transação
`fee_amount`	Não	Decimal	Coluna opcional de valor da tarifa
`fee_currency`	Não	String	Coluna opcional de moeda da tarifa
`direction`	Não	Object	`{column, debit, credit}`: a coluna que marca cada linha como débito ou crédito. Uma linha de débito é importada com valor negativo, uma de crédito com valor positivo. Apenas CSV, JSON e XML

O vocabulário canônico permanece fechado. O Matcher rejeita um mapa de campos que declare qualquer outra chave. Quando você mapeia direction, use uma coluna de valor sem sinal. O Matcher rejeita uma linha com valor com sinal, com a célula de direção vazia ou com um valor de direção desconhecido. Quando você envia um arquivo com o formato camt053, o Matcher usa o mapeamento ISO 20022 embutido e ignora o mapa de campos. A ativação trata como mapeada uma fonte que declara opções camt053.

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. Moeda e referência também precisam corresponder por padrão. As tolerâncias de valor omitidas e dateWindowDays têm padrão 0, então a regra não permite variação nem janela de data 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). DATE_LAG apenas propõe. Nunca autoconfirma.
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). `percentTolerance` é uma fração: `0.005` é 0,5%. A diferença permitida é o maior entre `absTolerance` e `percentTolerance` vezes o maior valor absoluto, com o `percentageBase` padrão. 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 os dois limites. Os valores precisam ser iguais, a menos que você defina `feeTolerance`.
FUZZY	`minSimilarity`: limiar de referência normalizada de `0` a `1` (padrão `0.80`), mais verificações de valor, moeda e data, ativas por padrão.

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 `UNMATCHED`

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. Ela ignora um bucket de candidatos que tenha mais de 40 transações em um lado.

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. O valor é o valor absoluto do valor base da transação ou, quando ela não tem valor base, do valor dela. Para um item em aberto envelhecido, é o valor absoluto do saldo em aberto.

Severidade	Critérios padrão
Crítica	Valor ≥ 100.000 ou idade ≥ 120 horas
Alta	Valor ≥ 10.000 ou idade ≥ 72 horas
Média	Valor ≥ 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. O Matcher limita uma exceção com motivo FEE_DATA_MISSING a Média, qualquer que seja o valor ou a idade dela.

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 e notas 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%	Peso total quando os valores correspondem pela regra ou a regra não verifica valores; caso contrário, `0`
Correspondência de moeda	30%	Peso total quando as moedas correspondem; caso contrário, `0`
Tolerância de data	20%	Peso total quando as datas ficam dentro da janela da regra ou a regra não verifica datas; caso contrário, `0`
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 para correspondências EXACT e TOLERANCE. As correspondências FUZZY e DATE_LAG sempre vão para revisão
Precisa de revisão	60–89	Marcada para revisão manual

O motor fixa os pesos de confiança e os limiares das faixas. Eles 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. 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

Os logs de auditoria são append-only. O arquivamento exporta partições mensais antigas para o armazenamento de objetos e depois as remove do banco de dados.

Visão geral

Guias

Console

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