> ## 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.
# Matcher e Midaz
> Como o Matcher se encaixa ao lado do Midaz Ledger em um stack da Lerian: dois serviços complementares e independentes que compartilham dados por meio de exportações e importações, em vez de uma conexão em tempo real.
**Não existe um conector direto de Matcher para Midaz.** O Matcher é um serviço de conciliação independente. Ele não abre uma conexão em tempo real com o Midaz e não possui configuração específica do Midaz. Esta página explica como os dois produtos funcionam juntos de forma conceitual.
O Matcher e o [Midaz](/pt/midaz) são serviços separados da Lerian com funções distintas:
* **Midaz** é o ledger — o sistema de registro de saldos e lançamentos.
* **Matcher** é o motor de conciliação — ele compara dois conjuntos de dados independentes e informa o que concorda, o que não concorda e por quê.
Eles são **complementares, não acoplados**. Você obtém valor do Midaz-mais-Matcher ao conciliar os dados do ledger *contra* um conjunto de dados externo (um extrato bancário, um relatório de liquidação de um gateway), que é exatamente o problema que o Matcher existe para resolver. Os dados se movem entre eles por meio de **exportação e importação**, não por meio de um link em tempo real.
## Como eles se encaixam
***
Um fluxo típico de conciliação na Lerian:
1. **O Midaz registra os lançamentos.** O Midaz contabiliza as transações no ledger normalmente.
2. **Você exporta os dados do ledger** do período que deseja conciliar (por exemplo, os lançamentos de uma conta de caixa de um dia).
3. **Você importa essa exportação para o Matcher** como um lado de um contexto — uma fonte do tipo `LEDGER`.
4. **Você importa os dados da contraparte** — o extrato bancário ou o relatório do gateway — como o outro lado.
5. **O Matcher combina os dois lados** usando suas regras de correspondência e expõe as exceções para revisão.
O Midaz é a origem de um conjunto de dados; o banco ou o gateway é a origem do outro. O Matcher nunca fala diretamente com o Midaz — ele trabalha a partir dos dados exportados que você fornece.
## Modelando o Midaz como uma fonte
***
Dentro de um contexto do Matcher, os dados do ledger do Midaz são representados por uma fonte do tipo `LEDGER`. `LEDGER` é simplesmente a categoria do Matcher para dados de "ledger interno / sistema contábil"; não é um driver do Midaz.
```json theme={null}
{
"name": "Midaz Cash Ledger",
"type": "LEDGER",
"side": "LEFT",
"config": {}
}
```
Referência da API: [Create source](/pt/reference/matcher/create-source)
O outro lado do contexto é o conjunto de dados externo contra o qual você está conciliando — geralmente uma fonte `BANK` ou `GATEWAY` no `side` oposto.
Tipos de fonte disponíveis no Matcher:
| Tipo | Significado |
| --------- | --------------------------------------------------------------------- |
| `LEDGER` | Ledger interno / sistema contábil (por exemplo, exportações do Midaz) |
| `BANK` | Feed de extrato bancário |
| `GATEWAY` | Relatório de gateway de pagamento |
| `CUSTOM` | Qualquer outro feed personalizado |
| `FETCHER` | Extração do motor de descoberta |
## Levando os dados do ledger para o Matcher
***
O Matcher ingere os dados que você exporta do Midaz da mesma forma que ingere qualquer outra fonte — não há transporte específico do Midaz.
* **Upload de arquivo.** Exporte os lançamentos do ledger (CSV/JSON) e envie o arquivo para a fonte. Este é o caminho mais comum.
* **Rail de consulta do motor de descoberta.** Para fontes vinculadas ao rail `query`, o Matcher extrai as linhas por meio de uma conexão do motor de descoberta em vez de um arquivo. Este é um rail de ingestão genérico, não um conector do Midaz.
De qualquer forma, você então define um [mapeamento de campos](/pt/matcher/configuration/matcher-field-mapping) que renomeia as colunas exportadas para os campos canônicos do Matcher (`external_id`, `amount`, `currency`, `date`, e os opcionais `description`, `fee_amount`, `fee_currency`).
Referência da API: [Upload transaction file](/pt/reference/matcher/upload-transaction-file)
### Mapeamento de campos customizado
A maioria das colunas do ledger mapeia diretamente, mas alguns valores que você precisa usar para correspondência ficam **dentro dos metadados da transação**, e não como campos de nível superior. Referencie-os no mapeamento de campos com notação de ponto — aponte uma chave canônica para o caminho aninhado.
Por exemplo, o `endToEndId` do Pix (Brasil) fica armazenado nos metadados da transação no Midaz. Para reconciliar por ele, mapeie uma chave canônica (aqui, `description`) para o caminho nos metadados:
```json theme={null}
{
"mapping": {
"external_id": "id",
"amount": "amount",
"currency": "asset_code",
"date": "created_at",
"description": "metadata.endToEndId"
}
}
```
Quando o Midaz está integrado, os campos padrão são mapeados automaticamente; apenas overrides de metadados como este precisam ser declarados explicitamente. Veja [Mapeamento de campos](/pt/matcher/configuration/matcher-field-mapping) para o vocabulário canônico completo.
## Fundamentos compartilhados da plataforma
***
Embora não exista uma integração em tempo real, o Matcher é construído para a mesma plataforma que o Midaz e espelha vários de seus padrões:
* **Autenticação.** O Matcher usa o stack de autenticação compartilhado da Lerian, portanto o mesmo provedor de identidade e os mesmos tokens usados em toda a plataforma se aplicam.
* **Multi-tenancy.** O Matcher segue um modelo de isolamento pool-por-tenant (um banco de dados dedicado por tenant) em linha com o restante do stack, mantendo os dados de cada tenant separados.
Esses são pontos em comum no nível da plataforma, não um canal de dados de Matcher para Midaz.
## O que esta integração *não* é
***
Para evitar confusão com rascunhos anteriores desta página:
* O Matcher **não** possui configuração `MIDAZ_BASE_URL` ou `MIDAZ_GRPC_ADDRESS`.
* **Não** há modo de sincronização em tempo real nem `account_filter` para uma fonte Midaz.
* O Matcher **não** se inscreve em eventos do Midaz nem abre uma conexão gRPC/HTTP com o Midaz.
Conciliar dados do Midaz significa exportá-los e importá-los para o Matcher como qualquer outra fonte.
## Boas práticas
***
Exporte apenas as contas do ledger e o período que você realmente precisa conciliar. Exportações menores e direcionadas mantêm os contextos rápidos e a correspondência precisa.
Se você concilia diariamente, exporte diariamente. Ajuste o cronograma de exportação à disponibilidade dos dados da contraparte (o extrato bancário).
Os mapeamentos de campos renomeiam colunas, mas não transformam valores. Produza exportações cujos valores, datas e códigos de moeda já estejam nos formatos que suas regras de correspondência esperam.
Inclua referências estáveis (números de fatura, IDs externos) como colunas na exportação para que as regras de correspondência possam usá-las como chave e obter taxas de correspondência mais altas.
## Próximos passos
***
Conecte o lado do banco ou do gateway da conciliação.
Mapeie as colunas do ledger exportadas para os campos canônicos do Matcher.