Última modificação: 11 de setembro de 2025
Esse recurso requer aprovação da HubSpot para ser usado. Se você tiver interesse em se inscrever para receber o acesso a objetos de aplicativo ou se quiser saber mais sobre a funcionalidade, envie este formulário de interesse.
Veja abaixo informações de referência para recursos de aplicativo da plataforma de desenvolvedor com objetos de aplicativo, incluindo definições de arquivo de configuração, detalhes de escopos e muito mais.

Estrutura do projeto

  • Todos os componentes do projeto devem estar no diretório src especificado no arquivo de configuração hsproject.json.
  • Todos os recursos e componentes do aplicativo devem estar no diretório app/.
  • As associações de objeto do aplicativo são definidas no diretório app-object-associations/.
  • As assinaturas de webhook são definidas no diretório webhooks/.
  • As ações de fluxo de trabalho personalizadas são definidas no diretório workflow-actions/.
  • Todos os recursos do cartão devem estar no diretório cards/.
  • Todas as declarações de instâncias de componente e recurso são feitas com arquivos *-hsmeta.json. Você deve usar algo significativo no nome do arquivo (por exemplo, my-app-hsmeta.json). Esses arquivos devem estar no nível raiz da respectiva pasta (por exemplo, app/my-app-hsmeta.json, cards/my-card-hsmeta.json).
O exemplo de estrutura de diretório abaixo descreve todos os recursos disponíveis.
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 exemplo no GitHub

Objetos de aplicativo

Para criar um objeto de aplicativo, inclua um diretório do componente app-objects no projeto, com um arquivo de configuração.
...
├──src
   ├── app/
   └── app-hsmeta.json
   └── ...
   └── app-objects/
     └── my-app-object-hsmeta.json
└──
Veja abaixo as opções de configuração disponíveis 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 exemplo no GitHub

Campos marcados com * são obrigatórios.

CampoTipoDescrição
uid*StringUm identificador exclusivo para o objeto do aplicativo. Deve ser globalmente exclusivo dentro do projeto.
type*StringO tipo de componente. Deve corresponder ao nome da pasta principal (app-object).
name*StringO nome do seu objeto de aplicativo. Use o nome aprovado recebido na confirmação do aplicativo aprovado. Deve usar letras maiúsculas separadas por sublinhado (snake case) (MY_OBJECT_NAME).
appPrefixStringUma sequência de caracteres que precede o nome singular ou plural do objeto na interface do usuário do HubSpot para ajudar a diferenciá-lo de outros. Neste exemplo, o appPrefix de Vroom e singularForm de Car resultaria na exibição de “Vroom Car” na interface.
description*StringA descrição do objeto, que será mostrada no HubSpot.
singularForm*StringA forma singular do nome do objeto.
pluralForm*StringA forma plural do nome do objeto.
properties*MatrizUma lista de propriedades de CRM definidas para o objeto. As propriedades são definidas usando os mesmos campos da API de propriedades. As propriedades resultantes terão o prefixo a<appId>_ (por exemplo, a12345_make) na criação. Você não deve incluir o prefixo no arquivo de configuração.
primaryDisplayLabelPropertyName*StringO nome da propriedade que deve ser usada como propriedade de exibição principal. O valor deve corresponder ao nome fornecido na lista properties (ou seja, não deve incluir o prefixo a<appId>_ gerado.)
secondaryDisplayLabelPropertyNames*MatrizA lista das propriedades que devem ser usadas como propriedades de exibição secundária. O valor deve corresponder ao nome fornecido na lista properties (ou seja, não deve incluir o prefixo a<appId>_ gerado.)
settings*ObjetoUm objeto que contém as configurações de objeto.
hasRecordPage*BooleanoSe existem páginas de registro para instâncias deste objeto de aplicativo. Quando definido como false, a página de índice existirá, mas não incluirá links para páginas de registro individuais.
allowsUserCreatedRecords*BooleanoSe os usuários finais poderão criar registros usando o objeto. Quando definido como false, os usuários não poderão criar registros no HubSpot
hasEngagements*BooleanoSe os registros de objeto do aplicativo permitem atividades/engajamentos. Quando definido como false, as páginas de registro de objeto do aplicativo não incluirão nenhuma funcionalidade de engajamento, como a guia de atividade ou filtros de linha do tempo relacionados à atividade.
O nome totalmente qualificado (FQN) do objeto do aplicativo será a<appId>_<objectName>. Por exemplo: se o seu appId é 16858319 e o nome do objeto do aplicativo é CARS, o FQN será a16858319_CARS. Você usará o FQN ao definir valores de escopo para seus objetos de aplicativo.

Esquema de aplicativo

Para criar um objeto de aplicativo, inclua um arquivo de configuração app-hsmeta.json no diretório app.
...
├──src
   ├── app/
   └── app-hsmeta.json/
└──
Veja abaixo as opções de configuração disponíveis 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 exemplo no GitHub

Campos *-hsmeta.json do esquema do aplicativo

Campos marcados com * são obrigatórios.

