> ## Documentation Index > Fetch the complete documentation index at: https://br.developers.hubspot.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Referência de objetos de aplicativo (BETA) > Informações de referência para criar objetos de aplicativo, incluindo opções de configuração para aplicativos, objetos de aplicativo e muito mais. 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](/apps/developer-platform/add-features/app-objects/overview). 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. ```shell theme={null} 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 └── ``` ## 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. ```shell theme={null} ... ├──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`. ```json theme={null} { "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 } ] } ] } } ```

Campos marcados com \* são obrigatórios.

| Campo | Tipo | Descrição | | ------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `uid`\* | String | Um identificador exclusivo para o objeto do aplicativo. Deve ser globalmente exclusivo dentro do projeto. | | `type`\* | String | O tipo de componente. Deve corresponder ao nome da pasta principal (`app-object`). | | `name`\* | String | O 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`). | | `appPrefix` | String | Uma 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`\* | String | A descrição do objeto, que será mostrada no HubSpot. | | `singularForm`\* | String | A forma singular do nome do objeto. | | `pluralForm`\* | String | A forma plural do nome do objeto. | | `properties`\* | Matriz | Uma lista de propriedades de CRM definidas para o objeto. As propriedades são definidas usando os mesmos campos da [API de propriedades](/api-reference/crm-properties-v3/guide). As propriedades resultantes terão o prefixo `a_` (por exemplo, `a12345_make`) na criação. Você não deve incluir o prefixo no arquivo de configuração. | | `primaryDisplayLabelPropertyName`\* | String | O nome da propriedade que deve ser usada como [propriedade de exibição principal](https://knowledge.hubspot.com/object-settings/create-custom-objects#:~:text=object%27s%20singular%20name.-,Primary%20display%20property,-%3A%20the%20property%20used). O valor deve corresponder ao nome fornecido na lista `properties` (ou seja, não deve incluir o prefixo `a_` gerado.) | | `secondaryDisplayLabelPropertyNames`\* | Matriz | A lista das propriedades que devem ser usadas como [propriedades de exibição secundária](https://knowledge.hubspot.com/object-settings/create-custom-objects#:~:text=Secondary%20properties%3A). O valor deve corresponder ao nome fornecido na lista `properties` (ou seja, não deve incluir o prefixo `a_` gerado.) | | `settings`\* | Objeto | Um objeto que contém as configurações de objeto. | | `hasRecordPage`\* | Booleano | Se 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`\* | Booleano | Se 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`\* | Booleano | Se 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_`. 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`. ```shell theme={null} ... ├──src │ ├── app/ │ │ └── app-hsmeta.json/ └── ``` Veja abaixo as opções de configuração disponíveis para `app-hsmeta.json`. Observe as seguintes alterações para os arquivos de configuração de cartão de aplicativo: * Campos de nível superior `uid`, `type` e `config` adicionados. * Campo `extensions` removido. * Campo `distribution` adicionado. ```json theme={null} { "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" } } } ``` ### Campos \*-hsmeta.json do esquema do aplicativo

Campos marcados com \* são obrigatórios.

| Campo | Tipo | Descrição | | --------------------------------------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `uid`\* | String | Um 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`\* | String | O tipo de componente. Deve corresponder ao nome da pasta principal (`app`). | | `description`\* | String | Uma descrição do que o aplicativo faz para o usuário que está instalando. Pode ser qualquer string de até 8192 caracteres. | | `name`\* | String | O 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`\* | String | O método de distribuição do aplicativo. Precisa ser definido como `marketplace` para que o aplicativo possa ser listado no Marketplace de aplicativos. | | `auth`\* | Objeto | Um objeto que contém os detalhes do método de autenticação do aplicativo. Consulte a [tabela de autenticação](#auth-fields) para obter detalhes. | | `permittedUrls` | Objeto | Uma 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](https://developer.mozilla.org/en-US/docs/Learn_web_development/Howto/Web_mechanics/What_is_a_URL#authority), seguido por um prefixo de caminho opcional, se necessário. | | `supportEmail` | String | Um endereço de e-mail válido com o qual os usuários podem entrar em contato para obter suporte. | | `documentationUrl` | String | O URL externa na qual os usuários podem navegar para documentação de suporte. Devem usar HTTPS. | | `supportUrl` | String | O URL externo para o qual os usuários podem navegar para obter suporte adicional. Devem usar HTTPS. | | `supportPhone` | String | O 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.

| Campo | Tipo | Descrição | | ----------------------------------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `type`\* | String | O tipo de autenticação. Deve ser definido como `oauth` para que o aplicativo use a autenticação OAuth. | | `redirectUrls`\* | Matriz | Uma 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`\* | Matriz | Uma 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](#scopes). | | `optionalScopes` | Matriz | Uma 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](#scopes). | | `conditionallyRequiredScopes` | Matriz | Uma 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](#scopes). | ### Escopos Na janela `auth` de um arquivo de configuração de aplicativo, você pode especificar três [tipos de escopos](/apps/legacy-apps/public-apps/overview#scope-types): 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..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. ```json theme={null} "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](/apps/legacy-apps/authentication/scopes). ## 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`. ```shell theme={null} ├──src │ ├── app/ │ │ └── app-hsmeta.json │ │ └── ... │ │ └── webhooks/ │ │ └── webhooks-hsmeta.json └── ``` Veja as opções de configuração disponíveis para o arquivo `*-hsmeta.json`. ```json theme={null} { "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.

| Campo | Tipo | Descrição | | ---------------------------------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `uid`\* | String | Um identificador exclusivo interno do componente de webhook. | | `type`\* | String | O tipo de componente, que deve ser `webhooks` neste caso. | | `settings`\* | Objeto | Um 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`\* | Objeto | Um objeto que especifica os tipos de assinatura em que seu aplicativo se inscreverá. | | `crmObjects` | Matriz | Uma 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. | | `legacyCrmObjects` | Matriz | Uma matriz que contém tipos de assinatura clássicos, como `contact.creation` e `deal.deletion`. | | `hubEvents` | Matriz | Uma 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`). | Campo | Tipo | Descrição | | ------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `subscriptionType` | String | O tipo de evento que está sendo assinado. | | `objectType` | String | Para 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`). | | `propertyName` | String | Para assinaturas de alteração de propriedade, especifica quais propriedades acionarão o evento de webhook. | | `active` | Booleano | Se 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. ```shell theme={null} ├──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](#app-card-*-hsmeta.json-fields) a seguir. Observe as seguintes alterações para os arquivos de configuração de cartão de aplicativo: * Campos de nível superior `uid`, `type` e `config` adicionados. * O campo `module` foi renomeado para `entrypoint`. * O campo `title` foi renomeado para `name`. * O campo `objectTypes` foi simplificado para aceitar uma matriz de strings. ```json theme={null} { "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](/apps/developer-platform/add-features/ui-extensibility/app-cards/create-an-app-card#view-the-card-in-hubspot). ### Campos \*-hsmeta.json do cartão de aplicativo

Campos marcados com \* são obrigatórios.

| Campo | Tipo | Descrição | | -------------------------------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `uid`\* | String | O 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. | | `type` | String | O tipo de componente, que deve ser `card` neste caso. | | `config` | Objeto | Um objeto que contém detalhes de configuração. | | `name`\* | String | O título do cartão, exibido na interface do usuário do HubSpot. | | `description` | String | Uma descrição do cartão. | | `previewImage` | Objeto | Um 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`\* | String | O caminho de arquivo do código do React de frontend do cartão. | | `location`\* | `crm.record.tab` \| `crm.record.sidebar` \| `helpdesk.sidebar` | Onde o cartão aparece na interface do usuário do HubSpot. Saiba mais sobre [localização da extensão](/apps/developer-platform/add-features/ui-extensibility/app-cards/reference#extension-location). | | `objectTypes`\* | Matriz | Os 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. ```shell theme={null} ├── 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`). ```json theme={null} { "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.

| Campo | Tipo | Descrição | | ------------------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `uid`\* | String | Um identificador exclusivo interno do aplicativo. Deve ser globalmente exclusivo dentro do projeto. | | `type`\* | String | O tipo de componente. Deve corresponder ao nome da pasta principal (`app-object-association`). | | `config`\* | Objeto | Um objeto que contém a configuração de associação de objeto. | | `firstObjectType`\* | String | O 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`\* | String | O segundo objeto na associação. Veja `firstObjectType` para mais informações. |