Trabajo con OAuth
OAuth es un medio seguro de autentificación que usa 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:
- 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.
- los usuarios que instalen aplicaciones en su cuenta de HubSpot deben ser superadministradores o tener permisos de acceso al mercado de aplicaciones.
Recursos recomendados
- La Guía de inicio de OAuth te ayudará a usar 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.
Para iniciar una integración con OAuth 2.0:
- En primer lugar, crea una aplicación en una cuenta de desarrollador de HubSpot. Después de crear la aplicación, podrás encontrar el ID de cliente de la aplicación y el secreto del cliente en la página de autentificación de la configuración de tu aplicación.
- Usa 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.
- Envía a los usuarios que deseen instalar tu aplicación a la URL de autorización, donde se les presentará una pantalla que les permitirá seleccionar su cuenta y conceder acceso a tu integración. Después de conceder 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.- Ejemplo de URL de autorización:
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
- Ejemplo de error:
https://www.example.com/?error=error_code&error_description=Human%20readable%20description%20of%20the%20error
- Ejemplo de URL de autorización:
- Usa el
access_token
para autentificar las llamadas de API realizadas para esa cuenta de HubSpot. - Una vez que expire el
access_token
, usa elrefresh_token
para generar un nuevoaccess_token
.
Nota:
- tu aplicación no aparecerá como Aplicación conectada en la cuenta de un usuario a menos que generes el token de actualización y el token de acceso inicial.
- los tokens de acceso reflejan los alcances solicitados desde la aplicación y no reflejan los permisos o limitaciones de lo que un usuario puede hacer en su cuenta de HubSpot. Por ejemplo, si un usuario tiene permisos para ver solo los contactos de su propiedad, pero autoriza una solicitud para el alcance
crm.objects.contacts.read
, el token de acceso resultante puede ver todos los contactos de la cuenta y no solo los que son propiedad del usuario autorizante.
Los siguientes parámetros son obligatorios al crear una URL de autorización para tu aplicación:
Parámetro | Descripción | Como usar |
---|---|---|
ID de cliente | client_id=x Se usa en la URL |
Obtén esto desde la página de configuración de autentificación de la aplicación (como se describió anteriormente). |
Redireccionar URL | redirect_uri=x Las URL a las 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 al que tu 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 incluirlo 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. |
Los siguientes parámetros son opcionales:
Parámetro | Como usar | Descripción |
---|---|---|
Alcances opcionales | &optional_scope=x%20x |
Un conjunto de permisos opcionales separados por un espacio para tu aplicación. 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 token de acceso o el token de actualización para ver cuáles se otorgaron. Ve 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 regreso a tu aplicación. |
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 HubSpot 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 usan las cuentas de CRM aún pueden autorizar tu 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.
Alcance | Descripción | Proporciona acceso a | Nivel de cuenta obligatorio |
---|---|---|---|
cms.domains.read |
Los integradores pueden enumerar dominios de CMS en la cuenta de un cliente. | API del CMS | Cualquier cuenta |
cms.domains.write |
Los integradores pueden crear, actualizar y eliminar dominios personalizados de CMS. | API del CMS | Cualquier cuenta |
cms.functions.read |
Los integradores pueden ver todas las funciones sin servidor de CMS, cualquier secreto relacionado y los resultados de la ejecución de funciones. | API del CMS | CMS Hub Enterprise |
cms.functions.write |
Los integradores pueden escribir funciones y secretos sin servidor de CMS. | API del CMS | CMS Hub Enterprise |
cms.knowledge_base.articles.read |
Ver detalles sobre los artículos de conocimiento. | API del CMS | Service Hub Pro y Enterprise |
|
Otorga acceso para actualizar artículos de conocimiento. | API del CMS | Service Hub Pro o Enterprise |
cms.knowledge_base.articles.publish |
Otorga acceso para actualizar y publicar artículos de conocimiento. | API del CMS | Service Hub Pro o Enterprise |
cms.knowledge_base.settings.read |
Ve la configuración general y de la base de conocimientos de la plantilla, como el dominio o la URL raíz. | API del CMS | Service Hub Pro o Enterprise |
cms.knowledge_base.settings.write |
Otorga acceso para actualizar la configuración general y de la base de conocimientos de la plantilla. Esto incluye escribir artículos de conocimiento. | API del CMS | Service Hub Pro o Enterprise |
cms.performance.read |
Los integradores pueden ver los datos de rendimiento de CMS para todos tus sitios. | API del CMS | Cualquier cuenta |
crm.lists.read |
Ve detalles de listas de contactos. | Puntos de terminación de listas | Cualquier cuenta |
crm.lists.write |
Crea, elimina o haz cambios en listas de contactos | Puntos de terminación de listas | Cualquier cuenta |
crm.objects.companies.read |
Ve propiedades y otros detalles acerca de las empresas. | Puntos de terminación de empresas | Cualquier cuenta |
crm.objects.companies.write |
Ve propiedades y crea, elimina o haz cambios en las empresas. | Puntos de terminación de empresas | Cualquier cuenta |
crm.objects.contacts.read |
Ve propiedades y otros detalles acerca de los contactos. | Puntos de terminación de contactos | Cualquier cuenta |
crm.objects.contacts.write |
Ve propiedades y crea, elimina o haz cambios en los contactos. | Puntos de terminación de contactos | Cualquier cuenta |
crm.objects.custom.read |
Ver detalles acerca de los objetos personalizados en el CRM | Puntos de terminación de objetos personalizados | Cualquier Enterprise |
crm.objects.custom.write |
Crear, eliminar o hacer cambios a los objetos personalizados en el CRM | Puntos de terminación de objetos personalizados | Cualquier Enterprise |
crm.objects.deals.read |
Ve propiedades y otros detalles acerca de los negocios. | Puntos de terminación de negocios | Cualquier cuenta |
crm.objects.deals.write |
Ve propiedades y crea, elimina o haz cambios en los negocios. | Puntos de terminación de negocios | Cualquier cuenta |
crm.objects.feedback_submission.read |
Ver detalles sobre los envíos a cualquiera de tus encuestas de feedback. | Puntos de terminación de encuestas de feedback | Service Hub Pro o Enterprise |
crm.objects.goals.read |
Ve todos los tipos de metas. | Puntos de terminación de metas | Sales Hub Starter, Pro o Enterprise |
crm.objects.line_items.read |
Ve propiedades y otros detalles acerca de los elementos de pedido. | Ver puntos de terminación de elementos de pedido | Cualquier cuenta |
crm.objects.line_items.write |
Crea, elimina o haz cambios a elementos de pedido. | Ver puntos de terminación de elementos de pedido | Cualquier cuenta |
crm.objects.marketing_events.read |
Ver detalles sobre eventos de marketing. | Puntos de terminación de eventos de marketing | Cualquier cuenta |
crm.objects.marketing_events.write |
Crear, eliminar o hacer cambios a los eventos de marketing. | Puntos de terminación de eventos de marketing | Cualquier cuenta |
crm.objects.owners.read |
Ve detalles de usuarios asignados a un registro del CRM. | Puntos de terminación de responsables | Cualquier cuenta |
crm.objects.quotes.read |
Ve propiedades y otros detalles acerca de las cotizaciones y plantillas de cotizaciones. | Puntos de terminación de cotizaciones | Cualquier cuenta |
crm.objects.quotes.write |
Crea, elimina o haz cambios a cotizaciones. | Puntos de terminación de cotizaciones | Cualquier cuenta |
crm.schemas.companies.read |
Ve detalles de configuración de propiedades de las empresas | Puntos de terminación de propiedades | Cualquier cuenta |
crm.schemas.companies.write |
Crea, elimina o haz cambios en la configuración de propiedades de las empresas. | Puntos de terminación de propiedades | Cualquier cuenta |
crm.schemas.contacts.read |
Ve detalles de configuración de propiedades de los contactos. | Puntos de terminación de propiedades. | Cualquier cuenta |
crm.schemas.contacts.write |
Crea, elimina o haz cambios en la configuración de propiedades de los contactos. | Puntos de terminación de propiedades | Cualquier cuenta |
crm.schemas.custom.read |
Ver detalles acerca de las definiciones de los objetos personalizados en el CRM. | Puntos de terminación de objetos personalizados | Cualquier Enterprise |
crm.schemas.deals.read |
Ve detalles de configuración de propiedades de los negocios. | Puntos de terminación de propiedades | Cualquier cuenta |
crm.schemas.deals.write |
Crea, elimina o haz cambios en la configuración de propiedades de los negocios. | Puntos de terminación de propiedades | Cualquier cuenta |
crm.schemas.line_items.read |
Ve detalles acerca de elementos de pedido. | Ver puntos de terminación de elementos de pedido | Cualquier cuenta |
crm.schemas.quotes.read |
Ver detalles acerca de las cotizaciones y plantillas de cotizaciones. | Puntos de terminación de cotizaciones | Cualquier cuenta |
settings.billing.write |
Realiza cambios en la configuración de facturación de tu cuenta. Esto incluye la gestión y asignación de licencias de pago para los usuarios. | Configurar puntos de terminación | Cualquier cuenta |
settings.currencies.read |
Lee los tipos de cambio existentes junto con la moneda actual de la empresa asociada con tu portal. | Puntos de terminación de información de la cuenta | Cualquier cuenta |
settings.currencies.write |
Crea, actualiza y elimina los tipos de cambio junto con la actualización de la moneda de la empresa asociada a tu portal. | Puntos de terminación de información de la cuenta | Cualquier cuenta |
settings.users.read |
Ve detalles sobre los usuarios de la cuenta y sus permisos. | Puntos de terminación de aprovisionamiento de usuarios | Cualquier cuenta |
settings.users.write |
Gestiona los usuarios y los permisos de usuario en tu cuenta de HubSpot. Esto incluye la creación de nuevos usuarios, la asignación de permisos y roles, y la eliminación de usuarios existentes. | Puntos de terminación de aprovisionamiento de usuarios | Cualquier cuenta |
settings.users.teams.read |
Consulta los detalles sobre los equipos de la cuenta. | Puntos de terminación de aprovisionamiento de usuarios | Cualquier cuenta |
settings.users.team.write |
Asigna usuarios a los equipos en tu cuenta de HubSpot. | Puntos de terminación de aprovisionamiento de usuarios | Cualquier cuenta |
account-info.security.read |
Incluye acceso a los registros de actividad de la cuenta y otra información de seguridad de la cuenta. | API de actividad de la cuenta | Cualquier cuenta |
accounting |
Esto permite que HubSpot y la integración de contabilidad compartan detalles de facturación, productos y contactos. | API de extensión de contabilidad | Cualquier cuenta |
actions |
Agrega formularios a las páginas del contacto que realizan acciones personalizadas. | API de extensiones del CRM | Cualquier cuenta |
analytics.behavioral_events.send |
Esto incluye el acceso al envío de eventos de comportamiento personalizados | API de analíticas | Marketing Hub Enterprise |
automation |
Esto incluye los workflows. | API de automatización (puntos de terminación de Workflows) | Marketing Hub Pro o Enterprise |
behavioral_events.event_definitions.read_write |
Crea, lee, actualiza o elimina eventos de comportamiento. Esto incluye propiedades de eventos de comportamiento. | API de analíticas | Marketing Hub Enterprise |
business_units.view.read |
Ve datos de unidades de negocio, incluida la información del logotipo. | API de unidades de negocio | Complemento de unidades de negocio |
business-intelligence |
Esto incluye puntos de terminación que aparecen sobre las fuentes y los correos. | API de analíticas | Cualquier cuenta |
collector.graphql_query.execute |
Consulta datos de tu cuenta de HubSpot utilizando el punto de terminación de API de GraphQL | Punto de terminación de API de GraphQL | CMS Hub Pro o Enterprise. |
collector.graphql_schema.read |
Realiza consultas de introspección a través de clientes de aplicaciones GraphQL, como GraphiQL | GraphiQL y otros clientes de terceros de GraphQL | CMS Hub Pro o Enterprise |
communication_preferences.read |
Ver detalles de las preferencias de suscripción de tus contactos. | API de preferencias de suscripción | Cualquier cuenta |
communication_preferences.read_write |
Suscríbete/cancela la suscripción de contactos a tus tipos de suscripción. No suscribirá a los contactos que se hayan dado de baja. | API de preferencias de suscripción | Cualquier cuenta |
communication_preferences.write |
Suscríbete/cancela la suscripción de contactos a tus tipos de suscripción. No suscribirá a los contactos que se hayan dado de baja. | API de preferencias de suscripción | Cualquier cuenta |
content |
Esto incluye sitios, páginas de destino, 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.read |
Ve detalles sobre las cadenas en la bandeja de entrada de conversaciones. | Bandeja de entrada de conversaciones y API de mensajes | Cualquier cuenta |
conversations.visitor_identification.tokens.create |
Obtén tokens de identificación para los visitantes del sitio web autentificados que interactúen con el widget de chat de HubSpot. | API de identificación de visitantes | Cualquier Pro o Enterprise |
conversaciones.write |
Envía mensajes en conversaciones. Crea y actualiza hilos de mensajes. | Bandeja de entrada de conversaciones y API de mensajes | Cualquier cuenta |
crm.export |
Exporta registros desde tu CRM para todos los tipos de datos de CRM. | API de importaciones de CRM | Cualquier cuenta |
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 |
ctas.read |
Permite el acceso de lectura para las CTA. | No hay publicAPI disponible | Marketing Hub o CMS Hub Starter, Pro o Enterprise |
e-commerce |
Esto incluye acceso a las características de comercio electrónico. | Puntos de terminación de productos y elementos de línea |
Cualquier cuenta Nota: solo las cuentas Pro y Enterprise pueden usar este alcance para la API de productos. |
external_integrations.forms.access |
Incluye la capacidad de cambiar el nombre, eliminar y clonar formularios existentes. | Puntos de terminación de formularios |
Cualquier cuenta |
files |
Esto incluye acceso al Administrador de archivos. | Los archivos (Administrador de archivos) y archivos de archivos (plantillas de CMS, módulos y diseño) | Cualquier cuenta |
files.ui_hidden.read |
Ver detalles o descargar archivos de usuarios, archivos adjuntos y archivos del sistema de todas las herramientas de HubSpot. | Los archivos (Administrador de archivos) y archivos de archivos (plantillas de CMS, módulos y diseño) | Cualquier cuenta |
forms |
Esto incluye acceso a los puntos de terminación de los formularios. | Puntos de terminación de formularios | 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 acceso a HubDB. | Puntos de terminación de HubDB | CMS Hub Pro o Enterprise, o Marketing Hub Pro o Enterprise con el el 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 bridge de comercio electrónico | Cualquier cuenta |
media_bridge.read |
Otorga acceso a eventos y objetos desde el puente multimedia. | API de Centro multimedia | Cualquier cuenta |
media_bridge.write |
Otorga acceso para crear y actualizar eventos y objetos desde el puente multimedia. | API de Centro multimedia | Cualquier cuenta |
oauth |
El alcance básico requerido para OAuth. Este alcance se agrega por opción predeterminada a todas las aplicaciones. | Cualquier cuenta | |
sales-email-read |
Otorga acceso para leer todos los detalles de correos electrónicos individuales enviados a contactos. | Puntos de terminación de interacciones Nota: este alcance es obligatorio para obtener el contenido de las interacciones por correo electrónico. Ver el Resumen de interacciones para más detalles. |
Cualquier cuenta |
social |
Esto incluye la bandeja de entrada de Redes sociales. | API de redes sociales | Marketing Hub Pro o Enterprise |
tickets |
Esto incluye acceso a tickets. | Puntos de terminación de tickets | Cualquier cuenta |
timeline |
Otorga acceso a la administración de eventos personalizados en los registros de HubSpot CRM. Esto incluye crear o actualizar registros. | Puntos de terminación de eventos de cronología | Cualquier cuenta |
transactional-email |
Esto incluye 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 el complemento de correo electrónico transaccional |