Última modificación: 11 de septiembre 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.
Abajo encontrarás información de referencia sobre las características de las aplicaciones de la plataforma de desarrollo con objetos de aplicación, incluidas las definiciones de los archivos de configuración, los detalles de los permisos y mucho más.

​
Estructura del proyecto

  • Todos los componentes del proyecto deben estar dentro del directorio src especificado en el archivo de configuración hsproject.json.
  • Todas las funciones y componentes de la aplicación deben estar en el directorio app/.
  • Las asociaciones de objetos de la aplicación se definen en el directorio app-object-associations/.
  • Las suscripciones a webhooks se definen en el directorio webhooks/.
  • Las acciones de workflow personalizadas se definen en el directorio workflow-actions/.
  • Todas las funciones de la tarjeta deben estar en el directorio cards/.
  • Todas las instancias de componentes y características se declaran utilizando los archivos *-hsmeta.json. Debes anteponer al nombre del archivo algo significativo (por ejemplo, my-app-hsmeta.json). Estos archivos deben estar en el nivel raíz de sus respectivas carpetas (por ejemplo, app/my-app-hsmeta.json, cards/my-card-hsmeta.json).
El ejemplo de estructura de directorios que aparece abajo describe todas las funciones disponibles. 
my-folder/
├── hsproject.json
├──src
│   ├── app/
│   │   └── app-hsmeta.json/
│   │   └── app-objects/
│   │     └── my-app-object-hsmeta.json
│   │   └── app-object-associations/
│   │     └── my-app-object-association-hsmeta.json
│   │   └── webhooks/
│   │     └── webhooks-hsmeta.json
│   │   └── cards/
│   │     └── my-app-card-hsmeta.json
│   │     └── MyCard.jsx
└──

Ver ejemplo en GitHub

​
Objetos de aplicación

Para crear un objeto de aplicación, incluye un directorio de componentes app-objects en el proyecto, junto con un archivo de configuración. 
...
├──src
│   ├── app/
│   │   └── app-hsmeta.json
│   │   └── ...
│   │   └── app-objects/
│   │     └── my-app-object-hsmeta.json
└──
Abajo se indican las opciones de configuración disponibles para *-object-hsmeta.json. 
{
  "uid": "car-app-object",
  "type": "app-object",
  "config": {
    "name": "CAR",
    "appPrefix": "Vroom",
    "description": "An automobile in our warehouse.",
    "singularForm": "Car",
    "pluralForm": "Cars",
    "primaryDisplayLabelPropertyName": "model",
    "secondaryDisplayLabelPropertyNames": ["make"],
    "settings": {
      "hasRecordPage": true,
      "allowsUserCreatedRecords": true,
      "hasEngagements": true
    },
    "properties": [
      {
        "type": "string",
        "fieldType": "text",
        "name": "model",
        "label": "Model",
        "description": "The model of the car"
      },
      {
        "type": "enumeration",
        "fieldType": "select",
        "name": "make",
        "label": "Make",
        "description": "The manufacturer of the car.",
        "options": [
          {
            "label": "Ford",
            "value": "ford",
            "displayOrder": 0
          },
          {
            "label": "Toyota",
            "value": "toyota",
            "displayOrder": 1
          },
          {
            "label": "Chevrolet",
            "value": "chevrolet",
            "displayOrder": 2
          }
        ]
      }
    ]
  }
}

Ver ejemplo en GitHub

Los campos marcados con * son obligatorios.

