Primeiros passos com o Midaz

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

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.

Para a especificação completa do endpoint, veja Criar uma Organização.

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"
    }
  }'

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.

Para a especificação completa do endpoint, veja Criar um Ledger.

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.

Para a especificação completa do endpoint, veja Criar um Ativo.

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

Para a especificação completa do endpoint, veja Criar uma Conta.

O Midaz criou a conta de origem @external/BRL quando você criou o ativo BRL. Crie uma conta 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"
  }'

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.

Para a especificação completa do endpoint, veja Criar uma Transação no modelo direto 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"
      }
    ]
  }'

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.

Para a especificação completa do endpoint, veja Buscar um Saldo pelo Alias da Conta.

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

Novo no Midaz? Comece com Entidades do Midaz para entender organizações, ledgers, contas e transações.

Criando transações

Aprenda as diferentes formas de criar transações, incluindo JSON, inflow e outflow, e quando usar cada uma.

Deploy para produção

Faça o deploy do Midaz no Kubernetes usando o Helm chart oficial.

Configurando o CRM

Gerencie titulares e contas alias para conectar identidades do mundo real às suas contas do Midaz.

Estenda com plugins

Adicione Pix e outras capacidades ao seu deploy do Midaz.

Midaz Core

CRM

Fees

Primeiros passos com o Midaz

Pré-requisitos

Passo 1: Verifique se o Midaz responde

Passo 2: Crie uma organização

Passo 3: Crie um ledger

Passo 4: Crie um ativo

Passo 5: Crie contas

Passo 6: Processe sua primeira transação

Passo 7: Verifique o saldo

Explore a API

Próximos passos

Criando transações

Deploy para produção

Configurando o CRM

Estenda com plugins

​Pré-requisitos

​Passo 1: Verifique se o Midaz responde

​Passo 2: Crie uma organização

​Passo 3: Crie um ledger

​Passo 4: Crie um ativo

​Passo 5: Crie contas

​Passo 6: Processe sua primeira transação

​Passo 7: Verifique o saldo

​Explore a API

​Próximos passos

Criando transações

Deploy para produção

Configurando o CRM

Estenda com plugins

Pré-requisitos

Passo 1: Verifique se o Midaz responde

Passo 2: Crie uma organização

Passo 3: Crie um ledger

Passo 4: Crie um ativo

Passo 5: Crie contas

Passo 6: Processe sua primeira transação

Passo 7: Verifique o saldo

Explore a API

Próximos passos