En este artículo, exploraremos dos enfoques distintos para añadir integraciones a una aplicación, utilizando Hubspot como ejemplo. En primer lugar, escribiremos un ejemplo mínimo de una app capaz de:
- Obtener tokens de acceso y de actualización mediante OAuth2
- Obtener nuevos tokens de acceso y de actualización utilizando el refresh token proporcionado
- Recuperar los contactos disponibles en Hubspot.
Todo el código utilizado en este artículo puede consultarse aquí: https://github.com/chift-oneapi/hubspot_example
Objetivos
Al final de este artículo, serás capaz de:
- Implementar un ejemplo mínimo de autenticación OAuth2 y de recuperación de información desde Hubspot
- Implementar el mismo alcance con la unified API de Chift
- Explicar las ventajas y los inconvenientes de utilizar una unified API frente a una integración tradicional
Preparativos para la implementación
Para seguir esta sección, necesitarás:
- Una cuenta de Hubspot, que puedes crear aquí
- Una cuenta de desarrollador de Hubspot, que puedes crear aquí
Una vez que dispongas de ambas cuentas, puedes pasar a la siguiente sección, donde crearemos una app que nos permitirá obtener la información necesaria para la autenticación OAuth2.
Crear tu app de Hubspot
Crear una app en Hubspot se hace en unos pocos pasos rápidos. Es bastante fácil de configurar a tu gusto, pero, por simplicidad, aquí nos centraremos en las partes obligatorias del proceso.
Accede a tu cuenta de desarrollador y ve a la página Apps. Desde allí, haz clic en el botón "Create app" y comienza.
Primero definimos el nombre obligatorio de la app:
Después elegimos los scopes a los que podrá acceder el token que generaremos durante el proceso OAuth2. Aquí necesitaremos tres scopes:
%%oauth%%: seleccionado por defecto y que habilita OAuth2 para esta app%%crm.objects.companies.read%%: nos permite tener acceso de lectura a los objetos companies%%crm.objects.contacts.read%%: nos permite tener acceso de lectura a los objetos contacts
Tus scopes deberían tener este aspecto:
A continuación tendremos que definir una URL de redirección para el proceso OAuth2. En este ejemplo, mi app se ejecutará en localhost, puerto 8000, y el endpoint de callback será %%callback%% . Puedes usar la URL que mejor se ajuste a tu configuración e incluso añadir más de una. Así es como queda mi configuración:
Una vez hecho esto, deberías poder finalizar la creación de la app en la parte inferior de la pantalla:
Una vez creada la app, deberías poder recuperar las credenciales de la aplicación en el apartado dedicado de la página:
Opción 1 - Escribir una app capaz de recuperar información desde Hubspot
Para este ejemplo, la app se escribirá en Python y utilizaremos FastAPI como framework para construirla. Después usaremos %%requests%% para generar y enviar peticiones HTTP y, por último, utilizaremos %%python-dotenv%% para cargar las variables de entorno desde nuestros archivos .env.
Primer paso: iniciar el proceso OAuth2
El inicio es bastante sencillo:
Creación del objeto app
A continuación necesitamos añadir un endpoint para recibir la solicitud de autenticación de un cliente que quiera utilizar la app. Llamemos a este endpoint %%auth%%. Este endpoint iniciará el flujo OAuth2. Para ello, primero creará el state a partir de una concatenación aleatoria de caracteres ascii. Después generará la petición HTTP a partir de los datos almacenados en nuestras variables de entorno. Finalmente, enviará la petición, almacenará el state en la app y seguirá la URL de redirección recibida. Esta URL debería ser la que hemos indicado en la petición, es decir, otro endpoint.
Empecemos por cargar las variables de entorno
Carga del archivo .env
Después podemos empezar a escribir la funcionalidad del endpoint. Necesitaremos importar %%RedirectResponse%% desde %%fastapi.responses%% para el valor de retorno.
Primera implementación del endpoint /auth
Primero generamos el state que se utilizará para verificar que la petición que recibimos en el segundo endpoint proviene realmente de nuestra app. Se genera concatenando letras ascii en mayúsculas y minúsculas con el siguiente código:
Generación aleatoria del state
Después recuperamos la URL base de Hubspot en la variable de entorno %%HUBSPOT_URL%%, a la que añadimos /oauth/authorize para apuntar al punto de entrada oauth2 de Hubspot. A partir de ahí, se trata de ensamblar la información necesaria como parámetros de consulta de la petición:
%%client_id%%: desde%%HUBSPOT_CLIENT_ID%%%%scope%%: desde%%HUBSPOT_SCOPE%%%%redirect_uri%%: desde%%HUBSPOT_REDIRECT_URI%%%%state%%: que se ha generado justo antes
Y ya nos topamos con un problema en nuestra implementación ingenua: los scopes de Hubspot están separados por espacios, lo que no encaja bien con la codificación de URL. Así que añadamos una codificación adecuada para nuestros parámetros. Para ello utilizaremos la función quote que ofrece %%urllib.parse%%:
Endpoint /auth final
¡Primer paso completado! Pasemos ahora al endpoint de redirección.
Paso 2: recuperar los tokens de acceso y de actualización
Ese endpoint será el responsable de finalizar el proceso OAuth2 recuperando los tokens de acceso y de actualización. En este ejemplo, este endpoint se llamará %%/callback%%. En este paso tendremos que validar que el state recibido coincide con el esperado, recuperar el code proporcionado por Hubspot y, por último, enviar una petición %%POST%% a la url de tokens de Hubspot para recuperar nuestros tokens.
Para esta nueva petición tendremos que construir un payload y enviarlo como datos codificados en formulario. Por suerte, requests se encarga de definir las cabeceras adecuadas para ello si proporcionamos el payload en el formato correcto. Esta vez queremos devolver los datos en formato JSON, así que necesitaremos importar %%JSONResponse%% desde %%fastapi.responses%%.
Implementación del endpoint callback
Primero comprobamos que el state recibido es el esperado: FastAPI analiza automáticamente la petición recibida por nosotros y traduce el parámetro de consulta %%state%% que hemos recibido a la variable %%state%%. Después se trata de comprobar si %%app.state%% y %%state%% son iguales.
El siguiente paso es construir el payload. Para que %%requests%% defina correctamente las cabeceras, este payload debe definirse como un diccionario de Python y contener la siguiente información:
%%grant_type%%: es una constante que debe fijarse en%%authorization_code%%%%client_id%%: el client ID de Hubspot desde la variable de entorno%%HUBSPOT_CLIENT_ID%%%%client_secret%%: el client secret de Hubspot desde la variable de entorno%%HUBSPOT_CLIENT_SECRET%%%%redirect_uri%%: nuestro redirect_uri desde la variable de entorno%%HUBSPOT_REDIRECT_URI%%%%code%%: el code recibido en la respuesta a la petición anterior
Después enviamos este payload a la URL de tokens de Hubspot recuperada de la variable de entorno %%HUBSPOT_TOKEN_URL%% . La respuesta a esta petición tendrá el siguiente formato:
Respuesta del endpoint de tokens de Hubspot
En este ejemplo sencillo no vamos a actualizar automáticamente el token cuando caduque ni a almacenarlo. Simplemente se lo devolveremos al usuario para que lo almacene y lo reutilice él mismo. Sin embargo, el almacenamiento y la actualización automática de estos tokens no es trivial, ya que deben guardarse de forma segura (cifrado) y no actualizarse con demasiada frecuencia, puesto que eso afectaría al rendimiento de tu app.
¡Segundo paso completado!
Paso extra: actualizar el access token
Ahora añadiremos un endpoint para que el usuario pueda utilizar su %%refresh_token%% y obtener un nuevo %%access_token%% válido. Este endpoint es muy similar al anterior, así que aquí solo cubriré las diferencias.
Endpoint para la renovación del token
Para este endpoint, pediremos al usuario que proporcione su %%refresh_token%% como parámetro de consulta. Después construiremos el payload para el endpoint de tokens de Hubspot como hicimos antes, con las siguientes diferencias:
%%grant_type%%: sigue siendo una constante, pero esta vez debe fijarse en %%refresh_token%%%%code%%: no es necesario y tampoco podríamos proporcionarlo, así que se elimina%%refresh_token%%: el refresh token proporcionado por el usuario
Aquí recibimos el mismo modelo de respuesta que en la primera negociación de tokens y, de nuevo, solo devolvemos los tokens de acceso y de actualización recién generados.
Último paso: recuperar datos de Hubspot
Pasemos al último paso: la recuperación de datos. Ahora que tenemos nuestro %%access_token%%, por fin podemos acceder a la API de Hubspot para recuperar algunos datos. En este ejemplo recuperaremos los contactos almacenados en nuestra empresa, tanto personas como empresas. Para que Hubspot autorice el acceso a estos datos, definimos previamente el scope de la app, que también utilizamos en la negociación del token. Ahora necesitamos demostrar que tenemos acceso proporcionando este token en la petición. En Hubspot, esto se hace a través de las cabeceras de la petición. Las cabeceras deben contener la siguiente:
Después tenemos que realizar la petición adecuada en el o los endpoints designados. Los datos que queremos recuperar se encuentran en 2 endpoints distintos del lado de Hubspot: %%/companies%% y %%/contacts%%. Necesitaremos hacer 2 peticiones para recuperar los datos que queremos.
En este ejemplo, el endpoint de nuestra app se llamará %%/contacts%%.
Este endpoint requerirá que el usuario proporcione su %%access_token%% como parámetro de consulta. A continuación construimos la cabecera tal como se ha descrito antes. En %%requests%%, las cabeceras se proporcionan en forma de diccionario. Por último, realizamos las peticiones %%GET%% en los dos endpoints de interés y almacenamos todos los datos en una lista que después devolvemos como respuesta JSON.
Conclusión
Como hemos visto en esta sección, configurar tu integración lleva bastante tiempo, ya que incluso después de recuperar las credenciales de Hubspot hemos tenido que configurar el proceso de autenticación para obtener secretos utilizables. Hemos pasado por alto las dificultades de almacenar y actualizar estos accesos dejando que el usuario se encargue de conservar el %%access_token%% y de actualizarlo cuando lo necesite. Sin embargo, no es la mejor experiencia de usuario, ya que este tendría que llevar un control de la fecha de caducidad de su token o detectar el fallo de autenticación durante la recuperación de datos para saber que debe actualizar sus accesos. En cambio, cada paso de la integración es modificable y personalizable para adaptarse mejor a nuestro caso de uso, lo que puede ser un factor decisivo.
En conjunto, se trata de una solución perfecta para un producto que requiera pocas integraciones y esté dispuesto a asumir el mantenimiento y un desarrollo que consume mucho tiempo a cambio de disponer de una integración perfectamente a medida.
Opción 2 - Utilizar las Unified APIs de Chift
Intentemos construir el mismo alcance, pero esta vez con Chift. El código que se presenta aquí no está integrado directamente en nuestra app, pero describiré cómo podría estarlo al final de esta sección.
Para construir la integración con Chift, necesitaremos:
- Una cuenta de Chift con la integración de Hubspot activada
Configurar los parámetros de OAuth2
Una vez que hayas iniciado sesión en tu cuenta de Chift, ve a la configuración de Hubspot.
Después, en la página de configuración del conector, puedes introducir el %%client_id%% y el %%client_secret%% que hemos recuperado de tu aplicación de Hubspot.
¡Y ya está todo listo!
Crear un consumer
Después de configurar la información de OAuth2, ve a la página de consumers.
Después añade uno nuevo con el nombre que prefieras.
Asegúrate de guardar el ID del consumer en tu archivo .env y después podrás seguir el enlace del consumer para completar el proceso OAuth2.
A continuación, selecciona "Connect" en la página de selección de conector. Se te pedirá que asignes un nombre a la conexión. Este valor puede ser cualquiera; en mi caso será %%MyConnection%% . Después haz clic en "Authorize" y se iniciará el proceso OAuth2 para recuperar el %%access_token%%.
¡Enhorabuena, solo queda un paso para poder utilizar la API!
Crear una API key
Para crear una API key, tendrás que ir a la sección dedicada en la plataforma de Chift. En esa página también puedes recuperar el account %%ID%% de tu cuenta, así que no olvides hacerlo y añadirlo a tu archivo %%.env%% .
Desde ahí puedes dar un nombre a tu API key y limitarla a un consumer concreto si lo deseas.
¡Y voilà! Ahora puedes guardar toda la información relevante en un lugar seguro, como un gestor de contraseñas y, para la tarea que nos ocupa, en el archivo %%.env%%.
Ahora que tenemos toda la información necesaria, podemos pasar al código.
Recuperar contactos con el SDK de Chift
Para ello volveremos a apoyarnos en la librería %%python-dotenv%% para poblar el entorno con la configuración almacenada en nuestro archivo %%.env%% y en %%chift%%, que es el SDK de Python de la aplicación de Chift.
Lo primero que hay que hacer al trabajar con el SDK es crear un cliente que proporcionará la autenticación para los demás métodos. Así que manos a la obra:
Creación de un objeto ChiftClient
Para crear un %%ChiftClient%%, necesitarás la siguiente información:
%%client_id%%: el client ID proporcionado durante la creación de la API key%%client_secret%%: el client secret proporcionado durante la creación de la API key%%account_id%%: el account ID proporcionado durante la creación de la API key, y también disponible en la página de API keys%%url_base%%: la url de la API de la aplicación de Chift.%%max_retries%%(opcional): número máximo de reintentos por petición; por defecto, 3.
Ahora que tenemos un cliente, podemos utilizarlo para recuperar la abstracción del consumer que creamos antes en la plataforma.
Recuperación de un consumer con el SDK de Chift
Y ahora podemos utilizar esta abstracción para acceder a los datos a los que el consumer tiene acceso. En nuestro ejemplo queríamos recuperar todos los contactos disponibles en nuestra instancia de Hubspot. Con el SDK de Chift, es una sola línea:
Así que ensamblemos las piezas que tenemos para recuperar los contactos de HubspotRecuperación de contactos con el SDK de Chift
Y... ¡eso es todo! Con solo unas pocas líneas de código hemos podido cubrir el mismo alcance que con el enfoque de la aplicación. La ventaja añadida aquí es que no tenemos que encargarnos de almacenar la información de autenticación de Hubspot ni de rotar el access_token nosotros mismos: Chift se ocupa de todo.
Extra: añadir el código de Chift a la app
Esto no está incluido en el repositorio que contiene el código, pero si quisieras añadir el código escrito aquí a tu aplicación, bastaría con portar las funciones de utilidad %%get_client%% y %%get_consumer%% a un lugar donde puedas acceder a ellas desde el código de tu aplicación. Después, mueve el código de la función %%main%% a un nuevo endpoint dedicado, como por ejemplo:
Endpoint de la aplicación que utiliza la integración de Chift
Conclusión
El lector atento probablemente habrá notado que la mayor parte de esta sección consistía en configurar cosas en la plataforma de Chift, lo que puede hacerse en unos pocos clics en cada paso, con muy poco código realmente escrito. Esa es una de las ventajas de utilizar una plataforma así para gestionar tus integraciones: hace falta mucho menos código para lograr el mismo resultado. Por simplicidad, la configuración del consumer se ha hecho a través de la interfaz, pero también podría haberse hecho mediante el SDK.
Esta solución es la más adecuada para soluciones de rápido crecimiento que dependen de múltiples integraciones, o que planean hacerlo. También es perfecta cuando escribir y mantener integraciones no es el núcleo de la solución, sino un medio para un fin. En resumen, cualquier solución que quiera dar soporte a muchas integraciones o que no disponga de los recursos para desarrollarlas y mantenerlas debería plantearse utilizar un proveedor de unified API.
Qué conviene retener de esta comparación
En este artículo hemos expuesto dos enfoques distintos de las integraciones: el primero, escribir las tuyas propias y, el segundo, utilizar un proveedor de unified API.
El primer enfoque tiene la ventaja de la personalización: escribir tu integración para que funcione exactamente como quieres. Pero también conlleva la fricción de hacer las cosas por uno mismo: gestionar el almacenamiento de secretos y la actualización de tus accesos, por ejemplo. Y eso es solo la punta del iceberg: esta solución es difícil de escalar, ya que requiere trabajo para cada una de las integraciones que quieras que tenga tu aplicación. También lleva tiempo mantenerla, ya que cualquier cambio en la API que estés utilizando podría hacer que tu aplicación dejara de funcionar.
Si eliges la segunda opción, puedes aliviar la mayoría de estos puntos de fricción: el proveedor de unified API se encarga de los secretos y de los accesos, la API que utilizas para las integraciones es una y la misma para todas ellas y el mantenimiento pasa a ser mínimo, ya que solo tienes que preocuparte de esa única API en lugar de una por integración. Y, aunque tengas que configurar la plataforma, es un punto de fricción de "primera configuración" en lugar de uno que se repite en todas tus integraciones.
Si quieres estar tranquilo cuando pienses en integraciones, ganar ventaja competitiva y posicionarte para el éxito, elige las Unified APIs de Chift. Ponte en contacto con nuestro equipo para una demo.
