> ## 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.

# Erros comuns a evitar

> Evite as armadilhas típicas de implementações do Midaz na estruturação do Ledger, segregação de Ativos, Rotas de Contabilização e Contas externas.

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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.