Authorization

Cuando se usa esto: si su institucion va a instalar o construir una app que se conecta via OAuth 2.0 (por ejemplo, una app del Marketplace), este es el flujo paso a paso que hay que seguir. Si solo necesitan conectar un sistema interno propio, la ruta más simple suele ser una Integración Privada en lugar de todo este flujo.

Autorizacion

HighLevel soporta el flujo Authorization Code Grant con las APIs v2. A continuacion, el procedimiento paso a paso para usar y entender el flujo OAuth 2.0.

Aquí tienes un video en Loom que explica todo el proceso.

1. Registra una app OAuth

1. Ve al Marketplace.
2. Registrate como developer.
3. Ve a "My Apps" y haz clic en "Create App".
4. Llena los datos requeridos en el formulario; tu app quedara creada.
5. Haz clic en la app y llegaras a la configuración, donde puedes definir los scopes, generar las llaves, etc.

2. Agrega la app a la ubicacion deseada

1. Haz que el admin de la ubicacion/agencia vaya a la Authorization Page URL de la app.
2. Selecciona la ubicacion que quiere conectar.
3. Es redirigido a la redirect URL con el Authorization Code.
4. Usa el Authorization Code para obtener el Access Token mediante la API "Get Access Token" bajo OAuth 2.0.
5. Usa el Access Token para llamar cualquier API.

3. Obten la Authorization Page URL de la app

Para generar la Authorization Page URL de una app, reemplaza client_id, redirect_uri y scope en la plantilla de abajo. Luego, redirige ahi al admin de la ubicacion/agencia que quiere instalar tu app.

1. Flujo de Auth URL estandar:

https://marketplace.gohighlevel.com/v2/oauth/chooselocation?
response_type=code&
redirect_uri=https://myapp.com/oauth/callback/gohighlevel&
client_id=CLIENT_ID&
scope=conversations/message.readonly conversations/message.write

1. Flujo de Auth URL de marca blanca (White-labeled):

https://marketplace.leadconnectorhq.com/v2/oauth/chooselocation?
response_type=code&
redirect_uri=https://myapp.com/oauth/callback/gohighlevel&
client_id=CLIENT_ID&
scope=conversations/message.readonly conversations/message.write

NOTA: Para usuarios que no han iniciado sesión al momento de dar el consentimiento, el desarrollador puede iniciar el login en una pestaña nueva o en la misma pestaña. Para iniciar el login en la misma pestaña, agrega &loginWindowOpenMode=self a la authorization url. Si no se pasa este parametro, el login en pestaña nueva es el comportamiento por defecto.

Cuando un usuario otorga acceso, su navegador es redirigido a la redirect URI especificada, con el Authorization Code en el parametro code.

https://myapp.com/oauth/callback/gohighlevel?code=7676cjcbdc6t76cdcbkjcd09821jknnkj

Preguntas frecuentes de OAuth

¿Cuánto tiempo son validos los access tokens?

Los access tokens son validos por un día. Después, puedes usar el refresh token para obtener un nuevo access token, valido por otro día.

¿Cuánto tiempo son validos los refresh tokens?

Los refresh tokens son validos por un año, mientras no se usen. Si se usan, el nuevo refresh token también sera valido por un año.

¿Cómo debemos manejar la expiracion del token?

Debes:

1. Hacer una peticion a cualquiera de nuestras APIs usando el accessToken.
2. Si la respuesta indica que el token expiro, renueva el token usando nuestra API y guarda el nuevo access token y refresh token en tu base de datos.
3. Repite la peticion con el nuevo accessToken.

Puedes escribir una función wrapper de tu lado para lograr esto y usarla en todas las llamadas que hagas a nuestras APIs.

¿Cuáles son los límites de tasa (rate limits) actuales para la API 2.0?

GHL ha implementado límites de tasa en nuestras APIs públicas V2 mediante OAuth para asegurar un rendimiento y estabilidad optimos. Estos límites son:

Límite de ráfaga (burst): máximo 100 peticiones API cada 10 segundos por cada app del Marketplace (es decir, cliente) por recurso (Ubicacion o Compania). Límite diario: 200,000 peticiones API por día por cada app del Marketplace (cliente) por recurso (Ubicacion o Compania).

Estos nuevos límites contribuyen a un mejor rendimiento y estabilidad general de nuestro sistema.

Para monitorear tu uso, revisa los siguientes headers de respuesta de la API:

'X-RateLimit-Limit-Daily': tu límite diario 'X-RateLimit-Daily-Remaining': peticiones restantes para el día 'X-RateLimit-Interval-Milliseconds': el intervalo de tiempo para las peticiones en rafaga 'X-RateLimit-Max': el límite máximo de peticiones en el intervalo especificado 'X-RateLimit-Remaining': las peticiones restantes en el intervalo actual

Ejemplo: si la app 'GHL-APP' esta instalada en dos ubicaciones (Sub-cuenta A y Sub-cuenta B) en el GHL Marketplace, los límites de tasa para cada ubicacion serian:

1. Sub-cuenta A: 'GHL-APP' puede hacer 200,000 peticiones API por día y 100 peticiones API cada 10 segundos.
2. Sub-cuenta B: 'GHL-APP' puede hacer 200,000 peticiones API por día y 100 peticiones API cada 10 segundos.