Pular para o conteúdo principal
Neste guia, você configurará um ambiente Midaz funcional e percorrerá o fluxo de trabalho principal por trás de qualquer aplicação financeira construída na plataforma: criar uma organização, definir um ledger, configurar contas e processar sua primeira transação. Ao final, você terá um sistema de ledger em funcionamento pronto para suportar seu caso de uso, seja pagamentos, empréstimos, liquidação de marketplace ou gestão de tesouraria interna.

​
Pré-requisitos

Antes de começar, certifique-se de que as seguintes ferramentas estejam instaladas:
FerramentaVersão mínimaComando de verificação
Go1.24+go version
Docker24+docker --version
Docker Compose2.20+docker compose version
Make3.81+make --version
Git2.30+git --version
O Midaz foi testado em macOS (Apple Silicon e Intel) e Linux (amd64). Usuários de Windows devem executá-lo através do WSL2.

​
Passo 1 — Clonar o repositório

Clone o repositório do Midaz e acesse o diretório do projeto. 
git clone https://github.com/LerianStudio/midaz.git
cd midaz

​
Passo 2 — Configurar os arquivos de ambiente

O Midaz utiliza arquivos .env para configurar cada componente. Gere-os a partir dos exemplos fornecidos: 
make set-env
Este comando copia .env.example para .env no diretório de cada componente. Os valores padrão estão prontos para desenvolvimento local, portanto nenhuma alteração é necessária.

​
Passo 3 — Iniciar a infraestrutura

Inicie os serviços de suporte necessários pelo Midaz: PostgreSQL, MongoDB, Valkey, RabbitMQ e OpenTelemetry. 
make infra
Aguarde até que todos os contêineres reportem um status saudável. Você pode verificar isso com: 
docker compose -f components/infra/docker-compose.yml ps
Os serviços de infraestrutura utilizam as seguintes portas padrão:
ServiçoPorta
PostgreSQL Primary5701
PostgreSQL Replica5702
MongoDB5703
Valkey (Redis)5704
Grafana (OTEL)3100
RabbitMQ Management3003
RabbitMQ AMQP3004

​
Passo 4 — Iniciar o Midaz

Você pode executar o Midaz em dois modos:
O modo unificado executa os serviços de Onboarding e Transaction em um único processo. Esta é a opção mais simples para desenvolvimento e testes locais.
make up UNIFIED=true
Todas as APIs estão disponíveis na porta 3002.
Se preferir executar cada serviço de forma independente:
make up
ServiçoPorta
Onboarding3000
Transaction3001
Verifique se os serviços estão em execução: 
curl http://localhost:3002/health
Você deverá receber uma resposta 200 OK.

​
Passo 5 — Criar uma organização

Uma organização representa a entidade comercial por trás da operação financeira: sua empresa, um cliente ou uma instituição regulada. Em produção, isso corresponde à entidade legal sob a qual ledgers, contas e transações são gerenciados.
Para a especificação completa do endpoint, consulte 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 utilizará nos próximos passos como {organization_id}.

​
Passo 6 — Criar 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 taxas ou liquidação, cada um com suas próprias contas e histórico de transações.
Para a especificação completa do endpoint, consulte 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 — Criar um ativo

Um ativo define a unidade de valor rastreada no ledger. Pode ser uma moeda fiduciária como BRL ou USD, mas também pontos de fidelidade, tokens cripto, títulos ou qualquer unidade personalizada que seu negócio precise movimentar e rastrear. Você deve criar pelo menos um ativo antes de criar contas.
Para a especificação completa do endpoint, consulte 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 — Criar contas

As contas representam os participantes ou compartimentos no seu fluxo financeiro: uma carteira de cliente, um pool de receitas, uma conta de liquidação de comerciante ou uma reserva interna. Cada conta está vinculada a um único ativo e segue as regras de contabilidade de partida dobrada. Você precisa de pelo menos duas contas para processar uma transação: uma para debitar (origem) e outra para creditar (destino).
Para a especificação completa do endpoint, consulte 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 — Processar sua primeira transação

Esta é a ação principal: mover valor entre contas com rastreabilidade completa. O Midaz registra cada transação como uma operação balanceada, debitando a origem e creditando o destino para que seus livros se mantenham consistentes por design.
Para a especificação completa do endpoint, consulte 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"
            }
          }
        ]
      }
    }
  }'
Esta transação envia R$ 10,00 de @revenue para @customer-001. O valor "1000" representa 10,00 na menor unidade do BRL, centavos.O Midaz utiliza valores inteiros para evitar problemas de precisão de ponto flutuante, o que é uma prática padrão em sistemas financeiros.

​
Passo 10 — Verificar o saldo

Confirme que a transação foi processada verificando o saldo da conta de destino.
Para a especificação completa do endpoint, consulte Consultar um Saldo por Alias de 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 processando transações reais.

​
Explorar a API

O Midaz inclui documentação Swagger integrada. Uma vez que os serviços estejam em execução, acesse em:
  • Modo unificado: http://localhost:3002/swagger/index.html
  • Onboarding: http://localhost:3000/swagger/index.html
  • Transaction: http://localhost:3001/swagger/index.html

​
Observabilidade

O Midaz inclui uma instância pré-configurada do Grafana integrada com OpenTelemetry.
  • Painel 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 contêineres e volumes e começar de um ambiente limpo: 
make clean-docker

​
Próximos passos

Novo no Midaz? Comece pelas 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 em produção

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

Configurando o CRM

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

Estender com plugins

Adicione Fees Engine, Pix e outras capacidades ao seu deploy do Midaz.