Primeros pasos con Midaz

En esta guía, configuras un entorno Midaz funcional. Luego recorres el flujo de trabajo 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. Puede ser pagos, préstamos, liquidación de marketplace o tesorería interna.

Prerrequisitos

Antes de comenzar, instala estas herramientas:

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

Midaz se ejecuta en macOS (Apple Silicon e Intel) y Linux (amd64). En Windows, ejecútalo a través de WSL2.

Paso 1 — Clonar el repositorio

Clona el repositorio de Midaz y accede 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 proporcionados:

make set-env

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

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 Management	3003
RabbitMQ AMQP	3004
Redpanda (Kafka API)	19092

Paso 4 — Iniciar Midaz

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

make up

Este comando inicia la infraestructura, si es necesario, y los servicios de Midaz. Todas las APIs están disponibles en el puerto 3002. Verifica que Midaz responda:

curl http://localhost:3002/health

Deberías recibir una respuesta 200 OK.

Paso 5 — Crear una organización

Una organización representa la entidad comercial detrás de la operación financiera: tu empresa, un cliente o una institución regulada. En producción, se corresponde con la entidad legal que contiene 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 próximos 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 diferentes dominios financieros, como pagos, cobro de tarifas 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 rastreada en el ledger. Puede ser una moneda fiduciaria como BRL o USD. También puede ser puntos de fidelidad, tokens cripto, valores o cualquier unidad personalizada que tu negocio rastree. 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 a los participantes o compartimentos en tu flujo financiero: una billetera de cliente, un pool de ingresos, una cuenta de 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 principal: mueve valor entre cuentas con trazabilidad completa. Midaz registra cada transacción como una operación balanceada. Debita el origen y acredita el destino, para que tus libros se mantengan 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 R$ 10,00 de @revenue a @customer-001. El valor "1000" representa 10,00 en la unidad más pequeña del BRL, centavos.Midaz usa valores enteros para evitar errores de punto flotante. Esta es una práctica estándar en sistemas financieros.

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 Consultar 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 debería reflejar el monto acreditado. En este punto, tienes un ledger funcional que procesa transacciones reales.

Explora la API

Midaz puede servir su especificación OpenAPI 3.1 y documentación interactiva de la API. Esta superficie de documentación está desactivada de forma predeterminada. Para activarla, define LEDGER_HUMA_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 preconfigurada de Grafana integrada con OpenTelemetry.

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

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

Detener Midaz

Para detener todos los servicios:

make down

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

make clean-docker

Próximos pasos

¿Nuevo en Midaz? Comienza con Entidades de Midaz para comprender organizaciones, ledgers, cuentas y transacciones.

Creando transacciones

Aprende las diferentes 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 chart oficial de Helm.

Configuración de CRM

Gestiona titulares y cuentas alias para conectar identidades del mundo real a tus cuentas de Midaz.

Extender con plugins

Agrega Fees Engine, Pix y otras capacidades a tu despliegue de Midaz.

​Prerrequisitos

​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

​Explora la API

​Observabilidad

​Detener Midaz

​Próximos pasos

Creando transacciones

Desplegar en producción

Configuración de CRM

Extender con plugins

Prerrequisitos

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

Explora la API

Observabilidad

Detener Midaz

Próximos pasos