Pré-requisitos

Antes de implantar o Matcher, certifique-se de que seu ambiente atende aos requisitos descritos nesta página. Estes pré-requisitos definem a base para executar conciliações de forma confiável em ambientes de desenvolvimento e produção.

Requisitos do sistema

Infraestrutura

Os valores abaixo são pontos de partida operacionais validados para a plataforma, não requisitos mínimos impostos pelo produto. Ajuste-os conforme seu volume de transações e suas necessidades de retenção.

Componente	Ponto de partida validado / orientação de escala	Finalidade
CPU	2 cores / 4+ cores	A lógica de matching e scoring é intensiva em CPU
Memória	2 GB / 4+ GB	Processamento em memória de lotes de transações
Armazenamento	10 GB / 50+ GB	Armazenamento persistente para transações e logs de auditoria

Dependências

A configuração local do Compose é a referência de dependências validada para a plataforma. Ela fixa:

PostgreSQL 17: Armazenamento principal para contextos de conciliação, transações, matches e logs de auditoria.
Valkey 8: Serviço compatível com Redis usado para cache, detecção de duplicatas, bloqueio distribuído e controle de idempotência.
RabbitMQ 4.1.3: Serviço de mensageria para processamento assíncrono entre contextos delimitados.

Ambiente de execução

As versões abaixo são a referência de ferramentas validada para a plataforma, não uma matriz de suporte do produto:

Go 1.26+ (necessário apenas ao compilar a partir do código-fonte)
Docker 24+ e Docker Compose 2.20+ para implantações containerizadas
Kubernetes 1.28+ para implantações em produção usando Helm

Opcional: conciliar dados do Midaz

O Matcher combina naturalmente com o Midaz Ledger, mas não há conector ao vivo entre eles — o Matcher não tem MIDAZ_API_URL e não abre nenhuma conexão com o Midaz. Conciliar dados do Midaz é totalmente opcional; o Matcher funciona como um produto standalone conciliando quaisquer fontes de dados.

Quando conciliar dados do Midaz

Concilie dados do ledger do Midaz se:

Você usa o Midaz como seu sistema de ledger
Você quer conciliar os lançamentos do Midaz contra fontes externas (extratos bancários, relatórios de gateway)

Quando o Midaz não está envolvido

O Matcher funciona independentemente quando:

Conciliando entre sistemas externos (bancos, ERPs, processadores de pagamento)
Usando um sistema de ledger diferente
Importando dados do ledger via arquivos CSV/JSON/XML

Como funciona

O Matcher concilia dados do Midaz da mesma forma que ingere qualquer fonte — por importação, não por consulta ao vivo:

Exporte os dados do ledger do período que você quer conciliar.
Importe essa exportação em um contexto do Matcher como uma fonte do tipo LEDGER.
Importe os dados da contraparte (extrato bancário ou relatório de gateway) como o outro lado.
O Matcher concilia os dois lados usando suas regras de match.

Veja o guia Matcher e Midaz para o fluxo completo.

Autenticação

O Matcher usa lib-auth para autenticação e autorização, consistente com o resto do ecossistema Lerian.

Fluxo de autenticação

O cliente obtém um JWT do provedor de identidade
O token é enviado no cabeçalho Authorization: Bearer $TOKEN
O Matcher valida o token via lib-auth
A identidade do tenant e permissões são extraídas das claims do token

Permissões necessárias

O acesso às funcionalidades do Matcher é controlado através de permissões granulares:

Permissão	Descrição
`contexts:create`	Criar contextos de conciliação
`contexts:read`	Visualizar configuração de contexto
`rules:create`	Criar e atualizar regras de match
`imports:create`	Fazer upload de arquivos de transações
`match-runs:run`	Executar jobs de matching
`exceptions:read`	Visualizar exceções
`exceptions:resolve`	Resolver exceções
`reports:read`	Acessar relatórios e views de auditoria

Modo de tenant único

MULTI_TENANT_ENABLED controla esse modo. O valor padrão é false, o que faz o Matcher usar o tenant padrão abaixo. O estado da autenticação ou a ausência de um identificador de tenant no JWT não altera o Matcher para o modo de tenant único.

# Default tenant configuration (single-tenant mode)
DEFAULT_TENANT_ID=11111111-1111-1111-1111-111111111111
DEFAULT_TENANT_SLUG=default

Formatos de importação genéricos

Os importadores genéricos do Matcher aceitam CSV, JSON e XML. Os analisadores integrados também aceitam CAMT.053, CNAB 240/400, OFX, diversos formatos de adquirentes e formatos de recebíveis. Veja o catálogo de formatos de importação para conferir o inventário completo. Cada formato genérico tem requisitos estruturais específicos para uma ingestão bem-sucedida.

CSV (valores separados por vírgula)

Comumente usado para extratos bancários e exportações. Requisitos:

Linha de cabeçalho é obrigatória
Codificação UTF-8
Delimitador vírgula (configurável)
Campos entre aspas para valores contendo delimitadores

Exemplo:

transaction_id,amount,currency,date,reference
TXN-001,1000.00,USD,2024-01-15,Invoice payment
TXN-002,-250.50,USD,2024-01-16,Refund

