Saltar al contenido principal
En esta guía, configurará un entorno Midaz funcional y recorrerá el flujo de trabajo principal detrás de cualquier aplicación financiera construida sobre la plataforma: crear una organización, definir un ledger, configurar cuentas y procesar su primera transacción. Al finalizar, tendrá un sistema de ledger en funcionamiento listo para soportar su caso de uso, ya sea pagos, préstamos, liquidación de marketplace o gestión de tesorería interna.

​
Prerrequisitos

Antes de comenzar, asegúrese de tener instaladas las siguientes herramientas:
HerramientaVersión mínimaComando de verificación
Go1.24+go version
Docker24+docker --version
Docker Compose2.20+docker compose version
Make3.81+make --version
Git2.30+git --version
Midaz ha sido probado en macOS (Apple Silicon e Intel) y Linux (amd64). Los usuarios de Windows deben ejecutarlo a través de WSL2.

​
Paso 1 — Clonar el repositorio

Clone el repositorio de Midaz y acceda al directorio del proyecto. 
git clone https://github.com/LerianStudio/midaz.git
cd midaz

​
Paso 2 — Configurar los archivos de entorno

Midaz utiliza archivos .env para configurar cada componente. Genérelos 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 están listos para desarrollo local, por lo que no se requieren cambios.

​
Paso 3 — Iniciar la infraestructura

Inicie los servicios de soporte requeridos por Midaz: PostgreSQL, MongoDB, Valkey, RabbitMQ y OpenTelemetry. 
make infra
Espere hasta que todos los contenedores reporten un estado saludable. Puede verificarlo con: 
docker compose -f components/infra/docker-compose.yml ps
Los servicios de infraestructura utilizan los siguientes puertos predeterminados:
ServicioPuerto
PostgreSQL Primary5701
PostgreSQL Replica5702
MongoDB5703
Valkey (Redis)5704
Grafana (OTEL)3100
RabbitMQ Management3003
RabbitMQ AMQP3004

​
Paso 4 — Iniciar Midaz

Puede ejecutar Midaz en dos modos:
El modo unificado ejecuta los servicios de Onboarding y Transaction en un solo proceso. Esta es la opción más simple para desarrollo y pruebas locales.
make up UNIFIED=true
Todas las APIs están disponibles en el puerto 3002.
Si prefiere ejecutar cada servicio de forma independiente:
make up
ServicioPuerto
Onboarding3000
Transaction3001
Verifique que los servicios estén en ejecución: 
curl http://localhost:3002/health
Debería 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: su empresa, un cliente o una institución regulada. En producción, esto se corresponde con la entidad legal bajo la cual se gestionan los ledgers, cuentas y transacciones.
Para la especificación completa del endpoint, consulte 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"
    }
  }'
Guarde el id devuelto en la respuesta. Lo utilizará 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. Puede crear ledgers separados para diferentes dominios financieros, como pagos, cobro de tarifas o liquidación, cada uno con sus propias cuentas e historial de transacciones.
Para la especificación completa del endpoint, consulte 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"
    }
  }'
Guarde 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, pero también puntos de fidelidad, tokens cripto, valores o cualquier unidad personalizada que su negocio necesite mover y rastrear. Debe crear al menos un activo antes de crear cuentas.
Para la especificación completa del endpoint, consulte 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 su flujo financiero: una billetera de cliente, un pool de ingresos, una cuenta de liquidación de comerciante o una reserva interna. Cada cuenta está vinculada a un único activo y sigue las reglas de contabilidad de partida doble. Necesita 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, consulte Crear una Cuenta.
Cree 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"
  }'
Cree 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 su primera transacción

Esta es la acción principal: mover valor entre cuentas con trazabilidad completa. Midaz registra cada transacción como una operación balanceada, debitando el origen y acreditando el destino para que sus libros se mantengan consistentes por diseño.
Para la especificación completa del endpoint, consulte 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 utiliza valores enteros para evitar problemas de precisión de punto flotante, lo cual es una práctica estándar en sistemas financieros.

​
Paso 10 — Verificar el saldo

Confirme que la transacción fue procesada verificando el saldo de la cuenta de destino.
Para la especificación completa del endpoint, consulte 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, tiene un ledger funcional procesando transacciones reales.

​
Explorar la API

Midaz incluye documentación Swagger integrada. Una vez que los servicios estén en ejecución, acceda en:
  • Modo unificado: http://localhost:3002/swagger/index.html
  • Onboarding: http://localhost:3000/swagger/index.html
  • Transaction: http://localhost:3001/swagger/index.html

​
Observabilidad

Midaz incluye una instancia preconfigurada de Grafana integrada con OpenTelemetry.
  • Panel de Grafana: http://localhost:3100
  • Credenciales predeterminadas: midaz / lerian
Desde Grafana, puede 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? Comience con Entidades de Midaz para comprender organizaciones, ledgers, cuentas y transacciones.

Creando transacciones

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

Desplegar en producción

Despliegue Midaz en Kubernetes usando el chart oficial de Helm.

Configuración de CRM

Gestione titulares y cuentas alias para conectar identidades del mundo real a sus cuentas de Midaz.

Extender con plugins

Agregue Fees Engine, Pix y otras capacidades a su despliegue de Midaz.