CampoTipoDescripción
uid*CadenaUn identificador único para el objeto de la aplicación. Debe ser globalmente único dentro del proyecto.
type*CadenaEl tipo de componente. Debe coincidir con el nombre de la carpeta primaria (app-object).
name*CadenaEl nombre de tu objeto de aplicación. Utiliza el nombre aprobado que recibiste en la confirmación de tu aplicación aprobada. Debe ser en mayúscula y snake case (MY_OBJECT_NAME).
appPrefixCadenaUna cadena que precede al nombre singular o plural del objeto en la interfaz de HubSpot para ayudar a diferenciarlo de otros objetos. En este ejemplo, appPrefix de Vroom y singularForm de Car harían que en la interfaz de usuario apareciera “Vroom Car”.
description*Cadenala descripción del objeto, que se mostrará en HubSpot.
singularForm*CadenaLa forma singular del nombre del objeto.
pluralForm*CadenaLa forma plural del nombre del objeto.
properties*MatrizLista de propiedades del CRM definidas para el objeto. Las propiedades se definen utilizando los mismos campos que la API de propiedades. A las propiedades resultantes se les agregará automáticamente a<appId>_ (por ejemplo, a12345_make) en el momento de la creación. No debes incluir el prefijo en el archivo de configuración.
primaryDisplayLabelPropertyName*CadenaEl nombre de la propiedad que debe utilizarse como propiedad de visualización principal. El valor debe coincidir con el nombre proporcionado en la lista properties (es decir, no debe incluir el prefijo generado a<appId>_.)
secondaryDisplayLabelPropertyNames*MatrizLa lista de propiedades que deben utilizarse como propiedades de visualización secundarias. El valor debe coincidir con el nombre proporcionado en la lista properties (es decir, no debe incluir el prefijo generado a<appId>_.)
settings*ObjetoUn objeto que contiene ajustes del objeto.
hasRecordPage*BooleanoSi existen páginas de registro para las instancias de este objeto de aplicación. Si se configura en false, la página de índice seguirá existiendo, pero no incluirá enlaces a páginas de registros individuales.
allowsUserCreatedRecords*BooleanoSi los usuarios finales podrán crear registros utilizando el objeto. Si se configura en false, los usuarios no podrán crear registros en HubSpot
hasEngagements*BooleanoSi el objeto de la aplicación registra actividades/interacciones de asistencia. Si se establece en false, las páginas de registro de objetos de la aplicación no incluirán ninguna funcionalidad de interacción, como la pestaña de actividad o los filtros de cronología relacionados con la actividad.
El nombre completo (FQN) de tu objeto de aplicación será a<appId>_<objectName>. Por ejemplo: si tu appId es 16858319 y el nombre del objeto de la aplicación es CARS, entonces el FQN sería a16858319_CARS. Utilizarás el FQN cuando establezcas valores de alcance para los objetos de tu aplicación.

​
Esquema de la aplicación

Para crear un objeto de aplicación, incluye un archivo de configuración app-hsmeta.json en el directorio app. 
...
├──src
│   ├── app/
│   │   └── app-hsmeta.json/
└──
Abajo se indican las opciones de configuración disponibles para app-hsmeta.json. 
{
  "uid": "app_object_poc_app",
  "type": "app",
  "config": {
    "description": "An example to demonstrate how to build an app with an app object on developer projects.",
    "name": "my first app object app",
    "distribution": "marketplace",
    "auth": {
      "type": "oauth",
      "redirectUrls": ["http://localhost:3000/oauth-callback"],
      "requiredScopes": [
        "crm.objects.contacts.read",
        "crm.objects.contacts.write"
      ],
      "optionalScopes": [],
      "conditionallyRequiredScopes": []
    },
    "permittedUrls": {
      "fetch": ["https://api.hubapi.com"],
      "iframe": [],
      "img": []
    },
    "support": {
      "supportEmail": "support@example.com",
      "documentationUrl": "https://example.com/docs",
      "supportUrl": "https://example.com/support",
      "supportPhone": "+18005555555"
    }
  }
}

Ver ejemplo en GitHub

​
Esquema de la aplicación *-hsmeta.json campos

Los campos marcados con * son obligatorios

