> ## 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 > Execute o Midaz localmente, crie sua primeira organização, Ledger, contas e processe sua primeira transação em menos de 10 minutos. 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](https://go.dev/dl/) | 1.26+ | `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 é 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. ```bash Terminal theme={null} 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: ```bash Terminal theme={null} 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. ```bash Terminal theme={null} make infra COMMAND=up ``` Aguarde até que todos os contêineres reportem um 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 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: ```bash Terminal theme={null} 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: ```bash Terminal theme={null} 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](/pt/reference/midaz/create-an-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 — 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](/pt/reference/midaz/create-a-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 — 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](/pt/reference/midaz/create-an-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 — 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](/pt/reference/midaz/create-an-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 — 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](/pt/reference/midaz/create-a-transaction-using-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" } } ] } } }' ``` 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](/pt/reference/midaz/retrieve-a-balance-by-account-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. ## 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: ```bash Terminal theme={null} make down ``` Para remover contêineres e volumes e começar de um ambiente limpo: ```bash Terminal theme={null} make clean-docker ``` ## Próximos passos *** Novo no Midaz? Comece pelas [Entidades do Midaz](/pt/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 chart oficial do Helm. Gerencie titulares e contas alias para conectar identidades do mundo real às suas contas no Midaz. Adicione Fees Engine, Pix e outras capacidades ao seu deploy do Midaz.