Pular para o conteúdo principal
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.

​
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 retries com backoff para erros transitórios e envie a mesma chave X-Idempotency em cada retry. Registre falhas permanentes. Garanta que sistemas upstream, como aplicações de core banking, tratem transações rejeitadas e notifiquem o usuário.