Skip to main content
Você já explorou como o Midaz funciona, desde suas entidades principais até sua arquitetura e segurança. Esta página transforma esse conhecimento em uma configuração funcional. Um fluxo de trabalho estruturado mantém cada transação clara, rastreável e auditável desde o início. Siga os passos abaixo em ordem. Eles configuram sua Organização, Ledgers, Ativos, Account Types e Contas.

​
Configurando e gerenciando Ledgers

Ao fazer o onboarding no Midaz, siga estes passos para construir uma base sólida para sua infraestrutura financeira:
Fluxo de trabalho para configurar e gerenciar ledgers durante a integração ao Midaz

Figura 1. Fluxo de trabalho para configuração e gerenciamento de ledgers.

​
Passo 1: Configurar a Organização

Sua organização no Midaz representa seu banco ou entidade empresarial. Se você ainda não a criou, configure-a no Console ou API. Certifique-se de que os detalhes essenciais estejam corretos, como a razão social e os identificadores. Esse contexto é a base de todas as operações do ledger.

​
Passo 2: Criar os Ledgers

Crie um Ledger sob sua organização para armazenar registros financeiros. A maioria das configurações começa com um ledger principal para todas as operações voltadas ao cliente (por exemplo, “Ledger Bancário Principal”). No início ele não contém contas. Ele serve como camada base para toda atividade financeira.

​
Passo 3: Definir tipos de Assets

Registre os assets que seu ledger suporta. Esses podem incluir moedas (por exemplo, BRL, USD), pontos ou tokens cripto. Você usa esses assets em toda a configuração de contas e transações. Você pode adicionar mais assets conforme seu portfólio de produtos cresce.

​
Passo 4: Criar Account Types

Para aplicar regras de classificação de contas, defina seus Account Types. Essas são categorias estruturadas, por exemplo user_wallet, treasury ou revenue. Você as referencia mais tarde durante a criação de contas ou a validação de transações.
Quando você habilita a validação de Account Type, cada nova conta deve usar um Account Type registrado. Por padrão, os Account Types são opcionais. Isso mantém a classificação consistente em todo o seu ledger.
Cada Account Type tem um keyValue. O keyValue deve ser único e alfanumérico, com hífens e underscores permitidos. Você usa esses identificadores em fluxos de validação e transaction routes.

​
Passo 5: Configurar Rotas Contábeis

Use Operation Routes e a Transaction Route (o recurso transactionRoute na API) para definir e aplicar a validação das suas transações.
  • Primeiro, crie as Operation Routes. Cada Operation Route valida uma perna da transação. Por exemplo, 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. Ela combina as operation routes individuais em um fluxo completo. Um exemplo é uma transação de saque com validações específicas de débito e crédito.
Depois que você configura o roteamento e habilita a validação no ledger, todas as transações devem estar em conformidade com a estrutura de roteamento definida. O Midaz rejeita qualquer transação que não esteja em conformidade.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, por exemplo “Testes”, “Interno” ou “Multi-entidade”. Documente a propriedade deles.
  • Revise e reconcilie os dados do ledger com regularidade, especialmente quando você integra com sistemas de liquidação externos.
  • O Midaz aplica lógica de partidas dobradas, então cada movimentação é totalmente rastreável. Não altere os saldos manualmente.

​
Configurando Contas, Portfólios e Segmentos

Esta seção mostra como estruturar dados de clientes e permissões de produtos no Midaz.
Fluxo de trabalho para configurar contas, portfólios e segmentos a fim de estruturar os dados de clientes e os direitos de produto no Midaz

Figura 2. Fluxo de trabalho para configuração de Contas, Portfólios e Segmentos.

​
Passo 1: Criar um Portfolio para o cliente

Crie 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 (por exemplo, um Entity ID).

​
Passo 2: Configurar Contas do cliente

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 você habilitar Account Types, o campo type deve corresponder a um dos valores pré-registrados.
  • Use aliases de conta para simplificar operações subsequentes.
Account Types padronizam a categorização de contas em todo o seu ecossistema. Eles melhoram roteamento, relatórios e integrações.

​
Passo 3: Aplicar segmentação

Use Segmentos para categorizar portfólios ou contas (por exemplo, standard, vip, enterprise). Essas tags impulsionam lógica dinâmica baseada na segmentação de clientes, como isenção de taxas ou juros escalonados.

​
Passo 4: Criar sub-contas (opcional)

Para organizações ou casos especiais, você pode configurar sub-contas. Use convenções de nomenclatura claras para manter a rastreabilidade (por exemplo, “Acme USD - Folha de Pagamento”).

​
Passo 5: Definir o saldo inicial

Use a API de Transactions para adicionar o saldo de abertura. Isso mantém a rastreabilidade e a conformidade com partidas dobradas:
  • Debite a fonte de financiamento.
  • Credite a nova conta.
  • Não atualize os saldos manualmente. O Midaz rastreia cada valor via transações.

​
Passo 6: Verificar e revisar

Antes de executar operações, verifique o seguinte:
  • Confirme que cada conta tem os assets e tipos corretos.
  • Valide os saldos das contas.
  • Verifique que você aplicou a segmentação.
  • Confirme a configuração na API ou no Console.

​
Passo 7: Gestão contínua de Contas

Gerencie as operações de ciclo de vida via API ou Console para manter a integridade do sistema:
  • 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.
Fluxo de trabalho para implementar a gestão de transações por partidas dobradas, em que cada transação carrega pelo menos uma operação de débito e uma de crédito

Figura 3. Fluxo de trabalho para implementação de gestão de transações com partidas dobradas

​
Passo 1: Estruturar a transação

Estruture seu objeto Transaction:
  • Depois que você configura sua Transaction Route, insira seu ID no campo route do payload da transação.
  • Defina as contas de origem e destino, com seus detalhes de asset e valor.
  • Adicione metadata descritiva para manter a rastreabilidade e a clareza.

​
Passo 2: Escolher seu método de integração

Use a API de Transações para criar transações de forma programática.

​
Passo 3: Aplicar validação de partidas dobradas

O Midaz verifica que a soma dos créditos é igual à soma dos débitos. O Midaz rejeita uma transação que tem uma incompatibilidade ou uma violação estrutural.

​
Passo 4: Implementar idempotência

Use chaves de idempotência para evitar duplicatas em retentativas de rede. O Midaz reconhece uma chave repetida e reproduz a resposta original em vez de processar a solicitação duas vezes.

​
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

Não edite nem exclua transações. Submeta um estorno em vez disso. O Midaz vincula cada estorno à sua transação original 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 mantém atomicidade em todas as pernas. Ou a transação completa é lançada, ou nada é.