CampoTipoDescripción
uid*CadenaUn identificador único interno para la aplicación. Debe ser globalmente único dentro del proyecto. Puede ser cualquier cadena de hasta 64 caracteres. Los caracteres pueden ser mayúsculas o minúsculas, y pueden incluir números, guiones bajos (_), guiones (-) y puntos (.).
type*CadenaEl tipo de componente. Debe coincidir con el nombre de la carpeta primaria (app).
description*CadenaDescripción de lo que hace la aplicación para el usuario que la instala. Puede ser cualquier cadena de hasta 8192 caracteres.
name*CadenaEl nombre de la aplicación, que se mostrará en HubSpot. Puede ser cualquier cadena de hasta 200 caracteres. No debe empezar ni terminar con un carácter de espacio en blanco.
distribution*CadenaEl método de distribución de la aplicación. Debe estar configurado en marketplace para que la aplicación pueda aparecer en el mercado de aplicaciones.
auth*ObjetoUn objeto que contiene los detalles del método de autenticación de la aplicación. Consulta la tabla de autenticación para más detalles.
permittedUrlsObjetoUna matriz que contiene las URL a las que la aplicación puede llamar. Las URL deben utilizar el esquema HTTPS y deben contener una autoridad, seguida de un prefijo de ruta opcional si es necesario.
supportEmailCadenaUna dirección de correo electrónico válida con la que los usuarios puedan ponerse en contacto para recibir asistencia.
documentationUrlCadenaLa URL externa a la que los usuarios pueden navegar para obtener documentación de apoyo. Debe utilizar HTTPS.
supportUrlCadenaLa URL externa a la que los usuarios pueden navegar para obtener asistencia adicional. Debe utilizar HTTPS.
supportPhoneCadenaEl número de teléfono al que pueden dirigirse los usuarios para solicitar asistencia. Debe empezar por el signo más (+).

​
campos de autenticación

Los campos marcados con * son obligatorios.

CampoTipoDescripción
type*CadenaEl tipo de autenticación. Debe estar configurado como oauth para que la aplicación utilice la autenticación con OAuth.
redirectUrls*MatrizLista de URL a las que el proceso de OAuth puede redirigir. Cada aplicación debe tener al menos una URL de redireccionamiento de autenticación, y debe utilizar HTTPS. La única excepción es que se permite http://localhost para las pruebas.
requiredScopes*MatrizUna lista de los permisos necesarios para tu aplicación. Cada aplicación debe incluir al menos un permiso, y el usuario que la instala debe conceder estos permisos para que la aplicación se instale correctamente. Más información sobre los permisos a continuación.
optionalScopesMatrizUna lista de los permisos opcionales de tu aplicación. Estos permisos pueden excluirse de la autorización durante la instalación si la cuenta o el usuario que instala la aplicación no tiene los permisos adecuados. En ese caso, el permiso no se incluirá en el token de actualización o de acceso resultante. Más información sobre los permisos abajo.
conditionallyRequiredScopesMatrizLista de permisos que solo son necesarios cuando se incluyen en el parámetro de consulta scope de la URL de instalación. Más información sobre los permisos abajo.

​
Permisos

En el campo auth del archivo de configuración de una aplicación, puedes especificar tres tipos de permisos: permisos requeridos, permisos requeridos condicionalmente y permisos opcionales. Para esta etapa de la beta, solo debes incluir los permisos de los objetos de tu aplicación como conditionallyRequiredScopes. Esto te permitirá aislar tus nuevas funciones para clientes específicos incluyendo los permisos de los objetos de la aplicación en la URL de instalación. Los permisos de los objetos de la aplicación utilizan el siguiente formato: crm.app.schemas.<appObjectFullyQualifiedName>.read Por ejemplo, para un objeto de aplicación con el FQN a16858319_cars, el permiso read sería: crm.app.schemas.a16858319_cars.read. Como mínimo, tu aplicación debe incluir el permiso read de arriba para que los clientes puedan acceder al objeto. Se recomienda incluir todos los permisos de objetos de aplicación en tu aplicación, como se muestra abajo. 
"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": []
    },
Para obtener una lista completa de los permisos disponibles, consulta la referencia de permisos.

​
Definición del componente de webhooks

