Aplicaciones públicas

En HubSpot, una aplicación pública es un tipo de integración que puede instalarse en las cuentas de clientes o anunciarse para la venta en el Mercado de aplicaciones. Requiere autentificación a través de OAuth. Una vez que un usuario instala tu aplicación en su cuenta de HubSpot, podrás hacer llamadas de API a esa cuenta usando un token de acceso de OAuth. Tu aplicación también aparecerá en la configuración de Aplicaciones conectadas de la cuenta.

Las aplicaciones conectadas también pueden aprovechar la posibilidad de suscribirse a cambios usando webhooks y creando eventos de línea de tiempo personalizados. 

A continuación, aprenderás a hacer lo siguiente:

Crear una API pública

Cuando creas una aplicación en HubSpot, básicamente estás asociando una aplicación que hayas creado con una cuenta de desarrollador. Para comenzar a crear tu aplicación HubSpot:

  • En tu cuenta de desarrollador de aplicaciones, ve a Aplicaciones en la barra de navegación principal. 
  • En la parte superior derecha, haz clic en Crear aplicación.
  • A continuación, completa la información básica y la configuración de tu aplicación. Cuando los usuarios autentican tu aplicación con su cuenta de HubSpot, verán el nombre, la descripción, el logotipo y cualquier información de contacto de asistencia técnica que proporciones en esta página.

Nota: el nombre de la aplicación se usará dondequiera que se muestre tu aplicación en HubSpot. Esto incluye la instalación de la aplicación, así como el pie de página de Desarrollado por para tarjetas de CRM y eventos de la línea de tiempo.

  • Haz clic en la pestaña Autenticación para ver tu ID de cliente y tu secreto de cliente, así como los alcances asignados de la aplicación. Necesitarás esta información para iniciar una conexión de OAuth entre tu aplicación y HubSpot.

 

Configurar alcances

Los alcances determinan los permisos de tu aplicación para acceder a fuentes de datos o herramientas en una cuenta que haya instalado tu aplicación. Los alcances que configures aparecerán como los parámetros de consulta scope y optional_scope en una URL de instalación que luego puedes proporcionar a los usuarios.

Tipos de alcance

En la pestaña Autenticación, hay tres tipos de alcances diferentes disponibles para que los configures. Debes especificar los alcances que tu aplicación requerirá para la instalación, pero también puedes especificar otros dos tipos de alcances: alcances condicionalmente requeridos y alcances opcionales.

  • Alcances requeridos: alcances que deben ser autorizados por el usuario y deben estar presentes en el parámetro de consulta scope en la URL de instalación de tu aplicación para una instalación exitosa.
  • Alcances condicionalmente requeridos: alcances que deben ser autorizados por el usuario solo si están presentes en el parámetro de consulta scope en la URL de instalación de tu aplicación para una instalación exitosa.
    • Este tipo de alcances te permite ser flexible y proporcionar una URL de instalación separada para funciones o alcances en niveles que solo se requieren cuando los usuarios habilitan ciertas funciones en tu aplicación. Por ejemplo, podrías ofrecer dos URL de instalación a tus usuarios: una URL de instalación podría incluir el alcance condicionalmente requerido en el parámetro de consulta scope para usuarios con acceso a una característica, mientras que otra URL de instalación omite ese alcance en el parámetro de consulta scope para usuarios sin acceso.
    • Si un alcance condicionalmente requerido está presente en la URL de instalación de tu aplicación y un usuario sin acceso a la función asociada intenta instalar tu aplicación utilizando esa URL, la instalación fallará.
  • Alcances opcionales: alcances que no son necesarios para instalar correctamente tu aplicación. Estos alcances se especifican en el parámetro de consulta optional_scope en la URL de instalación de tu aplicación. Por ejemplo, si quieres que tu aplicación pueda obtener datos de objetos personalizados (que solo están disponibles para las cuentas de HubSpot Enterprise), puedes agregar el alcance crm.objects.custom.read como alcance opcional. Luego, si una cuenta tiene acceso a los objetos personalizados, se autorizará el alcance. De lo contrario, aún se podrá instalar la aplicación sin el alcance de los objetos personalizados.

 

Configurar los alcances públicos de tu aplicación

Para personalizar tu configuración de alcances y agregar nuevos alcances:

  • Para configurar los alcances condicionalmente requeridos u opcionales, haz clic en para activar el botón Activar la configuración avanzada de alcances.

turn-on-advanced-scope-settings-toggle-in-public-app-auth-tab

Nota: a partir del 21 de octubre de 2024, se requerirán configuraciones avanzadas de alcance para todas las aplicaciones. Más información sobre el Changelog de desarrollador de HubSpot.
  • En la sección Alcances, haz clic en Agregar alcance nuevo.
  • En el panel derecho, usa la barra de búsqueda para buscar un alcance y luego selecciona la casilla de verificación junto a cualquier alcance que desees que el usuario autorice. Si activaste la configuración avanzada del alcance, haz clic en el menú desplegable junto al alcance y selecciona un tipo de alcance.
  • Haz clic en Actualizar.
