Saltar al contenido principal

Configuración de GoHighLevel

Esta guía resume los pasos para habilitar la integración con GoHighLevel en producción.

1. Credenciales Necesarias​

  1. Inicia sesión en GHL → Settings → API Keys
  2. Genera una API Key con permisos sobre Contacts, Opportunities y Tags
  3. Copia el Location ID desde Settings → Business Profile
  4. Genera un secreto para webhooks (python -c "import secrets; print(secrets.token_urlsafe(32))")
  5. Añade al .env del backend:
GHL_API_KEY=...
GHL_API_URL=https://services.leadconnectorhq.com
GHL_LOCATION_ID=...
GHL_WEBHOOK_SECRET=...

# Retry Scheduler (opcional, tiene defaults)
GHL_RETRY_ENABLED=true
GHL_RETRY_INTERVAL_MINUTES=30

# Pipelines (opcional)
GHL_PIPELINE_EMPRESAS_ID=...
GHL_PIPELINE_EXPERTOS_ID=...
GHL_PIPELINE_PROYECTOS_ID=...
GHL_PIPELINE_PROYECTOS_STAGE_INITIAL=...

Nota importante:

  • Para Private Integrations (recomendado), usa https://services.leadconnectorhq.com
  • Para instancias personalizadas: https://services.[tu-dominio] (ej: https://services.suitesapiens.com)
  • El token se usa con formato Bearer <TOKEN> en el header Authorization

2. Migraciones y Despliegue​

  1. Asegúrate de ejecutar docker compose exec backend alembic upgrade head para aplicar las tablas relacionadas (ghl_sync_log)
  2. Reinicia el backend para cargar variables
  3. Verifica que la migración a1b2c3d4e5f7_add_ghl_id_to_users se haya aplicado (agrega campo ghl_id a la tabla users)

3. Configurar Webhooks de GHL​

  1. En Settings → Integrations → Webhooks, crea un webhook con:
    • URL: https://api.tu-dominio.com/api/webhooks/ghl
    • Secret: el mismo GHL_WEBHOOK_SECRET
    • Eventos recomendados: Contact Create, Contact Update, Contact Tag Update, Opportunity Create, Opportunity Update
  2. Guarda y prueba el webhook

4. Pruebas Funcionales​

  • Registrar un usuario y verificar que se crea un contacto mínimo en GHL inmediatamente (con tags registro-incompleto, empresa-pendiente o experto-pendiente)
  • Completar el perfil del usuario y verificar que el contacto GHL se enriquece con todos los datos (tags reemplazados, custom fields, lead score)
  • Verificar que el tag marketing-opt-in aparece si el usuario aceptó comunicaciones comerciales
  • Publicar un proyecto y confirmar que se genera la oportunidad
  • Verificar un experto y confirmar que se actualizan las etiquetas en GHL (exp-verificado)
  • Cambiar el nivel de un experto y verificar sincronización (exp-nivel-*)
  • Probar el flujo multi-rol: registrar con ambos roles, crear un perfil, luego el segundo → verificar que solo hay un contacto GHL con ambos tags
  • Revisar la tabla ghl_sync_log y los logs del backend si hay fallos
  • Verificar que ghl_sync_log tiene entradas con event_type="registration_minimal" al registrar y event_type="profile_enriched" al crear perfil
  • Verificar que el Health Check funciona: GET /api/integrations/ghl/health-check?detail_level=quick
  • Verificar que el Retry Scheduler está activo en los logs de startup
  • Verificar que actualizar username/email de un usuario sincroniza con GHL (check ghl_sync_log)

Endpoints de Diagnóstico​

Una vez configurado, puedes usar los endpoints de diagnóstico:

# Diagnóstico completo de un usuario
GET /api/admin/users/{user_id}/ghl-diagnosis

# Sincronización manual si hay discrepancias
POST /api/admin/users/{user_id}/ghl-sync-tags

5. Checklist Rápido​

  • Variables GHL_* definidas en el backend
  • Migraciones aplicadas
  • Webhook configurado y activo
  • Sincronizaciones verificadas (contacto mínimo al registro + enriquecimiento al crear perfil + oportunidad al publicar)
  • Tags registro-incompleto y *-pendiente aparecen al registrar y desaparecen al crear perfil
  • Tag marketing-opt-in funciona correctamente
  • Flujo multi-rol probado (un solo contacto GHL con ambos roles)
  • Verificación de experto sincroniza correctamente
  • Cambio de nivel de experto sincroniza correctamente
  • Actualización de perfil sincroniza campos básicos y personalizados
  • Logs (ghl_sync_log) sin errores pendientes
  • Endpoints de diagnóstico funcionando correctamente
  • Health Check endpoint responde correctamente (GET /api/integrations/ghl/health-check)
  • Retry Scheduler activo en logs de startup
  • Campo ghl_id poblado en usuarios que sincronizaron con GHL
  • Variables GHL_RETRY_ENABLED y GHL_RETRY_INTERVAL_MINUTES configuradas

6. Funcionalidades de Sincronización​

La integración sincroniza automáticamente:

  • Registro de usuarios → Crea contacto mínimo en GHL inmediatamente (background task) con tags registro-incompleto, empresa-pendiente/experto-pendiente, y marketing-opt-in si aplica
  • Creación de perfil → Enriquece contacto GHL existente con datos completos del perfil, custom fields, lead score y tags definitivos
  • Verificación de expertos → Actualiza etiquetas (exp-verificado, exp-solicitud)
  • Cambio de nivel de experto → Actualiza etiquetas de nivel (exp-nivel-*)
  • Activación/desactivación → Actualiza etiquetas de estado (emp-inactivo, exp-inactivo)
  • Pre-evaluación → Añade/remueve exp-pre-evaluación
  • Recontacto → Añade emp-recontacto
  • Baja → Añade emp-baja y emp-baja-confirmada
  • Eliminación definitiva → Actualiza etiquetas antes de eliminar:
    • Empresas: Remueve emp-baja y emp-baja-confirmada, añade emp-eliminado
    • Expertos: Añade exp-eliminado
    • Registra evento user_deleted en ghl_sync_log
  • Publicación de proyecto → Crea oportunidad en GHL
  • Asignación de experto → Actualiza oportunidad y etiquetas
  • Completado de proyecto → Actualiza oportunidad y etiquetas
  • Actualización de username/email → Sincroniza cambios de datos del usuario con GHL (fire-and-forget)
  • Retry automático → Scheduler reintenta webhooks fallidos cada 30 minutos (configurable)
  • Health Check → Diagnóstico en tiempo real de la integración GHL

Más Información​