> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.
# Primeros pasos con Midaz
> Ejecuta Midaz localmente en unos diez minutos: clona el repositorio, inicia la infraestructura, crea tu primera organización, ledger, cuentas y procesa una primera transacción.
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](https://go.dev/dl/) | 1.26.4+ | `go version` |
| [Docker](https://docs.docker.com/get-docker/) | 24+ | `docker --version` |
| [Docker Compose](https://docs.docker.com/compose/install/) | 2.20+ | `docker compose version` |
| [Make](https://www.gnu.org/software/make/) | 3.81+ | `make --version` |
| [Git](https://git-scm.com/) | 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.
```bash Terminal theme={null}
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:
```bash Terminal theme={null}
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.
```bash Terminal theme={null}
make infra COMMAND=up
```
Espera hasta que todos los contenedores reporten un estado saludable. Verifica su estado con:
```bash Terminal theme={null}
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:
```bash Terminal theme={null}
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:
```bash Terminal theme={null}
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](/es/reference/products/midaz/v2/create-organization).
```bash Terminal theme={null}
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](/es/reference/products/midaz/v2/create-ledger).
```bash Terminal theme={null}
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](/es/reference/products/midaz/v2/create-asset).
```bash Terminal theme={null}
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](/es/reference/products/midaz/v2/create-account).
Crea una cuenta de origen:
```bash Terminal theme={null}
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:
```bash Terminal theme={null}
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](/es/reference/products/midaz/v1/create-transaction-json).
```bash Terminal theme={null}
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](/es/reference/products/midaz/v2/get-balances-by-alias).
```bash Terminal theme={null}
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:
```bash Terminal theme={null}
make down
```
Para eliminar contenedores y volúmenes y empezar desde un entorno limpio:
```bash Terminal theme={null}
make clean-docker
```
## Próximos pasos
***
¿Nuevo en Midaz? Empieza con [Entidades de Midaz](/es/products/midaz/core-entities) para entender las organizaciones, los ledgers, las cuentas y las transacciones.
Conoce las distintas formas de crear transacciones, incluyendo JSON, inflow y outflow, y cuándo usar cada una.
Despliega Midaz en Kubernetes usando el Helm chart oficial.
Gestiona holders y cuentas con alias para conectar identidades del mundo real con tus cuentas de Midaz.
Agrega Fees Engine, Pix y otras capacidades a tu implementación de Midaz.