================================================================================
GUÍA DE INSTALACIÓN DETALLADA - LEGALLYMAIL PARA SALESFORCE
================================================================================

Este documento proporciona instrucciones paso a paso para instalar y configurar
el componente LegallyMail Certified Email en tu organización de Salesforce.

================================================================================
TABLA DE CONTENIDOS
================================================================================
1. Requisitos Previos
2. Preparación del Entorno
3. Descarga del Paquete
4. Instalación mediante Salesforce CLI
5. Configuración Post-Instalación
6. Configuración de la Interfaz de Usuario
7. Verificación de la Instalación
8. Solución de Problemas Comunes

================================================================================
1. REQUISITOS PREVIOS
================================================================================

Antes de comenzar la instalación, asegúrate de tener:

1.1. Una Organización de Salesforce
   - Salesforce Developer Edition (recomendado para pruebas)
   - Salesforce Enterprise, Unlimited o Performance Edition
   - Puedes registrarte gratuitamente en: https://developer.salesforce.com/signup

1.2. Salesforce CLI Instalado
   - Descarga desde: https://developer.salesforce.com/tools/sfdxcli
   - Versión mínima requerida: 2.0.0 o superior
   - Para verificar la instalación, ejecuta en terminal:
     sf --version

1.3. Cuenta de LegallyMail
   - Regístrate en: https://legallymail.com
   - Obtén tu API Token desde el panel de control
   - El token se encuentra en: Configuración > API > Token de Acceso

1.4. Permisos de Usuario
   - Debes tener perfil de "Administrador del Sistema" en Salesforce
   - O permisos para:
     * Modificar todos los datos
     * Personalizar aplicación
     * Gestionar usuarios

================================================================================
2. PREPARACIÓN DEL ENTORNO
================================================================================

2.1. Verificar Salesforce CLI
   Abre una terminal o línea de comandos y ejecuta:
   
   sf --version
   
   Deberías ver algo como:
   @salesforce/cli/2.x.x

2.2. Verificar Conexión a Internet
   El proceso de instalación requiere conexión estable a internet para:
   - Autenticación con Salesforce
   - Descarga de dependencias
   - Despliegue de componentes

2.3. Preparar Credenciales
   Ten a mano:
   - Usuario y contraseña de tu organización Salesforce
   - Tu API Token de LegallyMail

================================================================================
3. DESCARGA DEL PAQUETE
================================================================================

3.1. Descargar el Paquete
   - Visita: https://legallymail.com/download-plugins
   - Localiza el plugin de Salesforce
   - Descarga el archivo: sfdx-project.zip
   - Tamaño aproximado: 50-100 KB

3.2. Extraer el Archivo
   - Descomprime sfdx-project.zip en una ubicación de tu preferencia
   - Ejemplo en Windows: C:\LegallyMail\salesforce_app
   - Ejemplo en Mac/Linux: ~/LegallyMail/salesforce_app
   
   La estructura de carpetas debe verse así:
   salesforce_app/
   ├── force-app/
   │   └── main/
   │       └── default/
   │           ├── classes/
   │           ├── lwc/
   │           ├── objects/
   │           └── tabs/
   ├── sfdx-project.json
   └── README.md

================================================================================
4. INSTALACIÓN MEDIANTE SALESFORCE CLI
================================================================================

4.1. Abrir Terminal en el Directorio del Proyecto
   - Windows: Abre PowerShell o CMD
   - Mac/Linux: Abre Terminal
   - Navega al directorio extraído:
     
     cd C:\LegallyMail\salesforce_app
     
     O en Mac/Linux:
     
     cd ~/LegallyMail/salesforce_app

4.2. Autenticarse en Salesforce
   Ejecuta el siguiente comando:
   
   sf org login web --set-default
   
   Esto abrirá una ventana del navegador:
   - Ingresa tu usuario y contraseña de Salesforce
   - Haz clic en "Permitir" cuando se solicite autorización
   - La terminal mostrará: "Successfully authorized [tu-usuario]"
   
   NOTA: Si ya tienes una sesión activa, puedes usar:
   sf org login web --alias legallymail-org

4.3. Verificar la Conexión
   Ejecuta:
   
   sf org display
   
   Deberías ver información de tu organización:
   - Org ID
   - Username
   - Instance URL
   - Access Token (parcialmente oculto)

