Primeiros passos com o Midaz

Neste guia, você configura um ambiente Midaz funcional. 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 estas ferramentas:

Ferramenta	Versão mínima	Comando de verificação
Go	1.26.4+	`go version`
Docker	24+	`docker --version`
Docker Compose	2.20+	`docker compose version`
Make	3.81+	`make --version`
Git	2.30+	`git --version`

O Midaz roda em macOS (Apple Silicon e Intel) e Linux (amd64). No Windows, rode por meio do WSL2.

Passo 1: Clone o repositório

Clone o repositório do Midaz e entre no diretório do projeto.

git clone https://github.com/LerianStudio/midaz.git
cd midaz

Passo 2: Configure os arquivos de ambiente

O Midaz usa arquivos .env para configurar cada componente. Gere-os a partir dos exemplos fornecidos:

make set-env

Esse comando copia .env.example para .env em cada diretório de componente. Os valores padrão funcionam para desenvolvimento local. Você não precisa alterá-los.

O Docker deve estar em execução antes desta etapa. O make set-env também gera as chaves LCRYPTO_* do CRM por meio de um container Docker one-shot. O comando falha se o Docker não estiver disponível.

Passo 3: Inicie a infraestrutura

Inicie os serviços de suporte que o Midaz precisa: PostgreSQL, MongoDB, Valkey, RabbitMQ, Redpanda e OpenTelemetry.

make infra COMMAND=up

Aguarde até que todos os containers reportem status saudável. Verifique o status deles com:

docker compose -f components/infra/docker-compose.yml ps

Os serviços de infraestrutura usam estas portas padrão:

Serviço	Porta
PostgreSQL Primary	5701
PostgreSQL Replica	5702
MongoDB	5703
Valkey (Redis)	5704
Grafana (OTEL)	3100
RabbitMQ AMQP	3003
RabbitMQ Management	3004
Redpanda (Kafka API)	19092

Passo 4: Inicie o Midaz

O Midaz roda como um único serviço de Ledger que inclui os domínios de onboarding e transação. Inicie-o com:

make up

Esse comando inicia a infraestrutura, se necessário, executa o container de migração do ledger e então inicia os serviços do Midaz — o ledger e o Tracer. Todas as APIs do ledger ficam disponíveis na porta 3002. Verifique se o Midaz responde:

curl http://localhost:3002/health

Você deve receber uma resposta 200 OK.

Passo 5: 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/v1/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 6: 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/v1/organizations/{organization_id}/ledgers \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Primary Ledger",
    "status": {
      "code": "ACTIVE"
    }
  }'

Salve o id retornado como {ledger_id}.

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

Passo 8: 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.

Crie uma conta de origem:

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

Crie uma conta 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"
  }'

Passo 9: Processe sua primeira transação

Essa é a ação principal: ela 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 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"
            }
          }
        ]
      }
    }
  }'

Essa transação envia "1000" de @revenue 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 10: 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/v1/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 em components/ledger/.env e reinicie o Midaz. Depois acesse:

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

Observabilidade

O Midaz vem com uma instância do Grafana pré-configurada e integrada ao OpenTelemetry.

Dashboard do Grafana: http://localhost:3100
Credenciais padrão: midaz / lerian

A partir do Grafana, você pode explorar logs, traces e métricas de todos os serviços do Midaz.

Parando o Midaz

Para parar todos os serviços:

make down

Para remover containers e volumes e começar em um ambiente limpo:

make clean-docker

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 o Fees Engine, Pix e outras capacidades ao seu deploy do Midaz.

​Pré-requisitos

​Passo 1: Clone o repositório

​Passo 2: Configure os arquivos de ambiente

​Passo 3: Inicie a infraestrutura

​Passo 4: Inicie o Midaz

​Passo 5: Crie uma organização

​Passo 6: Crie um ledger

​Passo 7: Crie um ativo

​Passo 8: Crie contas

​Passo 9: Processe sua primeira transação

​Passo 10: Verifique o saldo

​Explore a API

​Observabilidade

​Parando o Midaz

​Próximos passos

Criando transações

Deploy para produção

Configurando o CRM

Estenda com plugins

Pré-requisitos

Passo 1: Clone o repositório

Passo 2: Configure os arquivos de ambiente

Passo 3: Inicie a infraestrutura

Passo 4: Inicie o Midaz

Passo 5: Crie uma organização

Passo 6: Crie um ledger

Passo 7: Crie um ativo

Passo 8: Crie contas

Passo 9: Processe sua primeira transação

Passo 10: Verifique o saldo

Explore a API

Observabilidade

Parando o Midaz

Próximos passos