Skip to main content
Última modificación: 8 de octubre de 2025
Esta función requiere la aprobación de HubSpot para su uso. Si estás interesado en solicitar acceso a los objetos de la aplicación, o si quieres saber más sobre la funcionalidad, envía este formulario de interés.
Aprende a crear una aplicación de prueba de concepto en la que configurarás un objeto de aplicación que podrás probar y utilizar en una cuenta de prueba de desarrollador.
1

Instalar la última versión de la CLI de HubSpot

Necesitarás la última versión beta de la CLI de HubSpot para crear una aplicación unificada. En una ventana de terminal, ejecuta el siguiente comando:
npm install -g @hubspot/cli@next
La CLI debe ser de la versión 7.4.4-beta.0 o posterior. Puedes comprobar qué versión de la CLI tienes ejecutando hs --version.
2

Autenticar tu cuenta de desarrollador

A continuación, tendrás que autenticar tu cuenta de desarrollador ejecutando el siguiente comando:
hs auth
  • Sigue las indicaciones para generar una clave de acceso personal en tu cuenta, luego cópiala y pégala en la terminal para guardar tu configuración.
  • Durante este período beta, se recomienda que hagas de esta cuenta tu cuenta predeterminada en la CLI. Esto evitará posibles errores con el acceso de la cuenta que has inscrito en la beta.
3

Crear un nuevo proyecto estándar

Ejecuta el siguiente comando en tu terminal para crear un nuevo proyecto y una aplicación de mercado con las funciones compatibles actualmente o un esquema de referencia de objetos de aplicación.
hs project create --templateSource robrown-hubspot/hubspot-project-components-ua-app-objects-beta
4

Configura el proyecto recién creado y súbelo a tu cuenta de desarrollador

El marco de proyectos traslada las funciones de la aplicación que antes se configuraban en la interfaz de usuario o a través de la API a archivos de código fuente, normalmente definidos como archivos de configuración de <file-name>-hsmeta.json.A continuación, las funciones de la aplicación se crean utilizando una combinación de subcarpetas del directorio principal /src/app y otros archivos de configuración, según sea necesario. Para configurar tu proyecto:
  • Agrega una o varias URL de redireccionamiento válidas al archivo app-hsmeta.json en función de la configuración de tu servidor OAuth local (u otro que no esté en producción).

​
Nota:

Para empezar, puedes utilizar el ejemplo OAuth Node.js y ejecutarlo localmente. Ya está configurado para funcionar con https://localhost:3000/oauth-callback como la URL de redireccionamiento configurada en el código de ejemplo del comando hs project create que ejecutaste en el paso anterior.
  • Cambia la propiedad uid de la aplicación en el archivo app-hsmeta.json y en los demás archivos de configuración *-hsmeta.json de tu proyecto.
Los UID se utilizan como identificador único para todos los componentes y características de tu proyecto. Una vez creados una función y un UID, cambiar o modificar el UID en implantaciones posteriores forzará a la plataforma a reconocerlo como diferente de las funciones anteriores, lo que puede no ser intencionado.
  • Cuando utilices objetos de aplicación para tu aplicación unificada, solo se permitirán las definiciones de propiedad “nombre” autorizadas en función de tu solicitud de objeto. Como parte de esta beta privada, deberías haber recibido por separado la confirmación del “nombre” aprobado de tu aplicación, que debe utilizarse en la configuración de *-object-hsmeta.json. Como referencia, el nombre completo (FQN) de tu objeto de aplicación será a<appId>_<name>. Por ejemplo, si tu appId es 16858319 y tu name propiedad era CARS, entonces tu FQN sería a16858319_cars.
  • Una vez guardados los cambios, ejecuta el comando de CLI hs project upload para subir tu proyecto a la plataforma de desarrolladores de HubSpot y desencadenar automáticamente una nueva compilación.
  • En una ventana del navegador, navega a https://app.hubspot.com/developer_projects/<accountId> para visitar la interfaz de usuario del proyecto y confirmar que la aplicación y el proyecto se han creado, construido y desplegado correctamente.
5

