Primeiros passos com o Midaz

Neste guia, você configura um ambiente Midaz funcional. Em seguida, você percorre o fluxo de trabalho 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 seu caso de uso. 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+	`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 é executado em macOS (Apple Silicon e Intel) e Linux (amd64). No Windows, execute-o 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 usa 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 funcionam para desenvolvimento local. Você não precisa alterá-los.

Passo 3 — Iniciar a infraestrutura

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

make infra COMMAND=up

Aguarde até que todos os contêineres reportem um status saudável. Verifique o status deles com:

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

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

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

Passo 4 — Iniciar o Midaz

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

make up

Este comando inicia a infraestrutura, se necessário, e os serviços do Midaz. Todas as APIs estão disponíveis na porta 3002. Verifique se o Midaz responde:

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, ela corresponde à entidade legal que contém seus ledgers, contas e transações.

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 usa 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 ledger tem 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. Também pode ser pontos de fidelidade, tokens cripto, títulos ou qualquer unidade personalizada que seu negócio rastreie. 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 comerciante ou uma reserva interna. Cada conta se vincula 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: ela move valor entre contas com rastreabilidade completa. O Midaz registra cada transação como uma operação balanceada. Ela debita a origem e credita 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 usa valores inteiros para evitar erros de ponto flutuante. Esta é uma prática padrão em sistemas financeiros.

Passo 10 — Verificar o saldo

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

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 que processa transações reais.

Explorar a API

O Midaz pode servir sua especificação OpenAPI 3.1 e documentação interativa da API. Essa superfície de documentação está desativada por padrão. Para ativá-la, defina LEDGER_HUMA_DOCS_ENABLED=true em components/ledger/.env e reinicie o Midaz. Em seguida, 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 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.

​Pré-requisitos

​Passo 1 — Clonar o repositório

​Passo 2 — Configurar os arquivos de ambiente

​Passo 3 — Iniciar a infraestrutura

​Passo 4 — Iniciar o Midaz

​Passo 5 — Criar uma organização

​Passo 6 — Criar um ledger

​Passo 7 — Criar um ativo

​Passo 8 — Criar contas

​Passo 9 — Processar sua primeira transação

​Passo 10 — Verificar o saldo

​Explorar a API

​Observabilidade

​Parando o Midaz

​Próximos passos

Criando transações

Deploy em produção

Configurando o CRM

Estender com plugins

Pré-requisitos

Passo 1 — Clonar o repositório

Passo 2 — Configurar os arquivos de ambiente

Passo 3 — Iniciar a infraestrutura

Passo 4 — Iniciar o Midaz

Passo 5 — Criar uma organização

Passo 6 — Criar um ledger

Passo 7 — Criar um ativo

Passo 8 — Criar contas

Passo 9 — Processar sua primeira transação

Passo 10 — Verificar o saldo

Explorar a API

Observabilidade

Parando o Midaz

Próximos passos