> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.
# Conceitos do Matcher
> Aprenda os cinco conceitos centrais do Matcher que moldam cada conciliação que você monta: contextos, fontes, mapas de campos, regras de correspondência e correspondências.
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:
```json theme={null}
{
"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.
## Próximos passos
***
Veja como os contextos delimitados implementam esses conceitos.
Aplique esses conceitos em um fluxo guiado e prático.