4.4. Desplegar el Código Fuente
   Ejecuta el comando de despliegue:
   
   sf project deploy start
   
   El proceso puede tardar 1-3 minutos. Verás una salida similar a:
   
   Deploying v58.0 metadata to [tu-org]...
   ✓ Preparing deployment
   ✓ Deploying metadata
   ✓ Running tests
   
   Deploy Succeeded.
   
   IMPORTANTE: Si ves errores, consulta la sección 8 (Solución de Problemas).

4.5. Verificar el Despliegue
   Ejecuta:
   
   sf project deploy report
   
   Esto mostrará un resumen de los componentes desplegados:
   - ApexClass: LegallyMailService, LegallyMailController
   - CustomObject: LegallyMail_Log__c, LegallyMail_Template__c
   - LightningComponentBundle: legallyMailSender, legallyMailBulkSend
   - CustomTab: LegallyMail_Logs, LegallyMail_Templates

================================================================================
5. CONFIGURACIÓN POST-INSTALACIÓN
================================================================================

Una vez desplegado el código, debes configurar algunos ajustes en Salesforce:

5.1. CONFIGURAR REMOTE SITE SETTINGS
   
   Salesforce requiere autorización explícita para conectarse a APIs externas.
   
   Paso 1: Acceder a Setup
   - Inicia sesión en tu organización Salesforce
   - Haz clic en el icono de engranaje (⚙️) en la esquina superior derecha
   - Selecciona "Setup" (Configuración)
   
   Paso 2: Buscar Remote Site Settings
   - En el cuadro de búsqueda rápida (Quick Find), escribe: "Remote Site"
   - Haz clic en "Remote Site Settings"
   
   Paso 3: Crear Nuevo Remote Site
   - Haz clic en el botón "New Remote Site"
   - Completa los campos:
     * Remote Site Name: LegallyMailAPI
     * Remote Site URL: https://legallymail.com
     * Description: API endpoint for LegallyMail certified email service
     * Active: ✓ (marcado)
   - Haz clic en "Save"
   
   NOTA: Sin este paso, las llamadas API fallarán con error de endpoint no autorizado.

5.2. CONFIGURAR API TOKEN
   
   Debes proporcionar tu token de API de LegallyMail al código.
   
   OPCIÓN A: Configuración Rápida (Para Desarrollo/Pruebas)
   
   Paso 1: Acceder a Apex Classes
   - En Setup, busca "Apex Classes" en Quick Find
   - Haz clic en "Apex Classes"
   
   Paso 2: Editar LegallyMailService
   - Localiza la clase "LegallyMailService" en la lista
   - Haz clic en "Edit" junto a ella
   
   Paso 3: Actualizar el Token
   - Busca el método getApiToken():
     
     private static String getApiToken() {
         return 'YOUR_API_TOKEN';
     }
   
   - Reemplaza 'YOUR_API_TOKEN' con tu token real de LegallyMail
   - Ejemplo:
     
     private static String getApiToken() {
         return 'lm_live_abc123xyz789def456ghi012jkl345';
     }
   
   - Haz clic en "Save"
   
   OPCIÓN B: Configuración Segura (Para Producción) - RECOMENDADO
   
   Paso 1: Crear Custom Metadata Type
   - En Setup, busca "Custom Metadata Types"
   - Crea un nuevo tipo llamado "LegallyMail_Settings"
   - Agrega un campo de texto: "API_Token__c"
   
   Paso 2: Crear Registro
   - Crea un nuevo registro con tu API Token
   - Label: Default
   - API Token: [tu-token-aquí]
   
   Paso 3: Actualizar el Código
   - Modifica el método getApiToken() para leer desde Custom Metadata:
     
     private static String getApiToken() {
         LegallyMail_Settings__mdt settings = 
             LegallyMail_Settings__mdt.getInstance('Default');
         return settings.API_Token__c;
     }
   
   VENTAJA: El token no está hardcodeado y se puede cambiar sin modificar código.

5.3. CONFIGURAR PERMISOS DE OBJETOS PERSONALIZADOS
   
   Paso 1: Acceder a Permission Sets o Profiles
   - En Setup, busca "Permission Sets" o "Profiles"
   
   Paso 2: Editar Permisos
   - Selecciona el perfil "System Administrator" o crea un Permission Set
   - Ve a "Object Settings"
   - Busca:
     * LegallyMail Log
     * LegallyMail Template
   
   Paso 3: Habilitar Permisos
   - Para cada objeto, habilita:
     ✓ Read
     ✓ Create
     ✓ Edit
     ✓ Delete
     ✓ View All
     ✓ Modify All
   
   - Haz clic en "Save"

