¿Cómo Crear Propiedades Masivamente en Objetos de HubSpot?

Este proceso es beneficioso tanto para aquellos que están implementando HubSpot y necesitan configurar propiedades de manera eficiente en diferentes objetos, como para implementadores experimentados que desean simplificar su gestión en HubSpot


Tabla de Contenido


¿Cuál es el Objetivo de Este Proceso?

El objetivo de este proceso es guiar a los usuarios, ya sean nuevos implementadores o profesionales experimentados, a través de un método claro y estructurado para crear propiedades en HubSpot de manera masiva utilizando la API.

Pasos Detallados para Crear Propiedades Masivamente en HubSpot:

Paso 1: Configuración Inicial

  1. Accede a tu cuenta de HubSpot: Inicia sesión en tu cuenta de HubSpot para obtener acceso a las funcionalidades y recursos necesarios.

  2. Credenciales de API: Asegúrate de disponer de tus credenciales de API (Clave API) para autorizar las solicitudes a la API de HubSpot.

  3. Herramienta para Llamadas API: Utiliza herramientas como Postman. Postman te permite realizar solicitudes a la API y verificar las respuestas.

pm-logo-horiz

Puedes descargar Postman desde este enlace.


Paso 2: Autenticación

  • Genera una Clave API: Para obtenerla debes acceder a una App privada en tu Cuenta Hubspot.

    Las aplicaciones privadas permiten utilizar las API de HubSpot para obtener acceso a datos específicos de tu cuenta de HubSpot. Puedes autorizar lo que puede solicitar o cambiar cada aplicación privada en tu cuenta, lo que generará un token de acceso que es único para tu aplicación. 

📢 Debes ser un super admin para acceder a las aplicaciones privadas de tu cuenta de HubSpot.

 Si no tienes una App Privada generada en tu cuenta para acceder a las API de Hubspot, puedes crearla asi:

Paso 2.1 Crear una aplicación privada

  • En tu cuenta de HubSpot, haz clic en el ícono de configuración en la barra de navegación principal.
  • En el menú de la barra lateral izquierda, navega a Integraciones > Aplicaciones privadas.
  • Haz clic en Crear App privada.
  • En la ficha Información básica, configura los detalles de tu aplicación:
    • Introduce el Nombre de tu aplicación.
    • Coloca el cursor sobre el logotipo del parámetro de sustitución y haz clic en cargar icono para cargar una imagen cuadrada que funcionará como logotipo de tu aplicación.
    • Introduce una descripción para tu aplicación.
  • Haz clic en la pestaña Alcances.
  • Selecciona la casilla de comprobación Lectura o Escritura para cada uno de los alcances a los que deseas que tu aplicación pueda acceder (Te sugerimos para este caso marcar todas las opciones de la sección CRM). También puedes buscar un alcance específico usando la barra de búsqueda Buscar un alcance.
  • Después de configurar tu aplicación, haz clic en Crear aplicación en la parte superior derecha.

updated-read-write-scope-config-private-apps

  • En el cuadro de diálogo, revisa el contenido y haz clic en Enviar enlace.

Una vez hayas creado tu aplicación, puedes comenzar a hacer llamadas de API usando el token de acceso de la aplicación. Si necesitas editar la información de tu aplicación o cambiar sus alcances, haz clic en Editar detalles.

edit-details-of-private-app

Paso 2.2 Obtener el token/API key de acceso de tu aplicación.

Para obtener el token/Api Key, navega a la página de detalles de tu aplicación.

  • En la tarjeta de token Acceso, haz clic en Mostrar token para revelar tu token de acceso. Haz clic en Copiar para copiar el token en tu portapapeles.

A continuación, te proporcionamos un video explicativo que presenta los pasos descritos aquí, ofreciéndote una guía visual para realizar el proceso.

Paso 3: Preparación de Datos para Propiedades

  • Utiliza una Hoja de Cálculo de Excel: Abre una hoja de cálculo en Excel para organizar los datos de las propiedades que deseas crear.

  • Define Encabezados: Crea encabezados para cada propiedad, debes incluir los siguientes:

📝📥 Aquí te dejamos una plantilla guía para definir las propiedades. Descargar aqui.

Desglose Ilustrativo de los Componentes de una Propiedad en HubSpot
Nombre del Encabezado Descripción  Opciones disponibles Equivalencia con creación manual en Hubspot/Observaciones
type El valor type determina el tipo de propiedad, es decir, una cadena o un número bool, date, datetime, string, number, enumeration
fieldType fieldType determina cómo aparecerá la propiedad en HubSpot o en un formulario, es decir, como un campo de texto corto, campo de texto largo, un número o un selector de fechas.
bool booleancheckbox
date date
datetime date
string file, text, textarea, html
number number
enumeration checkbox, radio, select

 