Para definir un conjunto de suscripciones a webhook para tu aplicación, incluye un directorio webhooks en el proyecto, junto con un archivo de configuración *-hsmeta.json. 
├──src
│   ├── app/
│   │   └── app-hsmeta.json
│   │   └── ...
│   │   └── webhooks/
│   │     └── webhooks-hsmeta.json
└──
Abajo se indican las opciones de configuración disponibles para el archivo *-hsmeta.json. 
{
  "uid": "webhooks",
  "type": "webhooks",
  "config": {
    "settings": {
      "targetUrl": "https://example.com/webhook",
      "maxConcurrentRequests": 10
    },
    "subscriptions": {
      "crmObjects": [
        {
          "subscriptionType": "object.creation",
          "objectType": "contact",
          "active": true
        },
        {
          "subscriptionType": "object.propertyChange",
          "objectType": "car_app_object",
          "propertyName": "carProperty",
          "active": true
        }
      ],
      "legacyCrmObjects": [
        {
          "subscriptionType": "contact.propertyChange",
          "propertyName": "lastname",
          "active": true
        },
        {
          "subscriptionType": "contact.deletion",
          "active": true
        }
      ],
      "hubEvents": [
        {
          "subscriptionType": "contact.privacyDeletion",
          "active": true
        }
      ]
    }
  }
}

​
Webhook *-hsmeta.json campos

Los campos marcados con * son obligatorios.

CampoTipoDescripción
uid*CadenaUn identificador único interno para el componente webhook.
type*CadenaEl tipo de componente, que en este caso debe ser webhooks.
settings*ObjetoUn objeto que especifica dos campos: targetUrl, que es la URL disponible públicamente para que HubSpot llame a donde se entregarán las cargas de eventos, y maxConcurrentRequests, que es el límite de peticiones HTTP que HubSpot realizará en un período determinado.
subscriptions*ObjetoUn objeto que especifica los tipos de suscripción a los que se suscribirá tu aplicación.
crmObjectsMatrizMatriz que contiene definiciones de suscripción a eventos. Esta es la matriz estándar que hay que incluir, y debe utilizarse para todos los eventos en el nuevo formato (object.*). En cambio, los tipos de suscripción webhook clásicos deben incluirse en las matrices legacyCrmObjects y hubEvents, dependiendo del evento.
legacyCrmObjectsMatrizMatriz que contiene tipos de suscripción clásicos, como contact.creation y deal.deletion.
hubEventsMatrizMatriz que contiene los tipos de suscripción clásicos contact.privacyDeletion y conversation.*
Para cada objeto subscription, se pueden especificar los siguientes campos, en función del tipo de definición de suscripción al que estés suscrito (es decir, crmObjects, legacyCrmObjects o hubEvents) o de si estás suscrito a un cambio de propiedad específico (por ejemplo, contact.propertyChange).
CampoTipoDescripción
subscriptionTypeCadenaEl tipo de evento al que se está suscrito.
objectTypeCadenaPara las suscripciones especificadas en la matriz crmObjects, especifica el objeto del CRM al que se está suscribiendo tu aplicación. Para suscribirte a los cambios de un objeto de aplicación, incluye el nombre de tu objeto de aplicación para este campo (por ejemplo, car_app_object).
propertyNameCadenaPara las suscripciones de cambio de propiedad, especifica qué propiedad desencadenará el evento de webhook.
activeBooleanoSi se desencadenarán eventos de webhook para esta suscripción.

​
Esquema de la tarjeta de la aplicación

