> ## 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.
# Fluxo de trabalho recomendado
> Siga o fluxo de onboarding recomendado para configurar Organizações, Ledgers, Ativos e Contas passo a passo no Midaz.
Você já explorou como o Midaz funciona — desde suas entidades principais até sua arquitetura, lógica e segurança. Agora é hora de colocar esse conhecimento em prática.
Seja lançando um produto fintech ou modernizando sistemas internos, **fluxos de trabalho estruturados são a chave para traduzir os conceitos do Midaz em operações financeiras do mundo real**. Gerentes de produto e engenheiros desempenham um papel central nesse processo — especialmente no Modelo Community, onde as funcionalidades principais são auto-hospedadas e sem plugins.
Pense em cada transação como um evento do ledger. Com essa mentalidade, os fluxos de trabalho descritos aqui ajudarão você a aplicar tudo o que aprendeu — garantindo clareza, rastreabilidade e auditabilidade desde o início.
## Configurando e gerenciando Ledgers
***
Ao fazer o onboarding no Midaz, siga estes passos-chave para estabelecer uma base sólida para sua infraestrutura financeira:
### Passo 1: [Configurar a Organização](/pt/reference/midaz/create-an-organization)
Sua organização no Midaz representa seu banco ou entidade empresarial. Se ela ainda não foi criada, configure-a via Console ou API. Certifique-se de que todos os detalhes essenciais, como razão social e identificadores, estejam corretos, pois esse contexto será a base de todas as operações do ledger.
### Passo 2: [Criar os Ledgers](/pt/reference/midaz/create-a-ledger)
Crie um Ledger sob sua organização para armazenar registros financeiros. É comum começar com um ledger principal para todas as operações voltadas ao cliente (ex.: "Ledger Bancário Principal"). Inicialmente, ele não conterá contas, mas serve como camada base para toda atividade financeira.
### Passo 3: [Definir tipos de Assets](/pt/reference/midaz/create-an-asset)
Registre os assets que seu ledger suportará — isso pode incluir moedas (ex.: BRL, USD), pontos ou até tokens cripto. Esses assets serão usados em toda a configuração de contas e transações. Assets podem ser expandidos conforme seu portfólio de produtos evolui.
### Passo 4: [Criar Account Types](/pt/reference/midaz/create-an-account-type)
Se você planeja aplicar regras de classificação de contas, defina seus **Account Types**. Eles representam categorias estruturadas (ex.: `user_wallet`, `treasury`, `revenue`) que podem ser referenciadas posteriormente durante a criação de contas ou validação de transações.
Account Types são opcionais por padrão, mas quando **habilitados**, tornam-se obrigatórios durante a criação de contas para garantir consistência de classificação em todo o seu ledger.
Cada Account Type tem um `keyValue`, que deve ser único e alfanumérico (hífens e underscores são permitidos). Esses identificadores serão usados em fluxos de validação e transaction routes.
### Passo 5: Configurar Rotas Contábeis
Use **Operation Routes** e **Rotas Contábeis** (o recurso `transactionRoute` na API) para definir e aplicar validação estruturada para suas transações.
* Comece [**criando as Operation Routes**](/pt/reference/midaz/create-an-operation-route), que validam cada perna da transação individualmente (ex.: o débito deve vir de uma conta do tipo `user_wallet`, e o crédito deve ir para o alias `@external/BRL`).
* Em seguida, [**crie a Transaction Route**](/pt/reference/midaz/create-transaction-route), combinando as operation routes individuais em um fluxo completo (ex.: uma transação de saque com validações específicas de débito e crédito).
Uma vez que o roteamento esteja configurado e a validação habilitada no ledger, todas as transações submetidas devem estar em conformidade com a estrutura de roteamento definida — caso contrário, serão rejeitadas.
O campo `route` no payload da transação deve incluir o ID da **Transaction Route** que você criou.
### Passo 6: Gerenciar seus Ledgers
Mantenha seus ledgers organizados e escaláveis com as seguintes boas práticas:
* Use o sistema RBAC do Midaz para atribuir permissões e controlar acesso por ledger.
* Planeje ledgers separados quando necessário (ex.: "Testes", "Interno", "Multi-entidade") e documente a propriedade.
* Revise e reconcilie periodicamente os dados do ledger, especialmente ao integrar com sistemas de liquidação externos.
* O Midaz aplica lógica de partidas dobradas, então cada movimentação é totalmente rastreável — sem alterações manuais de saldo.
## Configurando Contas, Portfólios e Segmentos
***
Esta seção ajuda você a estruturar dados de clientes e permissões de produtos no Midaz.
### Passo 1: [Criar um Portfolio para o cliente](/pt/reference/midaz/create-a-portfolio)
Comece criando um **Portfolio** para cada novo cliente. Portfólios funcionam como contêineres lógicos para contas. Vincule cada portfolio ao seu CRM ou sistema interno via metadata (ex.: Entity ID).
### Passo 2: [Configurar Contas do cliente](/pt/reference/midaz/create-an-account)
Cada produto financeiro ou asset que o cliente possui se torna uma **Conta** separada sob seu portfolio.
* Uma conta corrente em BRL e uma conta poupança em USD são contas separadas.
* Se [Account Types](/pt/reference/midaz/create-an-account-type) estiverem habilitados, o campo `type` torna-se obrigatório e deve corresponder a um dos valores pré-registrados.
* Use aliases de conta para simplificar operações subsequentes.
Account Types ajudam a padronizar a categorização de contas em todo o seu ecossistema — melhorando roteamento, relatórios e integrações.
### Passo 3: [Aplicar segmentação](/pt/reference/midaz/create-a-segment)
Use Segmentos para categorizar Portfólios ou contas (ex.: `standard`, `vip`, `enterprise`). Essas tags permitem lógica dinâmica (ex.: isenção de taxas, juros escalonados) baseada na segmentação de clientes.
### Passo 4: Criar sub-contas (opcional)
Para organizações ou casos especializados, você pode configurar sub-contas. Use convenções de nomenclatura claras para manter a rastreabilidade (ex.: "Acme USD - Folha de Pagamento").
### Passo 5: [Definir o saldo inicial](/pt/reference/midaz/create-a-transaction-using-json)
Use a **API de Transactions** para injetar o saldo de abertura. Isso garante rastreabilidade e conformidade com partidas dobradas:
* Debite a fonte de financiamento.
* Credite a nova conta.
* Não atualize saldos manualmente — o Midaz rastreia cada valor via transações.
### Passo 6: Verificar e revisar
Antes de prosseguir com as operações:
* Confirme que as contas foram criadas com os assets e tipos corretos.
* Valide os saldos das contas.
* Verifique se a segmentação foi aplicada.
* Confirme a configuração via API ou Console.
### Passo 7: Gestão contínua de Contas
Mantenha a integridade do sistema gerenciando operações de ciclo de vida via API ou Console:
* Atualize detalhes das contas conforme necessário.
* Encerre contas somente quando o saldo chegar a zero.
* Reclassifique Portfólios/contas se a segmentação mudar.
## Implementando gestão de transações com partidas dobradas
***
O Midaz garante a integridade do ledger por meio da aplicação rigorosa da lógica de partidas dobradas. Toda transação deve conter pelo menos uma operação de débito e uma de crédito.
### Passo 1: Estruturar a transação
Comece estruturando seu objeto **Transaction**:
* **Uma vez que sua Transaction Route esteja configurada**, insira seu ID no campo `route` do payload da transação.
* Defina as contas de origem e destino, incluindo detalhes de asset e valor.
* Adicione metadata descritiva para garantir rastreabilidade e clareza.
### Passo 2: Escolher seu método de integração
Você pode definir transações via:
* **Transaction DSL (Gold Language)** — uma sintaxe legível por humanos para prototipagem rápida.
* **API de Transactions** — para controle total e execução programática.
Ambas as abordagens são totalmente suportadas e produzem lançamentos idênticos no ledger.
### Passo 3: Aplicar validação de partidas dobradas
O Midaz verifica automaticamente que a soma dos créditos é igual à soma dos débitos. Incompatibilidades ou violações estruturais rejeitarão a transação na submissão.
### Passo 4: Implementar idempotência
Use chaves de idempotência para evitar duplicatas em retentativas de rede. O Midaz reconhecerá chaves repetidas e evitará processamento duplicado.
### Passo 5: Rastrear e reconciliar transações
Use as ferramentas integradas para:
* Rastrear transações submetidas e lançadas.
* Auditar metadata e timestamps.
* Reconciliar lotes de transações para conformidade.
### Passo 6: Submeter correções via estornos
Em vez de editar ou excluir transações, submeta lançamentos corretivos. Cada estorno é vinculado ao original via metadata da transação para rastreabilidade completa.
### Passo 7: Otimizar fluxos de trabalho complexos
Use transações multi-operação para:
* Processar acúmulo de juros.
* Executar pagamentos em lote.
* Lidar com fluxos condicionais com lógica de roteamento.
O Midaz garante atomicidade em todas as pernas — ou a transação completa é lançada, ou nada é.