> ## 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.

# Primeiros passos com o Midaz

> Rode seu primeiro workflow no Midaz: verifique seu ledger, crie sua primeira Organização, Ledger e Contas e processe uma primeira transação.

Neste guia, você verifica um ledger Midaz em execução. Em seguida, executa o workflow principal por trás de qualquer aplicação financeira na plataforma. Você cria uma organização, um ledger e contas, e depois processa sua primeira transação.

Ao final, você tem um ledger em funcionamento, pronto para o seu caso de uso. Isso pode ser pagamentos, empréstimos, liquidação de marketplace ou tesouraria interna.

## Pré-requisitos

***

Antes de começar, instale o Midaz. O Midaz é distribuído como imagens de container públicas no Docker Hub. Veja [Instalando o Midaz](https://docs.lerian.studio/pt/products/midaz/midaz-setup.md).

Este guia chama o ledger em `http://localhost:3002`, onde `3002` é o `SERVER_PORT` padrão. Se o seu ledger roda em outro endereço, use esse endereço.

## Passo 1: Verifique se o Midaz responde

***

```bash Terminal theme={null}
curl http://localhost:3002/health
```

Você deve receber uma resposta `200 OK`.

## Passo 2: Crie uma organização

***

Uma organização representa a entidade de negócio por trás da operação financeira: sua empresa, um cliente ou uma instituição regulada. Em produção, ela corresponde à entidade legal que detém seus ledgers, contas e transações.

> [!TIP]
>
> Para a especificação completa do endpoint, veja [Criar uma Organização](https://docs.lerian.studio/pt/reference/products/midaz/v2/create-organization.md).

```bash Terminal theme={null}
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"
    }
  }'
```

> [!NOTE]
>
> Salve o `id` retornado na resposta. Você o usa nos próximos passos como `{organization_id}`.

## Passo 3: Crie um ledger

***

Um ledger é um livro de registros isolado dentro de uma organização. Você pode criar ledgers separados para diferentes domínios financeiros, como pagamentos, cobrança de tarifas ou liquidação. Cada ledger tem suas próprias contas e seu próprio histórico de transações.

> [!TIP]
>
> Para a especificação completa do endpoint, veja [Criar um Ledger](https://docs.lerian.studio/pt/reference/products/midaz/v2/create-ledger.md).

```bash Terminal theme={null}
curl -X POST http://localhost:3002/v2/organizations/{organization_id}/ledgers \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Primary Ledger",
    "status": {
      "code": "ACTIVE"
    }
  }'
```

Salve o `id` retornado como `{ledger_id}`.

## Passo 4: Crie um ativo

***

Um ativo define a unidade de valor rastreada no ledger. Pode ser uma moeda fiduciária como BRL ou USD. Também pode ser pontos de fidelidade, tokens de cripto, títulos ou qualquer unidade personalizada que o seu negócio rastreie.

Você deve criar pelo menos um ativo antes de criar contas.

> [!TIP]
>
> Para a especificação completa do endpoint, veja [Criar um Ativo](https://docs.lerian.studio/pt/reference/products/midaz/v2/create-asset.md).

```bash Terminal theme={null}
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"
    }
  }'
```

## Passo 5: Crie contas

***

Contas representam os participantes ou compartimentos do seu fluxo financeiro: uma wallet de cliente, um pool de receita, uma conta de comerciante ou uma reserva interna. Cada conta se vincula a um único ativo e segue as regras de partidas dobradas.

Você precisa de pelo menos duas contas para processar uma transação: uma para debitar (origem) e uma para creditar (destino).

> [!TIP]
>
> Para a especificação completa do endpoint, veja [Criar uma Conta](https://docs.lerian.studio/pt/reference/products/midaz/v2/create-account.md).

O Midaz criou a conta de origem `@external/BRL` quando você criou o ativo BRL. Crie uma conta de destino:

```bash Terminal theme={null}
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"
  }'
```

## Passo 6: Processe sua primeira transação

***

Uma transação move valor entre contas com rastreabilidade completa. O Midaz registra cada transação como uma operação balanceada. Ele debita a origem e credita o destino, de modo que seus livros permanecem consistentes por design.

> [!TIP]
>
> Para a especificação completa do endpoint, veja [Criar uma Transação no modelo direto v2](https://docs.lerian.studio/pt/reference/products/midaz/v2/create-transaction-direct.md).

```bash Terminal theme={null}
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"
      }
    ]
  }'
```

> [!NOTE]
>
> Essa transação envia `"1000"` de `@external/BRL` para `@customer-001`. O Midaz armazena valores monetários como strings decimais e não aplica uma escala específica do ativo.
>
> Sua integração define as regras de exibição e arredondamento para valores em BRL. Não faça parse de valores monetários como ponto flutuante binário.

## Passo 7: Verifique o saldo

***

Verifique o saldo da conta de destino para confirmar a transação.

> [!TIP]
>
> Para a especificação completa do endpoint, veja [Buscar um Saldo pelo Alias da Conta](https://docs.lerian.studio/pt/reference/products/midaz/v2/get-balances-by-alias.md).

```bash Terminal theme={null}
curl http://localhost:3002/v2/organizations/{organization_id}/ledgers/{ledger_id}/accounts/alias/@customer-001/balances
```

O saldo retornado deve refletir o valor creditado. Neste ponto, você tem um ledger funcional que processa transações reais.

## Explore a API

***

O Midaz pode servir sua especificação OpenAPI 3.1 e a documentação interativa da API. Essa superfície de documentação fica desativada por padrão. Para habilitá-la, defina `OPENAPI_DOCS_ENABLED=true` no ledger e reinicie-o. Depois acesse:

* **Documentação da API**: `http://localhost:3002/docs`
* **Especificação OpenAPI**: `http://localhost:3002/openapi.json` (ou `/openapi.yaml`)

## Próximos passos

***

> [!TIP]
>
> Novo no Midaz? Comece com [Entidades do Midaz](https://docs.lerian.studio/pt/products/midaz/core-entities.md) para entender organizações, ledgers, contas e transações.

> [card] [Criando transações](https://docs.lerian.studio/pt/products/midaz/transactions-overview)
>
> Aprenda as diferentes formas de criar transações, incluindo JSON, inflow e outflow, e quando usar cada uma.

> [card] [Deploy para produção](https://github.com/LerianStudio/helm/blob/main/charts/midaz/README.md#install-midaz-helm-chart)
>
> Faça o deploy do Midaz no Kubernetes usando o Helm chart oficial.

> [card] [Configurando o CRM](https://docs.lerian.studio/pt/products/midaz/crm/crm-getting-started.md)
>
> Gerencie titulares e contas alias para conectar identidades do mundo real às suas contas do Midaz.

> [card] [Estenda com plugins](https://docs.lerian.studio/pt/products/about-plugins.md)
>
> Adicione Pix e outras capacidades ao seu deploy do Midaz.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.