> ## 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
> Veja como o Matcher trabalha junto do Midaz Ledger: dois serviços independentes que compartilham dados por exportações e importações, não por uma conexão de API ativa.
**Não existe conector direto de Matcher para Midaz.** O Matcher é um serviço de conciliação independente. Ele não abre conexão ativa com o Midaz e não tem configuração específica de Midaz. Esta página explica como os dois produtos trabalham juntos no plano conceitual.
O Matcher e o [Midaz](/pt/products/midaz/what-is-midaz) são serviços Lerian separados, 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 bate, o que não bate e por quê.
Eles são **complementares, não acoplados**. Você tira valor de Midaz mais Matcher ao conciliar dados do ledger *contra* um conjunto de dados externo (um extrato bancário, um relatório de liquidação de gateway). Os dados vão de um para o outro por **exportação e importação**, não por um link em tempo real.
## Como eles se encaixam
***
Um fluxo de conciliação típico da Lerian:
1. **O Midaz registra os lançamentos.** O Midaz contabiliza as transações no ledger como sempre.
2. **Você exporta os dados do ledger** do período que quer conciliar (por exemplo, os lançamentos da conta 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 de gateway) como o outro lado.
5. **O Matcher faz a correspondência dos dois lados** usando suas regras de correspondência e apresenta 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 com o Midaz direto. Ele trabalha com os dados exportados que você fornece.
## Modelar o Midaz como fonte
***
Dentro de um contexto do Matcher, os dados de ledger vindos do Midaz são representados por uma fonte do tipo `LEDGER`. `LEDGER` é a categoria do Matcher para dados de "ledger interno / sistema contábil". Não é um driver de Midaz.
```json theme={null}
{
"name": "Midaz Cash Ledger",
"type": "LEDGER",
"side": "LEFT",
"config": {}
}
```
Referência da API: [Criar fonte](/pt/reference/products/matcher/create-source)
O outro lado do contexto é o conjunto de dados externo contra o qual você concilia, em geral 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 sob medida |
| `FETCHER` | Extração do motor de descoberta |
## Levar os dados do ledger para o Matcher
***
O Matcher ingere os dados que você exporta do Midaz do mesmo jeito que ingere qualquer outra fonte. Não existe transporte específico de Midaz.
* **Upload de arquivo.** Exporte os lançamentos do ledger (CSV/JSON) e envie o arquivo para a fonte. Este é o caminho mais comum.
* **Trilho de consulta do motor de descoberta.** Para fontes vinculadas ao trilho `query`, o Matcher puxa linhas por uma conexão do motor de descoberta, em vez de um arquivo. Esse é um trilho de ingestão genérico, não um conector de Midaz.
De um jeito ou de outro, você define depois um [mapa de campo](/pt/products/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: [Enviar arquivo de transações](/pt/reference/products/matcher/upload-transaction-file)
Mapeamento de campos customizado
A maioria das colunas do ledger mapeia direto. As buscas do mapa de campo são **planas**. Um valor de mapeamento deve nomear uma coluna que existe no nível mais alto da linha exportada, então um valor que fica dentro dos metadados da transação deve ser exportado como coluna plana própria antes de o Matcher conseguir fazer a correspondência por ele.
Por exemplo, o `endToEndId` do Pix brasileiro fica guardado nos metadados da transação no Midaz. Para conciliar por ele, exporte-o como coluna plana (aqui, `endToEndId`) e mapeie `external_id` para essa coluna. `external_id` é a referência que o motor de correspondência compara entre as fontes, então os dois lados do contexto devem mapeá-la para um valor que eles compartilham (a chave `description` serve apenas para mostrar e nunca alimenta a correspondência):
```json theme={null}
{
"mapping": {
"external_id": "endToEndId",
"amount": "amount",
"currency": "asset_code",
"date": "created_at"
}
}
```
Cada mapa de campo deve declarar todas as quatro chaves canônicas obrigatórias (`external_id`, `amount`, `currency`, `date`) de forma explícita. Não acontece mapeamento automático. Veja [Mapeamento de campos](/pt/products/matcher/configuration/matcher-field-mapping) para o vocabulário canônico completo.
## Bases compartilhadas da plataforma
***
Embora não exista integração ativa, o Matcher é feito para a mesma plataforma do Midaz e espelha vários padrões dele:
* **Autenticação.** O Matcher usa a stack de autenticação compartilhada da Lerian, então valem o mesmo provedor de identidade e os mesmos tokens usados em toda a plataforma.
* **Multi-tenancy.** O Matcher segue um modelo de isolamento de pool por tenant (um banco de dados dedicado por tenant) alinhado ao resto da 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* é
***
* O Matcher **não** tem a configuração `MIDAZ_BASE_URL` nem `MIDAZ_GRPC_ADDRESS`.
* **Não** existe modo de sincronização em tempo real, e **não** existe `account_filter` para uma fonte de Midaz.
* O Matcher **não** se inscreve nos eventos do Midaz nem abre conexão gRPC/HTTP com o Midaz.
Conciliar dados do Midaz quer dizer 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 todo dia, exporte todo dia. Alinhe o agendamento da exportação à disponibilidade dos dados da contraparte (extrato bancário).
Os mapas de campo renomeiam colunas, mas não transformam valores. Gere exportações cujos valores, datas e códigos de moeda já estejam no formato 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 se apoiar nelas e elevar as taxas de correspondência.
## Próximos passos
***
Conecte o lado bancário ou de gateway da conciliação.
Mapeie as colunas exportadas do ledger para os campos canônicos do Matcher.