CampoTipoDescrição
uid*StringUm identificador exclusivo interno do aplicativo. Deve ser globalmente exclusivo dentro do projeto. Pode ser qualquer string de até 64 caracteres. Os caracteres podem ser maiúsculos ou minúsculos e podem incluir números e sublinhados (_), traços (-) e pontos (.).
type*StringO tipo de componente. Deve corresponder ao nome da pasta principal (app).
description*StringUma descrição do que o aplicativo faz para o usuário que está instalando. Pode ser qualquer string de até 8192 caracteres.
name*StringO nome do aplicativo, que será exibido na interface do HubSpot. Pode ser qualquer string de até 200 caracteres. Não deve iniciar ou terminar com um caractere de espaço.
distribution*StringO método de distribuição do aplicativo. Precisa ser definido como marketplace para que o aplicativo possa ser listado no Marketplace de aplicativos.
auth*ObjetoUm objeto que contém os detalhes do método de autenticação do aplicativo. Consulte a tabela de autenticação para obter detalhes.
permittedUrlsObjetoUma matriz que contém os URLs que o aplicativo tem permissão para chamar. Os URLs devem usar o esquema HTTPS e devem conter uma autoridades, seguido por um prefixo de caminho opcional, se necessário.
supportEmailStringUm endereço de e-mail válido com o qual os usuários podem entrar em contato para obter suporte.
documentationUrlStringO URL externa na qual os usuários podem navegar para documentação de suporte. Devem usar HTTPS.
supportUrlStringO URL externo para o qual os usuários podem navegar para obter suporte adicional. Devem usar HTTPS.
supportPhoneStringO número de telefone com o qual os usuários podem entrar em contato para obter suporte. Deve começar com um sinal de mais (+).

campos de autenticação

Campos marcados com * são obrigatórios.

CampoTipoDescrição
type*StringO tipo de autenticação. Deve ser definido como oauth para que o aplicativo use a autenticação OAuth.
redirectUrls*MatrizUma lista de URLs que o OAuth tem permissão para usar em redirecionamentos. Cada aplicativo deve ter pelo menos um URL de redirecionamento de autenticação e deve usar HTTPS. A única exceção é que http://localhost é permitida para testes.
requiredScopes*MatrizUma lista dos escopos obrigatórios do seu aplicativo. Cada aplicativo deve incluir pelo menos um escopo, e o usuário instalador deve conceder esses escopos para instalar o aplicativo. Saiba mais sobre escopos abaixo.
optionalScopesMatrizUma lista dos escopos opcionais do seu aplicativo. Esses escopos podem ser excluídos da autorização durante a instalação se a conta ou o usuário que está instalando o aplicativo não tiver as permissões adequadas. Nesse caso, o escopo não será incluído no token de atualização ou de acesso resultante. Saiba mais sobre escopos abaixo.
conditionallyRequiredScopesMatrizUma lista de escopos que são necessários somente quando incluídos no parâmetro de consulta scope do URL de instalação. Saiba mais sobre escopos abaixo.

Escopos

Na janela auth de um arquivo de configuração de aplicativo, você pode especificar três tipos de escopos: necessários, condicionalmente necessários e opcionais. Para este estágio da versão beta, você deve apenas incluir seus escopos de objeto de aplicativo como conditionallyRequiredScopes. Isso permitirá armazenar seus novos recursos isoladamente para clientes específicos, incluindo os escopos de objeto de aplicativo no URL de instalação. Os escopos de objeto de aplicativo usam o seguinte formato: crm.app.schemas.<appObjectFullyQualifiedName>.read Por exemplo, para um objeto de aplicativo com o FQN a16858319_cars, o escopo read seria: crm.app.schemas.a16858319_cars.read. No mínimo, seu aplicativo deve incluir o escopo read acima para permitir que os clientes acessem o objeto. Recomendamos incluir todos os escopos de objeto de aplicativo em seu aplicativo, conforme mostrado abaixo.
"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 obter uma lista completa dos escopos disponíveis, consulte a referência de escopos.

Definição de componente webhooks

Para definir um conjunto de assinaturas de webhook para seu aplicativo, inclua um diretório webhooks no projeto, junto com um arquivo de configuração *-hsmeta.json.
├──src
   ├── app/
   └── app-hsmeta.json
   └── ...
   └── webhooks/
     └── webhooks-hsmeta.json
└──
Veja as opções de configuração disponíveis para o arquivo *-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
        }
      ]
    }
  }
}

Campos webhook *-hsmeta.json

Campos marcados com * são obrigatórios.

