Requisitos del sistema
Infraestructura
| Componente | Mínimo | Recomendado | Propósito |
|---|---|---|---|
| CPU | 2 núcleos | 4+ núcleos | La lógica de conciliación y puntuación es intensiva en CPU |
| Memoria | 2 GB | 4+ GB | Procesamiento en memoria de lotes de transacciones |
| Almacenamiento | 10 GB | 50+ GB | Almacenamiento persistente para transacciones y logs de auditoría |
Dependencias
Matcher depende de los siguientes servicios:- PostgreSQL 15+: Almacén de datos principal para contextos de conciliación, transacciones, conciliaciones y logs de auditoría.
- Redis 7+: Usado para caché, detección de duplicados, bloqueo distribuido y control de idempotencia.
- RabbitMQ 3.12+: Broker de mensajes para procesamiento asíncrono entre contextos acotados.
Entorno de ejecución
Matcher permite los siguientes entornos de ejecución y herramientas:- Go 1.24+ (solo requerido al compilar desde el código fuente)
- Docker 24+ y Docker Compose 2.20+ para despliegues containerizados
- Kubernetes 1.28+ para despliegues de nivel de producción usando Helm
Opcional: integración con Midaz
Matcher puede integrarse opcionalmente con Midaz Ledger para consultar transacciones del libro contable directamente. Esta integración es completamente opcional—Matcher funciona como un producto independiente que concilia cualquier fuente de datos.
Cuándo usar la integración con Midaz
Usa la integración con Midaz si:- Estás usando Midaz como tu sistema de libro contable
- Quieres conciliar transacciones de Midaz contra fuentes externas
- Quieres sincronización automática de transacciones desde Midaz
Cuándo no se necesita Midaz
Matcher funciona independientemente cuando:- Concilias entre sistemas externos (bancos, ERPs, procesadores de pago)
- Usas un sistema de libro contable diferente
- Importas datos del libro contable mediante archivos CSV/JSON/XML
Requisitos de conexión
Para habilitar la integración con Midaz, asegúrate de que:- Una instancia de Midaz esté ejecutándose y sea accesible desde la red de Matcher
- El acceso a la API esté configurado con permisos para consultar transacciones
- La autenticación compartida esté habilitada mediante lib-auth (mismo proveedor de identidad)
Configuración
Configura la conexión con Midaz a través de variables de entorno:Consulta la guía de Integración con Midaz para instrucciones completas de configuración.
Autenticación
Matcher usa lib-auth para autenticación y autorización, consistente con el resto del ecosistema Lerian.
Flujo de autenticación
- El cliente obtiene un JWT del proveedor de identidad
- El token se envía en el encabezado
Authorization: Bearer <token> - Matcher valida el token mediante lib-auth
- La identidad del tenant y los permisos se extraen de los claims del token
Permisos requeridos
El acceso a las funcionalidades de Matcher se controla a través de permisos detallados:| Permiso | Descripción |
|---|---|
config:context:create | Crear contextos de conciliación |
config:context:read | Ver configuración de contexto |
config:rule:create | Crear y actualizar reglas de conciliación |
ingestion:import:create | Subir archivos de transacciones |
matching:job:run | Ejecutar trabajos de conciliación |
exception:item:list | Ver excepciones |
exception:item:resolve | Resolver excepciones |
governance:report:read | Acceder a informes y vistas de auditoría |
Modo de tenant único
Si la autenticación está deshabilitada o no hay identificador de tenant presente en el JWT, Matcher se ejecuta en modo de tenant único usando un tenant por defecto.Formatos de archivo soportados
Matcher acepta datos de transacciones en los siguientes formatos. Cada formato tiene requisitos estructurales específicos para una ingesta exitosa.
CSV (valores separados por comas)
Comúnmente usado para extractos bancarios y exportaciones. Requisitos:- Se requiere fila de encabezado
- Codificación UTF-8
- Delimitador de coma (configurable)
- Campos entre comillas para valores que contengan delimitadores
JSON (notación de objetos JavaScript)
Recomendado para integraciones basadas en API. Requisitos:- Array JSON válido de objetos de transacción
- Codificación UTF-8
- Nombres de campos consistentes entre registros
XML (lenguaje de marcado extensible)
Común en integraciones empresariales y bancarias. Requisitos:- Elemento raíz único
- Codificación UTF-8
- Estructura de elementos consistente
Límites de tamaño de archivo
| Límite | Por defecto | Configurable mediante |
|---|---|---|
| Tamaño máximo de archivo | 100 MB | HTTP_BODY_LIMIT_BYTES |
| Máximo de transacciones por archivo | 100,000 | Configuración a nivel de contexto |
Requisitos de red
Acceso entrante
Matcher expone una API REST que debe ser accesible por los clientes:| Puerto | Protocolo | Propósito |
|---|---|---|
| 8080 | HTTP | Servidor API (por defecto) |
| 8443 | HTTPS | Servidor API con TLS |
Acceso saliente
Matcher debe poder alcanzar los siguientes servicios:| Servicio | Propósito | Requerido |
|---|---|---|
| PostgreSQL | Persistencia de datos | Sí |
| Redis | Caché y coordinación | Sí |
| RabbitMQ | Mensajería | Sí |
| Servicio de autenticación | Validación de tokens | Si la autenticación está habilitada |
| API de Midaz | Consultas al libro contable | Opcional (solo si usas Midaz) |
| JIRA / ServiceNow | Enrutamiento de excepciones | Opcional |
| Webhooks personalizados | Notificaciones de eventos | Opcional |
Configuración de TLS
Para entornos de producción, configura TLS:Lista de verificación del entorno
Antes de proceder con la instalación, confirma que:
- La infraestructura está lista: PostgreSQL, Redis y RabbitMQ están ejecutándose y accesibles
- La autenticación está configurada: El servicio de autenticación está disponible, o la autenticación está explícitamente deshabilitada
- El acceso de red está validado: La conectividad entrante y saliente requerida está en su lugar
- Las credenciales están disponibles: Las credenciales de base de datos y tokens de API están configurados
- Los datos de muestra están preparados: Los archivos de transacciones están listos para pruebas (ver Inicio rápido)