Requisitos previos

​

Requisitos del sistema

​

Infraestructura

​

Dependencias

• PostgreSQL 17: almacén de datos principal de contextos de conciliación, transacciones, coincidencias y logs de auditoría.
• Valkey 8: servicio compatible con Redis que se usa para cache, detección de duplicados, bloqueo distribuido y control de idempotencia.
• RabbitMQ 4.1.3: broker de mensajes para el procesamiento asíncrono entre contextos delimitados.

​

Entorno de ejecución

• Go 1.26+ (obligatorio solo cuando compilas desde el código fuente)
• Docker 24+ y Docker Compose 2.20+ para despliegues en contenedores
• Kubernetes 1.28+ para despliegues de nivel productivo con Helm

​

Opcional: conciliar datos de Midaz

​

Cuándo conciliar datos de Midaz

• Usas Midaz como tu sistema de ledger
• Quieres conciliar los asientos de Midaz contra fuentes externas (extractos bancarios, informes de gateway)

​

Cuándo Midaz no participa

• Se concilia entre sistemas externos (bancos, ERP, procesadores de pago)
• Se usa otro sistema de ledger
• Se importan datos del ledger mediante archivos CSV/JSON/XML

​

Cómo funciona

1. Exporta los datos del ledger del período que quieres conciliar.
2. Importa esa exportación a un contexto de Matcher como una fuente de tipo LEDGER.
3. Importa los datos de la contraparte (extracto bancario o informe de gateway) como el otro lado.
4. Matcher empareja los dos lados con tus reglas de coincidencia.

​

Autenticación

​

Flujo de autenticación

1. El cliente obtiene un JWT del proveedor de identidad
2. El cliente envía el token en el header Authorization: Bearer ***.
3. Matcher valida el token mediante lib-auth
4. Los claims del token aportan la identidad del tenant y los permisos

​

Permisos obligatorios

​

Modo single-tenant

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

​

Formatos de importación genéricos

​

CSV (valores separados por comas)

• El archivo debe tener una fila de encabezado
• Codificación UTF-8
• Delimitador de coma (configurable)
• Campos entre comillas para valores que contienen delimitadores

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)

• Arreglo JSON válido de objetos de transacción
• Codificación UTF-8
• Nombres de campo consistentes en todos los registros

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

​

XML (lenguaje de marcado extensible)

• Un único elemento raíz
• Codificación UTF-8
• Estructura de elementos consistente

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

​

Requisitos de red

​

Acceso de entrada

​

Acceso de salida

​

Configuración de TLS

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

​

Lista de verificación del entorno

• La infraestructura está lista: PostgreSQL, Redis y RabbitMQ están activos y accesibles. El almacenamiento de objetos compatible con S3 también está listo si habilitas el worker de exportación (la opción predeterminada)
• La autenticación está lista: el servicio de autenticación está disponible, o desactivaste la autenticación de forma explícita
• El acceso de red funciona: la conectividad de entrada y de salida necesaria está en su lugar
• Las credenciales están disponibles: tienes las credenciales de la base de datos y los tokens de API
• Los datos de prueba están listos: tienes archivos de transacciones para tu primera prueba (consulta Inicio rápido)

​

Próximos pasos