Skip to main content
Uma implementação confiável do Midaz depende de algumas escolhas estruturais feitas logo no início. Evite os erros comuns abaixo para manter os saldos precisos e o acesso sob controle.

​
Estruturação inadequada do Ledger

  • Erro: Você projeta ledgers complexos demais ou simples demais. Por exemplo, um ledger por cliente cria fragmentação. Agrupar processos não relacionados cria confusão.
  • Boa prática: Estruture os ledgers em torno de áreas de negócio principais ou entidades legais. Use agrupamentos organizados em vez de uma abordagem um-para-um. Isso melhora a gerenciabilidade e as transferências internas.

​
Não usar Portfolios para clientes

  • Erro: Você trata cada conta isoladamente em vez de agrupá-la sob um portfolio. Isso dificulta rastrear todas as contas vinculadas a um único cliente.
  • Boa prática: Crie um portfolio para cada cliente. Agrupe suas contas para consultas simples, gestão de relacionamento e relatórios.

​
Misturar Ativos em uma Conta

  • Erro: Você gerencia múltiplas moedas ou tipos de ativos em uma única conta, muitas vezes por meio de sobrescritas de metadata. Isso leva a saldos pouco claros e inconsistências nos relatórios.
  • Boa prática: Atribua um ativo por conta. Se um cliente precisar de suporte a múltiplas moedas, crie contas separadas. Use convenções de nomenclatura ou portfolios para estruturá-las.

​
Rotas de Contabilização inadequadas

  • Erro: Você envia transações sem Rotas de Operação ou Rotas de Contabilização (Transaction Routes na API) devidamente configuradas. Isso causa validações inconsistentes, fundos roteados incorretamente e dados de ledger não confiáveis.
  • Boa prática: Defina Rotas de Contabilização que reflitam sua lógica de negócio e seus requisitos de compliance, depois defina a configuração de Ledger accounting.validateRoutes como true para aplicá-las. O padrão é false. Use Rotas de Operação para validar a origem e o destino de cada operação quando a validação de rotas estiver habilitada. Rotas estruturadas mantêm cada transação auditável.

​
Negligenciar o tratamento de Contas externas

  • Erro: Você trata mal as transações externas. Por exemplo, você exclui uma conta quando os fundos saem do banco, o que causa desequilíbrios.
  • Boa prática: Use a Conta canônica @external/<asset-code> (por exemplo, @external/BRL) para o dinheiro que entra e sai do Midaz. Isso mantém o ledger equilibrado e corresponde aos extratos bancários reais.

​
Falhas de segurança no controle de acesso

  • Erro: Você concede privilégios excessivos a administradores ou usa contas compartilhadas. Isso compromete a segurança e a responsabilização.
  • Boa prática: Implemente controle de acesso baseado em papéis (RBAC) desde o início. Não use contas root ou admin para operações do dia a dia. Aplique uma gestão rigorosa de credenciais. Audite as permissões regularmente para evitar escalonamento de privilégios não autorizado.

​
Tratamento inadequado de erros em transações

  • Erro: Você deixa de tratar transações que falham na camada de integração. Isso leva a suposições falsas sobre operações bem-sucedidas.
  • Boa prática: Sempre valide as respostas da API de transações. Implemente mecanismos de retry com backoff para erros transitórios. Registre falhas permanentes. Garanta que sistemas upstream, como aplicações de core banking, tratem transações rejeitadas e notifiquem o usuário.