CampoTipoDescrição
uid*StringUm identificador exclusivo interno do componente de webhook.
type*StringO tipo de componente, que deve ser webhooks neste caso.
settings*ObjetoUm objeto que especifica dois campos: targetUrl, que é o URL disponível publicamente para que o HubSpot chame onde as cargas do evento serão entregues, e maxConcurrentRequests, que é o limite superior das solicitações HTTP que o HubSpot fará em um determinado intervalo de tempo.
subscriptions*ObjetoUm objeto que especifica os tipos de assinatura em que seu aplicativo se inscreverá.
crmObjectsMatrizUma matriz que contém definições de assinatura de evento. Essa é a matriz padrão a ser incluída e deve ser usada para todos os eventos no novo formato (object.*). Os tipos de assinatura de webhook clássico devem ser incluídos nas matrizes legacyCrmObjects e hubEvents, dependendo do evento.
legacyCrmObjectsMatrizUma matriz que contém tipos de assinatura clássicos, como contact.creation e deal.deletion.
hubEventsMatrizUma matriz que contém os tipos de assinatura clássica contact.privacyDeletion e conversation.*
Para cada objeto subscription, os seguintes campos podem ser especificados, com base no tipo de definição de assinatura em que você está inscrito (ou seja, crmObjects, legacyCrmObjects, ou hubEvents) ou se você está se inscrevendo em uma mudança de propriedade específica (por exemplo, contact.propertyChange).
CampoTipoDescrição
subscriptionTypeStringO tipo de evento que está sendo assinado.
objectTypeStringPara assinaturas especificadas dentro da matriz crmObjects, especifica o objeto do CRM que seu aplicativo está assinando. Para se inscrever em alterações em um objeto de aplicativo, inclua o nome do objeto de aplicativo para este campo (por exemplo, car_app_object).
propertyNameStringPara assinaturas de alteração de propriedade, especifica quais propriedades acionarão o evento de webhook.
activeBooleanoSe os eventos de webhook serão disparados para esta assinatura.

Esquema do cartão de aplicativo

Para criar um cartão de aplicativo que aparece em uma página de registro de objeto de aplicativo, inclua um diretório cards do componente no projeto, junto com um arquivo de configuração.
├──src
   ├── app/
   └── app-hsmeta.json
   └── ...
   └── cards/
     └── my-app-card-hsmeta.json
     └── MyCard.jsx
└──
  • Lembre-se de executar hs project upload depois de criar o componente de objeto de aplicativo e os arquivos de configuração associados.
  • No seu arquivo my-app-card-hsmeta.json, adicione o UID do objeto do aplicativo à matriz objectTypes ("app_object_uid", neste exemplo). Cada um dos campos disponíveis no arquivo .json são detalhados na seção tabela a seguir.
{
  "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"]
  }
}
  • Depois de salvar as alterações no seu arquivo example-card-hsmeta.json, execute hs project upload.
Os cartões são adicionados automaticamente à exibição padrão para objetos de aplicativo. Se o cartão não aparecer automaticamente, veja como adicionar cartões a registros de CRM.

Ver exemplo no GitHub

Campos *-hsmeta.json do cartão de aplicativo

Campos marcados com * são obrigatórios.

CampoTipoDescrição
uid*StringO identificador exclusivo do cartão. Ele pode ser qualquer string, mas deve identificar o aplicativo de uma maneira significativa. O HubSpot identificará o cartão por esse ID para que você possa alterar o título do cartão sem remover dados do histórico ou de estado, como a posição no registro de CRM.
typeStringO tipo de componente, que deve ser card neste caso.
configObjetoUm objeto que contém detalhes de configuração.
name*StringO título do cartão, exibido na interface do usuário do HubSpot.
descriptionStringUma descrição do cartão.
previewImageObjetoUm objeto que contenha os campos file e altText. O campo file é o caminho relativo para a imagem de visualização. As extensões de arquivo válidas são png, jpeg, jpg ou gif. O tamanho máximo do arquivo é 5,0 MB. O campo altText é uma breve descrição da imagem.
entrypoint*StringO caminho de arquivo do código do React de frontend do cartão.
location*crm.record.tab | crm.record.sidebar | helpdesk.sidebarOnde o cartão aparece na interface do usuário do HubSpot. Saiba mais sobre localização da extensão.
objectTypes*MatrizOs tipos de registros de CRM em que o cartão aparecerá.

Associações de objetos de aplicativo

Para ativar as associações entre o objeto do aplicativo e outros objetos de CRM, inclua um diretório do componente app-object-associations no projeto, junto com um arquivo de configuração.
├── src
   ├── app/
   └── app-hsmeta.json
   └── ...
   └── app-object-associations/
     └── my-app-object-association-hsmeta.json
└──
Veja abaixo as opções de configuração de objeto do aplicativo disponíveis (*-association-hsmeta.json).
{
  "uid": "car_to_contact_association",
  "type": "app-object-association",
  "config": {
    "firstObjectType": "car-app-object",
    "secondObjectType": "CONTACT"
  }
}

Campos *-association-hsmeta.json de associação

Campos marcados com * são obrigatórios.

CampoTipoDescrição
uid*StringUm identificador exclusivo interno do aplicativo. Deve ser globalmente exclusivo dentro do projeto.
type*StringO tipo de componente. Deve corresponder ao nome da pasta principal (app-object-association).
config*ObjetoUm objeto que contém a configuração de associação de objeto.
firstObjectType*StringO primeiro objeto da associação. Pode ser um objeto ou um objeto de CRM da HubSpot. Objetos de aplicativo são referenciados por seu uid especificado no arquivo de origem. Objetos padrão são referenciados por seu fullyQualifiedName. A associação resultante será bidirecional, de modo que a ordem desses valores de campo é arbitrária.
secondObjectType*StringO segundo objeto na associação. Veja firstObjectType para mais informações.