Primeros pasos con Midaz

En esta guía, configuras un entorno de Midaz funcional. Luego ejecutas el workflow principal detrás de cualquier aplicación financiera en la plataforma. Creas una organización, un ledger y cuentas, y luego procesas tu primera transacción. Al final, tienes un ledger en funcionamiento listo para tu caso de uso. Esto puede ser pagos, préstamos, liquidación de marketplace o tesorería interna.

Requisitos previos

Antes de empezar, instala estas herramientas:

Herramienta	Versión mínima	Comando de verificación
Go	1.26.4+	`go version`
Docker	24+	`docker --version`
Docker Compose	2.20+	`docker compose version`
Make	3.81+	`make --version`
Git	2.30+	`git --version`

Midaz funciona en macOS (Apple Silicon e Intel) y Linux (amd64). En Windows, ejecútalo mediante WSL2.

Paso 1: Clonar el repositorio

Clona el repositorio de Midaz y muévete al directorio del proyecto.

git clone https://github.com/LerianStudio/midaz.git
cd midaz

Paso 2: Configurar los archivos de entorno

Midaz usa archivos .env para configurar cada componente. Genéralos a partir de los ejemplos incluidos:

make set-env

Este comando copia .env.example a .env en cada directorio de componente. Los valores predeterminados funcionan para el desarrollo local. No necesitas cambiarlos.

Docker debe estar en ejecución antes de este paso. make set-env también genera las claves de CRM LCRYPTO_* mediante un contenedor Docker de un solo uso. El comando falla si Docker no está disponible.

Paso 3: Iniciar la infraestructura

Inicia los servicios de soporte que Midaz necesita: PostgreSQL, MongoDB, Valkey, RabbitMQ, Redpanda y OpenTelemetry.

make infra COMMAND=up

Espera hasta que todos los contenedores reporten un estado saludable. Verifica su estado con:

docker compose -f components/infra/docker-compose.yml ps

Los servicios de infraestructura usan los siguientes puertos predeterminados:

Servicio	Puerto
PostgreSQL Primary	5701
PostgreSQL Replica	5702
MongoDB	5703
Valkey (Redis)	5704
Grafana (OTEL)	3100
RabbitMQ AMQP	3003
RabbitMQ Management	3004
Redpanda (Kafka API)	19092

Paso 4: Iniciar Midaz

Midaz se ejecuta como un único servicio de Ledger que incluye los dominios de onboarding y transacciones. Inícialo con:

make up

Este comando inicia la infraestructura, si hace falta, ejecuta el contenedor de migración del ledger y luego inicia los servicios de Midaz: el ledger y Tracer. Todas las API del ledger están disponibles en el puerto 3002. Verifica que Midaz responde:

curl http://localhost:3002/health

Debes recibir una respuesta 200 OK.

Paso 5: Crear una organización

Una organización representa la entidad de negocio detrás de la operación financiera: tu empresa, un cliente o una institución regulada. En producción, corresponde a la entidad legal que posee tus ledgers, cuentas y transacciones.

Para la especificación completa del endpoint, consulta Crear una organización.

curl -X POST http://localhost:3002/v1/organizations \
  -H "Content-Type: application/json" \
  -d '{
    "legalName": "Acme Corp",
    "legalDocument": "12345678000100",
    "status": {
      "code": "ACTIVE"
    },
    "address": {
      "country": "BR"
    }
  }'

Guarda el id devuelto en la respuesta. Lo usas en los siguientes pasos como {organization_id}.

Paso 6: Crear un ledger

Un ledger es un libro de registros aislado dentro de una organización. Puedes crear ledgers separados para distintos dominios financieros, como pagos, cobro de comisiones o liquidación. Cada ledger tiene sus propias cuentas e historial de transacciones.

Para la especificación completa del endpoint, consulta Crear un ledger.

curl -X POST http://localhost:3002/v1/organizations/{organization_id}/ledgers \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Primary Ledger",
    "status": {
      "code": "ACTIVE"
    }
  }'

Guarda el id devuelto como {ledger_id}.

Paso 7: Crear un activo

Un activo define la unidad de valor que se registra en el ledger. Puede ser una moneda fiat como BRL o USD. También puede ser puntos de lealtad, tokens cripto, valores, o cualquier unidad personalizada que tu negocio registre. Debes crear al menos un activo antes de crear cuentas.

Para la especificación completa del endpoint, consulta Crear un activo.

curl -X POST http://localhost:3002/v1/organizations/{organization_id}/ledgers/{ledger_id}/assets \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Brazilian Real",
    "type": "currency",
    "code": "BRL",
    "status": {
      "code": "ACTIVE"
    }
  }'

Paso 8: Crear cuentas

Las cuentas representan los participantes o contenedores en tu flujo financiero: la billetera de un cliente, un fondo de ingresos, la cuenta de un comerciante o una reserva interna. Cada cuenta se vincula a un único activo y sigue las reglas de contabilidad de partida doble. Necesitas al menos dos cuentas para procesar una transacción: una para debitar (origen) y otra para acreditar (destino).

