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 (10)​

  • 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/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 (9)​

  • exp/solicitud, exp/pre-evaluación, exp/verificado - Estados de verificación
  • exp/inactivo - Estado de inactividad
  • 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
  • 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
  • Publicación de proyecto → Crea oportunidad en GHL
  • Asignación de experto → Actualiza oportunidad y etiquetas

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: 63 tests pasando ✅

  • test_ghl_integration.py - 11 tests (sincronización básica)
  • test_ghl_sync.py - 9 tests (sincronización en endpoints admin)
  • 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
docker compose exec backend pytest 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