Saltar al contenido principal

Integración GoHighLevel

Integración completa y funcional con GoHighLevel (GHL) para sincronización automática de contactos, oportunidades y tags.

Estado: ✅ 100% IMPLEMENTADO | Listo para configurar y usar

Última actualización: 2025-01-21 Versión: 2.2 (Lead Score, Estado Dinámico, Etiquetas de Proyecto)

Resumen Ejecutivo​

La integración con GoHighLevel permite:

  • ✅ Sincronización bidireccional de contactos
  • ✅ Gestión automática de etiquetas
  • ✅ Lead Score dinámico (0-100)
  • ✅ Estado del contacto calculado automáticamente
  • ✅ Sincronización de campos básicos y personalizados
  • ✅ Webhooks bidireccionales
  • ✅ Creación automática de oportunidades

Campos Sincronizados​

Campos Básicos (7)​

  • phone, location, email, username
  • company_name, company_website, contact_person

Campos Personalizados - Empresas (6)​

  • company_type, industry, company_size, preferred_language, cif, company_email

Campos Personalizados - Expertos (9)​

  • main_area, work_language, experience_years, expert_level, availability, internal_rating, portfolio_url, linkedin_url, lead_score

Campos Comunes (2)​

  • tipo_de_usuario, fuente_del_contacto, estado_del_contacto

Etiquetas Automáticas​

Las etiquetas se generan automáticamente según eventos:

Etiquetas de Empresa (11)​

  • emp-nuevo-registro - Al registrar empresa
  • emp-inactivo, emp-reactivado - Cambios de estado
  • emp-recontacto, emp-baja, emp-baja-confirmada - Gestión de contactos
  • emp-eliminado - Usuario eliminado definitivamente (remueve emp-baja y emp-baja-confirmada)
  • emp-proyecto-publicado, emp-proyecto-en-ejecución, emp-proyecto-completado - Estados de proyecto
  • emp-borrador-creado, emp-proyecto-en-validación - Nuevas etiquetas v2.2

Etiquetas de Experto (10)​

  • exp-solicitud, exp-pre-evaluación, exp-verificado - Estados de verificación
  • exp-inactivo - Estado de inactividad
  • exp-eliminado - Usuario eliminado definitivamente
  • exp-nivel-global, exp-nivel-pro, exp-nivel-enterprise - Niveles de experto
  • exp-invitado-proyecto, exp-propuesta-enviada, exp-proyecto-asignado - Nuevas etiquetas v2.2

Etiquetas de Fuente (4)​

  • src/ads, src/linkedin, src/referral, src/web

Ver Listado Completo de Etiquetas para más detalles.

Funcionalidades Principales​

Sincronización Automática​

  • Registro de usuarios → Crea contacto en GHL con etiquetas iniciales según el primer perfil creado
  • Añadir nuevo rol → Actualiza contacto existente en GHL añadiendo etiquetas del nuevo rol y actualizando tipo_de_usuario a "Empresa y Experto"
  • Verificación de expertos → Actualiza etiquetas (exp-verificado, exp-solicitud)
  • Eliminación de usuarios → Actualiza etiquetas en GHL 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
    • Si GHL falla, no bloquea la eliminación (solo registra warning)
  • Cambio de nivel de experto → Actualiza etiquetas de nivel (exp-nivel-*)
  • Activación/desactivación → Actualiza etiquetas de estado
  • Publicación de proyecto → Crea oportunidad en GHL
  • Asignación de experto → Actualiza oportunidad y etiquetas

Sincronización Multi-Rol​

Cuando un usuario tiene múltiples roles (empresa y experto), GHL gestiona un único contacto para ese usuario:

Registro con múltiples roles:

  1. Usuario se registra con ambos roles (empresa y experto)
  2. Al crear el primer perfil → Se crea contacto en GHL con etiqueta del primer rol
  3. Al crear el segundo perfil → Se actualiza el contacto existente:
    • Se añade la etiqueta del nuevo rol (emp-nuevo-registro o exp-solicitud)
    • Se actualiza el campo personalizado tipo_de_usuario a "Empresa y Experto"

Etiquetas acumulativas:

  • Si el usuario tiene ambos roles, tendrá ambas etiquetas: emp-nuevo-registro y exp-solicitud
  • Las etiquetas se acumulan, no se reemplazan
  • El campo tipo_de_usuario refleja si tiene uno o ambos roles

