Prerrequisitos

Antes de desplegar Matcher, asegúrate de que tu entorno cumpla con los requisitos descritos en esta página. Estos prerrequisitos definen la línea base para ejecutar conciliaciones de forma confiable en entornos de desarrollo y producción.

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.26+ (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: conciliar datos de Midaz

Matcher combina de forma natural con Midaz Ledger, pero no hay un conector en vivo entre ellos: Matcher no tiene MIDAZ_API_URL y no abre ninguna conexión con Midaz. Conciliar datos de Midaz es completamente opcional; Matcher funciona como un producto independiente que concilia cualquier fuente de datos.

Cuándo conciliar datos de Midaz

Concilia datos del libro contable de Midaz si:

Usas Midaz como tu sistema de libro contable
Quieres conciliar los asientos de Midaz contra fuentes externas (extractos bancarios, reportes de gateway)

Cuándo no interviene 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

Cómo funciona

Matcher concilia datos de Midaz igual que ingiere cualquier fuente — por importación, no por consulta en vivo:

Exporta los datos del libro contable del período que quieres conciliar.
Importa esa exportación en un contexto de Matcher como una fuente de tipo LEDGER.
Importa los datos de la contraparte (extracto bancario o reporte de gateway) como el otro lado.
Matcher concilia ambos lados usando tus reglas de match.

Consulta la guía Matcher y Midaz para el flujo completo.

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
`contexts:create`	Crear contextos de conciliación
`contexts:read`	Ver configuración de contexto
`rules:create`	Crear y actualizar reglas de conciliación
`imports:create`	Subir archivos de transacciones
`match-runs:run`	Ejecutar trabajos de conciliación
`exceptions:read`	Ver excepciones
`exceptions:resolve`	Resolver excepciones
`reports: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.

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

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

Ejemplo:

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 (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

Ejemplo:

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

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

Ejemplo:

<?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>

Límites de tamaño de archivo

Límite	Por defecto	Configurable mediante
Tamaño máximo de archivo subido	1 GiB	`INGESTION_MAX_UPLOAD_BYTES` (ruta de subida en streaming)
Cuerpo máximo de solicitud en búfer	100 MiB	`HTTP_BODY_LIMIT_BYTES` (solicitudes que no son de subida)
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
4018	HTTP/HTTPS	Servidor API (por defecto `:4018`; sirve HTTPS cuando TLS está configurado)

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
JIRA / ServiceNow	Enrutamiento de excepciones	Opcional
Webhooks personalizados	Notificaciones de eventos	Opcional

Configuración de TLS

Para entornos de producción, configura TLS:

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

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)

Prerrequisitos

Requisitos del sistema

Infraestructura

Dependencias

Entorno de ejecución

Opcional: conciliar datos de Midaz

Cuándo conciliar datos de Midaz

Cuándo no interviene Midaz

Cómo funciona

Autenticación

Flujo de autenticación

Permisos requeridos

Modo de tenant único

Formatos de archivo soportados

CSV (valores separados por comas)

JSON (notación de objetos JavaScript)

XML (lenguaje de marcado extensible)

Límites de tamaño de archivo

Requisitos de red

Acceso entrante

Acceso saliente

Configuración de TLS

Lista de verificación del entorno

Próximos pasos

Instalación

Inicio rápido

​Requisitos del sistema

​Infraestructura

​Dependencias

​Entorno de ejecución

​Opcional: conciliar datos de Midaz

​Cuándo conciliar datos de Midaz

​Cuándo no interviene Midaz

​Cómo funciona

​Autenticación

​Flujo de autenticación

​Permisos requeridos

​Modo de tenant único

​Formatos de archivo soportados

​CSV (valores separados por comas)

​JSON (notación de objetos JavaScript)

​XML (lenguaje de marcado extensible)

​Límites de tamaño de archivo

​Requisitos de red

​Acceso entrante

​Acceso saliente

​Configuración de TLS

​Lista de verificación del entorno

​Próximos pasos

Instalación

Inicio rápido

Requisitos del sistema

Infraestructura

Dependencias

Entorno de ejecución

Opcional: conciliar datos de Midaz

Cuándo conciliar datos de Midaz

Cuándo no interviene Midaz

Cómo funciona

Autenticación

Flujo de autenticación

Permisos requeridos

Modo de tenant único

Formatos de archivo soportados

CSV (valores separados por comas)

JSON (notación de objetos JavaScript)

XML (lenguaje de marcado extensible)

Límites de tamaño de archivo

Requisitos de red

Acceso entrante

Acceso saliente

Configuración de TLS

Lista de verificación del entorno

Próximos pasos