Cómo integrar HotConnect y Webhook

Afiliado

Cómo integrar HotConnect y Webhook

Conoce la finalidad de cada una de estas herramientas.

Daniel Barbosa de Barros

29/11/2022 | Por Daniel Barbosa de Barros

Qué aprenderás en este post

Hotmart ofrece dos formas de conexión automatizadas: HotConnect y Webhook. 

Para usar estas formas de conexión, es necesario contar con la ayuda de un desarrollador. Sin embargo, muchas veces existen dudas sobre cuál es la mejor manera de hacer una integración.

Por eso, con este post, vamos a ayudarte a elegir la mejor forma de conectar el sistema de los usuarios a la plataforma y a mostrarte algunos puntos positivos de HotConnect y Webhook. 

Banner versão desktop

HotConnect

HotConnect es el medio de conexión de los sistemas de los usuarios a la plataforma, utilizando las APIs disponibles en este link (primero debes iniciar sesión en tu cuenta Hotmart). 

Las principales funcionalidades de esta herramienta son:

  • Credenciales
  • Autenticación de usuarios
  • Autenticación de aplicaciones
  • API

Credenciales

Antes de empezar a utilizar HotConnect, es importante crear una credencial en la pestaña Credenciales, haciendo clic en el botón Nueva credencial en la lateral derecha de la pantalla.

Al hacer clic, se abrirá una ventana emergente en la cual tienes que ponerle un nombre a la credencial y guardarla para que aparezca en tus credenciales ya creadas. 

Al hacer clic en Acciones, aparecerán tres opciones:

  • Editar: en la cual puedes alterar el nombre de tu credencial.
  • Parámetros de autenticación: muestra los parámetros necesarios para utilizar los recursos de HotConnect.
  • Quitar: elimina la autenticación. Si eliges esta opción, los sistemas que utilicen esta credencial dejarán de funcionar. 

Al hacer clic en Parámetros de autenticación, aparecerá una nueva ventana emergente con las credenciales para acceder a los recursos de HotConnect, como:

  • Client ID: clave única de identificación de la credencial.
  • Client Secret: código para habilitación de la credencial.
  • Basic: código generado para acceso a los recursos de HotConnect.

Es importante resaltar que, para más seguridad, se permitirán los accesos solo cuando todas las informaciones sean correctas.

Una vez que tienes la credencial, ya puedes utilizar los recursos de HotConnect. A continuación, te mostraremos los principales escenarios de aplicación. 

Autenticación de usuarios

A través de este recurso, el usuario inicia sesión en la plataforma Hotmart habilitando el acceso a las informaciones de las APIs de HotConnect. 

Esta herramienta es muy útil en caso de que tu software necesite información del usuario en la plataforma. 

Un ejemplo son los sistemas que generan facturas a través del historial de ventas. Cuando el Productor acepta el inicio de sesión, el sistema puede generar las notas necesarias con el token de usuario.

Es importante dejar claro que la utilización de este recurso solo es posible con la autorización previa del usuario. 

Autenticación de aplicaciones

Esta funcionalidad es, generalmente, la más utilizada de HotConnect. Con ella, tu aplicación puede usar todas las herramientas de forma automática, pero antes, es necesario autorizar tu aplicación. 

Con las credenciales generadas, la solicitud debe ser realizada, y se ve de la siguiente forma:

Recordando que los espacios [CLIENT_ID], [CLIENT_SECRET] y [BASIC] se deben cambiar por los valores que están en la pestaña Credenciales.

Para que lo entiendas mejor, aquí tienes un ejemplo de código en Curl:

En Java:

Y en Javascript:

En caso de que la solicitud sea realizada correctamente, habrá un retorno en JSON, como en el ejemplo:

Con el access_token en mano, todo lo relacionado con HotConnect puede ser ejecutado agregando la header de la solicitud en el parámetro “Authorization” -> “Bearer [ACCESS_TOKEN]”.

La solicitud debe ser de la siguiente forma:

Ejemplo en Curl:

En Java:

En Javascript:

APIs

