Trabajo con OAuth

OAuth es un medio seguro de autentificación que utiliza tokens de autorización en lugar de una contraseña para conectar tu aplicación a una cuenta de usuario. Iniciar el acceso de OAuth es el primer paso para permitir a los usuarios instalar tu aplicación en sus cuentas de HubSpot.

Nota para todos los creadores de aplicaciones: Cualquier aplicación diseñada para ser instalada por varias cuentas de HubSpot o que se anuncie en el Mercado de aplicaciones debe usar OAuth. Si usas una clave API, se rechazará el anuncio de tu aplicación.

Recursos recomendados

La Guía de inicio de OAuth te ayudará a utilizar una aplicación de ejemplo.
Este Tutorial de HubSpot Academy ofrece una introducción rápida en el uso de OAuth con HubSpot, incluyendo un desglose del flujo de HubSpot-OAuth y cómo actualizar un token de acceso.

Iniciando una integración con OAuth 2.0

1. El primer paso para usar OAuth es crear una aplicación en una cuenta de desarrollador de HubSpot. Cuando hagas esto, encontrarás el ID de cliente y la clave del cliente para tu aplicación en la página de autentificación de la configuración de tu aplicación

2. Utiliza el ID de cliente y la clave del cliente, junto con los parámetros de consulta y los alcances que se describen a continuación, para crear la URL de autorización.

3. Envía a los usuarios que deseen instalar tu aplicación la URL de autorización, donde se les presentará con una pantalla que les permita seleccionar una cuenta (si tienen varias cuentas) y conceder acceso a tu integración. Después de conceder el acceso, se redireccionarán a tu aplicación mediante una redirect_url, que tendrá un parámetro de consulta de código adjunto. Usarás ese código y la clave del cliente para obtener un access_token y refresh_token de HubSpot.

URL de autorización de ejemplo

https://app.hubspot.com/oauth/authorize?client_id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&scope=contacts%20automation&redirect_uri=https://www.example.com/

Ejemplo de URL de redireccionamiento

https://www.example.com/?code=xxxx

Error de ejemplo

https://www.example.com/?error=error_code&error_description=Human%20readable%20description%20of%20the%20error

4. Usa el access_token para autentificar las llamadas de API realizadas para esa cuenta de HubSpot.

5. Una vez que expire el access_token, utiliza el refresh_token del paso 3 para generar un nuevo access_token.

Nota: Tu aplicación no aparecerá como una aplicación conectada en la configuración de integración de un usuario a menos que complete los dos primeros pasos. Debes generar el token de actualización y el token de acceso inicial para que la aplicación aparezca como "conectada".

Parámetros de consulta

Estos parámetros son obligatorios al crear una URL de autorización para tu aplicación:

Parámetros obligatorios
Parámetro obligatorio	Descripción	Como usar
ID de cliente	`client_id=x` Usado en la URL	Obtén esto desde la página de configuración de autentificación de la aplicación (como se describe anteriormente).
Redireccionar URL	`redirect_uri=x` Las URL a la que serán redireccionados los visitantes al recibir acceso a tu aplicación	También designarás esto en la página de configuración de autentificación de tu aplicación. Nota: Por razones de seguridad, esta URL debe usar https en producción. (Cuando pruebes usando localhost, puede usarse http) También debes usar un dominio, ya que las direcciones IP no son compatibles.
Alcance	`scope=x%20x`	Un conjunto de permisos separados por espacios a los que su aplicación necesita tener acceso. Cualquier alcance que hayas marcado en la configuración de autentificación de tu aplicación se considerará como obligatorio y tendrás que incluirlos en este parámetro o la página de autentificación mostrará un error. Además, los usuarios recibirán un error si intentan instalar tu aplicación en una cuenta que no tiene acceso a un alcance incluido. Ver la tabla de alcances a continuación para más detalles sobre los puntos de terminación que pueden tener acceso a los alcances específicos.

Y esto es lo que es opcional:

Parámetros opcionales
Parámetro opcional	Como usar	Descripción
Alcances opcionales	`&optional_scope=x%20x`	Un conjunto de permisos opcionales separados por un espacio. Los alcances opcionales se eliminarán automáticamente de la solicitud de autorización si el usuario selecciona una cuenta de HubSpot que no tiene acceso a esa herramienta (como solicitar el alcance en las redes sociales en un portal de CRM). Si estás usando alcances opcionales, deberás verificar el access token o refresh token para ver cuáles se otorgaron. Ver la tabla a continuación para obtener más información sobre los alcances.
Estado	`&state=y` Si este parámetro está incluido en la url de autorización, el valor se incluirá en un parámetro de consulta de estado cuando el usuario sea dirigido a redirect_url.	Un valor de cadena que se puede usar para mantener el estado del usuario cuando se redirecciona de vuelta a tu aplicación

Alcances

OAuth requiere que configures alcances, o permisos, para tu aplicación. Cada alcance proporciona acceso a un conjunto de puntos de terminación de la API de Hub Spot y permite a los usuarios otorgar a tu aplicación acceso a herramientas específicas en su cuenta de HubSpot.

El acceso a las API o puntos de terminación específicos depende del nivel de cuenta de HubSpot. Puedes encontrar una lista completa de alcances disponibles y puntos de terminación disponibles en la siguiente tabla. Si tu aplicación puede funcionar con varios tipos de cuentas de HubSpot, puedes usar el parámetro optional_scope para incluir los alcances con los que trabajas. De esta manera, los clientes que utilizan las cuentas de CRM aún pueden autorizar su aplicación, incluso si no pueden acceder a todos sus alcances. Tu aplicación debe verificar y manejar cualquier alcance para el que no esté autorizada.

Todos los alcances
Alcance	Descripción	Proporciona acceso a	Nivel de cuenta obligatorio
`automation`	Esto incluye los flujos de trabajo.	API de automatización (puntos de terminación de Workflows)	Marketing Hub Pro o Enterprise
`business-intelligence`	Esto incluye puntos de terminación que aparecen sobre las fuentes y los correos.	API de analíticas	Cualquier cuenta
`contacts`	Esto incluye contactos y listas.	Puntos de terminación de contacto, empresas, negocios, propiedades, interacciones y propietarios	Cualquier cuenta
`content`	Esto incluye sitios, páginas de destino, CTA, correo electrónico, blog y campañas.	Puntos de terminación de la API de CMS y Calendario, Correo electrónico y Eventos de Correo Electrónico	CMS Hub Pro o Enterprise o Marketing Hub Pro o Enterprise
`conversations.visitor_identification.tokens.create`	Obtener tokens de identificación para los visitantes del sitio web autentificados que interactúan con el widget de chat de HubSpot.	API de identificación de visitantes	Pro o Empresa
`crm.import`	Te permite importar registros en tu CRM. Esto incluye crear nuevos registros o modificar alguno de tus registros existentes para todos los tipos de datos de CRM (contactos, empresas, negocios, tickets, etc.). No incluye archivar ni eliminar ningún dato.	API de importaciones de CRM	Cualquier cuenta
`cms.source_code.read_write`	Proporciona la capacidad de cargar y descargar plantillas, módulos y otros archivos para los que los desarrolladores deben escribir para los sitios web y los correos electrónicos.	Nombre de la API de archivos de contenido, API de módulos CMS, diseños de CMS, API de plantillas de CMS	CMS Hub Pro o Enterprise o Marketing Hub Pro o Enterprise
`e-commerce`	Esto incluye el acceso a las características de comercio electrónico.	Puntos de terminación de productos y elementos de línea	Sales Hub Pro o Enterprise Nota: Los usuarios deben asignar un cupo de pago de Sales Hub para autorizar este alcance.
`files`	Esto incluye el acceso al Administrador de archivos.	Los archivos (Administrador de archivos) y archivos de archivos (plantillas de CMS, módulos y diseño)	Cualquier cuenta
`forms`	Esto incluye el acceso a los puntos de terminación de los formularios.	Puntos de finalización de los formularios Nota: El acceso a los formularios también requiere el alcance de los `contactos`.	Cualquier cuenta
`forms-uploaded-files`	Descargar archivos enviados a través de un formulario.	Recibe un archivo cargado a través del punto de terminación del envío de formulario	Cualquier cuenta
`hubdb`	Esto incluye el acceso a HubDB.	Puntos de terminación de HubDB	CMS Hub Pro o Enterprise o Marketing Hub Pro o Enterprise con complemento de sitios web
`integration-sync`	Esto expone la API de sincronización, que permite la sincronización de la mayoría de los objetos del CRM.	API del puente de comercio electrónico	Cualquier cuenta
`oauth`	El alcance básico requerido para OAuth.		Cualquier cuenta
`sales-email-read`	Otorga acceso para leer todos los detalles de correos electrónicos individuales enviados a contactos.	Puntos de finalización de las interacciones Nota: Este alcance es obligatorio para obtener el contenido de las interacciones. Ver el Resumen de interacciones para más detalles.	Sales Hub Free, Starter, Pro o Enterprise
`social`	Esto incluye la bandeja de entrada de Redes sociales.	API de redes sociales	Marketing Hub Pro o Enterprise
`tickets`	Esto incluye el acceso a las entradas.	Puntos de terminación de billetes	Service Hub Free, Starter, Pro o Enterprise
`timeline`	Otorga acceso a la administración de eventos personalizados en los registros de HubSpot CRM. Esto incluye crear o actualizar registros.	Puntos de finalización de eventos de cronología	Cualquier cuenta
`transactional-email`	Esto incluye los correos electrónicos transaccionales y los puntos de terminación de los correos electrónicos transaccionales.	Puntos de terminación de correos transaccionales	Marketing Hub Pro o Enterprise con Complemento de correos transaccionales