Para la especificación completa del endpoint, consulta Crear una cuenta.

Crea una cuenta de origen:

curl -X POST http://localhost:3002/v1/organizations/{organization_id}/ledgers/{ledger_id}/accounts \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Revenue Account",
    "assetCode": "BRL",
    "type": "deposit",
    "status": {
      "code": "ACTIVE"
    },
    "alias": "@revenue"
  }'

Crea una cuenta de destino:

curl -X POST http://localhost:3002/v1/organizations/{organization_id}/ledgers/{ledger_id}/accounts \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Account",
    "assetCode": "BRL",
    "type": "deposit",
    "status": {
      "code": "ACTIVE"
    },
    "alias": "@customer-001"
  }'

Paso 9: Procesar tu primera transacción

Esta es la acción central: mueve valor entre cuentas con trazabilidad completa. Midaz registra cada transacción como una operación balanceada. Debita el origen y acredita el destino, de modo que tus libros se mantienen consistentes por diseño.

Para la especificación completa del endpoint, consulta Crear una transacción usando JSON.

curl -X POST http://localhost:3002/v1/organizations/{organization_id}/ledgers/{ledger_id}/transactions/json \
  -H "Content-Type: application/json" \
  -d '{
    "description": "First transaction",
    "send": {
      "asset": "BRL",
      "value": "1000",
      "source": {
        "from": [
          {
            "accountAlias": "@revenue",
            "amount": {
              "asset": "BRL",
              "value": "1000"
            }
          }
        ]
      },
      "distribute": {
        "to": [
          {
            "accountAlias": "@customer-001",
            "amount": {
              "asset": "BRL",
              "value": "1000"
            }
          }
        ]
      }
    }
  }'

Esta transacción envía "1000" de @revenue a @customer-001. Midaz almacena los valores monetarios como cadenas decimales y no aplica una escala específica del activo.Tu integración define las reglas de presentación y redondeo para los montos en BRL. No proceses los valores monetarios como punto flotante binario.

Paso 10: Verificar el saldo

Verifica el saldo de la cuenta de destino para confirmar la transacción.

Para la especificación completa del endpoint, consulta Obtener un saldo por alias de cuenta.

curl http://localhost:3002/v1/organizations/{organization_id}/ledgers/{ledger_id}/accounts/alias/@customer-001/balances

El saldo devuelto debe reflejar el monto acreditado. En este punto, tienes un ledger en funcionamiento que procesa transacciones reales.

Explorar la API

Midaz puede exponer su especificación OpenAPI 3.1 y documentación interactiva de la API. Esta interfaz de documentación está deshabilitada de forma predeterminada. Para habilitarla, define OPENAPI_DOCS_ENABLED=true en components/ledger/.env y reinicia Midaz. Luego accede a:

Documentación de la API: http://localhost:3002/v1/docs
Especificación OpenAPI: http://localhost:3002/v1/openapi.json (o /v1/openapi.yaml)

Observabilidad

Midaz incluye una instancia de Grafana preconfigurada e integrada con OpenTelemetry.

Panel de Grafana: http://localhost:3100
Credenciales predeterminadas: midaz / lerian

Desde Grafana, puedes explorar logs, trazas y métricas en todos los servicios de Midaz.

Detener Midaz

Para detener todos los servicios:

make down

Para eliminar contenedores y volúmenes y empezar desde un entorno limpio:

make clean-docker

Próximos pasos

¿Nuevo en Midaz? Empieza con Entidades de Midaz para entender las organizaciones, los ledgers, las cuentas y las transacciones.

Crear transacciones

Conoce las distintas formas de crear transacciones, incluyendo JSON, inflow y outflow, y cuándo usar cada una.

Desplegar en producción

Despliega Midaz en Kubernetes usando el Helm chart oficial.

Configurar CRM

Gestiona holders y cuentas con alias para conectar identidades del mundo real con tus cuentas de Midaz.

Extender con plugins

Agrega Fees Engine, Pix y otras capacidades a tu implementación de Midaz.

​Requisitos previos

​Paso 1: Clonar el repositorio

​Paso 2: Configurar los archivos de entorno

​Paso 3: Iniciar la infraestructura

​Paso 4: Iniciar Midaz

​Paso 5: Crear una organización

​Paso 6: Crear un ledger

​Paso 7: Crear un activo

​Paso 8: Crear cuentas

​Paso 9: Procesar tu primera transacción

​Paso 10: Verificar el saldo

​Explorar la API

​Observabilidad

​Detener Midaz

​Próximos pasos

Crear transacciones

Desplegar en producción

Configurar CRM

Extender con plugins

Requisitos previos

Paso 1: Clonar el repositorio

Paso 2: Configurar los archivos de entorno

Paso 3: Iniciar la infraestructura

Paso 4: Iniciar Midaz

Paso 5: Crear una organización

Paso 6: Crear un ledger

Paso 7: Crear un activo

Paso 8: Crear cuentas

Paso 9: Procesar tu primera transacción

Paso 10: Verificar el saldo

Explorar la API

Observabilidad

Detener Midaz

Próximos pasos