Primeros pasos con Midaz

En esta guía, verificas un ledger de Midaz en ejecución. 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 Midaz. Midaz se distribuye como imágenes de contenedor públicas en Docker Hub. Consulta Instalar Midaz. Esta guía llama al ledger en http://localhost:3002, donde 3002 es el SERVER_PORT predeterminado. Si tu ledger se ejecuta en otra dirección, usa esa dirección.

Paso 1: Verificar que Midaz responde

curl http://localhost:3002/health

Debes recibir una respuesta 200 OK.

Paso 2: 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/v2/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 3: 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/v2/organizations/{organization_id}/ledgers \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Primary Ledger",
    "status": {
      "code": "ACTIVE"
    }
  }'

Guarda el id devuelto como {ledger_id}.

Paso 4: 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/v2/organizations/{organization_id}/ledgers/{ledger_id}/assets \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Brazilian Real",
    "type": "currency",
    "code": "BRL",
    "status": {
      "code": "ACTIVE"
    }
  }'

Paso 5: 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.

Midaz creó la cuenta de origen @external/BRL cuando creaste el activo BRL. Crea una cuenta de destino:

curl -X POST http://localhost:3002/v2/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 6: Procesar tu primera transacción

Una transacción 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 con el modelo directo v2.

curl -X POST http://localhost:3002/v2/transactions/direct \
  -H "Content-Type: application/json" \
  -d '{
    "description": "First transaction",
    "asset": "BRL",
    "amount": "1000",
    "debits": [
      {
        "alias": "@external/BRL",
        "organizationId": "{organization_id}",
        "ledgerId": "{ledger_id}",
        "amount": "1000"
      }
    ],
    "credits": [
      {
        "alias": "@customer-001",
        "organizationId": "{organization_id}",
        "ledgerId": "{ledger_id}",
        "amount": "1000"
      }
    ]
  }'

Esta transacción envía "1000" de @external/BRL 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 7: 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/v2/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 el ledger y reinícialo. Luego accede a:

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

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 Pix y otras capacidades a tu implementación de Midaz.

Midaz Core

CRM

Fees

Primeros pasos con Midaz

Requisitos previos

Paso 1: Verificar que Midaz responde

Paso 2: Crear una organización

Paso 3: Crear un ledger

Paso 4: Crear un activo

Paso 5: Crear cuentas

Paso 6: Procesar tu primera transacción

Paso 7: Verificar el saldo

Explorar la API

Próximos pasos

Crear transacciones

Desplegar en producción

Configurar CRM

Extender con plugins

​Requisitos previos

​Paso 1: Verificar que Midaz responde

​Paso 2: Crear una organización

​Paso 3: Crear un ledger

​Paso 4: Crear un activo

​Paso 5: Crear cuentas

​Paso 6: Procesar tu primera transacción

​Paso 7: Verificar el saldo

​Explorar la API

​Próximos pasos

Crear transacciones

Desplegar en producción

Configurar CRM

Extender con plugins

Requisitos previos

Paso 1: Verificar que Midaz responde

Paso 2: Crear una organización

Paso 3: Crear un ledger

Paso 4: Crear un activo

Paso 5: Crear cuentas

Paso 6: Procesar tu primera transacción

Paso 7: Verificar el saldo

Explorar la API

Próximos pasos