Zum Hauptinhalt springen
Última modificação: 8 de outubro 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.
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.
1

Instale a versão mais recente da CLI da HubSpot

Você precisará da versão beta mais recente da CLI da HubSpot para criar um aplicativo unificado. Em uma janela de terminal, execute o seguinte comando:
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.
2

Autenticar sua conta de desenvolvedor

Você precisará autenticar sua conta de desenvolvedor executando o seguinte comando:
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.
3

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.
hs project create --templateSource robrown-hubspot/hubspot-project-components-ua-app-objects-beta
4

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

​
Observação:

Para começar, você pode usar o exemplo de Node.js OAuth 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.
  • Altere a propriedade uid do aplicativo no arquivo app-hsmeta.json e os outros arquivos de configuração *-hsmeta.json em seu projeto.
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.
  • 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.
5

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

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 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 não poderão ser removidos.

​
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.
  • 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:
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.
7

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

​
Observação:

  • 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.
  • 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.
  • Quando terminar de adicionar esses escopos e salvar suas alterações, execute os seguintes comandos para confirmar as alterações na plataforma:
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.
8

Crie uma conta de teste de desenvolvedor (opcional) e instale seu aplicativo

Se ainda não tiver uma conta de teste, 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.
app-object-available-in-crm
9

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

​
Próximas etapas

Confira a documentação de referência para obter as próximas etapas sobre como usar objetos de aplicativo com diferentes recursos da plataforma de desenvolvedor:
⌘I