Agrega a tu aplicación el ID de cliente y el secreto de cliente de tu aplicación

  • Después de subir tu proyecto, tendrás que obtener los detalles de autenticación de tu aplicación para copiarlos en tu configuración de OAuth:
    • Haz clic en Proyectos en el menú de navegación Desarrollo.
    • Haz clic en el nombre de la aplicación.
    • Haz clic en UID de tu aplicación y, a continuación, en la pestaña Autenticación.
    • Copia el ID de cliente y el secreto de cliente de tu nueva aplicación y pégalos en las ubicaciones correspondientes de la configuración de tu servidor OAuth local, luego reinicia tu servidor OAuth.
6

Configurar el esquema de objetos de la aplicación

A continuación configurarás el esquema de objetos de tu aplicación:
  • Agrega un nuevo objeto de la aplicación creando un directorio dentro del directorio /src/app y nómbralo app-objects. La ruta resultante al nuevo directorio debe ser /src/app/app-objects.
  • Crea un nuevo archivo de configuración para representar el esquema de tu objeto, Debes utilizar el nombre del objeto concedido a tu aplicación durante el proceso de previsualización como prefijo para el nombre del archivo, seguido de -object-hsmeta.json. Por ejemplo, en la plantilla del proyecto de referencia, el nombre del objeto de la aplicación es “CAR”, por lo que el archivo de configuración resultante se llama car-object-hsmeta.json.
  • Consulta el archivo de referencia de definición del componente del objeto de la aplicación y personaliza los campos con los valores correspondientes a tu objeto de la aplicación.
    • Dentro del objeto config de tu definición, el campo name debe coincidir con el nombre que se concedió a tu aplicación durante el proceso de revisión, formateado en UPPER_SNAKE_CASE.
    • Ten en cuenta que una vez que las propiedades y los campos se han agregado al esquema del objeto de tu aplicación y se han subido a tu proyecto en el paso siguiente, no se pueden eliminar.

​
Nota:

Para mayor comodidad durante las pruebas, se puede utilizar el mismo nombre de objeto de aplicación en varias aplicaciones para apoyar tu ciclo de vida de desarrollo. Empieza con esta aplicación de prueba de concepto y, a medida que las migraciones estén disponibles, podrás utilizar el mismo nombre y las mismas definiciones de esquema en tus aplicaciones de desarrollo, ensayo y producción. Los UID de cada una de estas instancias deberán ser únicos.
  • Cuando hayas terminado de editar la definición del esquema del objeto de tu aplicación y estés listo para confirmar los cambios, ejecuta los siguientes comandos para guardar los cambios:
hs project upload
hs project deploy
  • En una ventana del navegador, navega a https://app.hubspot.com/developer_projects/<hubId> para visitar la interfaz de usuario del proyecto y confirmar que la aplicación y el proyecto se han creado, construido y desplegado correctamente.
7

Actualizar la aplicación

Ahora que has subido el esquema de objetos de tu aplicación, tendrás que actualizar los permisos definidos en tu archivo app-hsmeta.json para que reflejen los permisos creados en el paso anterior. Estos permisos deberían ser visibles en los registros de la CLI después de ejecutar hs project upload.
  • Edita el archivo app-hsmeta.json y agrega los nuevos permisos a la matriz de requiredScopes dentro de la definición de auth. Por ejemplo, si tu appId fuera a12345, entonces editarías la definición de auth a lo siguiente:
"auth": {
  "type" : "oauth",
  "redirectUrls": ["http://localhost:3000/oauth-callback"],
  "requiredScopes": [
    "crm.objects.contacts.read",
    "crm.objects.contacts.write",
    "crm.app.objects.a12345_my_app_object.view",
    "crm.app.objects.a12345_my_app_object.create",
    "crm.app.objects.a12345_my_app_object.edit",
    "crm.app.schemas.a12345_my_app_object.read",
    "crm.app.objects.a12345_my_app_object.merge",
    "crm.app.objects.a12345_my_app_object.delete",
    "crm.app.schemas.a12345_my_app_object.properties.write"
  ],
  "optionalScopes": [],
  "conditionallyRequiredScopes": []
},