Para crear una tarjeta de aplicación que aparezca en una página de registro de objetos de aplicación, incluye un directorio de componentes cards en el proyecto, junto con un archivo de configuración. 
├──src
│   ├── app/
│   │   └── app-hsmeta.json
│   │   └── ...
│   │   └── cards/
│   │     └── my-app-card-hsmeta.json
│   │     └── MyCard.jsx
└──
  • Asegúrate de que has ejecutado hs project upload después de crear tu componente de objeto de aplicación y los archivos de configuración asociados.
  • En tu archivo my-app-card-hsmeta.json, agrega el UID del objeto de tu aplicación a la matriz objectTypes (por ejemplo, "app_object_uid" en este ejemplo). Cada uno de los campos disponibles en el archivo .json se detalla en la tabla siguiente.
{
  "uid": "my-app-card",
  "type": "card",
  "config": {
    "name": "My app card",
    "description": "An example description of the card, which lives on contact records.",
    "previewImage": {
      "file": "./preview.png",
      "altText": "A short description of the preview image"
    },
    "entrypoint": "/app/cards/MyCard.jsx",
    "location": "crm.record.tab",
    "objectTypes": ["contacts", "app_object_uid"]
  }
}
  • Cuando hayas guardado los cambios en tu archivo example-card-hsmeta.json, ejecuta hs project upload.
Las tarjetas se agregan automáticamente a la vista predeterminada de los objetos de la aplicación. Si la tarjeta no aparece automáticamente, aprende a agregar tarjetas a los registros de CRM.

Ver ejemplo en GitHub

​
Tarjeta de aplicación *-hsmeta.json campos

Los campos marcados con * son obligatorios.

CampoTipoDescripción
uid*CadenaEl identificador único de la tarjeta. Puede ser cualquier cadena, pero debe identificar significativamente a la tarjeta. HubSpot identificará la tarjeta por este ID para que puedas cambiar el título de la tarjeta sin eliminar datos históricos o de estado, como la posición en el registro del CRM.
typeCadenaEl tipo de componente, que en este caso debe ser card.
configObjetoUn objeto que contiene detalles de configuración.
name*CadenaEl título de la tarjeta, tal y como se muestra en la interfaz de usuario de HubSpot.
descriptionCadenaDescripción de la tarjeta.
previewImageObjetoObjeto que contiene los campos file y altText. El campo file es la ruta relativa a la imagen de previsualización. Las extensiones de archivo válidas son png, jpeg, jpg o gif. El tamaño máximo del archivo es de 5.0 MB. El campo altText es una breve descripción de la imagen.
entrypoint*CadenaLa ruta del archivo del código React del front-end de la tarjeta.
location*crm.record.tab | crm.record.sidebar | helpdesk.sidebarDónde aparece la tarjeta en la interfaz de usuario de HubSpot. Más información sobre la ubicación de la extensión.
objectTypes*MatrizLos tipos de registros del CRM en los que aparecerá la tarjeta.

​
Asociaciones de objetos de la aplicación

Para habilitar las asociaciones entre el objeto de tu aplicación y otros objetos del CRM, incluye un directorio de componentes app-object-associations en el proyecto, junto con un archivo de configuración. 
├── src
│   ├── app/
│   │   └── app-hsmeta.json
│   │   └── ...
│   │   └── app-object-associations/
│   │     └── my-app-object-association-hsmeta.json
└──
Abajo se indican las opciones de configuración del objeto de la aplicación disponibles (*-association-hsmeta.json). 
{
  "uid": "car_to_contact_association",
  "type": "app-object-association",
  "config": {
    "firstObjectType": "car-app-object",
    "secondObjectType": "CONTACT"
  }
}

​
Asociación *-asociación-hsmeta.json campos

Los campos marcados con * son obligatorios.

CampoTipoDescripción
uid*CadenaUn identificador único interno para la aplicación. Debe ser globalmente único dentro del proyecto.
type*CadenaEl tipo de componente. Debe coincidir con el nombre de la carpeta primaria (app-object-association).
config*ObjetoObjeto que contiene la configuración de la asociación de objetos.
firstObjectType*CadenaEl primer objeto de la asociación. Puede ser un objeto de aplicación o un objeto del CRM de HubSpot. Se hace referencia a los objetos de la aplicación por su uid especificado en su archivo fuente. Los objetos estándar se denominan por su fullyQualifiedName. La asociación resultante será bidireccional, por lo que el orden de los valores de estos campos es arbitrario.
secondObjectType*CadenaEl segundo objeto de la asociación. Consulta firstObjectType para más detalles.