JSON (JavaScript Object Notation)

Recomendado para integrações baseadas em API. Requisitos:

Array JSON válido de objetos de transação
Codificação UTF-8
Nomes de campos consistentes entre registros

Exemplo:

[
  {
    "transaction_id": "TXN-001",
    "amount": 1000.0,
    "currency": "USD",
    "date": "2024-01-15",
    "reference": "Invoice payment"
  }
]

XML (Extensible Markup Language)

Comum em integrações empresariais e bancárias. Requisitos:

Elemento raiz único
Codificação UTF-8
Estrutura de elementos consistente

Exemplo:

<?xml version="1.0" encoding="UTF-8"?>
<transactions>
 <transaction>
 <transaction_id>TXN-001</transaction_id>
 <amount>1000.00</amount>
 <currency>USD</currency>
 <date>2024-01-15</date>
 <reference>Invoice payment</reference>
 </transaction>
</transactions>

Limites de tamanho de arquivo

Limite	Padrão	Configuração
Tamanho máximo do arquivo enviado	1 GiB	`INGESTION_MAX_UPLOAD_BYTES` na inicialização ou Systemplane em tempo de execução (de 1 MiB a 8 GiB)
Corpo máximo de requisição em buffer	100 MiB	`HTTP_BODY_LIMIT_BYTES` (requisições que não são de upload)

Requisitos de rede

Acesso de entrada

O Matcher expõe uma API REST que deve ser acessível pelos clientes:

Porta	Protocolo	Propósito
4018	HTTP/HTTPS	Servidor de API (padrão `:4018`; serve HTTPS quando o TLS está configurado)

Acesso de saída

O Matcher deve ser capaz de alcançar os seguintes serviços:

Serviço	Propósito	Obrigatório
PostgreSQL	Persistência de dados	Sim
Redis	Cache e coordenação	Sim
RabbitMQ	Mensageria	Sim
Armazenamento de objetos compatível com S3	Exportações e arquivamento	Quando o processo de exportação está habilitado (habilitado por padrão)
Serviço de auth	Validação de token	Se autenticação estiver habilitada
JIRA	Roteamento de exceções	Opcional
Webhooks customizados	Notificações de eventos	Opcional

Configuração TLS

Para ambientes de produção, configure TLS:

SERVER_TLS_CERT_FILE=/path/to/cert.pem
SERVER_TLS_KEY_FILE=/path/to/key.pem

Checklist do ambiente

Antes de prosseguir com a instalação, confirme que:

Infraestrutura está pronta: PostgreSQL, Redis e RabbitMQ estão em execução e acessíveis; o armazenamento de objetos compatível com S3 também está pronto quando o processo de exportação está habilitado (o padrão)
Autenticação está configurada: Serviço de auth está disponível, ou auth está explicitamente desabilitada
Acesso de rede está validado: Conectividade de entrada e saída necessária está em vigor
Credenciais estão disponíveis: Credenciais de banco de dados e tokens de API estão configurados
Dados de exemplo estão preparados: Arquivos de transações estão prontos para teste (veja Início Rápido)

Visão geral

Guias

Matcher UI

Servidor MCP

Operações

Pré-requisitos

Requisitos do sistema

Infraestrutura

Dependências

Ambiente de execução

Opcional: conciliar dados do Midaz

Quando conciliar dados do Midaz

Quando o Midaz não está envolvido

Como funciona

Autenticação

Fluxo de autenticação

Permissões necessárias

Modo de tenant único

Formatos de importação genéricos

CSV (valores separados por vírgula)

JSON (JavaScript Object Notation)

XML (Extensible Markup Language)

Limites de tamanho de arquivo

Requisitos de rede

Acesso de entrada

Acesso de saída

Configuração TLS

Checklist do ambiente

Próximos passos

Instalação

Início rápido

​Requisitos do sistema

​Infraestrutura

​Dependências

​Ambiente de execução

​Opcional: conciliar dados do Midaz

​Quando conciliar dados do Midaz

​Quando o Midaz não está envolvido

​Como funciona

​Autenticação

​Fluxo de autenticação

​Permissões necessárias

​Modo de tenant único

​Formatos de importação genéricos

​CSV (valores separados por vírgula)

​JSON (JavaScript Object Notation)

​XML (Extensible Markup Language)

​Limites de tamanho de arquivo

​Requisitos de rede

​Acesso de entrada

​Acesso de saída

​Configuração TLS

​Checklist do ambiente

​Próximos passos

Instalação

Início rápido

Requisitos do sistema

Infraestrutura

Dependências

Ambiente de execução

Opcional: conciliar dados do Midaz

Quando conciliar dados do Midaz

Quando o Midaz não está envolvido

Como funciona

Autenticação

Fluxo de autenticação

Permissões necessárias

Modo de tenant único

Formatos de importação genéricos

CSV (valores separados por vírgula)

JSON (JavaScript Object Notation)

XML (Extensible Markup Language)

Limites de tamanho de arquivo

Requisitos de rede

Acesso de entrada

Acesso de saída

Configuração TLS

Checklist do ambiente

Próximos passos