Integraciones Privadas: la forma mas simple y segura de conectar tus sistemas
Integraciones Privadas: todo lo que necesitas saber
Si tu colegio o universidad quiere conectar la plataforma con una herramienta propia (el sistema de admisiones, un formulario en la página web, el ERP academico), las Integraciones Privadas son, en la gran mayoria de los casos, el camino correcto para empezar. Son más simples de configurar que una app publica y, sobre todo, más seguras: tu decides exactamente que puede ver y hacer cada integración dentro de tu cuenta.
Para la lista completa de endpoints disponibles (que datos se pueden leer o escribir), la referencia técnica siempre esta en: https://marketplace.gohighlevel.com/docs/
¿Qué es, en terminos simples, una Integración Privada?
Piensa en una Integración Privada como una llave de acceso que tu mismo generas, con permisos que tu mismo eliges, para que un sistema externo se conecte a tu cuenta de la plataforma de forma controlada.
Si quieren conectar la plataforma con otra herramienta, hay dos caminos:
- Buscar e instalar una app ya existente desde el Marketplace de la plataforma (lo más rápido, si ya existe una que resuelva lo que necesitan).
- Construir su propia conexión a la medida, con ayuda de un desarrollador — por ejemplo, para sincronizar las inscripciones de su portal de admisiones directo a la plataforma.
Las Integraciones Privadas son la manera recomendada de lograr esta segunda opción sin complicarse.
Sus dos grandes ventajas:
- Son simples de crear: se genera el token de acceso directo desde la configuración de la cuenta, sin pasos técnicos adicionales.
- Son seguras por diseno: tu decides exactamente que partes de la información puede tocar cada integración (por ejemplo, "solo puede leer y crear contactos", nada más).
Estan disponibles tanto para la cuenta de Agencia como para cada sede/sub-cuenta por separado — muy útil si tu institucion administra varios campus desde la plataforma.
¿Por qué son mejores que las API Keys antiguas?
| Integraciones Privadas | API Keys (V1) |
|---|---|
| Puedes limitar exactamente que puede ver o modificar el desarrollador. | El desarrollador tiene acceso a todos los datos de la cuenta, sin restriccion. |
| Usan la tecnologia más reciente de la plataforma (API v2.0). | Funcionan sobre una versión de API que ya no tiene mantenimiento ni soporte. |
| Tienen más funcionalidades disponibles. | Funcionalidades limitadas. |
Si tu institucion todavia tiene una integración basada en API Keys, es un buen momento para planear su migración — no de emergencia, pero si con tiempo.
¿En que se diferencian de un token de OAuth2?
En pocas palabras, una Integración Privada es como un token de OAuth2, pero fijo: no expira todos los días como los tokens normales, y se genera con un par de clics desde la interfaz, sin que un desarrollador tenga que programar todo el flujo de autorizacion.
Como se usa en la práctica
El token de la Integración Privada se coloca en el encabezado (header) Authorization de cada peticion, igual que cualquier otro token de acceso. Por ejemplo, para consultar los datos de una sede:
curl --request GET \
--url https://services.leadconnectorhq.com/locations/ve9EPM428h8vShlRW1KT \
--header 'Accept: application/json' \
--header 'Authorization: <TU TOKEN DE INTEGRACION PRIVADA>' \
--header 'Version: 2021-07-28'
Un primer ejemplo para probar que todo funciona
Antes de conectar un sistema completo, es buena idea hacer una prueba pequeña. Por ejemplo, registrar un contacto nuevo (podria ser un prospecto que llena un formulario en tu página):
curl --request POST \
--url https://services.leadconnectorhq.com/contacts/ \
--header 'Authorization: <TU TOKEN DE INTEGRACION PRIVADA>' \
--header 'Content-Type: application/json' \
--header 'Version: 2021-07-28' \
--data '{
"firstName": "Juan",
"lastName": "Perez",
"email": "juan.perez@ejemplo.com",
"phone": "+521234567890",
"locationId": "ID_DE_TU_SEDE"
}'
Solo recuerden reemplazar ID_DE_TU_SEDE por el Id real de la sede o campus, y el valor de Authorization por el token que generaron.
Para ver la lista completa de endpoints y todo lo que se puede hacer, la documentación oficial esta en: https://developers.gohighlevel.com
¿Quién puede crear y administrar Integraciones Privadas?
Por default, cualquier administrador de la agencia puede crearlas y administrarlas. Si tu institucion prefiere controlar esto con más cuidado (por ejemplo, que solo la dirección de sistemas pueda hacerlo), se puede restringir por usuario desde Configuración > Equipo > [editar al administrador] > Roles y Permisos.
Se puede controlar en dos niveles distintos:
- Quien puede administrar las integraciones privadas de la agencia completa.
- Quien puede administrar las integraciones privadas de cada sede/sub-cuenta.
¿Dónde se encuentran dentro de la plataforma?
Estan en la configuración de la agencia. Si no las ven ahi, verifiquen que la funcionalidad este activada en la sección "Labs".
Como crear su primera Integración Privada (guia paso a paso)
- Hagan clic en "Create new Integration".
- Denle un nombre y una breve descripcion que ayude a todo el equipo a identificar para que sirve (por ejemplo: "Sincronización portal de admisiones").
- Seleccionen unicamente los permisos (scopes) que realmente necesita esa integración. Menos es más: entre menos acceso le den, menos riesgo hay si el token se filtra por accidente.
- Copien el token generado y compartanlo directamente con la persona o empresa que va a desarrollar la conexión.
Compartan el token solo con quien vaya a usarlo, nunca por canales públicos ni sin cifrar.
Nota: el token solo se muestra una vez al crearlo — si no lo copiaron a tiempo, tendran que generar uno nuevo.
Buenas prácticas de seguridad que recomendamos seguir
Sugerimos rotar el token cada 90 días, como buena práctica general de seguridad (igual que cambiar una contraseña periodicamente):
- Vayan a Integraciones Privadas en configuración y abran la integración correspondiente.
- Hagan clic en "Rotate and expire this token later".
- Confirmen en el mensaje de advertencia.
- Copien el token nuevo y actualicenlo en el sistema externo.
Durante 7 días, el token viejo y el nuevo funcionan al mismo tiempo — así le dan tiempo a su desarrollador de actualizar todo sin que nada se caiga. Pasado ese periodo, el token anterior deja de funcionar automáticamente.
Si sospechan que un token se filtro o fue comprometido
No hay que entrar en panico, pero si actuar rápido:
- Vayan a Integraciones Privadas y abran la integración en cuestion.
- Hagan clic en "Rotate and expire this token now" (esto invalida el token viejo de inmediato, sin periodo de gracia).
- Confirmen la acción.
- Copien el token nuevo y actualicenlo en el sistema externo lo antes posible.
¿Se pueden cambiar los permisos sin generar un token nuevo?
Si. Pueden editar el nombre, la descripcion y los permisos (scopes) en cualquier momento, sin que esto invalide el token que ya esta en uso — el token existente sigue funcionando igual después de la edicion.
Nota: cada cuenta (agencia o sede) puede tener hasta 5 tokens de Integración Privada activos a la vez.
Cuando ya no la necesiten
Simplemente vayan a Integraciones Privadas, seleccionen "Delete" desde el menu de tres puntos de esa integración, y listo — el acceso queda revocado de inmediato.