> ## 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 o Midaz localmente em cerca de dez minutos: clone o repositório, inicie a infraestrutura, crie sua primeira Organização, Ledger, Contas e processe uma primeira transação. 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](https://go.dev/dl/) | 1.26.4+ | `go version` | | [Docker](https://docs.docker.com/get-docker/) | 24+ | `docker --version` | | [Docker Compose](https://docs.docker.com/compose/install/) | 2.20+ | `docker compose version` | | [Make](https://www.gnu.org/software/make/) | 3.81+ | `make --version` | | [Git](https://git-scm.com/) | 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. ```bash Terminal theme={null} 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: ```bash Terminal theme={null} 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. ```bash Terminal theme={null} make infra COMMAND=up ``` Aguarde até que todos os containers reportem status saudável. Verifique o status deles com: ```bash Terminal theme={null} 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: ```bash Terminal theme={null} 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: ```bash Terminal theme={null} 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](/pt/reference/products/midaz/v2/create-organization). ```bash Terminal theme={null} 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](/pt/reference/products/midaz/v2/create-ledger). ```bash Terminal theme={null} 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](/pt/reference/products/midaz/v2/create-asset). ```bash Terminal theme={null} 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](/pt/reference/products/midaz/v2/create-account). Crie uma conta de origem: ```bash Terminal theme={null} 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: ```bash Terminal theme={null} 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](/pt/reference/products/midaz/v1/create-transaction-json). ```bash Terminal theme={null} 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](/pt/reference/products/midaz/v2/get-balances-by-alias). ```bash Terminal theme={null} 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: ```bash Terminal theme={null} make down ``` Para remover containers e volumes e começar em um ambiente limpo: ```bash Terminal theme={null} make clean-docker ``` ## Próximos passos *** Novo no Midaz? Comece com [Entidades do Midaz](/pt/products/midaz/core-entities) para entender organizações, ledgers, contas e transações. Aprenda as diferentes formas de criar transações, incluindo JSON, inflow e outflow, e quando usar cada uma. Faça o deploy do Midaz no Kubernetes usando o Helm chart oficial. Gerencie titulares e contas alias para conectar identidades do mundo real às suas contas do Midaz. Adicione o Fees Engine, Pix e outras capacidades ao seu deploy do Midaz.