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

# Mejores prácticas

> Aplica mejores prácticas operacionales, de integración y gestión de datos para desplegar y usar el CRM de Midaz en producción con seguridad y trazabilidad.

CRM gestiona datos sensibles relacionados con la identidad. Estas prácticas te ayudan a integrar CRM correctamente, proteger esos datos y ejecutarlo de forma segura en producción.

Estas recomendaciones complementan la guía de [Seguridad de datos del CRM](/es/midaz/crm/crm-data-security), que cubre cifrado, hashing y gestión de claves en detalle.

## 1. Sigue el flujo correcto de integración

***

CRM depende de un orden específico para crear entidades. Si te saltas pasos o creas entidades fuera de orden, puedes romper integraciones y perder datos en flujos posteriores.

El flujo esperado es:

1. **Crear el holder** — el individuo o la organización.
2. **Vincular el holder a una cuenta del ledger de Midaz** — asocia el holder con una cuenta que ya existe en el ledger.
3. **Asegúrate de que ambos existan** — antes de iniciar cualquier flujo posterior.

Sin un holder vinculado a una cuenta del ledger, la mayoría de las funcionalidades impulsadas por CRM (tarifas, notificaciones, facturación, verificación de identidad) no funcionan como se espera.

<Warning>
  Asegúrate de que tus identificadores sean correctos antes de crear o vincular registros. La API de CRM **no** valida la exactitud de los datos que envías. Un `ledgerId` o `accountId` que no coincida puede causar fallos de integración con el ledger u otros componentes.
</Warning>

## 2. Protege tus claves de cifrado

***

CRM cifra y aplica hash a los campos sensibles antes de almacenarlos. La seguridad de estos datos depende completamente de cómo gestionas tus claves.

* **Genera claves únicas** para `LCRYPTO_HASH_SECRET_KEY` y `LCRYPTO_ENCRYPT_SECRET_KEY` con `openssl rand -hex 32`.
* **Almacena las claves en un gestor de secretos** (AWS Secrets Manager, Azure Key Vault, HashiCorp Vault o equivalente). Nunca las codifiques directamente en archivos de configuración, código fuente o control de versiones.
* **Planifica la rotación de claves.** Si una clave se ve comprometida, genera una nueva y re-cifra todos los datos afectados. Este es un proceso manual, así que diseña tus runbooks operacionales para ello.
* **Usa Kubernetes Secrets** en producción. Referencia secretos existentes vía `useExistingSecret` y `existingSecretName` en tus valores de Helm en lugar de almacenar claves inline.

Para la lista completa de campos protegidos y estrategias de cifrado, consulta [Seguridad de datos del CRM](/es/midaz/crm/crm-data-security).

## 3. Nunca almacenes datos sensibles en metadata

***

El objeto `metadata` en las entidades de CRM **no está cifrado**. CRM lo almacena en texto plano solo para información auxiliar no sensible.

No uses metadata para:

* Números de identificación personal (CPF, SSN, pasaporte)
* Detalles de cuentas financieras
* Información de contacto (email, teléfono)
* Cualquier dato sujeto a LGPD, GDPR o regulaciones similares