Las APIs de HotConnect permiten que tu sistema obtenga todas las informaciones del usuario dentro de Hotmart, tales como:

  • Afiliaciones: Permite que accedas a tus HotLinks de productos ya afiliados para hacer una divulgación más automatizada.
  • Productos: Gestiona tu producto con la posibilidad de crear nuevas ofertas y recupera todos los posibles valores por los que se ofrece tu producto.
  • Reports: Recupera todas las compras y obtén todos sus detalles. Recuerda que los datos de las ventas como Afiliados están disponibles apenas con la autorización del Productor.
  • Suscripción: Permite que tengas las informaciones de las suscripciones de tus clientes.
  • Usuario: Presenta informaciones del usuario que utiliza HotConnect.

Puntos positivos y negativos de HotConnect

Muchos desarrolladores piensan que esta es la mejor forma de conexión porque el control de buscar información sería de total responsabilidad del sistema del cliente, pero eso trae algunos inconvenientes.

Imaginemos que tu software debe comportarse de la siguiente manera:

Después de que se aprueba una compra, el software le envía un email a tu cliente con un bonus. En caso de que sea una solicitud de pago, el sistema debe enviar ese mensaje solamente cuando la compra sea aprobada, y una única vez. Tu sistema tiene la responsabilidad de garantizar esta acción y puede que cueste trabajo que funcione adecuadamente. 

Además, existe una serie de rutinas que tu software debe realizar cada cierto tiempo para verificar si ha habido alguna alteración en el estatus de las entidades que deseas.

Si lo hace varias veces por minuto, además de ser caro, algunas solicitudes pueden ser bloqueadas por Hotmart para evitar una sobrecarga en los servicios. 

Como puntos positivos, tienes la posibilidad de revisar el historial siempre que lo desees y de acceder a tu producto para hacer alteraciones que se reflejarán en tu página.

Webhook

Webhook es la forma que utilizamos para notificar al sistema de forma pasiva. Esto quiere decir que tu sistema solo debe permanecer en espera cuando haya alguna alteración de compra o suscripción.

Antes de empezar, tu sistema debe estar preparado con una API esperando la publicación de las actividades que habrá.

Un consejo: lo primero que tu sistema debe hacer después de recibir la solicitud es guardar el dato para tener toda la información, en caso que sea necesario.

Para empezar a utilizar esta funcionalidad, solo debes hacer clic en este link (primero debes iniciar sesión en tu cuenta Hotmart), y encontrarás la sección de configuración, documentación e historial de envíos. 

Pero, no te preocupes, vamos a hablar sobre cada parte más adelante.

Configuración

En la parte lateral derecha de la pantalla hay un botón + para añadir un nuevo Webhook.

Al hacer clic, llegarás al lugar donde puedes configurar los tipos de eventos que Webhook le notificará al sistema.

En Mi configuración, basta colocar el nombre que deseas para esa configuración.  

El nuevo Webhook permite que sea realizada una segmentación por estatus de las compras, alteraciones de suscripciones, abandono de carritos y productos. 

En el campo de URL debes colocar la de la API de tu plataforma que espera la publicación. 

Después de tu registro, aparecerá una lista con todas las APIs que ya han sido configuradas. 

Ahora, a la derecha, puedes enviar una prueba para esa segmentación, editar o eliminar el registro, además de poder dejarla inactiva temporalmente. 

Prueba de segmentación

Al utilizar Webhook, siempre que lo desees, puedes hacer disparos para tu API con las pruebas que ofrecemos. 

Al hacer clic en Prueba, puedes elegir qué tipo de envío quieres probar. Si lo deseas, puedes probarlos todos al mismo tiempo y ver cómo se comporta tu sistema recibiendo múltiples solicitudes. 

Para las pruebas de compra, será enviado como QUERYSTRING un formulario con un modelo parecido a este:

Para los casos de abandono de carrito y cambio de plan, hemos mejorado las solicitudes utilizando JSON. La publicación para estos casos será en el siguiente formato.

Abandono de carrito:

Cambio de plan:

Documentación

En la pestaña Documentación, puedes encontrar todo lo que enviaremos para cada tipo de notificación.

A continuación, destacamos los campos más importantes que puedes verificar en tu sistema.

  • Hottok:  Token de verificación. Cada cuenta de Hotmart posee un Hottok único para que verifiques que la solicitud está realmente siendo realizada por nuestro Webhook.
  • Prod: Identificador del producto con el que fue realizada la compra o la cancelación.
  • Off: Identificador de la oferta adquirida.
  • Price: Precio de oferta en el momento de la compra.
  • Email: Email del Comprador.
  • Doc: Documento informado por el comprador en el momento de la compra.
  • Transaction: Número de transacción generado por Hotmart.
  • Status: Estatus de la compra. Posibles valores: approved, canceled, billet_printed, refunded, dispute, completed, blocked, chargeback, delayed, expired.
  • Subscriber_code: Enviado en casos de suscripción, es un código para de identificación única de cada Suscriptor.
  • Subscription_status: Estatus de la suscripción. Posibles valores: active, canceled, past_due, expired, started, inactive.
  • Full_price: Valor total de la compra.
  • Currency: Campo utilizado para exhibir la moneda de pago.

Esos campos serán suficientes para el control de tus compras.

Es importante saber que no enviamos información de Comprador a Afiliados sin su permiso, que debe ser habilitado en la plataforma.

Historial

Además de todos los puntos citados, contamos también con la pestaña Historial en la que puedes acompañar las respuestas que estamos recibiendo de tu API al enviar las publicaciones. 

Algunas respuestas son más comunes y vamos a detallarlas aquí:

  • 200: Respuesta positiva para Hotmart diciendo que recibió nuestra solicitud con éxito.
  • 401: No autorizado. Cuando esto ocurre, tu sistema tiene algún tipo de bloqueo que debe ser eliminado para que las solicitudes funcionen normalmente.
  • 404: NOT FOUND. Muchas veces, cuando esto sucede, tu sistema puede haberse caído, o la URL informada es incorrecta.
  • 500: Error interno del servidor. Tu servicio pudo recibir nuestra solicitud pero ha habido un problema y no pudo procesarla correctamente.
  • 1: TIME_OUT: el tiempo límite de espera de respuesta ha sido alcanzado. 

Para todos los errores, se realizan 5 reintentos y es posible visualizar la última respuesta en el detalle de cada historial.

Si tienes algún problema, es posible pedir un nuevo procesamiento de la solicitud cuando ya esté solucionado.

Aspectos positivos y negativos de Webhook

Webhook es muy útil para casos en los que tu aplicación tiene que tomar una decisión instantánea después de algún evento, como, por ejemplo, enviar un email luego de una aprobación de compra. 

En ese caso, cuando cambia el estatus, tu sistema recibe un aviso y puede seguir con el flujo deseado. 

Además, con el conjunto de herramientas de reprocesamiento e historial de solicitudes junto a Hotmart, esta sería una preocupación menos para tu sistema. 

Ahora bien, un aspecto negativo es que, para datos creados antes de que tu sistema entre en funcionamiento, no se crearon solicitudes. Siendo así, es necesario exportar datos más antiguos. 

Otro problema es que, cuando ocurren ventas simultáneas, como en un lanzamiento, si el sistema no está preparado, puede caerse y perder algunas publicaciones. De todos modos, las publicaciones pueden ser procesadas nuevamente. 

Conclusión

Podemos decir que no existe una receta simple para escoger un tipo de integración. 

Para cada caso, se debe analizar cuál es la mejor opción dentro de un amplio abanico de posibilidades, considerando que, para cada aplicación, existe un tipo de conexión que será más adecuado. 

Si necesitas un procesamiento más instantáneo, una buena alternativa es utilizar Webhook, recordando escalar el sistema en caso de un comportamiento atípico, como un lanzamiento. 

Pero, si tu intención es hacer un sistema que va a ponerse en movimiento de vez en cuando para actualizarse a través de un historial, tal vez lo mejor es usar HotConnect.

De todas formas, lo más importante es que primero conozcas esta nueva solución dentro del universo Hotmart.

Sabemos que pensar en conexiones es algo que exige un mayor conocimiento técnico sobre desarrollo. Pero, Hotmart crea soluciones con el objetivo de que nuestros Productores y Afiliados puedan concentrarse cada vez más en trabajar con lo que aman.  

Si quieres conocer otras soluciones, lee nuestro post con 19 herramientas de Hotmart para que vendas más.

Banner versão desktop