add-new-scope-panel-in-public-app-setup
  • Revisa tus alcances configurados. Si activaste la configuración avanzada del alcance, puedes cambiar el tipo de cualquier alcance haciendo clic en el menú desplegable que aparece a su lado. También puedes hacer clic en Eliminar para eliminar uno de los alcances de tu aplicación.
review-new-scope-settings-in-public-app-setup
  • Cuando hayas terminado de configurar la aplicación, haz clic en Crear aplicación en la parte inferior izquierda.

Con tu aplicación creada, ahora puedes recorrer el proceso de instalación.

Nota: se recomienda agregar un dominio verificado a la aplicación para agregar otro nivel de confianza para los usuarios que instalan tu aplicación. De lo contrario, la aplicación mostrará un banner que indica que la aplicación no está verificada.

Instalar una aplicación

Nota: antes de instalar la aplicación, ten en cuenta lo siguiente:

  • Una aplicación no aparecerá en la página Aplicaciones conectadas de una cuenta hasta que se creen tokens de acceso inicial y de actualización.
  • Solo los usuarios con acceso a los alcances requeridos o condicionalmente requeridos de una aplicación pueden instalarla.
  • Las aplicaciones no se pueden instalar en las cuentas de desarrollador. Para probar tu aplicación, deberás crear una cuenta de prueba en tu cuenta de desarrollador de aplicaciones e instalarla allí.

Instalar una aplicación puede dividirse en dos pasos: autorización y generación de tokens.

Autorizar tu aplicación con una cuenta de cliente 

  • Para autorizar tu aplicación con una cuenta de HubSpot, deberás crear una URL de autorización. Haz esto al obtener el ID del cliente para tu aplicación e iniciar el proceso de OAuth.
  • Una vez que tu URL esté lista, ábrela en tu navegador para ver una lista de todas tus cuentas de HubSpot. Esto también es lo que verán los usuarios una vez que comienzas a dirigirlos a esta URL.
  • Selecciona la cuenta donde deseas instalar tu aplicación.

select_account-1

  • Después de elegir una cuenta, recibirás una lista de alcances basados en los parámetros &scopes= y &optional_scope= que configuraste para la URL de autorización.

Nota: si incluyes un optional_scope y la cuenta seleccionada no tiene acceso a é (como el alcance del contenido para una cuenta de CRM), no se incluirá en la lista.

  • Haz clic en Autorizar acceso para autorizar la conexión.

approve_scopes-1

  • Después de otorgar acceso, se te redireccionará según el parámetro &redirect_uri= en la URL de autorización original y un parámetro ?code= se anexará a la URL. Usa ese código en el siguiente paso para generar un token de acceso.

Generar los tokens OAuth iniciales 

Para generar tus tokens de acceso inicial y de actualización, necesitaras el código del parámetro ?code= de la URL de autorización, redirect_url, ID de cliente y secreto del cliente. Las instrucciones detalladas están aquí

Una vez que hayas autorizado tu aplicación y de que hayas generado el token inicial, la instalación estará completa. Se incluirá en la página Aplicaciones conectadas y comenzarás a recibir solicitudes de búsqueda de webhook y Tarjetas de CRM.

connected_apps-1

 

Gestionar aplicaciones públicas en HubSpot

Find an app's ID

Puedes encontrar el ID de una aplicación pública en tu cuenta de desarrollador de aplicaciones utilizando cualquiera de los siguientes métodos:

  • En tu cuenta de desarrollador, navega a Aplicaciones en la barra de navegación principal y luego ve el ID de la aplicación que aparece debajo del nombre de tu aplicación.
find-app-id
  • En tu cuenta de desarrollador, navega a Aplicaciones en la barra de navegación principal y luego haz clic en el nombre de la aplicación. En la página Información básica, haz clic en la pestaña Autenticación y luego ve el ID de la aplicación.

find-app-id-auth-settings

Monitorear del comportamiento de la aplicación

HubSpot registra todas las solicitudes realizadas desde o hacia una aplicación conectada, incluidas las solicitudes entrantes usando un token de acceso OAuth o las solicitudes salientes de webhooks o tarjetas de CRM. 

Para ver este registro de solicitud:

  • En tu cuenta de desarrollador, ve a Aplicaciones en la barra de navegación principal.
  • Haz clic en el nombre de la aplicación.
  • En el menú de la barra lateral izquierda, navega a Monitorización
  • Usa las pestañas para ver los diferentes tipos de solicitudes que se realizan desde o hacia la aplicación. Mientras ves estos registros, puedes hacer clic en una solicitud individual para ver más información sobre ella, que incluye:
    • para solicitudes exitosas, el método de solicitud, la ruta y el tiempo de solicitud.
    • para solicitudes fallidas, información de error adicional, como los encabezados y el cuerpo de la respuesta.

request_details

A continuación, obtén más información sobre cada pestaña de la página Monitorización.

  • Llamadas de API: la pestaña Llamadas de API muestra todas las solicitudes realizadas a tu aplicación usando un token de acceso OAuth. Se puede filtrar por método HTTP, código de respuesta, período o URL de solicitud.
  • Webhooks: la pestaña Webhooks muestra las solicitudes de HubSpot para cualquiera de las suscripciones a webhook de tu aplicación. Filtrar por respuesta (incluyendo tiempos de espera y fallas de conexión), estado (exitoso, volverá a intentar o falla), tipo de suscripción, período de tiempo, intento, lote, evento o ID de cuenta.

