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

> Entenda os cinco conceitos centrais que sustentam o Matcher: contextos, fontes, mapeamentos de campos, regras e matches.

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ê está conciliando. É o container que contém suas fontes, regras e resultados.

<Info>
  Um contexto responde: *o que estou conciliando contra o quê?*
</Info>

### 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 as transações vêm. Todo contexto precisa de pelo menos duas fontes—é isso que você está conciliando.

### Tipos de fonte

* **LEDGER**: Sistemas de ledger internos (incluindo Midaz)
* **BANK**: Feeds de extratos bancários
* **GATEWAY**: Liquidações de gateways de pagamento (Stripe, Adyen, PayPal)
* **CUSTOM**: Feeds personalizados definidos pelo usuário
* **FETCHER**: Fontes obtidas automaticamente pelo motor de descoberta (conexões de agregadores)

### 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`)
* **Config**: Configurações de conexão e parsing específicas da fonte

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            | Tipo     | Descrição                                       |
| ---------------- | -------- | ----------------------------------------------- |
| `transaction_id` | String   | Identificador da transação no sistema de origem |
| `amount`         | Decimal  | Valor da transação (positivo ou negativo)       |
| `currency`       | String   | Código de moeda ISO 4217                        |
| `date`           | DateTime | Data da transação                               |
| `reference`      | String   | Referência externa ou descrição                 |
| `metadata`       | Object   | Atributos específicos da fonte                  |

### Exemplo de mapeamento

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

```json theme={null}
{
  "transaction_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 ordem de prioridade—o primeiro match vence.

### Tipos de regra

* **EXACT**: Os campos devem corresponder exatamente (valor, data, referência)
* **TOLERANCE**: Permite pequenas diferenças (0,5% de variância, R\$10 absolutos)
* **DATE\_LAG**: Match dentro de uma janela de datas (±3 dias)
* **FUZZY**: Similaridade graduada em referências/descrições (normalizada, substring ou pontuada por similaridade). FUZZY apenas propõe—nunca autoconfirma, então um humano revisa cada vínculo fuzzy.

### Ordem de prioridade

Números menores são executados primeiro. O Matcher para na primeira regra que faz match.

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

### Parâmetros da regra

| Tipo de regra | Parâmetros                                                                  |
| ------------- | --------------------------------------------------------------------------- |
| EXACT         | `fields`: lista de campos para comparar                                     |
| TOLERANCE     | `percent`: variância percentual, `absolute`: valor de variância fixo        |
| DATE\_LAG     | `days_before`, `days_after`: offset permitido a partir da data da transação |

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

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

#### Match 1:N

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

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

#### Match N:1

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

```
Bank: $50.00 + $50.00 + $50.00 → ERP: $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** é uma transação que não fez match. Ela precisa de revisão manual.

### 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                                             |
| ------------ | ----------------------------------------------------------- |
| **Critical** | Valor ≥ \$100K, idade ≥ 5 dias, ou sinalizado por regulação |
| **High**     | Valor ≥ \$10K ou idade ≥ 3 dias                             |
| **Medium**   | Valor ≥ 1.000 ou idade ≥ 1 dia                              |
| **Low**      | Todos os outros casos                                       |

### Tipos de resolução

* **Force match**: Conciliar transações manualmente
* **Adjustment**: Registrar um ajuste compensatório
* **Write-off**: Encerrar a exceção com justificativa

## 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/descrição | 10%  | Alinhamento de referência/descrição (graduado 0–1 para regras FUZZY) |

### Faixas de confiança

| Faixa               | Intervalo de score | Comportamento do sistema       |
| ------------------- | ------------------ | ------------------------------ |
| **Auto-aprovado**   | ≥ 90               | Confirmado automaticamente     |
| **Precisa revisão** | 60–89              | Sinalizado para revisão manual |
| **Sem match**       | \< 60              | Tratado como exceção           |

<Tip>
  Os limites de confiança podem ser customizados por tenant para refletir diferentes tolerâncias a risco.
</Tip>

## Log de auditoria

***

Um **log de auditoria** é um registro imutável de todas as ações do sistema.
Ele fornece rastreabilidade completa para revisão operacional, auditorias e compliance regulatório.

### Eventos registrados

Entradas de auditoria são criadas para:

* Alterações em contextos, fontes e regras
* Ingestão e processamento de arquivos
* Confirmações e rejeições de matches
* Resolução de exceções e overrides

### Conteúdo da entrada de auditoria

| Campo           | Descrição                        |
| --------------- | -------------------------------- |
| `timestamp`     | Timestamp da ação (UTC)          |
| `user_id`       | Ator responsável pela ação       |
| `action`        | Ação realizada                   |
| `resource_type` | Tipo do recurso afetado          |
| `resource_id`   | Identificador do recurso afetado |
| `before_state`  | Estado antes da ação             |
| `after_state`   | Estado após a ação               |
| `notes`         | Justificativa, quando aplicável  |

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

## Próximos passos

***

<Card title="Arquitetura" icon="sitemap" href="/pt/matcher/matcher-architecture" horizontal>
  Veja como esses conceitos são implementados através dos bounded contexts.
</Card>

<Card title="Início rápido" icon="rocket" href="/pt/matcher/getting-started/matcher-quick-start" horizontal>
  Aplique esses conceitos em um fluxo guiado e prático.
</Card>