API de GoHighLevel: Guía de Integración para Desarrolladores

La API de GoHighLevel permite conectar la plataforma con cualquier sistema externo, automatizar procesos que van más allá de los workflows nativos y construir integraciones personalizadas. En esta guía cubrimos todo lo que un desarrollador necesita saber para empezar: los endpoints principales, los dos métodos de autenticación (API Key y OAuth 2.0), cómo configurar webhooks para eventos en tiempo real, los rate limits y casos de uso prácticos. Si no tienes experiencia técnica, este tutorial es avanzado; te recomendamos empezar por nuestros tutoriales de GoHighLevel y los workflows antes de abordar la API.

Visión general de la API de GoHighLevel

La API de GoHighLevel es una API REST que permite interactuar programáticamente con prácticamente todas las funcionalidades de la plataforma: contactos, oportunidades, calendarios, workflows, conversaciones, funnels, pagos y más. Todas las respuestas se devuelven en formato JSON.

Existen dos versiones de la API:

• API v1: La versión original, que usa autenticación por API Key. Sigue operativa pero no recibe nuevas funcionalidades. La documentación está disponible en developers.gohighlevel.com.
• API v2: La versión actual y recomendada, que usa OAuth 2.0 para la autenticación. Ofrece más endpoints, mejores respuestas de error y documentación más completa. La base URL es https://services.leadconnectorhq.com.

Para nuevas integraciones, siempre recomendamos usar la API v2. La v1 solo tiene sentido si estás manteniendo una integración existente que ya la usa y no tienes recursos para migrar.

La documentación oficial de la API está disponible en el portal de desarrolladores de GoHighLevel. Es importante consultarla como referencia principal, ya que los endpoints pueden actualizarse con frecuencia. Esta guía complementa la documentación oficial con explicaciones en español, contexto y ejemplos prácticos.

Autenticación: API Key vs OAuth 2.0

El primer paso para usar la API es autenticarte. GoHighLevel ofrece dos métodos, cada uno adecuado para diferentes escenarios.

API Key (v1)

El método más sencillo. Cada subcuenta de GoHighLevel tiene una API Key única que puedes encontrar en Settings > Business Profile > API Key. Para usarla, incluye la clave en el header de cada petición:

Authorization: Bearer tu_api_key_aqui

Ventajas: Configuración inmediata, ideal para scripts internos y automatizaciones rápidas.
Limitaciones: Solo accede a los datos de una subcuenta. Si gestionas múltiples clientes, necesitas una API Key por cada uno. No es adecuada para aplicaciones que distribuyas a terceros.

OAuth 2.0 (v2)

El método recomendado para integraciones profesionales. OAuth 2.0 permite que tu aplicación solicite acceso a la cuenta de un usuario de GoHighLevel sin necesitar su API Key directamente. El flujo funciona así:

1. Registra tu aplicación en el portal de desarrolladores de GoHighLevel (marketplace.gohighlevel.com). Obtendrás un Client ID y un Client Secret.
2. Redirige al usuario a la página de autorización de GoHighLevel, donde aceptará los permisos que tu app solicita (scopes).
3. Recibe un código de autorización en tu URL de callback.
4. Intercambia el código por un access token y un refresh token.
5. Usa el access token en tus peticiones a la API.
6. Refresca el token cuando expire (cada 24 horas) usando el refresh token.

Ventajas: Más seguro, permite acceder a múltiples cuentas con una sola aplicación, necesario para publicar en el marketplace.
Limitaciones: Configuración más compleja, necesitas gestionar el ciclo de vida de los tokens.

Scopes (permisos)

Al usar OAuth 2.0, debes especificar qué permisos necesita tu aplicación. Los scopes más comunes son:

• contacts.readonly / contacts.write — Leer/escribir contactos.
• opportunities.readonly / opportunities.write — Leer/escribir oportunidades.
• calendars.readonly / calendars.write — Leer/escribir calendarios y citas.
• conversations.readonly / conversations.write — Leer/escribir conversaciones.
• workflows.readonly — Leer workflows (no se pueden crear workflows por API).
• locations.readonly / locations.write — Leer/escribir subcuentas.

Solicita solo los permisos que tu aplicación realmente necesita. Esto es una buena práctica de seguridad y aumenta la probabilidad de que los usuarios acepten la autorización.

Endpoints principales de la API

La API de GoHighLevel cubre la mayoría de las funcionalidades de la plataforma. Estos son los endpoints que más se usan en integraciones reales:

Contactos

El recurso más usado de la API. Permite crear, leer, actualizar y eliminar contactos, así como buscar por email, teléfono o cualquier campo.

• GET /contacts/ — Listar contactos (con filtros y paginación).
• GET /contacts/:id — Obtener un contacto específico.
• POST /contacts/ — Crear un contacto nuevo.
• PUT /contacts/:id — Actualizar un contacto existente.
• DELETE /contacts/:id — Eliminar un contacto.
• GET /contacts/lookup — Buscar contacto por email o teléfono.
• POST /contacts/:id/tags — Añadir tags a un contacto.

Oportunidades

Gestiona las oportunidades del pipeline de ventas.

• GET /opportunities/ — Listar oportunidades.
• POST /opportunities/ — Crear una oportunidad.
• PUT /opportunities/:id — Actualizar (mover de etapa, cambiar estado).
• DELETE /opportunities/:id — Eliminar una oportunidad.

Calendarios y citas