groupName Corresponde al nombre interno del grupo que se utiliza para agrupar propiedades relacionadas. Cualquier propiedad agrupada aparecerá junto entre sí en los registros de HubSpot

N/A

Se recomienda que los grupos sean creados previamente en Hubspot para luego usarlos en el cargue masivo. 

Para obtener el nombre interno del grupo debes hacer lo siguiente:

  • Haz clic en el ícono de configuración en la barra de navegación principal.
  • En el menú de la barra lateral izquierda, navega a Propiedades
  • Luego en el objeto elegido filtra por el grupo que deseas saber su nombre interno.
  • Sobre la URL puedes tomar el nombre interno una vez sea aplicado el filtro.

    A continuación un ejemplo de URL donde podemos ver el valor a tomar, que  es lo que sigue de group=
  • "https://app.hubspot.com/property-settings/21864279/properties?type=0-1&group=contactinformation"
label Una etiqueta de propiedad legible por humanos que se mostrará en HubSpot N/A
name El nombre interno de la propiedad, que debe usarse al hacer referencia a la propiedad a través de la API. N/A

Debe ser en minúsculas y no usar caracteres especiales y no debe tener espacios.

description Una descripción de la propiedad que se mostrará como texto de ayuda en HubSpot. (Es opcional) N/A
displayOrder Las propiedades se muestran en orden comenzando con el valor entero positivo más bajo. Los valores de -1 harán que la propiedad se muestre después de cualquier valor positivo.  N/A (Puedes dejar por defecto el valor 1 a todas o ponerle el orden que desees que aparezcan en Hubspot)
hasUniqueValue Si el valor de la propiedad debe ser único o no. Una vez establecido, esto no puede cambiarse. N/A

Esta caracteristica no es compatiblecon Objeto contactos,  en caso de crear propeidades para este objeto enviar el valor en "false" siempre.

hidden Si es verdadero, la propiedad no será visible y no podrá utilizarse en HubSpot.  N/A Se recomienda dejarlo por defecto en  "false".
formField Si es verdadero, la propiedad podrá ser usada en formularios. Si asi se desea se debe enviar "true" o en caso contrario en "false"  N/A

 

  • Ingresa los Detalles: Completa los detalles de cada propiedad en las filas subsiguientes de la hoja de cálculo. Asegúrate de proporcionar información precisa y clara.

A continuación, te brindamos un video de explicación que ilustra los pasos mencionados anteriormente, proporcionando una orientación visual para llevar a cabo el procedimiento.

Paso 3.1 Definición de Opciones para Propiedades con Elecciones [Casillas, Desplegables o Lista]

    • Utiliza una Hoja de Cálculo de Excel: Abre una hoja de cálculo en Excel para organizar los datos de las opciones de propiedad que deseas crear.

    • Define Encabezados: Crea encabezados para cada opción de propiedad, debes incluir los siguientes:

📝📥 Adjuntamos una plantilla guía para definir los criterios de opciones de una propiedad individual (Esta plantilla es para establecer opciones de una única propiedad; repite el proceso para cada propiedad con elecciones). Descargar aqui.

Desglose Ilustrativo de los Componentes de una Opción de Propiedad en HubSpot
Nombre del Encabezado Descripción Equivalencia con creación manual en Hubspot/ Observaciones
label Una etiqueta de propiedad legible por humanos que se mostrará en HubSpot
description Una descripción de la opción de propiedad.  No es visible en HubSpot (Es opcional)
value El nombre interno de la opción de  propiedad, que debe usarse al hacer referencia a la propiedad a través de la API.
displayOrder Es la posición en lista que deseas que ocupe la opción al momento de que en HubSpot se vaya a seleccionar esta opción.
hidden Si es verdadero, la propiedad no será visible y no podrá utilizarse en HubSpot.  Se recomienda dejarlo por defecto en  "false".

 

Adjuntamos un video que ilustra los pasos mencionados, complementando las instrucciones anteriores con una guía visual del proceso.

Paso 4: Conversión a JSON, Envío de Solicitud API y Verificación

En esta etapa, convertirás tus datos de Excel en un formato llamado JSON, que es especialmente útil para organizar información de manera estructurada y legible por la API de HubSpot. Te proporcionaré una guía detallada para llevar a cabo este proceso:

Paso 4.1: Convertir plantillas preparadas de Excel a JSON

  • 1. Entendiendo JSON: JSON (JavaScript Object Notation) es una forma de representar datos en un formato que las APIs pueden entender fácilmente. Es como un esquema organizado de etiquetas y valores, similar a cómo organizamos información en formularios o tablas. Cada "objeto" en JSON consta de pares de "claves" y "valores" que describen un aspecto específico de los datos.
  • 2. Utiliza una Herramienta de Conversión: Si no estás familiarizado con la programación, puedes utilizar herramientas en línea para convertir tus datos de Excel en JSON. Estas herramientas automatizan el proceso y generan el JSON por ti.

💡 Una herramienta altamente recomendada para llevar a cabo esta tarea es la siguiente: https://products.aspose.app/cells/conversion/excel-to-json.

  • 3. Estructura del JSON: El JSON que obtendrás tendrá parte de la estructura final que requeriremos para enviar a las APIs de HubSpot. Cada propiedad en tus datos de Excel se representará como un "objeto JSON". 
    • Aquí un ejemplo de cómo debe lucir la estructura para un grupo de propiedades que no son de tipo selección:
{
  "inputs": [
    {
      "label": "Nombre de la Propiedad",
      "type": "string",
      "fieldType": "text",
      "groupName": "contactinformation",
      "hidden": false,
      "displayOrder": 1,
      "hasUniqueValue": false,
      "formField": true,
    },
   {
      "label": "Nombre de la Propiedad2",
      "type": "string",
      "fieldType": "textarea",
      "groupName": "contactinformation",
      "hidden": false,
      "displayOrder": 1,
      "hasUniqueValue": false,
      "formField": true,
    }
    // Más objetos similares aquí...
  ]
}
    • Ahora un ejemplo de cómo debe lucir la estructura para un grupo de propiedades que contiene opciones de selección:
{
  "inputs": [
    {
      "label": "Nombre de la Propiedad",
      "type": "enumeration",
      "fieldType": "checkbox",
      "groupName": "contactinformation",
      "hidden": false,
      "displayOrder": 1,
      "hasUniqueValue": false,
      "formField": true,
      "options": [
        {
          "label": "Opción A",
          "description": "Descripción de la Opción A",
          "value": "A",
          "displayOrder": 1,
          "hidden": false
        },
        {
          "label": "Opción B",
          "description": "Descripción de la Opción B",
          "value": "B",
          "displayOrder": 2,
          "hidden": false
        }
      ]
    },

   {
      "label": "Nombre de la Propiedad",
      "type": "enumeration",
      "fieldType": "checkbox",
      "groupName": "contactinformation",
      "hidden": false,
      "displayOrder": 1,
      "hasUniqueValue": false,
      "formField": true,
      "options": [
        {
          "label": "Opción A",
          "description": "Descripción de la Opción A",
          "value": "A",
          "displayOrder": 1,
          "hidden": false
        },
        {
          "label": "Opción B",
          "description": "Descripción de la Opción B",
          "value": "B",
          "displayOrder": 2,
          "hidden": false
        }
      ]
    }
    // Más objetos similares aquí...
  ]
}

Este archivo JSON,  es como un organizador digital. Vamos a analizar una parte del JSON que podría guardar detalles sobre una propiedad , como su etiqueta y opciones.

  1. Llaves {}: Estas llaves son como un contenedor digital. Abren y cierran el espacio donde pondremos nuestra información ordenada.

  2. Pares de Clave y Valor: En el JSON, organizamos la información en "pares" de dos partes: una "clave" y su correspondiente "valor". Es como etiquetar cosas para encontrarlas fácilmente.

  3. "inputs": Imagina que estás dividiendo tu archivo en secciones. "inputs" es una sección especial donde guardaremos información de todas las propiedades que queramos importar a HubSpot.

  4. Lista de Elementos []: Dentro de la sección "inputs", hay una lista de elementos (todas las propiedades que queremos enviar a Hubspot). Es como una línea de casillas donde colocamos diferentes detalles.

  5. Objeto {}: Cada casilla en la línea contiene un objeto. Este objeto es como un contenedor para los datos específicos de una propiedad.

  6. "label", "type", "fieldType", ...: Dentro del objeto, hay etiquetas como "label", "type", "fieldType", etc. Estas etiquetas describen diferentes aspectos de la propiedad, como su nombre, tipo y características.

  7. "options": Dentro del objeto de la propiedad, hay una sección llamada "options". Aquí es donde guardamos diferentes opciones para elegir (Sólo se debe especificar para propiedades que sean de tipo selección).

  8. Objetos en "options": Cada opción es como una mini caja dentro de la sección "options". Cada mini caja tiene detalles sobre una elección posible.

  9. Detalles de la Opción: Dentro de cada mini caja de opción, hay detalles como el nombre de la opción, una descripción de qué significa y un valor único para representarla.

