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
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
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
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
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.
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 o Roteamento de Transações
Use Operation Routes e Transaction Routes para definir e aplicar validação estruturada para suas transações.- Comece criando as Operation Routes, 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, 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).
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
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
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 estiverem habilitados, o campo
typetorna-se obrigatório e deve corresponder a um dos valores pré-registrados. - Use aliases de conta para simplificar operações subsequentes.
Passo 3: Aplicar segmentação
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
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
routedo 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.
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.