Prerrequisitos

Verifica la infraestructura, las dependencias y los requisitos de tiempo de ejecución que necesita tu entorno antes de desplegar Matcher.

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

Los valores siguientes son puntos de partida operativos validados para la plataforma, no mínimos impuestos por el producto. Ajústalos según tu volumen de transacciones y tus necesidades de retención.

Componente	Punto de partida validado / orientación de escalado	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

La configuración local de Compose es la línea base de dependencias validada para la plataforma. Fija:

• PostgreSQL 17: Almacén de datos principal para contextos de conciliación, transacciones, conciliaciones y logs de auditoría.
• Valkey 8: Servicio compatible con Redis usado para caché, detección de duplicados, bloqueo distribuido y control de idempotencia.
• RabbitMQ 4.1.3: Bróker de mensajes para procesamiento asíncrono entre contextos acotados.

​

Entorno de ejecución

Las siguientes versiones son la línea base de herramientas validada para la plataforma, no una matriz de soporte del producto:

• 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:

1. Exporta los datos del libro contable del período que quieres conciliar.
2. Importa esa exportación en un contexto de Matcher como una fuente de tipo LEDGER.
3. Importa los datos de la contraparte (extracto bancario o reporte de gateway) como el otro lado.
4. 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

1. El cliente obtiene un JWT del proveedor de identidad
2. El token se envía en el encabezado Authorization: Bearer $TOKEN
3. Matcher valida el token mediante lib-auth
4. 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

MULTI_TENANT_ENABLED controla este modo. Su valor por defecto es false, por lo que Matcher usa el tenant predeterminado que aparece a continuación. El estado de la autenticación o la ausencia de un identificador de tenant en el JWT no cambia Matcher al modo de tenant único.

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

​

Formatos de importación genéricos

---

Los importadores genéricos de Matcher aceptan CSV, JSON y XML. Los analizadores integrados también admiten CAMT.053, CNAB 240/400, OFX, varios formatos de adquirentes y formatos de cuentas por cobrar. Consulta el catálogo de formatos de importación para ver el inventario completo.

Cada formato genérico 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	Configuración
Tamaño máximo de archivo subido	1 GiB	INGESTION_MAX_UPLOAD_BYTES en el arranque o Systemplane en tiempo de ejecución (de 1 MiB a 8 GiB)
Cuerpo máximo de solicitud en búfer	100 MiB	HTTP_BODY_LIMIT_BYTES (solicitudes que no son de subida)

​

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í
Almacenamiento de objetos compatible con S3	Exportaciones y archivado	Cuando el proceso de exportación está habilitado (habilitado por defecto)
Servicio de autenticación	Validación de tokens	Si la autenticación está habilitada
JIRA	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; el almacenamiento de objetos compatible con S3 también está listo cuando el proceso de exportación está habilitado (el valor por defecto)
• 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)

​

Próximos pasos

---

Instalación

Despliega Matcher usando Docker o Kubernetes.

Inicio rápido

Ejecuta tu primera conciliación.