Si necesitas almacenar un atributo sensible que no está en la [lista de campos protegidos](/es/midaz/crm/crm-data-security#protected-fields), contacta a tu representante de Lerian para discutir opciones.

## 4. No expongas CRM directamente en capas de borde

***

CRM se ejecuta dentro del ledger de Midaz y expone una API interna. Si lo expones directamente a través de API gateways, balanceadores de carga o aplicaciones frontend, aumentas tu superficie de ataque. También eludes los controles de acceso a nivel de aplicación.

En su lugar:

* Enruta el tráfico de CRM a través de tus **servicios backend** o una capa de API interna.
* Usa [Access Manager](/es/platform/access-manager/access-manager) para aplicar autenticación y autorización si necesitas control granular.
* Restringe el acceso de red a los pods del ledger con Kubernetes NetworkPolicies o los grupos de seguridad de tu proveedor de nube.

## 5. Usa soft delete como opción predeterminada

***

CRM soporta tanto **soft delete** como **hard delete**:

* **Soft delete** (predeterminado): CRM marca el registro con un timestamp `deletedAt`. El registro deja de aparecer en las consultas estándar pero permanece en la base de datos para auditoría y recuperación.
* **Hard delete**: CRM solicita la eliminación del registro, sujeta a las reglas de retención y cumplimiento de tu implementación. Cuando obligaciones legales, regulatorias, de auditoría o de conservación de registros exigen la retención, CRM no garantiza la eliminación física.

Para la mayoría de los casos, soft delete es la opción más segura. Preserva las pistas de auditoría y te permite recuperar datos que eliminas por error. Reserva hard delete para casos donde las regulaciones exigen eliminación completa (por ejemplo, solicitudes de derecho al olvido del GDPR).

<Note>
  Confirma tu política de retención y de retención legal (legal hold) antes de ejecutar un hard delete. El derecho al olvido del GDPR (Artículo 17) no es absoluto. Cuando obligaciones legales, regulatorias, de auditoría o de conservación de registros exigen la retención de datos, estas pueden prevalecer y restringir la supresión.
</Note>

## 6. Valida los datos antes de enviarlos a CRM

***

CRM actúa como una **capa de datos neutral y persistente**. No aplica reglas de negocio, no valida formatos de documentos ni verifica cumplimiento KYC. La integridad de los datos es tu responsabilidad.

Antes de crear o actualizar un registro:

* Valida los formatos de documentos (CPF, CNPJ, números de pasaporte) en tu capa de aplicación.
* Asegúrate de que los valores de `ledgerId` y `accountId` apunten a entidades reales en Midaz.
* Sanitiza las entradas para no almacenar datos malformados o inconsistentes.

## 7. Mantén CRM y Midaz alineados en versiones

***

CRM se distribuye dentro del binario del ledger de Midaz, por lo que comparte la versión de Midaz. Antes de actualizar:

* Consulta la [tabla de compatibilidad de versiones](/es/platform/plugins/midaz-version-compatibility) para confirmar tu versión objetivo.
* Prueba la actualización en un entorno de staging antes de aplicarla en producción.
* Haz respaldo de tus datos de MongoDB y valores de Helm antes de cualquier actualización mayor.

Para procedimientos de actualización, consulta la [guía de actualización de Helm](/es/platform/helm/midaz/midaz-upgrade-guide).

## 8. Monitorea la salud y el rendimiento de la base de datos

***

CRM usa MongoDB para almacenamiento de datos. En producción:

* **Monitorea el uso del pool de conexiones.** El valor predeterminado de `MONGO_CRM_MAX_POOL_SIZE` es 1000. Ajústalo según tus patrones de tráfico y cantidad de réplicas.
* **Configura alertas** para uso de disco de MongoDB, retraso de replicación y saturación de conexiones.
* **Habilita respaldos.** Ya sea que uses el MongoDB Bitnami incluido o una instancia externa, ejecuta respaldos automatizados y pruébalos regularmente.
* **Habilita OpenTelemetry** (`ENABLE_TELEMETRY: true`) para recolectar trazas y métricas del CRM. Intégralo con tu stack de observabilidad para visibilidad de extremo a extremo.

## 9. Revisa las recomendaciones de seguridad

***

CRM maneja datos personales y sensibles. Más allá de las prácticas específicas de CRM, asegúrate de que tu despliegue siga las [Recomendaciones de seguridad](/es/midaz/security-recommendations) de la plataforma, que cubren:

* Segmentación de red y Arquitectura Zero Trust
* Aplicación de TLS 1.2+ para todas las comunicaciones
* Configuración de IAM y RBAC
* Planificación de respuesta a incidentes
* Gestión de parches y escaneo de vulnerabilidades