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

# Errores comunes a evitar

> Evita los errores típicos al implementar Midaz — estructuración de Ledgers, segregación de Activos, Rutas Contables y Cuentas externas.

Asegurar una implementación fluida de Midaz requiere planificación cuidadosa y adhesión a las mejores prácticas. Al evitar estos errores frecuentes, puedes mantener un sistema financiero resiliente, eficiente y seguro.

## Mala estructuración del *Ledger*

***

* **Error:** Diseñar *Ledgers* de una forma que sea demasiado compleja o excesivamente simple. Por ejemplo, crear un *Ledger* por cliente provoca fragmentación, mientras que agrupar procesos no relacionados genera confusión.
* **Mejor Práctica:** Estructura los *Ledgers* en torno a áreas de negocio clave o entidades legales. Utiliza agrupaciones organizadas en lugar de un enfoque uno a uno. Esto mejora la capacidad de gestión y las transferencias internas.

## No usar Portafolios para clientes

***

* **Error:** Tratar cada cuenta de forma aislada en lugar de agruparlas bajo una cartera. Esto dificulta el seguimiento de todas las cuentas vinculadas a un único cliente.
* **Mejor Práctica:** Establece una cartera para cada cliente, agrupando sus cuentas para consultas optimizadas, gestión de relaciones y *reporting*.

## Mezclar Activos en una Cuenta

***

* **Error:** Gestionar múltiples monedas o tipos de activos dentro de una sola cuenta, a menudo mediante la sobrescritura de metadatos. Esto conduce a saldos poco claros e inconsistencias en los informes.
* **Mejor Práctica:** Asigna un solo activo por cuenta. Si un cliente requiere soporte multidivisa, crea cuentas separadas y utiliza convenciones de nomenclatura o portafolios para estructurarlas eficientemente.

## Rutas Contables Inadecuadas

***

* **Error:** Enviar transacciones sin Rutas de Operación (*Operation Routes*) o Rutas Contables (*Transaction Routes* en la API) configuradas correctamente, lo que resulta en validaciones inconsistentes, fondos mal dirigidos y datos de *Ledger* no fiables.
* **Mejor Práctica:** Define y aplica Rutas Contables que reflejen tu lógica de negocio y requisitos de cumplimiento. Utiliza Rutas de Operación para validar el origen y destino de cada operación, asegurando que todas las transacciones sigan patrones estructurados y auditables.

## Descuidar el manejo de Cuentas Externas

***

* **Error:** Manejar incorrectamente las transacciones externas, como eliminar una cuenta cuando los fondos salen del banco, lo que provoca desequilibrios.
* **Mejor Práctica:** Utiliza cuentas **\`@external\`** para todos los flujos de dinero que entran y salen de Midaz. Esto mantiene el saldo del *Ledger* y garantiza que las transacciones se alineen con los extractos bancarios del mundo real.

## Fallos de seguridad en el control de acceso

***

* **Error:** Otorgar privilegios excesivos a los administradores o utilizar cuentas compartidas, comprometiendo la seguridad y la rendición de cuentas.
* **Mejor Práctica:** Implementa el control de acceso basado en roles (**RBAC**) desde el inicio. Evita usar cuentas *root*/administrador para operaciones diarias y aplica prácticas estrictas de gestión de credenciales. Audita los permisos regularmente para prevenir la escalada de privilegios no autorizada.

## Manejo de errores inapropiado en transacciones

***

* **Error:** No gestionar las transacciones fallidas en la capa de integración, lo que lleva a suposiciones erróneas sobre operaciones exitosas.
* **Mejor Práctica:** Valida siempre las respuestas de la *API* de transacciones. Implementa mecanismos de reintento con *backoff* para errores transitorios y registra los fallos permanentes. Asegúrate de que los sistemas ascendentes, como las aplicaciones de banca central, manejen con gracia las transacciones rechazadas y proporcionen notificaciones adecuadas al usuario.

## Asegurando una implementación robusta de Midaz

***

Al abordar proactivamente estas trampas, Midaz puede servir como una columna vertebral financiera de confianza, permitiendo a los equipos centrarse en la innovación en lugar de solucionar problemas evitables. Una implementación bien estructurada, segura y en cumplimiento normativo allana el camino para operaciones bancarias fluidas y éxito a largo plazo.