Cartões de CRM

Solicitações de busca de dados

Conforme mencionado na guia de visão geral, o HubSpot faz uma solicitação de busca de dados ao seu aplicativo sempre que um usuário visualizar o registro de CRM associado. Essas solicitações são enviadas à busca/targetUrl especificado do cartão com uma carga útil que fornece detalhes para o registro do CRM associado.

As respostas podem conter até cinco propriedades de cartão. Se mais propriedades de cartão estiverem disponíveis para um objeto de CRM específico, seu aplicativo pode vincular a eles.

Observe que o tempo limite da solicitação é de 5 segundos. Nesse período, uma conexão deve ser feita em 3 segundos. 

Exemplo de solicitação de busca de dados:

GET: https://example.com/demo-tickets?userId=12345&userEmail=testuser@example.com&associatedObjectId=78912&associatedObjectType=COMPANY&portalId=9999999&domain=testcompany.com

Com um cabeçalho:

X-HubSpot-Signature: <some base64 string>

o cabeçalho X-HubSpot-Signature oferece uma confirmação de que a solicitação veio do HubSpot. Veja solicitar assinaturas para detalhes.

Parâmetros de consulta:

• userId: o ID numérico do usuário do cliente que solicita dados.
• userEmail: o endereço da HubSpot do usuário que solicita dados.
• portalId: o ID da conta da HubSpot do cliente que solicita dados. A conta e o Portal são usados intercambiavelmente. 
• associatedObjectId: o ID do objeto atual, dependendo do associatedObjectType. Será companyId, dealId, contact vID ou objectId para tíquetes.
• associatedObjectType: o tipo de objeto do qual o usuário solicita dados (contato, empresa, negócio ou tíquete). Esse será um dos associatedHubSpotObjectTypes fornecidos para esse tipo de registro.
• E valores para qualquer um dos associatedHubSpotObjectTypeProperties solicitados. Se uma das propriedades de solicitação não for definida para o objeto atual, ela não será listada na linha de consulta. No exemplo acima, o domínio de propriedade da empresa está incluído. As propriedades de solicitação podem ser definidas na UI de configurações do aplicativo, como você pode ver na captura de tela abaixo: 

Exemplo de resposta:

Definições:

• results: uma lista de até cinco propriedades de cartão válidas. 
• results[].objectId: um ID exclusivo para este objeto. Esta propriedade é necessária.
• results[].title: O título desse objeto. Esta propriedade é necessária.
• results[].link: a URI que o usuário pode seguir para obter mais detalhes sobre este objeto. Esta propriedade é opcional, mas se todos os objetos não têm um link, você deve fornecer um valor de nulo.
• results[].properties: uma lista de propriedades personalizadas que não são definidas nas configurações do cartão. Você pode usar essa lista para exibir propriedades exclusivas de objeto específico. Essas propriedades serão exibidas na ordem em que são fornecidas, mas depois das propriedades definidas nas configurações do cartão. Esta propriedade é opcional.
• results[].actions: uma lista de ações disponíveis que um usuário pode efetuar nesse objeto. Consulte tipos de ação para detalhes das ações especificadas. Esta propriedade é opcional.
• totalCount: o número total de propriedades de cartão disponíveis, se houver mais de cinco relacionados ao objeto de CRM solicitado. Esta propriedade é opcional.
• allItemsLink: uma URI que mostra todas as propriedades do cartão associadas ao objeto de CRM solicitado, se houver mais de cinco. Esta propriedade é opcional.
• itemLabel: o rótulo a ser usado no link "Ver mais", por exemplo, "Ver mais tíquetes". Esta propriedade é opcional e, se não for fornecida, ela será o título do cartão.
• settingsAction: uma ação iframe que oferece a capacidade de atualizar as configurações do aplicativo aos usuários. Consulte tipos de ação para detalhes das ações especificadas. Esta propriedade é opcional.
• primaryAction: a ação principal para um tipo de registro, normalmente uma ação de “criação”. Consulte tipos de ação para detalhes das ações especificadas. Esta propriedade é opcional.
• secondaryActions: Uma lista de ações exibidas no nível do cartão. Consulte tipos de ação para detalhes das ações especificadas. Esta propriedade é opcional.

Além das propriedades acima, o integrador pode fornecer valores para as propriedades definidas nas configurações do cartão. No exemplo acima, a propriedade JSON criada:

"created":"2016-08-04"

Fornece um valor para esse objeto para a propriedade created predefinida.

Lidar com hooks de ação 

Quando um usuário clica em uma ação definida como um hook de ação, o HubSpot envia uma solicitação usando o método URI e HTTP especificado na definição de ação.

Exemplo de solicitação:

DELETE https://example.com/tickets/245?userId=12345&userEmail=testuser@example.com&associatedObjectId=78912&associatedObjectType=COMPANY&portalId=9999999&domain=testcompany.com

Com um cabeçalho:

X-HubSpot-Signature: <some base64 string>

Parâmetros de consulta:

• userId: o ID numérico do usuário do cliente que solicita dados.
• userEmail: o endereço de usuário da HubSpot do cliente que solicita dados.
• associatedObjectId: o ID do objeto atual, dependendo do associatedObjectType. Será companyId, dealId, contact vid ou objectId para tíquetes.
• associatedObjectType: o tipo de objeto para o qual o usuário está solicitando dados (contato, empresa, negócio ou tíquete).
• portalId: o ID da conta (também chamado de ID do Hub) do cliente que solicita dados.
• E os valores de qualquer  associatedObjectProperties solicitado. Se uma das propriedades solicitadas for indefinida para o objeto atual, ele não será listado na string de consulta. No exemplo acima, o domínio de propriedade da empresa está incluído.