================================================================================
6. CONFIGURACIÓN DE LA INTERFAZ DE USUARIO
================================================================================

6.1. AGREGAR COMPONENTE A PÁGINAS DE REGISTRO
   
   Para enviar emails certificados desde registros individuales:
   
   Paso 1: Navegar a un Registro de Contacto
   - Ve a la pestaña "Contacts" (Contactos)
   - Abre cualquier contacto existente o crea uno nuevo
   
   Paso 2: Editar la Página
   - Haz clic en el icono de engranaje (⚙️) en la esquina superior derecha
   - Selecciona "Edit Page" (Editar página)
   - Se abrirá el Lightning App Builder
   
   Paso 3: Agregar el Componente
   - En el panel izquierdo, busca "Custom" (Personalizados)
   - Localiza el componente: "legallyMailSender"
   - Arrastra y suelta el componente en la página
   - Ubicación recomendada: Columna derecha, debajo de detalles del contacto
   
   Paso 4: Configurar el Componente (Opcional)
   - Selecciona el componente en la página
   - En el panel derecho, puedes ajustar:
     * Altura del componente
     * Visibilidad condicional
   
   Paso 5: Guardar y Activar
   - Haz clic en "Save" (Guardar)
   - Haz clic en "Activate" (Activar)
   - Selecciona "Assign as Org Default" (Asignar como predeterminado de org)
   - Marca las opciones:
     ✓ Desktop
     ✓ Phone
     ✓ Tablet
   - Haz clic en "Next" y luego "Save"
   
   Paso 6: Repetir para Leads
   - Repite los pasos 1-5 para las páginas de Lead (Clientes Potenciales)
   - También puedes agregarlo a Account (Cuentas) si lo deseas

6.2. HABILITAR ENVÍO MASIVO (BULK SENDING)
   
   Para enviar emails certificados a múltiples contactos a la vez:
   
   Paso 1: Acceder a Object Manager
   - En Setup, busca "Object Manager"
   - Haz clic en "Object Manager"
   
   Paso 2: Seleccionar Contact
   - En la lista de objetos, busca y haz clic en "Contact"
   
   Paso 3: Crear Nueva Acción
   - En el menú lateral izquierdo, haz clic en "Buttons, Links, and Actions"
   - Haz clic en "New Action"
   
   Paso 4: Configurar la Acción
   - Action Type: Lightning Web Component
   - Lightning Web Component: c:legallyMailBulkSend
   - Height: 600 (píxeles)
   - Label: Send Certified Email (Bulk)
   - Name: Send_Certified_Email_Bulk
   - Description: Send certified emails to multiple contacts at once
   - Haz clic en "Save"
   
   Paso 5: Agregar a List View
   - Ve a "Search Layouts for Salesforce Classic"
   - Haz clic en "Edit" junto a "List View"
   - NO es necesario agregar aquí para Lightning Experience
   
   Paso 6: Agregar a Lightning List View
   - Sal de Setup
   - Ve a la pestaña "Contacts"
   - Haz clic en el icono de engranaje junto a cualquier vista de lista
   - Selecciona "Select List Display"
   - En "Available Actions", busca "Send Certified Email (Bulk)"
   - Arrástrala a "Selected Actions"
   - Haz clic en "Save"
   
   Paso 7: Repetir para Leads
   - Repite los pasos 2-6 para el objeto Lead

6.3. CONFIGURAR PESTAÑAS DE NAVEGACIÓN
   
   Para acceder fácilmente a logs y plantillas:
   
   Paso 1: Editar App de Navegación
   - Haz clic en el App Launcher (icono de 9 puntos) en la esquina superior izquierda
   - Haz clic en "Edit" junto a "Sales" o la app que uses
   
   Paso 2: Agregar Pestañas
   - En "Available Items", busca:
     * LegallyMail Logs
     * LegallyMail Templates
   - Arrástralas a "Selected Items"
   - Ordénalas según tu preferencia
   
   Paso 3: Guardar
   - Haz clic en "Save"
   
   Ahora podrás acceder a logs y plantillas desde el menú principal.

================================================================================
7. VERIFICACIÓN DE LA INSTALACIÓN
================================================================================

