Pré-requisitos

Antes do deploy do Matcher, garanta que seu ambiente atende aos requisitos descritos nesta página. Estes pré-requisitos definem a base para rodar a conciliação de forma confiável em ambientes de desenvolvimento e de produção.

Requisitos de sistema

Infraestrutura

Os valores abaixo são pontos de partida operacionais validados na plataforma, não mínimos aplicados pelo produto. Ajuste-os conforme seu volume de transações e sua necessidade de retenção.

Componente	Ponto de partida validado / orientação de escala	Finalidade
CPU	2 cores / 4+ cores	A lógica de correspondência e de pontuação usa muita CPU
Memória	2 GB / 4+ GB	Processamento em memória de lotes de transações
Armazenamento	10 GB / 50+ GB	Armazenamento persistente de transações e logs de auditoria

Dependências

A stack local do Compose é a base de dependências validada na plataforma. Ela fixa:

PostgreSQL 17: armazenamento primário de dados para contextos de conciliação, transações, correspondências e logs de auditoria.
Valkey 8: serviço compatível com Redis usado para cache, detecção de duplicados, travas distribuídas e controle de idempotência.
RabbitMQ 4.1.3: message broker para processamento assíncrono entre bounded contexts.

Runtime

As versões a seguir são a base de ferramentas validada na plataforma, não uma matriz de suporte do produto:

Go 1.26+ (obrigatório apenas ao compilar a partir do código-fonte)
Docker 24+ e Docker Compose 2.20+ para deploys em contêineres
Kubernetes 1.28+ para deploys de nível de produção com Helm

Opcional: conciliar dados do Midaz

O Matcher se combina com o Midaz Ledger, mas não existe conector ativo entre eles. O Matcher não tem MIDAZ_API_URL e não abre conexão com o Midaz. Conciliar dados do Midaz é totalmente opcional. O Matcher funciona como produto independente que concilia quaisquer fontes de dados.

Quando conciliar dados do Midaz

Concilie dados de ledger do Midaz se:

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

Quando o Midaz não está envolvido

O Matcher funciona de forma independente quando:

Ao conciliar entre sistemas externos (bancos, ERPs, processadores de pagamento)
Ao usar outro sistema de ledger
Ao importar dados de ledger por arquivos CSV/JSON/XML

Como funciona

O Matcher concilia dados do Midaz do mesmo jeito que ingere qualquer fonte (por importação, não por consulta ativa):

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

Veja o guia Matcher e Midaz para o fluxo completo.

Autenticação

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

Fluxo de autenticação

O cliente obtém um JWT do provedor de identidade
O cliente envia o token no header Authorization: Bearer ***.
O Matcher valida o token pela lib-auth
As claims do token fornecem a identidade do tenant e as permissões

Permissões obrigatórias

Permissões refinadas controlam o acesso aos recursos do Matcher:

Permissão	Descrição
`contexts:create`	Criar contextos de conciliação
`contexts:read`	Ver a configuração do contexto
`rules:create`	Criar e atualizar regras de correspondência
`imports:create`	Enviar arquivos de transações
`match-runs:run`	Executar jobs de correspondência
`exceptions:read`	Ver exceções
`exceptions:resolve`	Resolver exceções
`reports:read`	Acessar relatórios e visões de auditoria

Modo single-tenant

MULTI_TENANT_ENABLED controla esse modo. O padrão dele é false, o que faz o Matcher usar o tenant padrão abaixo. O estado de autenticação ou a ausência da claim de tenant no JWT não muda o Matcher para o modo single-tenant.

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

Formatos genéricos de importação

Os importadores genéricos do Matcher aceitam CSV, JSON e XML. Os parsers embutidos também aceitam CAMT.053, CNAB 240/400, OFX, vários formatos de adquirente e formatos de recebíveis. Veja o catálogo de formatos de importação para o inventário completo. Cada formato genérico tem requisitos estruturais específicos para a ingestão dar certo.

CSV (valores separados por vírgula)

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

O arquivo deve ter uma linha de cabeçalho
Codificação UTF-8
Delimitador vírgula (configurável)
Campos entre aspas para valores que contêm 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 (notação de objetos javascript)

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

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

Exemplo:

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

XML (linguagem de marcação extensível)

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

Um único elemento raiz
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` no bootstrap ou Systemplane em tempo de execução (1 MiB a 8 GiB)
Corpo de requisição máximo 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 estar acessível para os clientes:

Porta	Protocolo	Finalidade
4018	HTTP/HTTPS	Servidor da API (padrão `:4018`; serve HTTPS quando o TLS está configurado)

Acesso de saída

O Matcher deve conseguir alcançar os serviços a seguir:

Serviço	Finalidade	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 worker de exportação está habilitado (habilitado por padrão)
Serviço de autenticação	Validação de token	Se a autenticação estiver habilitada
JIRA	Roteamento de exceções	Opcional
Webhooks customizados	Notificações de eventos	Opcional

Configuração de TLS

Em ambientes de produção, configure o TLS:

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

Checklist do ambiente

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

A infraestrutura está pronta: PostgreSQL, Redis e RabbitMQ estão no ar e acessíveis. O armazenamento de objetos compatível com S3 também está pronto se você habilitar o worker de exportação (o padrão)
A autenticação está pronta: o serviço de autenticação está disponível, ou você desligou a autenticação de forma explícita
O acesso de rede funciona: a conectividade de entrada e de saída obrigatória está no lugar
As credenciais estão disponíveis: você tem as credenciais do banco de dados e os tokens da API
Os dados de exemplo estão prontos: você tem arquivos de transações para o primeiro teste (veja Início rápido)

Visão geral

Guias

Matcher UI

Servidor MCP

Operações

Pré-requisitos

Requisitos de 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 obrigatórias

Modo single-tenant

Formatos genéricos de importação

CSV (valores separados por vírgula)

JSON (notação de objetos javascript)

XML (linguagem de marcação extensível)

Limites de tamanho de arquivo

Requisitos de rede

Acesso de entrada

Acesso de saída

Configuração de TLS

Checklist do ambiente

Próximos passos

Instalação

Início rápido

​Requisitos de 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 obrigatórias

​Modo single-tenant

​Formatos genéricos de importação

​CSV (valores separados por vírgula)

​JSON (notação de objetos javascript)

​XML (linguagem de marcação extensível)

​Limites de tamanho de arquivo

​Requisitos de rede

​Acesso de entrada

​Acesso de saída

​Configuração de TLS

​Checklist do ambiente

​Próximos passos

Instalação

Início rápido

Requisitos de 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 obrigatórias

Modo single-tenant

Formatos genéricos de importação

CSV (valores separados por vírgula)

JSON (notação de objetos javascript)

XML (linguagem de marcação extensível)

Limites de tamanho de arquivo

Requisitos de rede

Acesso de entrada

Acesso de saída

Configuração de TLS

Checklist do ambiente

Próximos passos