• GET /calendars/ — Listar calendarios.
• GET /calendars/:id/appointments — Listar citas de un calendario.
• POST /calendars/:id/appointments — Crear una cita.
• PUT /calendars/appointments/:id — Actualizar una cita.

Conversaciones

• GET /conversations/ — Listar conversaciones.
• GET /conversations/:id/messages — Obtener mensajes de una conversación.
• POST /conversations/messages — Enviar un mensaje (email, SMS).

Locations (subcuentas)

• GET /locations/ — Listar subcuentas.
• GET /locations/:id — Obtener detalles de una subcuenta.
• POST /locations/ — Crear una subcuenta (solo con plan adecuado).

Webhooks: eventos en tiempo real

Los webhooks permiten que GoHighLevel notifique a tu sistema cuando ocurre un evento, en lugar de tener que consultar la API periódicamente (polling). Son fundamentales para integraciones en tiempo real.

Cómo funcionan los webhooks

Configuras una URL de tu servidor en GoHighLevel, y cada vez que ocurre un evento específico, GoHighLevel envía una petición HTTP POST a esa URL con los datos del evento en formato JSON. Tu servidor procesa esos datos y ejecuta la lógica que necesites.

Eventos disponibles

Los eventos más comunes que puedes suscribir son:

• ContactCreate / ContactUpdate / ContactDelete: Cuando se crea, modifica o elimina un contacto.
• OpportunityCreate / OpportunityUpdate: Cuando se crea o mueve una oportunidad.
• AppointmentCreate / AppointmentUpdate: Cuando se agenda o modifica una cita.
• NoteCreate: Cuando se añade una nota a un contacto.
• TaskCreate: Cuando se crea una tarea.
• InboundMessage: Cuando se recibe un mensaje entrante.
• OutboundMessage: Cuando se envía un mensaje saliente.

Configuración de webhooks

Puedes configurar webhooks de dos formas:

• En la interfaz: Ve a Settings > Webhooks en la subcuenta, introduce tu URL y selecciona los eventos.
• Por API: Usa el endpoint POST /webhooks/ para crear webhooks programáticamente.

Buenas prácticas para webhooks:

• Responde siempre con un HTTP 200 en menos de 5 segundos. Si tu procesamiento es largo, acepta el webhook inmediatamente y procesa los datos en segundo plano.
• Implementa un mecanismo de reintentos. Si tu servidor no responde, GoHighLevel reintentará el envío varias veces, pero es buena práctica tener tu propio sistema de recuperación.
• Valida los datos recibidos. Aunque los webhooks de GoHighLevel son de confianza, siempre es buena práctica verificar que los datos son válidos antes de procesarlos.
• Registra los webhooks recibidos (logging) para poder depurar problemas.

Rate limits (límites de velocidad)

Como toda API profesional, GoHighLevel impone límites en el número de peticiones que puedes hacer para proteger la estabilidad del servicio. Estos son los límites principales:

• API v2: 10 peticiones por segundo por subcuenta, y un máximo de 100.000 peticiones diarias por aplicación OAuth.
• API v1: Límites más restrictivos, aproximadamente 5 peticiones por segundo.
• Bulk operations: Algunas operaciones masivas (como la importación de contactos) tienen sus propios límites más generosos.

Cuando superas el rate limit, la API devuelve un código HTTP 429 (Too Many Requests) con un header Retry-After que indica cuántos segundos debes esperar antes de reintentar. Para gestionar esto correctamente:

• Implementa un mecanismo de exponential backoff: si recibes un 429, espera 1 segundo; si vuelves a recibirlo, espera 2 segundos; luego 4, 8, etc.
• Usa colas de peticiones para controlar el ritmo de envío y no superar los límites.
• Agrupa operaciones siempre que sea posible. En lugar de hacer 100 peticiones individuales para actualizar 100 contactos, usa los endpoints bulk cuando estén disponibles.

Casos de uso prácticos de la API

La API de GoHighLevel se usa en escenarios donde los workflows nativos no son suficientes. Estos son los casos más comunes que hemos implementado para agencias en España:

1. Sincronización bidireccional con un ERP

Muchas empresas en España usan ERPs como Holded, A3 o SAP. La API permite sincronizar contactos, oportunidades y datos de facturación entre GoHighLevel y el ERP, eliminando la doble entrada de datos. Los webhooks de GoHighLevel notifican al ERP cuando cambia un contacto, y viceversa.

2. Dashboard personalizado con métricas de negocio

Aunque GoHighLevel incluye reporting básico, muchas agencias necesitan dashboards personalizados con métricas específicas. La API permite extraer datos de contactos, oportunidades, citas y conversaciones para alimentar herramientas de BI como Google Data Studio, Power BI o dashboards personalizados.

3. Integración con formularios externos

Si usas formularios de Typeform, JotForm o formularios personalizados en tu web, la API permite enviar los datos directamente al CRM de GoHighLevel y activar workflows automáticamente. Esto es una alternativa a usar los formularios nativos de GoHighLevel.

4. Automatización avanzada con IA

Un caso de uso cada vez más demandado: usar la API para conectar GoHighLevel con servicios de inteligencia artificial (ChatGPT, Claude, etc.) para responder automáticamente a mensajes, cualificar leads o generar propuestas personalizadas basadas en los datos del CRM.

5. Migración masiva desde otras plataformas

Cuando una agencia migra desde HubSpot, ActiveCampaign u otra plataforma, la API permite importar contactos, notas, tags y datos históricos de forma programática, mucho más eficiente que la importación manual por CSV.

Preguntas frecuentes sobre la API de GoHighLevel