7.1. Verificar Componentes Desplegados
   
   Paso 1: Verificar Apex Classes
   - En Setup, busca "Apex Classes"
   - Confirma que existen:
     ✓ LegallyMailService
     ✓ LegallyMailController
   
   Paso 2: Verificar Lightning Web Components
   - En Setup, busca "Lightning Components"
   - Confirma que existen:
     ✓ legallyMailSender
     ✓ legallyMailBulkSend
   
   Paso 3: Verificar Custom Objects
   - En Setup, busca "Object Manager"
   - Confirma que existen:
     ✓ LegallyMail Log
     ✓ LegallyMail Template

7.2. Prueba de Envío Individual
   
   Paso 1: Crear o Abrir un Contacto
   - Asegúrate de que tenga una dirección de email válida
   
   Paso 2: Usar el Componente
   - Localiza el componente "LegallyMail Certified Email" en la página
   - Verifica que el email del contacto se cargue automáticamente
   
   Paso 3: Enviar Email de Prueba
   - Subject: Test Email
   - Message: This is a test certified email from Salesforce
   - Haz clic en "Send Certified Email"
   
   Paso 4: Verificar Respuesta
   - Deberías ver un mensaje de éxito con un Tracking ID
   - Ejemplo: "Email sent successfully! Tracking ID: LM-2026-ABC123"
   
   Paso 5: Verificar Log
   - Ve a la pestaña "LegallyMail Logs"
   - Deberías ver el email recién enviado
   - Verifica que muestre:
     * Recipient Email
     * Subject
     * Tracking ID
     * Status: Sent

7.3. Prueba de Envío Masivo
   
   Paso 1: Ir a Lista de Contactos
   - Ve a la pestaña "Contacts"
   - Selecciona cualquier vista de lista
   
   Paso 2: Seleccionar Múltiples Contactos
   - Marca las casillas de 2-3 contactos con emails válidos
   
   Paso 3: Ejecutar Acción Masiva
   - Haz clic en el menú desplegable de acciones
   - Selecciona "Send Certified Email (Bulk)"
   
   Paso 4: Completar Formulario
   - Verifica que muestre el número correcto de destinatarios
   - Subject: Bulk Test Email
   - Message: This is a bulk certified email test
   - Haz clic en "Send Bulk"
   
   Paso 5: Verificar Resultados
   - Deberías ver un resumen de envíos exitosos
   - Verifica los logs para confirmar todos los envíos

7.4. Prueba de Plantillas
   
   Paso 1: Crear Plantilla
   - Ve a "LegallyMail Templates"
   - Haz clic en "New"
   - Name: Welcome Email
   - Subject: Welcome to Our Service
   - Body: Dear Customer, welcome to our service...
   - Haz clic en "Save"
   
   Paso 2: Usar Plantilla
   - Abre un contacto
   - En el componente LegallyMail, selecciona la plantilla del dropdown
   - Verifica que Subject y Message se completen automáticamente
   
   Paso 3: Enviar con Plantilla
   - Haz clic en "Send Certified Email"
   - Verifica que se envíe correctamente

================================================================================
8. SOLUCIÓN DE PROBLEMAS COMUNES
================================================================================

8.1. Error: "Remote host closed connection during handshake"
   
   CAUSA: Remote Site Settings no configurado correctamente
   
   SOLUCIÓN:
   - Ve a Setup > Remote Site Settings
   - Verifica que existe "LegallyMailAPI"
   - Verifica que la URL sea exactamente: https://legallymail.com
   - Verifica que esté marcado como "Active"
   - Si existe, elimínalo y créalo de nuevo

8.2. Error: "Unauthorized endpoint"
   
   CAUSA: API Token incorrecto o no configurado
   
   SOLUCIÓN:
   - Ve a Setup > Apex Classes > LegallyMailService
   - Verifica que el token sea correcto
   - Copia el token directamente desde tu cuenta de LegallyMail
   - Asegúrate de no incluir espacios al inicio o final
   - Verifica que el token no haya expirado

8.3. Error: "Component not found on page"
   
   CAUSA: El componente no se agregó a la página o no se activó
   
   SOLUCIÓN:
   - Abre un registro de Contact o Lead
   - Haz clic en ⚙️ > Edit Page
   - Verifica que el componente "legallyMailSender" esté en la página
   - Si no está, agrégalo desde el panel izquierdo
   - Haz clic en Save > Activate > Assign as Org Default

