Matcher e Midaz

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

O Midaz registra os lançamentos. O Midaz contabiliza as transações no ledger normalmente.
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).
Você importa essa exportação para o Matcher como um lado de um contexto — uma fonte do tipo LEDGER.
Você importa os dados da contraparte — o extrato bancário ou o relatório do gateway — como o outro lado.
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.

{
  "name": "Midaz Cash Ledger",
  "type": "LEDGER",
  "side": "LEFT",
  "config": {}
}

Referência da API: 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 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

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:

{
  "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 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 a menor fatia relevante

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.

Mantenha a cadência de exportação alinhada com a conciliação

Se você concilia diariamente, exporte diariamente. Ajuste o cronograma de exportação à disponibilidade dos dados da contraparte (o extrato bancário).

Normalize antes do upload quando possível

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.

Leve as referências por meio de colunas de metadados

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.

Matcher e Midaz

Como eles se encaixam

Modelando o Midaz como uma fonte

Levando os dados do ledger para o Matcher

Mapeamento de campos customizado

Fundamentos compartilhados da plataforma

O que esta integração não é

Boas práticas

Próximos passos

Fontes externas

Mapeamento de campos

​Como eles se encaixam

​Modelando o Midaz como uma fonte

​Levando os dados do ledger para o Matcher

​Mapeamento de campos customizado

​Fundamentos compartilhados da plataforma

​O que esta integração não é

​Boas práticas

​Próximos passos

Fontes externas

Mapeamento de campos

Como eles se encaixam

Modelando o Midaz como uma fonte

Levando os dados do ledger para o Matcher

Mapeamento de campos customizado

Fundamentos compartilhados da plataforma

O que esta integração não é

Boas práticas

Próximos passos