​
Nota:

  • Los clientes solo podrán ver el objeto de tu aplicación si el permiso schemas.read se incluye en la configuración de tu aplicación, y se solicita durante el flujo de instalación/autorización de OAuth. Es muy recomendable incluir todos los permisos de objetos de la aplicación en tu configuración, pero schemas.read es obligatorio para que los clientes puedan acceder a ella. Por ejemplo, para una appId de 12345, incluirías crm.app.schemas.a12345_MY_APP_OBJECT.read como un permiso obligatorio.
  • Dependiendo de la aplicación con la que estés probando (prototipo, desarrollo, preparación, producción), tendrás que tener en cuenta dónde agregas las definiciones de tu permiso. Aunque todavía no se puede implementar una aplicación de producción durante esta fase de la beta privada, suele ser más seguro incluir estos permisos como conditionallyRequiredScopes cuando estés listo para la producción. Más información sobre estos tipos de permisos en la documentación de la aplicación pública .
  • Cuando hayas terminado de agregar estos permisos y hayas guardado los cambios, ejecuta los siguientes comandos para confirmar los cambios en la plataforma:
hs project upload
hs project deploy
Una vez completada la implementación, tu aplicación y el objeto de aplicación correspondiente ya están listos para probar con una cuenta instalada.
8

Crear una cuenta de prueba de desarrollador (opcional) e instalar la aplicación

Si aún no tienes una cuenta de prueba, puedes crear una en HubSpot:
  • Navega hasta Cuentas de prueba en el menú de navegación Desarrollo y haz clic en Crear cuenta de prueba de desarrollador. Sigue las indicaciones para crear tu nueva cuenta de prueba.
  • En el menú de la barra lateral izquierda, navega hasta Proyectos, haz clic en el nombre de tu nuevo proyecto y haz clic en el UID de tu aplicación en la lista de componentes.
  • En la pestaña Autenticación , copia el enlace de instalación de tu aplicación.
  • Utiliza este enlace para instalar la aplicación en tu cuenta de prueba de desarrollador.
  • Abre la cuenta de prueba y ve a la página de Aplicaciones conectadas, donde deberías ver tu aplicación instalada.
  • En tu cuenta de prueba, navega hasta CRM > Contactos, y haz clic en el menú desplegable objeto del CRM y confirma que el objeto de tu aplicación está disponible.
  • A continuación, puedes confirmar que tu definición del esquema se ajusta a tu archivo de configuración creando un nuevo registro de tu objeto de la aplicación.
app-object-available-in-crm
9

Acceso programático a datos mediante la API de objetos de HubSpot

Ahora que has creado con éxito tu objeto de aplicación y lo has probado en una cuenta de prueba de desarrollador, puedes utilizar el token de acceso OAuth asociado a la cuenta de prueba instalada para realizar solicitudes de actualización de datos en la cuenta directamente a través de la API de objetos.Lee la API de objetos para obtener más información sobre la API, pero cualquier solicitud específica del objeto de tu aplicación seguirá las mismas convenciones que otros objetos estándar de HubSpot. Tendrás que utilizar la dirección objectTypeId o fullyQualifiedName de tu objeto de aplicación como parámetro de la ruta objectType en tu solicitud.Por ejemplo, el siguiente bloque de código demuestra cómo hacer una petición a cURL para crear un nuevo registro del objeto de tu aplicación:
curl --request POST \
  --url https://api.hubapi.com/crm/v3/objects/<fullyQualifiedName> \
  --header 'authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'content-type: application/json' \
  --data '{
  "properties": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  }
}'
Puedes encontrar el objectTypeId de tu objeto de aplicación navegando a la página del índice de registros:
  • Navega a CRM > Contactos en la cuenta de prueba de desarrollador en la que instalaste tu aplicación.
  • Haz clic en el menú desplegable de la parte superior de la página y selecciona tu objeto de aplicación.
  • El objectTypeId aparecerá en la URL entre la parte /objects/<objectTypeId>/views.

​
Próximos pasos

Consulta la documentación de referencia para saber cómo utilizar los objetos de aplicación con las distintas funciones de la plataforma de desarrollo: