Documentación técnica

Conectar sistemas externos con Cosmiq

Cosmiq corre sobre el motor de LeadConnector, así que su API pública es la misma que documenta HighLevel: mismos endpoints, mismos permisos, mismo flujo de autorización. Lo único que cambia son las URLs de marca blanca. Todo lo que hay en esta página está adaptado a Cosmiq y sirve tal cual para conectar cualquier sistema externo a una sub-cuenta.

¿Cuál de los dos métodos me toca?

Token de integraciones privadas

Es una credencial estática que conectas a una sub-cuenta desde la interfaz, sin montar el flujo de OAuth. Sustituye a las antiguas claves de API y mejora sobre ellas en lo importante: puedes restringir exactamente qué permisos tiene en lugar de dar acceso total.

Cómo se crea

1. Abre Ajustes › Integraciones privadas

   Dentro de la sub-cuenta con la que vas a trabajar. Por defecto solo los administradores de la agencia ven esta pantalla; el acceso se puede abrir usuario por usuario.

2. Crea la integración

   Pulsa Crear nueva integración y ponle nombre y descripción. Escribe algo que un compañero entienda dentro de seis meses: «Sincronización con la web», no «token 3».

3. Elige los permisos

   Marca solo los scopes que el sistema va a usar. Se pueden editar después sin regenerar el token, así que empieza corto y amplía si hace falta.

4. Copia el token

   Se muestra una sola vez. Si cierras la ventana sin copiarlo, no hay forma de recuperarlo: toca revocarlo y crear otro. Guárdalo en tu gestor de secretos, nunca en el repositorio.

Cómo se usa

Va en la misma cabecera Authorization que un token de OAuth. Para la API son indistinguibles.

GET https://services.leadconnectorhq.com/contacts/?locationId=ID_DE_TU_SUBCUENTA
Authorization: Bearer TU_TOKEN_PRIVADO
Version: 2021-07-28
Accept: application/json
Content-Type: application/json

En qué se diferencia de OAuth

OAuth 2.0

El flujo es Authorization Code. Lo necesitas si tu aplicación la van a instalar terceros: cada administrador aprueba los permisos sobre su propia sub-cuenta y puede retirarlos cuando quiera.

1. Registra tu aplicación

   1. Entra al Marketplace de desarrolladores en marketplace.leadconnectorhq.com.
   2. Crea una cuenta de desarrollador.
   3. Ve a My Apps y pulsa Create App.
   4. Completa el formulario; la app queda creada.
   5. Ábrela para configurar los permisos y generar client_id y client_secret.

   Pide solo lo que vas a usar. Cada permiso extra alarga la pantalla de consentimiento y da una razón más para dudar.

2. Arma la URL de autorización

   Es la página a la que envías al administrador. Los permisos van separados por espacios.

   # Flujo de marca blanca — el que corresponde a Cosmiq
   https://marketplace.leadconnectorhq.com/oauth/chooselocation
     ?response_type=code
     &redirect_uri=https://tu-servidor.pe/oauth/callback/cosmiq
     &client_id=TU_CLIENT_ID
     &scope=contacts.readonly contacts.write conversations/message.write

   Si el usuario no ha iniciado sesión, el login se abre en una pestaña nueva. Añade &loginWindowOpenMode=self para que lo haga en la misma.

3. Recibes el código en tu callback

   El admin elige la sub-cuenta y su navegador vuelve a tu redirect_uri con un código de un solo uso.

   https://tu-servidor.pe/oauth/callback/cosmiq?code=7676cjcbdc6t76cdcbkjcd09821jknnkj

   Caduca en minutos y solo se canjea una vez.