O cabeçalho X-HubSpot-Signature permite que o integrador verifique se uma solicitação veio do HubSpot. Veja solicitar assinaturas para detalhes.

Exemplo de resposta:

{"message": "Successfully deleted object"}

O HubSpot tentará analisar as respostas aos hooks de ação como JSON e procurar uma propriedade de mensagem. O usuário receberá uma mensagem em caso de sucesso ou falha.

O código de status da resposta de 2XX mostrará uma mensagem de sucesso e 4XX ou 5XX mostrará mensagens de erro.

Tipos de ação

As seções a seguir fornecem detalhes sobre cada tipo de ação que pode ser especificado.

Ações Iframe

Quando um usuário clica em uma ação iframe, uma caixa de diálogo modal com um iframe apontando para o URL fornecido será aberta.

Exemplo de ação iframe:

Definições:

• type: deve ser IFRAME para indicar que essa é uma ação iframe.
• width, height: as dimensões de iframe desejadas.
• uri: a URI aberta no iframe.
• label: o rótulo exibido no menu suspenso de ação.
• associatedObjectProperties: uma lista de propriedades no contato, empresa, negócio ou tíquete associado. Os valores de propriedade do objeto atual serão anexados à URI como parâmetros de consulta ao abrir o iframe.

Sinalizar para o modal fechar

Quando o usuário concluir uma ação do iframe, o diálogo modal deve fechar e retornar o usuário à tela CRM original. Para fechar o modelo de diálogo, o aplicativo pode usar um window.postMessage. As seguintes mensagens são aceitas:

• {"action": "DONE"} - O usuário conclui a ação com sucesso.
• {"action": "CANCEL"} - O usuário cancelou a ação.

Exaemplo: window.parent.postMessage(JSON.stringify({"action": "DONE"}), "*");

Observação: modais iframe acessados por uma ação iframe terá uma largura responsiva. 

Ações do hook de ação

Ações do hook de ação enviam uma solicitação do lado do servidor para um aplicativo. A única UI que um usuário vê para essa ação é uma mensagem de sucesso ou de erro. Este tipo de ação é útil para operações simples que não exigem mais entrada de usuário.

Exemplo de ação de hook de ação:

Definições:

• type: deve ser ACTION_HOOK para indicar que essa é uma ação de hook de ação.
• httpMethod: o método HTTP a usar ao fazer a solicitação. Pode ser GET, POST, PUT, DELETE ou PATCH.
• uri: a URI da solicitação a fazer.
• label: o rótulo para exibir no menu suspenso de ação.
• associatedObjectProperties: uma lista de propriedades no contato, empresa, negócio ou tíquete associado. Se httpMethod for GET ou DELETE, esses valores de propriedade serão adicionados à URI da solicitação como parâmetros de consulta. Caso contrário, eles serão enviados como um corpo de solicitação JSON.

Veja Lidar com hooks de ação para mais detalhes sobre como implementar o endpoint de ação.

Ações de confirmação

As ações de confirmação se comportam como os hooks de ação, exceto que uma caixa de diálogo de confirmação é mostrada para o usuário antes de executar a solicitação do lado do servidor.

Definições:

• type: deve ser ACTION_HOOK para indicar que essa é uma ação de hook de ação.
• httpMethod: o método HTTP a usar ao fazer a solicitação. Pode ser GET, POST, PUT, DELETE ou PATCH.
• uri: a URI da solicitação a fazer.
• label: o rótulo para exibir no menu suspenso de ação.
• associatedObjectProperties: uma lista de propriedades no contato, empresa, negócio ou tíquete associado. Se httpMethod for GET ou DELETE, esses valores de propriedade serão adicionados à URI da solicitação como parâmetros de consulta. Caso contrário, eles serão enviados como um corpo de solicitação JSON.

Veja Lidar com hooks de ação para mais detalhes sobre como implementar o endpoint de ação.

Ações de confirmação

As ações de confirmação se comportam como os hooks de ação, exceto que uma caixa de diálogo de confirmação é mostrada para o usuário antes de executar a solicitação do lado do servidor.

Definições:

• type: deve ser CONFIRMATION_ACTION_HOOK para indicar que essa é uma ação do hook de ação de confirmação.
• httpMethod: o método HTTP a usar ao fazer a solicitação. Pode ser GET, POST, PUT, DELETE ou PATCH.
• uri: a URI da solicitação a fazer.
• label: o rótulo para exibir no menu suspenso de ação.
• associatedObjectProperties: uma lista de propriedades no contato, empresa, negócio ou tíquete associado. Se httpMethod for GET ou DELETE, esses valores de propriedade serão adicionados à URI da solicitação como parâmetros de consulta. Caso contrário, eles serão enviados como um corpo de solicitação JSON.
• confirmationMessage: a mensagem a exibir ao usuário na caixa de diálogo de confirmação.
• confirmButtonText: o texto do botão "OK". Ele é opcional, pois o padrão do texto do botão é “OK”.
• cancelButtonText: texto para o botão "Cancelar". Ele é opcional, pois o padrão do texto do botão é “Cancelar.”

Veja Lidar com hooks de ação para mais detalhes sobre como implementar o endpoint de ação.