Na HubSpot, um aplicativo público é um tipo de integração que pode ser instalada nas contas de clientes ou listadas no Marketplace de aplicativos. Isso requer autenticação por OAuth. Assim que um usuário instalar o app em sua conta da HubSpot, você poderá fazer chamadas de API para essa conta usando um token de acesso OAuth. O app também aparecerá nas configurações Apps conectados da conta.
Os aplicativos conectados também podem fazer a assinatura de alterações usando webhooks e criar eventos de linha do tempo personalizados.
Abaixo, aprenda como:
- Criar um aplicativo público
- Instalar um aplicativo público em uma conta
- Gerenciar o aplicativo, inclusive o monitoramento do uso
- Adicionar um domínio verificado ao aplicativo
Ao criar um app na HubSpot, você basicamente associa o app criado com uma conta de desenvolvedor. Para começar a criar seu app da HubSpot:
- Na sua conta de desenvolvedor de apps, navegue até Apps na barra de navegação principal.
- No canto superior direito, clique em Criar app.
- Em seguida, preencha algumas informações básicas e configurações do app. Quando os usuários autenticarem o aplicativo na conta da HubSpot, eles verão o nome, a descrição, o logotipo e qualquer informação de contato de suporte que você fornecer nesta página.
Observação: o nome do app será usado sempre que ele for exibido na HubSpot. Isso inclui a instalação do app, bem como o rodapé Fornecido por para cartões CRM e eventos de linha do tempo.
- Clique na guia Autenticação para visualizar o ID e o segredo do cliente, bem como os escopos atribuídos ao aplicativo. Você precisará dessas informações aoiniciar uma conexão OAuth entre o aplicativo e o HubSpot.
Os escopos determinam as permissões do seu aplicativo para acessar as fontes de dados ou ferramentas em uma conta que tenha instalado o aplicativo. Os escopos configurados aparecerão como os parâmetros de consulta scope
e optional_scope
em um URL de instalação que você pode fornecer aos usuários.
Na guia Autenticação, estão disponíveis três tipos de escopos diferentes para você configurar. Você deve especificar os escopos do aplicativo necessários para a instalação, mas também pode especificar dois outros tipos de escopos: condicionalmente obrigatórios e opcionais.
- Escopos obrigatórios: escopos que devem ser autorizados pelo usuário e devem estar presentes no parâmetro de consulta
scope
no URL de instalação do aplicativo para uma instalação bem-sucedida. - Escopos condicionalmente obrigatórios: escopos que devem ser autorizados pelo usuário somente se estiverem presentes no parâmetro de consulta
scope
no URL de instalação do aplicativo para uma instalação bem-sucedida.- Este tipo de escopo permite ser flexível e fornecer um URL de instalação separado para funcionalidades ou escopos escalonados que só são obrigatórios quando os usuários ativam determinadas funcionalidades no seu aplicativo. Por exemplo, você pode oferecer dois URLs de instalação aos seus usuários: um URL de instalação pode incluir o escopo condicionalmente obrigatório no parâmetro de consulta
scope
para usuários com acesso a uma funcionalidade, enquanto outro URL de instalação omite esse escopo no parâmetro de consultascope
para usuários sem acesso. - Se um escopo condicionalmente obrigatório estiver presente no URL de instalação do seu aplicativo e um usuário sem acesso à funcionalidade associada tentar instalar o aplicativo utilizando esse URL, a instalação falhará.
- Este tipo de escopo permite ser flexível e fornecer um URL de instalação separado para funcionalidades ou escopos escalonados que só são obrigatórios quando os usuários ativam determinadas funcionalidades no seu aplicativo. Por exemplo, você pode oferecer dois URLs de instalação aos seus usuários: um URL de instalação pode incluir o escopo condicionalmente obrigatório no parâmetro de consulta
- Escopos opcionais: escopos que não são obrigatórios para instalar o aplicativo com êxito. Estes escopos são especificados no parâmetro de consulta
optional_scope
no URL de instalação do seu aplicativo. Por exemplo, se quiser que seu aplicativo possa obter dados de objetos personalizados (que só estão disponíveis para contas Enterprise da HubSpot), poderá adicionar o escopocrm.objects.custom.read
como um escopo opcional. Depois, se uma conta tiver acesso aos objetos personalizados, o escopo será autorizado. Caso contrário, ainda será possível instalar o aplicativo sem o escopo dos objetos personalizados.
Para personalizar as configurações do seu escopo e adicionar novos escopos:
- Para configurar os escopos condicionalmente obrigatórios ou opcionais, clique para ativar a opção Ativar configurações avançadas de escopo.
Observe: a partir de 21 de outubro de 2024, serão necessárias configurações avançadas de escopo para todos os aplicativos. Saiba mais no Registro de alterações para desenvolvedores da HubSpot.
- Na seção Escopos, clique em Adicionar novo escopo.
- No painel direito, utilize a barra de pesquisa para procurar um escopo e, em seguida, marque a caixa de seleção ao lado de qualquer escopo que pretenda que o usuário autorize. Se você ativou as configurações avançadas de escopo, clique no menu suspenso ao lado do escopo e selecione um tipo de escopo.
- Clique em Atualizar.
- Revise os escopos configurados. Se você ativou as configurações avançadas de escopo, poderá mudar o tipo de escopo de qualquer escopo clicando no menu suspenso ao lado do escopo. Você também pode clicar em Excluir para remover um dos escopos do seu aplicativo.
- Quando tiver terminado de definir as configurações do aplicativo, clique em Criar aplicativo no canto inferior esquerdo.
Com o seu app criado, agora é possível realizar o processo de instalação.
Observação: é recomendável adicionar um domínio verificado ao aplicativo para incluir outro nível de confiança para os usuários que instalarem o aplicativo. Caso contrário, o aplicativo exibirá um banner informando que não foi verificado.
Observação: antes de instalar seu app, lembre-se do seguinte:
- Um app não aparecerá na página Apps conectados da conta até os tokens de acesso iniciais e de atualização serem criados.
- Um aplicativo só poderá ser instalado por usuários com acesso aos escopos obrigatórios ou condicionalmente obrigatórios de um aplicativo.
- Não é possível instalar aplicativos em contas de desenvolvedor. Para testar o app, crie uma conta de teste em sua conta de desenvolvedor do app e instale-a ali.
A instalação de um app pode ser dividida em duas etapas: autorização e geração de token.
- Para autorizar o aplicativo com uma conta da HubSpot, você precisará criar um URL de autorização. Para fazer isso, obtenha o ID de cliente do aplicativo e inicie o processo do OAuth.
- Depois que o URL estiver pronto, abra-o no navegador para ver uma lista de todas as suas contas da HubSpot. É exatamente isso que os usuários verão quando você direcioná-los para esse URL.
- Selecione a conta em que deseja instalar o app.
- Depois de escolher uma conta, você verá uma lista de escopos com base nos parâmetros
&scope=
e&optional_scope=
definidos para o URL de autorização.
Observação: se você incluir optional_scope
e a conta selecionada não tiver acesso a ele (como o escopo do conteúdo para uma conta somente do CRM), ele não será listado.
- Clique em Conceder acesso para autorizar a conexão.
- Depois que o acesso for concedido, você será redirecionado de acordo com o parâmetro
&redirect_uri=
no URL de autorização original, e um parâmetro?code=
será anexado ao URL. Use esse código na próxima etapa para gerar um token de acesso.
Para gerar seus tokens de acesso iniciais e de atualização, você precisará do código do parâmetro ?code=
do URL de autorização, do redirect_url
e do ID e do segredo do cliente. Você encontrará instruções detalhadas aqui.
Depois de autorizar o aplicativo e gerar os tokens iniciais, a instalação estará concluída. Ele será listado em sua página Apps conectados e você começará a receber solicitação de busca de webhook e cartões CRM.
Você pode encontrar o ID de um aplicativo público na sua conta de desenvolvedor de aplicativos, usando um dos métodos a seguir:
- Na sua conta de desenvolvedor, acesse Aplicativos na barra de navegação principal e visualize o ID do aplicativo listado abaixo do nome do seu aplicativo.
- Na sua conta de desenvolvedor, acesse Aplicativos na barra de navegação principal e clique no nome do aplicativo. Na página Informações básicas, clique na guia Autenticação e visualize o ID do aplicativo.
O HubSpot registra todas as solicitações feitas para um app conectado, incluindo solicitações recebidas usando um token de acesso OAuth ou solicitações enviadas para webhooks ou cartões de CRM.
Para visualizar este registro de solicitação:
- Na sua conta de desenvolvedor, acesse Aplicativos na barra de navegação principal.
- Clique no nome do aplicativo.
- No menu da barra lateral esquerda, acesse Monitoramento.
- Use as guias para visualizar diferentes tipos de solicitações feitas para ou por meio do app. Ao visualizar esses registros, você pode clicar em uma solicitação individual para visualizar mais informações sobre ela, incluindo:
- para solicitações bem-sucedidas, o método, o caminho e o horário da solicitação.
- para solicitações malsucedidas, informações de erro adicionais, como cabeçalhos de resposta e corpo.
Abaixo, saiba mais sobre cada guia da página Monitoramento.
- Chamadas de API: a guia Chamadas de API mostrará todas as solicitações feitas no aplicativo usando um token de acesso de OAuth. Ele pode ser filtrado por método HTTP, código de resposta, período ou URL de solicitação.
- Webhooks: a guia Webhooks mostra as solicitações do HubSpot para todas as suas assinaturas de webhook do aplicativo. Filtre por resposta (inclusive tempo limite e falhas de conexão), status (sucesso, nova tentativa ou falha), tipo de assinatura, período de tempo, tentativa, lote, evento ou ID da conta.
Observação: o ID da tentativa é uma combinação de subscriptionId
, eventId
, e attemptNumber
de uma solicitação específica.
- Extensões do CRM: a guia Extensões do CRM mostra as solicitações para os Cartões de CRM do aplicativo. Filtre por tipo de objeto de extensão, tipo de objeto de CRM (contato, empresa, ticket ou negócio), erro ou tipo de aviso, período de tempo, ID da solicitação ou ID de registro de CRM (ou seja, um ID de contato específico).
- Configurações do aplicativo: a guia Configurações do aplicativo permite configurar a página de configurações do aplicativo.
Em cada guia, se algum evento associado ocorreu nos últimos 30 dias (por exemplo, um gatilho de webhook ou uma chamada de API), você pode clicar em Exportar registros para exportar os dados de evento associados para um CSV:
- Na caixa de diálogo, configure quantos dias de dados devem ser exportados (até 30 dias).
- Clique em Exportar. Será enviada uma notificação por e-mail para o endereço de e-mail associado ao seu usuário nas suas configurações da HubSpot.
Quando os usuários do HubSpot instalam um aplicativo, eles consentem o acesso aos dados de suas contas ao desenvolvedor do aplicativo. A identidade e a reputação do desenvolvedor desempenham um papel importante na decisão de um usuário de continuar com a instalação. Para garantir o consentimento total do usuário ao instalar um aplicativo, a HubSpot exibirá uma mensagem na tela de instalação do aplicativo para indicar seu nível de verificação e a listagem no Marketplace de aplicativos:
-
Se um aplicativo não tiver um domínio verificado, a HubSpot exibirá um banner na tela de instalação, informando que o aplicativo não foi verificado.
-
Se o aplicativo tiver um domínio verificado, mas não estiver listado no Marketplace de aplicativos, o HubSpot exibirá o domínio verificado junto com um banner na tela de instalação, informando que o aplicativo não foi revisado ou aprovado pela HubSpot.
-
Quando um aplicativo for listado no marketplace e aprovado pelo processo de revisão do aplicativo da HubSpot, o HubSpot não exibirá nenhum dos banners acima. Não é necessário verificar o domínio se o aplicativo tiver sido listado no Marketplace de aplicativos.
Para adicionar um domínio verificado ao aplicativo, você precisará primeiro adicionar o domínio às configurações do aplicativo e, em seguida, um registro TXT às configurações de DNS do domínio:
- Na sua conta de desenvolvedor de aplicativos, acesse Aplicativos.
- Clique no nome do aplicativo.
- Na barra lateral esquerda, acesse Contato e suporte.
- No campo Domínio da empresa, insira seu domínio e clique em Salvar. Uma mensagem será exibida abaixo do Domínio da empresa, informando que o domínio ainda não foi verificado.
- Clique em Verificar agora para iniciar o processo de verificação.
-
No painel direito, confirme se o domínio foi inserido corretamente e clique em Próximo.
-
Copie o valor do registro de TXT exigido, clicando em Copiar na coluna Valor.
-
No seu provedor de DNS, crie um registro de TXT com o valor copiado. Veja a seguir as instruções para alguns provedores de DNS comuns:
-
Depois de atualizar as configurações de DNS, volte ao HubSpot e clique em Próximo no painel direito. Os registros de DNS podem levar até 48 horas para serem atualizados, portanto, o HubSpot pode não reconhecer a alteração imediatamente. Você pode voltar a essa tela a qualquer momento, selecionando novamente a opção Verificar agora na página de configurações Informações da empresa.
-
Depois da verificação, será exibido um indicador de status de sucesso no campo Domínio da empresa.
- Para garantir a propriedade contínua do domínio, o HubSpot continuará a verificar se o registro TXT está presente regularmente. O aviso de instalação retornará se o registro TXT for removido ou modificado.
- Atualmente, você pode ter apenas um domínio verificado por conta de desenvolvedor. Todos os aplicativos em uma conta compartilham o domínio verificado. O domínio na página de instalação será vinculado ao seu domínio raiz.
- Se você excluir seu domínio verificado, todos os aplicativos da sua conta de desenvolvedor receberão o aviso de instalação novamente. Você pode verificar outro domínio, mas o processo levará algumas horas.