Nota: el ID de intento sería una combinación de subscriptionId, eventId y attemptNumber de una solicitud específica.

  • Extensiones de CRM: la pestaña Extensiones de CRM muestra las solicitudes de las tarjetas de CRM de su aplicación. Filtrar por tipo de objeto de extensión, tipo de objeto de CRM (contacto, empresa, ticket o negocio), tipo de error o advertencia, período de tiempo, ID de solicitud o ID de registro de CRM (es decir, un ID de contacto específico).
  • Configuración de la aplicación: la pestaña Configuración de la aplicación te permite configurar la página de configuración que viene con tu aplicación.

En cada pestaña, si se produjo algún evento asociado en los últimos 30 días (por ejemplo, se produjo un desencadenante de webhook o se realizó una llamada a la API), puedes hacer clic en Exportar registros para exportar los datos del evento asociado a un CSV:

  • En el cuadro de diálogo, configura cuántos días de datos exportar (hasta 30 días).
  • Haz clic en Exportar. Se enviará una notificación por correo electrónico a la dirección de correo asociada con tu usuario en la configuración de HubSpot.

Agregar un dominio verificado

Cuando los usuarios de HubSpot instalan una aplicación, consienten en dar acceso al desarrollador de la aplicación a los datos de su cuenta. La identidad y la reputación del desarrollador juegan un papel importante en la decisión de un usuario de continuar con la instalación. Para garantizar el pleno consentimiento del usuario al instalar una aplicación, HubSpot mostrará un mensaje en la pantalla de instalación de la aplicación para indicar el nivel de verificación de la aplicación y el anuncio en el mercado de aplicaciones:

  • Cuando una aplicación no tiene un dominio verificado, HubSpot mostrará un banner en la pantalla de instalación que dice que la aplicación no ha sido verificada.
    not-verified
  • Cuando la aplicación tiene un dominio verificado pero no aparece en el Mercado de aplicaciones, HubSpot mostrará el dominio verificado junto con un banner en la pantalla de instalación que dice que la aplicación no ha sido revisada o aprobada por HubSpot. verified-not-listed
  • Cuando una aplicación se anuncia en el mercado, pasando el proceso de revisión de aplicaciones de HubSpot, HubSpot no mostrará ninguno de los banners anteriores. No es necesario que verifiques el dominio si tu aplicación aparece en el Mercado de aplicaciones.
    verified-and-listed

Agregar un dominio verificado

Para agregar un dominio verificado a la aplicación, primero deberás agregar el dominio a la configuración de la aplicación y luego agregar un registro TXT a la configuración de DNS del dominio:

  • En tu cuenta de desarrollador de aplicaciones, navega a Aplicaciones.
  • Haz clic en el nombre de la aplicación.
  • En la barra lateral izquierda, navega a Contacto y asistencia técnica.
  • En el campo Dominio de la empresa, escribe tu dominio y luego haz clic en Guardar. Aparecerá un mensaje debajo del dominio de la empresa indicando que el dominio aún no ha sido verificado.
  • Haz clic en Verificar ahora para comenzar el proceso de verificación.

domain-verification-for-app


  • En el panel derecho, confirma que el dominio se ha introducido correctamente y luego haz clic en Siguiente.
  • Copia el valor de registro TXT requerido haciendo clic en Copiar en la columna Valor.
    verify-app-domain-copy-value
  • En tu proveedor de DNS, crea un registro TXT con el valor copiado. A continuación, aparecen instrucciones para algunos proveedores de DNS comunes:
  • Después de actualizar la configuración de tu DNS, vuelve a HubSpot y luego haz clic en Siguiente en el panel derecho. Los registros DNS pueden tardar hasta 48 horas en actualizarse, por lo que es posible que HubSpot no reconozca el cambio de inmediato. Puedes volver a esta pantalla en cualquier momento seleccionando Verificar ahora de nuevo en la página de configuración Información de la empresa.
  • Una vez verificado, verás un indicador de estado de éxito en el campo Dominio de la empresa.

Domain verified__export

Notas adicionales

  • Para garantizar la propiedad continua del dominio, HubSpot continuará verificando que el registro de TXT esté presente de forma regular. La advertencia de instalación volverá si el registro TXT se elimina o modifica.
  • Actualmente, solo puedes tener un dominio verificado por cuenta de desarrollador. Todas las aplicaciones en una cuenta comparten el dominio verificado. El dominio en la página de instalación se enlaza con tu dominio raíz.
  • Si eliminas tu dominio verificado, todas las aplicaciones de tu cuenta de desarrollador volverán a recibir la advertencia de instalación. Puedes verificar otro dominio, pero el proceso tardará algunas horas.

 


¿Te resultó útil este artículo?
Con este formulario puedes enviar tu opinión sobre nuestros documentos para desarrolladores. Si tienes comentarios sobre el producto de HubSpot, puedes enviarlos al Foro de ideas.