8.4. Error: "Bulk action doesn't appear"
   
   CAUSA: La acción no se agregó a la List View
   
   SOLUCIÓN:
   - Ve a Setup > Object Manager > Contact
   - Haz clic en "Buttons, Links, and Actions"
   - Verifica que existe "Send_Certified_Email_Bulk"
   - Si no existe, créala siguiendo la sección 6.2
   - Ve a la vista de lista de Contacts
   - Haz clic en ⚙️ > Select List Display
   - Agrega la acción a "Selected Actions"

8.5. Error: "Deployment failed"
   
   CAUSA: Conflictos con componentes existentes o permisos insuficientes
   
   SOLUCIÓN:
   - Verifica que tienes permisos de administrador
   - Ejecuta: sf org display
   - Confirma que estás conectado a la org correcta
   - Intenta desplegar de nuevo con modo verbose:
     sf project deploy start --verbose
   - Revisa los mensajes de error específicos
   - Si hay conflictos de nombres, renombra los componentes

8.6. Error: "Email not sent - API error"
   
   CAUSA: Problemas con la API de LegallyMail o saldo insuficiente
   
   SOLUCIÓN:
   - Verifica tu saldo en legallymail.com
   - Verifica que tu cuenta esté activa
   - Revisa los logs de Salesforce:
     Setup > Debug Logs > New
     Reproduce el error
     Revisa el log para ver el mensaje de error exacto
   - Contacta a soporte: support@legallymail.com

8.7. Error: "Invalid email address"
   
   CAUSA: El registro no tiene un email válido
   
   SOLUCIÓN:
   - Verifica que el Contact/Lead tenga un email en el campo "Email"
   - Verifica que el formato sea válido (ejemplo@dominio.com)
   - Actualiza el email y vuelve a intentar

8.8. Componente no carga el email automáticamente
   
   CAUSA: El componente no está detectando el contexto del registro
   
   SOLUCIÓN:
   - Verifica que estás en una página de Contact o Lead
   - Refresca la página (F5)
   - Si persiste, edita la página y reposiciona el componente
   - Verifica en Developer Console si hay errores JavaScript:
     F12 > Console

================================================================================
9. INFORMACIÓN ADICIONAL
================================================================================

9.1. Límites de Salesforce
   - Llamadas API por día: Depende de tu edición de Salesforce
   - Developer Edition: 15,000 llamadas/día
   - Enterprise Edition: 100,000 llamadas/día
   - Cada email certificado consume 1 llamada API

9.2. Límites de LegallyMail
   - Tamaño máximo de adjuntos: 10 MB por archivo
   - Número máximo de adjuntos: 4 por email
   - Formatos soportados: PDF, DOC, DOCX, JPG, PNG
   - Longitud máxima del mensaje: 50,000 caracteres

9.3. Mejores Prácticas
   - Usa plantillas para emails recurrentes
   - Revisa los logs regularmente para monitorear el estado
   - Configura Named Credentials en producción (no hardcodees el token)
   - Haz backup de tus plantillas periódicamente
   - Capacita a los usuarios antes de dar acceso masivo

9.4. Actualizaciones
   - Verifica actualizaciones en: https://legallymail.com/download-plugins
   - Para actualizar, simplemente ejecuta:
     sf project deploy start
   - Los datos existentes (logs, plantillas) se preservarán

9.5. Desinstalación
   Si necesitas desinstalar el componente:
   
   Paso 1: Eliminar de Páginas
   - Remueve el componente de todas las páginas de registro
   
   Paso 2: Eliminar Acciones
   - Elimina las acciones masivas de Contact y Lead
   
   Paso 3: Eliminar Componentes
   - En Setup > Apex Classes, elimina las clases
   - En Setup > Lightning Components, elimina los componentes
   
   Paso 4: Eliminar Objetos (PRECAUCIÓN: Esto eliminará todos los datos)
   - En Setup > Object Manager, elimina:
     * LegallyMail Log
     * LegallyMail Template

================================================================================
10. SOPORTE Y CONTACTO
================================================================================

Si tienes problemas durante la instalación o uso del componente:

Email: support@legallymail.com
Website: https://legallymail.com
Documentación: https://legallymail.com/docs
Horario de soporte: Lunes a Viernes, 9:00 - 18:00 (CET)

Al contactar soporte, proporciona:
- Versión de Salesforce (Setup > Company Information)
- Mensaje de error completo
- Pasos para reproducir el problema
- Capturas de pantalla si es posible

================================================================================
FIN DEL DOCUMENTO
================================================================================

Versión: 1.0
Última actualización: Febrero 2026
Desarrollado por: LegallyMail
Licencia: GPLv2 or later
