> ## 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.

# Introdução aos Objetos de aplicativo (BETA)

> Saiba como criar um novo aplicativo unificado de prova de conceito (BETA).

<Info>
  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](https://developers.hubspot.com/app-objects-interest).
</Info>

Saiba como criar um aplicativo de prova de conceito no qual você configurará um objeto de aplicativo que pode ser testado e usado em uma conta de teste de desenvolvedor.

<Steps>
  <Step title="Instale a versão mais recente da CLI da HubSpot">
    Você precisará da versão beta mais recente da [CLI da HubSpot](/developer-tooling/local-development/hubspot-cli/reference) para criar um aplicativo unificado. Em uma janela de terminal, execute o seguinte comando:

    ```shell theme={null}
    npm install -g @hubspot/cli@next
    ```

    A CLI precisa ter a versão `7.4.4-beta.0` ou posterior. Você pode verificar qual versão da CLI você tem executando `hs --version`.
  </Step>

  <Step title="Autenticar sua conta de desenvolvedor">
    Você precisará autenticar sua conta de desenvolvedor executando o seguinte comando:

    ```shell theme={null}
    hs auth
    ```

    * Siga os prompts para gerar uma Chave de acesso pessoal em sua conta e, em seguida, copie e cole a chave criada no terminal para salvar sua configuração.
    * Durante esse período beta, é recomendado que você torne essa conta sua conta padrão na CLI. Isso evitará possíveis erros de acesso para a conta inscrita na versão beta.
  </Step>

  <Step title="Criar um novo projeto básico">
    Execute o comando abaixo no terminal para criar um novo projeto e aplicativo do marketplace com os recursos atualmente compatíveis ou um esquema de referência de objeto do aplicativo.

    ```shell theme={null}
    hs project create --templateSource robrown-hubspot/hubspot-project-components-ua-app-objects-beta
    ```
  </Step>

  <Step title="Configurar o projeto recém-criado e carregá-lo na sua conta de desenvolvedor">
    O framework de projetos move os recursos do aplicativo em que foram configurados anteriormente na interface ou via API para arquivos de código-fonte, geralmente definidos como arquivos de configuração `<file-name>-hsmeta.json`.

    Os recursos do aplicativo são então criados usando uma combinação de subpastas do diretório `/src/app` e outros arquivos de configuração conforme necessário. Para configurar seu projeto:

    * Adicione um ou mais URLs de redirecionamento válidos ao arquivo `app-hsmeta.json` com base na configuração do seu servidor OAuth local (ou de não-produção).

    <Tip>
      ### Observação:

      Para começar, você pode usar o [exemplo de Node.js OAuth](http://github.com/hubspot/oauth-quickstart-nodejs) e executá-lo localmente. Ele já está configurado para funcionar com `https://localhost:3000/oauth-callback` como o URL de redirecionamento configurado no código de exemplo básico a partir do comando `hs project create` executado na etapa anterior.
    </Tip>

    * Altere a propriedade `uid` do aplicativo no arquivo `app-hsmeta.json` e os outros arquivos de configuração `*-hsmeta.json` em seu projeto.

    <Warning>
      Os UIDs são usados como um identificador exclusivo para todos os componentes e recursos do projeto. Depois que um recurso e UID são criados, alterar ou modificar o UID em implantações subsequentes forçará a plataforma a reconhecê-lo como diferente dos recursos anteriores, o que pode não ser o pretendido.
    </Warning>

    * Ao usar objetos para seu aplicativo unificado, somente as definições de propriedade de "nome" autorizadas serão permitidas com base em sua solicitação de objeto. Como parte desta versão beta privada, você deve ter recebido separadamente a confirmação do "nome" aprovado do seu aplicativo, que deve ser usado na configuração `*-object-hsmeta.json`. Para referência, o nome totalmente qualificado (FQN) do objeto de aplicativo será `a<appId>_<name>`. Por exemplo, se o `appId` for `16858319` e a propriedade `name` foi `CARS`, o FQN será `a16858319_cars`.
    * Depois de salvar as alterações, execute o comando da CLI `hs project upload` para carregar seu projeto na plataforma de desenvolvedor da HubSpot e disparar automaticamente uma nova compilação.
    * Em uma janela do navegador, navegue até `https://app.hubspot.com/developer_projects/<accountId>` para acessar a interface de projetos e confirmar se o aplicativo e o projeto foram criados, compilados e implantados corretamente.
  </Step>

  <Step title="Adicione o ID e o segredo do cliente ao backend do seu aplicativo">
    * Depois de carregar seu projeto, você precisará obter os detalhes de autenticação para que seu aplicativo copie para sua configuração OAuth:

      * Clique em **Projetos** no menu de navegação *Desenvolvimento*.
      * Clique no **nome** do novo projeto.
      * Clique no **UID** do seu aplicativo e clique na guia **Autenticação**.
      * Copie o *ID do cliente* e o *Segredo do cliente* do seu novo aplicativo e cole-o nos locais correspondentes na configuração do seu servidor OAuth local e, em seguida, reinicie o servidor OAuth.
  </Step>

  <Step title="Definir a configuração do esquema do objeto de aplicativo">
    Em seguida, você configurará o esquema do objeto de aplicativo:

    * Adicione um novo objeto de aplicativo criando um diretório dentro do diretório `/src/app` e nomeie-o como `app-objects`. O caminho resultante para o novo diretório deve ser `/src/app/app-objects`.
    * Crie um novo arquivo de configuração para representar o esquema do seu objeto. Você deve usar o nome do objeto concedido ao seu aplicativo durante o processo de visualização como o prefixo do nome do arquivo, seguido por `-object-hsmeta.json`. Por exemplo, no modelo de projeto de referência, o nome do objeto do aplicativo é "CAR", de modo que o arquivo de configuração resultante é `car-object-hsmeta.json`.
    * Consulte o arquivo de referência sobre [definição de componente do objeto de aplicativo](/apps/developer-platform/add-features/app-objects/reference#app-schema) e personalize os campos com os valores correspondentes para o seu objeto de aplicativo.
      * No objeto `config` na sua definição, o campo `name` deve corresponder ao nome concedido ao seu aplicativo durante o processo de revisão, formatado como `UPPER_SNAKE_CASE`.
      * Observe que, depois que as propriedades e os campos forem adicionados ao esquema do objeto de aplicativo e carregados no projeto na próxima etapa, eles <u>não</u> poderão ser removidos.

    <Tip>
      ### Observação:

      Para conveniência durante o teste, o mesmo nome de objeto de aplicativo pode ser usado em vários aplicativos para dar suporte ao seu ciclo de vida de desenvolvimento. Comece com este aplicativo de prova de conceito e, assim que as migrações se tornarem disponíveis, você poderá usar o mesmo nome e definições de esquema em seus aplicativos de desenvolvimento, preparação e produção. Os UIDs para cada uma dessas instâncias precisarão ser exclusivos.
    </Tip>

    * Quando terminar de editar a definição do esquema do objeto de aplicativo e estiver pronto para confirmar essas alterações, execute os seguintes comandos para salvar as alterações:

    ```shell theme={null}
    hs project upload
    hs project deploy
    ```

    * Em uma janela do navegador, navegue até `https://app.hubspot.com/developer_projects/<hubId>` para acessar a interface de projetos e confirmar se o aplicativo e o projeto foram criados, compilados e implantados corretamente.
  </Step>

  <Step title="Atualize seu aplicativo">
    Agora que seu esquema de objeto do aplicativo foi carregado, você precisará atualizar os escopos definidos em seu arquivo `app-hsmeta.json` para refletir os escopos criados na etapa anterior. Esses escopos devem estar visíveis nos registros da CLI após a execução de `hs project upload`.

    * Edite o arquivo `app-hsmeta.json` e adicione os novos escopos à matriz de `requiredScopes` dentro da definição `auth`. Por exemplo, se o seu `appId` foi `a12345`, então você editará a definição `auth` como o seguinte:

    ```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": []
    },
    ```

    <Warning>
      ### Observação:

      <ul>
        <li>
          Os clientes somente poderão ver o objeto de aplicativo se o escopo `schemas.read`
          estiver incluído nas configurações do aplicativo e for solicitado durante o
          fluxo de OAuth de instalação/reautorização. É altamente recomendado incluir
          todos os escopos de objeto de aplicativo em suas configurações, mas `schemas.read` é obrigatório para que os
          clientes possam acessá-lo. Por exemplo, para um `appId` de `12345`,
          você incluiria `crm.app.schemas.a12345_MY_APP_OBJECT.read` como o escopo
          necessário.
        </li>

        <li>
          Dependendo do aplicativo que você está testando (protótipo, desenvolvimento, preparação,
          produção), você precisará ter em mente onde adiciona suas definições
          de escopo. Embora ainda não haja suporte para a implantação de um aplicativo de produção durante
          esta fase da versão beta privada, geralmente é mais seguro incluir estes
          escopos como `conditionallyRequiredScopes` quando estiver pronto para produção.
          Saiba mais sobre esses tipos de escopo na [documentação do
          aplicativo público](/apps/legacy-apps/public-apps/overview#scope-types).
        </li>
      </ul>
    </Warning>

    * Quando terminar de adicionar esses escopos e salvar suas alterações, execute os seguintes comandos para confirmar as alterações na plataforma:

    ```shell theme={null}
    hs project upload
    hs project deploy
    ```

    Depois que a implantação for concluída, seu aplicativo e o objeto de aplicativo correspondente estarão prontos para serem testados com uma conta instalada.
  </Step>

  <Step title="Crie uma conta de teste de desenvolvedor (opcional) e instale seu aplicativo">
    Se ainda não tiver uma [conta de teste](/getting-started/account-types#developer-test-accounts), você poderá criar uma no HubSpot:

    * Acesse **Contas de teste** no menu de navegação *Desenvolvimento* e clique em **Criar conta de teste de desenvolvedor**. Siga as instruções para criar sua nova conta de teste.
    * No menu da barra lateral esquerda, acesse **Projetos**, clique no **nome** do seu novo projeto e, em seguida, clique no **UID** do seu aplicativo na lista de componentes.
    * Na guia *Autenticação*, copie o link de instalação do aplicativo.
    * Use este link para instalar o aplicativo em sua conta de teste de desenvolvedor.
    * Abra a conta de teste e acesse a página *Aplicativos conectados*, onde você deverá ver seu aplicativo instalado listado.
    * Em sua conta de teste, acesse **CRM** > **Contatos**, clique no menu suspenso do objeto do CRM e confirme se o objeto de aplicativo está disponível.
    * Em seguida, você pode confirmar se a definição do esquema está de acordo com o arquivo de configuração criando um novo registro do seu objeto de aplicativo.

    <Frame>
      <img src="https://www.hubspot.com/hubfs/Knowledge_Base_2023-24-25/test-app-object-in-developer-test-account-1.png" alt="app-object-available-in-crm" />
    </Frame>
  </Step>

  <Step title="Acesso a dados programáticos usando a API de objetos da HubSpot">
    Agora que você criou com sucesso o objeto de aplicativo e o testou em uma conta de teste de desenvolvedor, é possível usar o token de acesso OAuth associado à conta de teste instalada para fazer solicitações de atualização de dados na conta diretamente por meio da API de objetos.

    Leia a documentação da [API de objetos](/guides/crm/using-object-apis) para obter mais informações sobre a API, mas qualquer solicitação específica para o objeto de aplicativo seguirá as mesmas convenções dos outros objetos padrão no HubSpot. Você precisará usar o objeto de aplicativo `objectTypeId` ou `fullyQualifiedName` como o parâmetro de caminho `objectType` na sua solicitação.

    Por exemplo, o bloco de código a seguir demonstra como fazer cURL solicitar a criação de um novo registro do seu objeto de aplicativo:

    ```shell theme={null}
    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"
      }
    }'
    ```

    Você pode encontrar o `objectTypeId` para seu objeto de aplicativo navegando até a página de índice de registros:

    * Acesse **CRM** > **Contatos** na conta de teste de desenvolvedor em que você instalou seu aplicativo.
    * Clique no **menu suspenso** na parte superior da página e selecione o **objeto de aplicativo**.
    * O `objectTypeId` aparecerá no URL entre a parte `/objects/<objectTypeId>/views`.
  </Step>
</Steps>

## Próximas etapas

Confira a [documentação de referência](/apps/developer-platform/add-features/app-objects/reference) para obter as próximas etapas sobre como usar objetos de aplicativo com diferentes recursos da plataforma de desenvolvedor:

* [Configurar um cartão de aplicativo](/apps/developer-platform/add-features/app-objects/reference#app-card-schema)
* [Configurar assinaturas do webhook](/apps/developer-platform/add-features/app-objects/reference#webhooks-component-definition)
* [Habilitar associações com outros tipos de objetos do CRM](/apps/developer-platform/add-features/app-objects/reference#app-object-associations)