Requisitos do sistema
Infraestrutura
| Componente | Mínimo | Recomendado | Propósito |
|---|---|---|---|
| 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.24+ (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: integração com Midaz
O Matcher pode opcionalmente se integrar com o Midaz Ledger para consultar transações do ledger diretamente. Esta integração é totalmente opcional—o Matcher funciona como um produto standalone conciliando quaisquer fontes de dados.
Quando usar a integração com Midaz
Use a integração com Midaz se:- Você está usando o Midaz como seu sistema de ledger
- Você quer conciliar transações do Midaz contra fontes externas
- Você quer sincronização automática de transações do Midaz
Quando o Midaz não é necessário
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
Requisitos de conexão
Para habilitar a integração com Midaz, certifique-se de que:- Uma instância do Midaz está em execução e acessível da rede do Matcher
- Acesso à API está configurado com permissões para consultar transações
- Autenticação compartilhada está habilitada via lib-auth (mesmo provedor de identidade)
Configuração
Configure a conexão com o Midaz através de variáveis de ambiente:Veja o guia de Integração com Midaz para instruções completas de configuração.
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 |
|---|---|
config:context:create | Criar contextos de conciliação |
config:context:read | Visualizar configuração de contexto |
config:rule:create | Criar e atualizar regras de match |
ingestion:import:create | Fazer upload de arquivos de transações |
matching:job:run | Executar jobs de matching |
exception:item:list | Visualizar exceções |
exception:item:resolve | Resolver exceções |
governance:report: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.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
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
XML (Extensible Markup Language)
Comum em integrações empresariais e bancárias. Requisitos:- Elemento raiz único
- Codificação UTF-8
- Estrutura de elementos consistente
Limites de tamanho de arquivo
| Limite | Padrão | Configurável via |
|---|---|---|
| Tamanho máximo do arquivo | 100 MB | HTTP_BODY_LIMIT_BYTES |
| 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 |
|---|---|---|
| 8080 | HTTP | Servidor de API (padrão) |
| 8443 | HTTPS | Servidor de API com TLS |
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 |
| API do Midaz | Consultas ao ledger | Opcional (apenas se usar Midaz) |
| JIRA / ServiceNow | Roteamento de exceções | Opcional |
| Webhooks customizados | Notificações de eventos | Opcional |
Configuração TLS
Para ambientes de produção, configure TLS: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)