4. Canjéalo por un token de acceso

   Desde tu servidor. El cuerpo va como application/x-www-form-urlencoded.

   POST https://services.leadconnectorhq.com/oauth/token
   Content-Type: application/x-www-form-urlencoded
   Accept: application/json
   
   client_id=TU_CLIENT_ID
   &client_secret=TU_CLIENT_SECRET
   &grant_type=authorization_code
   &code=EL_CODIGO_DEL_PASO_3
   &user_type=Location          # o Company, para token de agencia
   &redirect_uri=https://tu-servidor.pe/oauth/callback/cosmiq

   La respuesta trae lo que hay que guardar:

   {
     "access_token":  "…",
     "token_type":    "Bearer",
     "expires_in":    86399,
     "refresh_token": "…",
     "scope":         "contacts.readonly contacts.write",
     "userType":      "Location",
     "locationId":    "…",     # solo en tokens de sub-cuenta
     "companyId":     "…",
     "userId":        "…"      # quién instaló la app
   }

5. Llama a la API

   GET https://services.leadconnectorhq.com/contacts/?locationId=…
   Authorization: Bearer EL_ACCESS_TOKEN
   Version: 2021-07-28
   Accept: application/json

   Cada respuesta incluye un traceId único. Guárdalo en tus logs: es lo primero que pide soporte.

6. De token de agencia a token de sub-cuenta

   Un token de agencia administra la cuenta pero no lee datos de negocio. Para eso lo cambias por uno de la sub-cuenta concreta.

   POST https://services.leadconnectorhq.com/oauth/location-token
   Authorization: Bearer TOKEN_DE_AGENCIA
   Version: 2021-07-28
   Content-Type: application/x-www-form-urlencoded
   
   companyId=…&locationId=…

   Con GET /oauth/installed-locations consultas dónde está instalada tu app.

7. Renueva antes de que te bloquee

   1. Llama al endpoint con el access_token que tienes.
   2. Si responde que expiró, pide uno nuevo con grant_type=refresh_token y guarda los dos valores nuevos.
   3. Repite la llamada original.

   El refresh token también se renueva. Cada uso emite uno nuevo con un año por delante. Si guardas solo el access_token, en 24 horas pierdes la conexión y el cliente tiene que reinstalar la app.

Permisos (scopes)

Los permisos siguen el patrón recurso.readonly / recurso.write, y algunos bajan un nivel más: conversations/message.write, locations/customFields.readonly. Cada uno declara además si es de sub-cuenta, de agencia o de ambas.

.write no incluye .readonly. Si tu integración crea contactos y luego los consulta, necesita los dos.

Hay 91 permisos en total. El catálogo completo vive en la documentación del marketplace.

Descripción general del SDK

Hay clientes oficiales para tres lenguajes. Ahorran justo lo que suele salir mal a mano: el refresco de tokens, el almacenamiento por sub-cuenta y la validación de firmas de webhook.

Instalación

# Node.js
npm install @gohighlevel/api-client

# Python
pip install gohighlevel-api-client

# PHP
composer require gohighlevel/api-client

Qué te resuelven

• Flujo de OAuth automático — el intercambio de código y el refresco de tokens sin escribirlo tú.
• Soporte para tokens privados — el mismo cliente sirve para los dos métodos de autenticación.
• Almacenamiento por sub-cuenta — gestiona un token distinto para cada locationId, incluido el caso de instalación masiva.
• Ayudas para webhooks — validación de firma y manejo de los eventos de instalación y desinstalación.
• Métodos tipados — autocompletado y errores en tiempo de compilación en lugar de cadenas sueltas.

Servidor MCP

MCP (Model Context Protocol) es el estándar que usan los asistentes de IA para conectarse a herramientas y datos externos. El servidor MCP de LeadConnector expone el CRM directamente a un asistente: puede buscar contactos, consultar oportunidades y ejecutar operaciones sin que escribas una sola llamada a la API.

Autenticación

Dos opciones. La primera es un inicio de sesión de un clic y es la recomendada:

• OAuth — el cliente MCP abre el flujo de consentimiento y guarda el token.
• Token de integración privada — para conexiones de servidor sin interfaz.

Authorization: Bearer pit-tu-token
locationId: tu-location-id          # opcional

Herramientas que expone

Cómo conectarlo

Claude (aplicación web o de escritorio)

Configuración → Conectores → Agregar conector personalizado, y pega la URL del endpoint.

Claude Code

claude mcp add --transport http leadconnector \
  https://services.leadconnectorhq.com/mcp/anthropic/v2