En resumen, imagina que estás organizando información en un archivo digital. Utilizas etiquetas para clasificar diferentes partes de la información. Cada parte tiene su propio espacio en el que puedes agregar detalles específicos. El JSON ayuda a que todo esté estructurado y sea fácil de entender. ¡Espero que esta explicación te ayude a comprender cómo se forma un JSON y cómo se organiza la información en él!


Siguiendo estos pasos, podrás convertir tus datos de Excel a un formato JSON fácil de entender para la API de HubSpot. 

Paso 4.2: Envío de Solicitud API

Paso 4.2.1: Descargar e instalar Postman (si aún no lo tienes instalado)

Si aún no tienes Postman instalado, descárgalo e instálalo desde el sitio oficial de Postman: https://www.postman.com/downloads/

Paso 4.2.2: Importar la colección prearmada

  • Accede al enlace a continuación para descargar la colección de Postman diseñada específicamente para simplificar el proceso de montaje del punto de conexión en HubSpot, destinado a la creación masiva de API: Colección de Postman para HubSpot.

La URL de la API preconfigurada en la colección es: https://api.hubapi.com/crm/v3/properties/:objectType/batch/create.

  • Abre Postman y haz clic en el botón "Import" en la esquina superior izquierda.

  • Selecciona el archivo de colección descargado y haz clic en "Open" para importarla. Deberías ver ahora la colección "Properties" en el panel izquierdo de Postman.

Paso 4.2.3: Configurar la colección con la URL de la API de HubSpot y otros detalles

  • Abre la colección "Properties" en el panel izquierdo de Postman.

  • Haz doble clic en la solicitud llamada "Create a batch of properties" para abrirla en el panel principal.




  • En la pestaña "Params", en la sección de "Key" agrega un parámetro llamado "objectType" y asigna el valor correspondiente según el tipo de objeto que estás creando: "CONTACT" para contactos, "DEAL" para negocios, "COMPANY" para empresas y "TICKET" para tickets. 

  • En la pestaña "Authorization", selecciona el tipo de autorización "Bearer Token". Ingresa el token que obtuviste de la aplicación privada que creaste en HubSpot (Ver Paso 2.1). Este token es esencial para autenticar tus solicitudes a la API.

  • En la pestaña "Body", verás el JSON de ejemplo que contiene detalles de las propiedades que deseas crear. Modifica este JSON según tus necesidades, asegurándote de seguir el formato correcto, para ello vas a necesitar los Excel que transformaste en paoss anteriores a formato JSON. (Asegúrate que en esta sección este definido la opción "raw" y elegido el formato de datos "JSON").

Paso 4.2.4: Enviar la solicitud y revisar la respuesta

  • Una vez que hayas configurado los detalles según tus necesidades, haz clic en el botón "Send" para enviar la solicitud.

  • Observa la respuesta en la sección de abajo. Dependiendo de la respuesta, podrás ver si la solicitud fue exitosa o si hay algún error que resolver.

Siguiendo estos pasos, podrás utilizar la colección prearmada en Postman para interactuar con la API de HubSpot. Recuerda que es importante estar familiarizado con la documentación de la API de HubSpot para comprender los detalles específicos de los endpoints y los datos requeridos en las solicitudes.

Paso 4.3 : Verificación y Revisión en HubSpot

  • Respuesta de la API: Verifica la respuesta de la API. Un código de respuesta exitoso (por ejemplo, código 201) indica que las propiedades se han creado correctamente.

  • Verificación en HubSpot: Accede a tu cuenta de HubSpot y verifica que las propiedades se hayan creado como se esperaba.

A continuación, te proporcionamos un video instructivo que detalla todos los pasos previamente mencionados, con el objetivo de facilitar su comprensión de manera más efectiva.

Paso 5: Exploración y Uso Continuo

  • Implementa las Propiedades: Utiliza las propiedades recién creadas en tus objetos de HubSpot según las necesidades de tu negocio.

¿Por Qué Deberías Seguir Este Proceso?

  • Ahorro de Tiempo: La creación masiva ahorra tiempo en comparación con la configuración manual.
  • Eficiencia: Utiliza Excel para organizar datos y herramientas de conversión para facilitar la preparación de JSON.
  • Escalabilidad: Útil cuando necesitas configurar muchas propiedades a la vez.
  • Automatización: Facilita la automatización de tareas de gestión de datos.

En Resumen

Este proceso proporciona una guía detallada para crear propiedades masivamente en HubSpot utilizando la API. Ya sea que estés implementando HubSpot o desees simplificar la gestión de datos, este método te ayudará a crear propiedades de manera eficiente y efectiva. Recuerda referirte a la documentación oficial de HubSpot para obtener detalles específicos sobre la API y su uso.