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

Componente	Mínimo / recomendado	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

O Matcher depende dos seguintes serviços:

PostgreSQL 15+: Armazenamento principal para contextos de conciliação, transações, matches e logs de auditoria.
Redis 7+: Usado para cache, detecção de duplicatas, locking distribuído e controle de idempotência.
RabbitMQ 3.12+: Message broker para processamento assíncrono entre bounded contexts.

Runtime

O Matcher permite os seguintes runtimes e ferramentas:

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 header 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 single-tenant

Se a autenticação estiver desabilitada ou nenhum identificador de tenant estiver presente no JWT, o Matcher executa em modo single-tenant usando um tenant padrão.

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

Formatos de arquivo suportados

O Matcher aceita dados de transações nos seguintes formatos. Cada formato tem requisitos estruturais específicos para 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	Configurável via
Tamanho máximo do arquivo enviado	1 GiB	`INGESTION_MAX_UPLOAD_BYTES` (rota de upload em streaming)
Corpo máximo de requisição em buffer	100 MiB	`HTTP_BODY_LIMIT_BYTES` (requisições que não são de upload)
Máximo de transações por arquivo	100.000	Configuração no nível do contexto

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
Serviço de auth	Validação de token	Se autenticação estiver habilitada
JIRA / ServiceNow	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
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

Runtime

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 single-tenant

Formatos de arquivo suportados

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

​Runtime

​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 single-tenant

​Formatos de arquivo suportados

​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

Runtime

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 single-tenant

Formatos de arquivo suportados

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