Límites de tarifas

Dos límites simultáneos, aplicados por aplicación y por recurso — cada sub-cuenta y cada compañía tienen su propia cuota. Que tu app esté instalada en veinte sub-cuentas significa veinte cuotas independientes, no una repartida.

Cabeceras de control

Vienen en todas las respuestas. Léelas y frena antes de chocar, en lugar de esperar al error.

Cómo convivir con ellos

• Encola y espacia. 100 por cada 10 segundos son 10 por segundo sostenidos: reparte, no dispares en ráfaga.
• Reintenta con espera creciente. Ante un rechazo por límite, duplica la espera en cada intento en lugar de insistir de inmediato.
• Cachea lo que no cambia. Campos custom, etapas de pipeline y etiquetas no necesitan consultarse en cada llamada.
• Las migraciones grandes van de noche y por lotes. Cargar 50 000 contactos a 10 por segundo son casi 90 minutos: planifícalo, no lo improvises.

Control de versiones

La versión viaja en la cabecera Version de cada petición. Sin ella la API responde error, y ese es el fallo más común en una primera integración.

Version: 2021-07-28     # estable, la que usa la mayoría
Version: v3             # versión nueva, respuestas normalizadas

Política de retirada

Cuando sale una versión nueva, la anterior entra en ventana de mantenimiento: sigue recibiendo correcciones críticas y parches de seguridad, pero ninguna función nueva. Al llegar su fecha de retirada, la API deja de aceptar esa cabecera y las integraciones que la usen dejan de funcionar.

Registro de cambios

El changelog recoge cada modificación de la API: endpoints nuevos, propiedades retiradas, valores de enumeración añadidos y cambios de comportamiento. Se ordena por fecha, de lo más reciente hacia atrás, y dentro de cada fecha por módulo.

Los cambios se marcan con tres símbolos: ⚠ ruptura + añadido − retirado. Los de ruptura son los únicos que exigen acción inmediata.

Lista de países

El campo country de un contacto espera un código de dos letras (ISO 3166-1 alfa-2), no el nombre del país. Enviar "Perú" en lugar de "PE" es motivo de error de validación.

Preguntas frecuentes

¿Cómo escucho los eventos de webhook?

1. Registra una aplicación en el marketplace.
2. En sus ajustes, indica la URL donde quieres recibir los eventos.
3. En la misma pantalla, añade los permisos que el evento requiere. Sin el permiso correspondiente el evento no se envía.
4. Pide al administrador de la agencia o de la sub-cuenta que abra la página de la app y pulse Add App.
5. Al seleccionar la sub-cuenta, se le redirige a tu URL de retorno con el código de autorización.
6. Canjea el código por el token de acceso.
7. A partir de ahí empiezas a recibir los eventos de esa sub-cuenta.

¿Cuánto duran los tokens?

El de acceso, 24 horas. El de refresco, un año — y se renueva cada vez que lo usas, así que una integración activa nunca lo pierde. Una que lleva más de un año parada, sí.

¿Qué hago cuando un token expira?

Envuelve todas tus llamadas en una función que, ante un error de token expirado, pida uno nuevo con el refresh token, guarde el par nuevo y repita la petición. Escríbela una vez y úsala en todas partes.

¿Por qué mi token de agencia no lee contactos?

Porque no le corresponde. Un token de agencia administra la cuenta; los datos de negocio viven en las sub-cuentas. Cámbialo por uno de sub-cuenta con POST /oauth/location-token.

¿Puedo usar un token privado para una app del marketplace?

No. El token privado es para tus propias integraciones, en tu propia cuenta. Una app que instalen terceros necesita el flujo de OAuth: es lo que permite al cliente aprobar y revocar el acceso.

¿Qué hago con el traceId?

Guárdalo en tus logs junto a cada petición fallida. Identifica de forma única esa llamada y es lo primero que va a pedirte soporte.

Documentación del marketplace

El marketplace es donde se publican las aplicaciones que otros pueden instalar. Más allá de la autorización, cubre las piezas que convierten una integración en un producto.