Ejemplo:

  • Usuario registra primero perfil de empresa → Contacto GHL con etiqueta emp-nuevo-registro, tipo_de_usuario: "Empresa"
  • Usuario crea perfil de experto → Contacto GHL actualizado con etiqueta exp-solicitud añadida, tipo_de_usuario: "Empresa y Experto"

Lead Score Dinámico​

El Lead Score se calcula automáticamente (0-100) basado en:

  • Proyectos completados (30% del peso)
  • Reviews y ratings (25% del peso)
  • Verificación de perfil (20% del peso)
  • Actividad reciente (15% del peso)
  • Tiempo en la plataforma (10% del peso)

Sugerencias de nivel basadas en Lead Score:

  • Global: 0-50 puntos
  • Pro: 51-75 puntos
  • Enterprise: 76-100 puntos

Estado del Contacto Dinámico​

Se calcula automáticamente según:

  • Proyectos activos/completados
  • Verificación de perfil
  • Hitos pendientes
  • Estado del usuario

Configuración​

1. Variables de Entorno​

Añadir en backend/.env:

# GoHighLevel Integration
GHL_API_KEY=tu_api_key_aqui
GHL_API_URL=https://services.leadconnectorhq.com
GHL_LOCATION_ID=tu_location_id
GHL_WEBHOOK_SECRET=tu_secret_seguro

IMPORTANTE: Private Integrations vs API Keys

  • Private Integrations (recomendado): Token se usa directamente sin "Bearer" en el header Authorization
  • URL base: https://services.leadconnectorhq.com (para instancias estándar)
  • Para instancias personalizadas: https://services.[tu-dominio] (ej: https://services.suitesapiens.com)

2. Ejecutar Migración​

docker compose exec backend alembic upgrade head

3. Configurar Webhook en GHL​

  1. Ir a Settings → Integrations → Webhooks en GHL
  2. Añadir nuevo webhook:
    • URL: https://tu-dominio.com/api/webhooks/ghl
    • Secret: (el mismo que GHL_WEBHOOK_SECRET)
    • Eventos: Contact Create, Contact Update, Contact Tag Update, Opportunity Create, Opportunity Update

API Endpoints​

Administración (Solo Admin)​

Sincronización Manual​

  • POST /api/integrations/ghl/contact - Sincronizar contacto manualmente
  • POST /api/integrations/ghl/opportunity - Crear oportunidad
  • POST /api/integrations/ghl/tag - Añadir tags

Diagnóstico​

  • GET /api/admin/users/{user_id}/ghl-diagnosis - Diagnóstico completo de sincronización GHL
  • POST /api/admin/users/{user_id}/ghl-sync-tags - Forzar sincronización manual de tags

Webhooks​

  • POST /api/webhooks/ghl - Recibe eventos de GHL (validación HMAC)

Testing​

Total: 66 tests pasando ✅

  • test_ghl_integration.py - 11 tests (sincronización básica)
  • test_ghl_sync.py - 12 tests (sincronización en endpoints admin, incluyendo eliminación de usuarios)
  • test_ghl_contact_status.py - 6 tests (estado del contacto dinámico)
  • test_ghl_lead_score.py - 4 tests (cálculo y sincronización de lead_score)
  • test_ghl_project_tags.py - 5 tests (etiquetas de proyecto)
  • Y más...

Ejecutar Tests​

# Todos los tests de GHL
./scripts/test_backend.sh tests/endpoints/test_ghl_*.py -v

Troubleshooting​

Endpoint de Diagnóstico​

Para diagnosticar problemas de sincronización:

GET /api/admin/users/{user_id}/ghl-diagnosis

Sincronización Manual​

Si hay discrepancias entre Floutic y GHL:

POST /api/admin/users/{user_id}/ghl-sync-tags

Documentación Completa​

Para documentación detallada, consulta:

Checklist de Activación​

  • Obtener API Key de GoHighLevel
  • Configurar variables en backend/.env
  • Ejecutar migración de base de datos
  • Reiniciar backend
  • Configurar webhook en panel de GHL
  • Probar creación de contacto
  • Probar creación de oportunidad
  • Verificar logs de sincronización