Cartões de CRM

Dentro de um aplicativo público, você pode criar cartões de CRM personalizados para exibir informações de outros sistemas nos registros de contatos, empresas, negócios e tickets da HubSpot. Cada aplicativo pode incluir até 25 cartões de CRM.

Observação: os cartões de CRM referenciados neste artigo são diferentes dos cartões personalizados que você pode criar como extensões de interface do usuário com projetos. Os cartões de CRM incluídos neste artigo destinam-se para o uso em aplicativos públicos, não para aplicativos privados criados com projetos.

Exemplo de caso de uso: você está criando uma integração para o Marketplace de aplicativos para o seu software de rastreamento de bugs. Você quer poder expor bugs rastreados em registros de contatos para que os representantes de suporte possam referenciá-los ao trabalhar com clientes. Seu aplicativo pode definir um cartão personalizado que exibe essas informações diretamente no registro de contato do HubSpot.
CRM_Card_1Os cartões podem ser definidos como parte das configurações de recurso do aplicativo. Assim que o aplicativo for instalado e um usuário visualizar os registros do CRM de destino, o HubSpot fará uma solicitação de saída para o aplicativo, recuperará os dados relevantes e os exibirá em um cartão na página de registro. Os apps também podem especificar ações personalizadas que o usuário pode realizar com base nessas informações. Por exemplo, seu aplicativo pode incluir uma ação para abrir um modal para exibir a própria interface do usuário do aplicativo no HubSpot.

CRM_card_diagram

Requisitos do escopo

Para criar cartões de CRM personalizados, seu aplicativo precisa solicitar os escopos de OAuth necessários para modificar os registros de CRM em que seu cartão aparecerá. Por exemplo, para que um cartão do CRM apareça nos registros de contato, o aplicativo deve ter os escopos crm.objects.contacts.read e crm.objects.contacts.write. Se mais tarde precisar remover escopos de objeto do CRM do seu aplicativo, primeiro será necessário excluir todos os cartões existentes para esses tipos de objetos.

Veja a documentação de OAuth para obter mais detalhes sobre os escopos e configurar o URL de autorização para seu aplicativo.

Criar um cartão de CRM

Você pode criar cartões do CRM para o seu aplicativo por meio da API ou editando o aplicativo na sua conta de desenvolvedor. Para saber mais sobre como configurar um cartão por meio da API, confira a guia Endpoints na parte superior do artigo.

Para criar um cartão do CRM usando a interface do usuário da HubSpot:

    • Na sua conta de desenvolvedor da HubSpot, acesse Aplicativos na barra de navegação principal.
    • Selecione o aplicativo no qual deseja adicionar um cartão.
    • No menu da barra lateral esquerda, selecione Cartões do CRM.
    • No canto superior direito, clique emCriar cartão do CRM.
      private-app-create-crm-card

Saiba mais sobre as opções de configuração em cada guia.

Solicitação de dados

Quando um usuário da HubSpot visualiza um registro do CRM no qual o cartão do CRM está ativo, o HubSpot fará uma solicitação de busca de dados para a integração. Essa solicitação é feita para o URL de destino especificado, que inclui um conjunto de parâmetros de consulta padrão, juntamente com parâmetros adicionais que contêm dados de propriedade, conforme especificado nas configurações do cartão. 

private-app-create-crm-card-data-request-tab

  • No campo URL de busca de dados, insira o URL do qual você buscará os dados. Na API, este URL está adicionado ao campo targetUrl

  • Na seção Tipos de registro de destino, clique para ativar os botões para selecionar em quais registos do CRM o cartão será exibido. Em seguida, use os menus suspensos Propriedades enviadas do HubSpot para selecionar as propriedades do HubSpot que serão incluídas como parâmetros de consulta no URL de solicitação. Na API, cada tipo de registro e suas propriedades correspondentes são adicionados como objetos na matriz objectTypes.
// Example data fetch configuration { "title": "New CRM Card", "fetch": { "targetUrl": "https://www.example.com/demo-fetch", "objectTypes": [ { "name": "contacts", "propertiesToSend": [ "firstname", "email", "lastname" ] } ] } ... }

Exemplo de solicitação

A configuração acima faria com que o HubSpot enviasse a solicitação GET da seguinte forma.

https://www.example.com/demo-fetch?userId=12345&userEmail=loggedinuser@hubspot.com&associatedObjectId=53701&associatedObjectType=CONTACT&portalId=987654&firstname=Tim&email=timrobinson@itysl.com&lastname=Robinson
Use this table to describe parameters / fields
ParameterTypeDescription
userId
Default

O ID do usuário do HubSpot que carregou o registo do CRM.

userEmail
Default

O endereço de e-mail do usuário que carregou o registo do CRM.

associatedObjectId
Default

O ID do registo do CRM que foi carregado.

associatedObjectType
Default

O tipo de registo do CRM carregado (por exemplo, contato, empresa, negócio).

portalId
Default

O ID da conta da HubSpot na qual o registro do CRM foi carregado.

firstname
Custom

O primeiro nome do contato, conforme especificado no menu suspenso Propriedades enviadas do HubSpot (no aplicativo) e na matriz propertiesToSend (API).

e-mail
Custom

O endereço de e-mail do contato, conforme especificado no menu suspenso Propriedades enviadas do HubSpot (no aplicativo) e na matriz propertiesToSend (API).

lastname
Custom

O sobrenome do contato, conforme especificado no menu suspenso Propriedades enviadas do HubSpot (no aplicativo) e na matriz propertiesToSend (API).

Observação: as solicitações atingirão o tempo limite após cinco segundos. Nesse tempo, uma conexão deve ser feita dentro de três segundos. 

Exemplo de resposta

Veja abaixo um exemplo de resposta que o integrador pode fornecer para a solicitação acima.

results  array

An array of up to five valid card properties. If more card properties are available for a specific CRM object, your app can link to them.

objectId  number (required)

A unique ID for this object.

title  string (required)

The title of this object.

link  string

The URL that the user can follow to get more details about the object. This property is optional, but if no objects have a link, you should provide a value of null.

created  string (required)

A custom property as defined in the card's settings that denotes the date of the object's creation.

priority  string (required)

A custom property as defined in the card's settings that denotes external ticket's priority level.

actions  array

A list of available actions a user can take.

properties  string

A list of custom properties that aren't defined in the card settings. You can use this list to display a specific object's unique properties. These properties will be shown in the order they're provided, but after the properties defined in the card settings.

settingsAction  object

An iframe action that enables users to update the app's settings. 

primaryAction  object 

The primary action for a record type, typically a creation action.

secondaryActions  array

A list of actions displayed on the card.

// Example response { "results": [ { "objectId": 245, "title": "API-22: APIs working too fast", "link": "http://example.com/1", "created": "2016-09-15", "priority": "HIGH", "project": "API", "description": "Customer reported that the APIs are just running too fast. This is causing a problem in that they're so happy.", "reporter_type": "Account Manager", "status": "In Progress", "ticket_type": "Bug", "updated": "2016-09-28", "actions": [ { "type": "IFRAME", "width": 890, "height": 748, "uri": "https://example.com/edit-iframe-contents", "label": "Edit", "associatedObjectProperties": [] }, { "type": "IFRAME", "width": 890, "height": 748, "uri": "https://example.com/reassign-iframe-contents", "label": "Reassign", "associatedObjectProperties": [] }, { "type": "ACTION_HOOK", "httpMethod": "PUT", "associatedObjectProperties": [], "uri": "https://example.com/tickets/245/resolve", "label": "Resolve" }, { "type": "CONFIRMATION_ACTION_HOOK", "confirmationMessage": "Are you sure you want to delete this ticket?", "confirmButtonText": "Yes", "cancelButtonText": "No", "httpMethod": "DELETE", "associatedObjectProperties": [ "protected_account" ], "uri": "https://example.com/tickets/245", "label": "Delete" } ] }, { "objectId": 988, "title": "API-54: Question about bulk APIs", "link": "http://example.com/2", "created": "2016-08-04", "priority": "HIGH", "project": "API", "reported_by": "ksmith@hubspot.com", "description": "Customer is not able to find documentation about our bulk Contacts APIs.", "reporter_type": "Support Rep", "status": "Resolved", "ticket_type": "Bug", "updated": "2016-09-23", "properties": [ { "label": "Resolved by", "dataType": "EMAIL", "value": "ijones@hubspot.com" }, { "label": "Resolution type", "dataType": "STRING", "value": "Referred to documentation" }, { "label": "Resolution impact", "dataType": "CURRENCY", "value": "94.34", "currencyCode": "GBP" } ], "actions": [ { "type": "IFRAME", "width": 890, "height": 748, "uri": "https://example.com/edit-iframe-contents", "label": "Edit" }, { "type": "CONFIRMATION_ACTION_HOOK", "confirmationMessage": "Are you sure you want to delete this ticket?", "confirmButtonText": "Yes", "cancelButtonText": "No", "httpMethod": "DELETE", "associatedObjectProperties": [ "protected_account" ], "uri": "https://example.com/tickets/245", "label": "Delete" } ] } ], "settingsAction": { "type": "IFRAME", "width": 890, "height": 748, "uri": "https://example.com/settings-iframe-contents", "label": "Settings" }, "primaryAction": { "type": "IFRAME", "width": 890, "height": 748, "uri": "https://example.com/create-iframe-contents", "label": "Create Ticket" } }

Solicitar assinaturas

Para garantir que as solicitações venham realmente do HubSpot, o seguinte cabeçalho de solicitação está incluído. Esse cabeçalho conterá um hash do segredo para o seu aplicativo e os detalhes da solicitação. 

X-HubSpot-Signature: <some base64 string>

Para verificar essa assinatura, execute as seguintes etapas:

  1. Crie uma string que concatene o seguinte: <app secret> + <HTTP method> + <URL> + <request body> (if present).
  2. Crie um hash SHA-256 da string resultante.
  3. Compare o valor do hash à assinatura. Se forem iguais, a solicitação passou na validação. Se os valores não corresponderem, a solicitação pode ter sido adulterada em trânsito ou alguém pode estar falsificando solicitações para seu endpoint.

Propriedades do cartão

Na guia Propriedades do cartão, defina quaisquer propriedades personalizadas que você deseja que o HubSpot exiba no cartão do CRM. Depois de definidas, a integração poderá preencher essas propriedades, incluindo-as em sua resposta.

    • Clique em Adicionar propriedade para adicionar uma nova propriedade para ser exibida pelo cartão. A carga útil fornecida em resposta à chamada de busca de dados deve conter valores para todas essas propriedades.
    • No painel direito, defina o nome exclusivo da propriedade, o rótulo de exibição e o tipo de dados. Você pode selecionar entre os seguintes tipos: MoedaDataData/horaE-mailLinkNuméricoStatusStringSaiba mais sobre como usar os tipos de propriedade de extensão.
    • Clique em Adicionar para salvar a propriedade.
      private-app-create-crm-card-card-properties-tab

Quando o HubSpot enviar sua solicitação de dados, a integração poderá fornecer valores para essas propriedades em sua resposta junto com outros valores em cada objeto nos results. Além das propriedades configuradas nesta guia, a integração também pode incluir suas próprias propriedades personalizadas sem precisar que elas sejam definidas nas configurações do cartão.

Por exemplo, na resposta abaixo, created e priority são ambos definidos na guia Propriedades do cartão, enquanto a matriz properties envia suas próprias definições e valores de propriedade. Essas propriedades específicas do objeto devem ser definidas por objeto.

// Example object within a response { "objectId": 988, "title": "API-54: Question about bulk APIs", "link": "http://example.com/2", "created": "2016-08-04", "priority": "HIGH", "properties": [ { "label": "Resolved by", "dataType": "EMAIL", "value": "ijones@hubspot.com" }, { "label": "Resolution type", "dataType": "STRING", "value": "Referred to documentation" }, { "label": "Resolution impact", "dataType": "CURRENCY", "value": "94.34", "currencyCode": "GBP" } ], "actions": [ ... ] }

Ao enviar propriedades personalizadas, o campo dataType para cada propriedade pode ser definido como um de: CURRENCY, DATE, DATETIME, EMAIL, LINK, NUMERIC, STATUS, STRING. Dependendo do tipo de propriedade, a integração pode precisar fornecer campos adicionais. Saiba mais sobre cada tipo de propriedade.  

Propriedades da moeda

As propriedades de CURRENCY devem incluir um currencyCode, que precisa ser um código ISO 4217 válido. Isso garantirá que o usuário veja o símbolo da moeda e a formatação numérica corretos.

// Example custom currency property { "results": [ { "properties": [ { "label": "Resolution impact", "dataType": "CURRENCY", "value": "94.34", "currencyCode": "GBP" } ] } ] }

Propriedades de data

As propriedades de DATE devem estar no formato yyyy-mm-dd. Estas propriedades serão exibidas em um formato apropriado à localidade do usuário. Se precisar incluir um carimbo de data/hora, use uma propriedade de DATETIME.

// Example custom date property { "results": [ { "properties": [ { "label": "Date", "dataType": "DATE", "value": "2023-10-13" } ] } ] }

Datetime properties

DATETIME properties indicate a specific time and must be provided as milliseconds since epoch. These properties will be displayed in a format appropriate to the user's locale.

// Example custom datetime property { "results": [ { "properties": [ { "label": "Timestamp", "dataType": "DATETIME", "value": "1697233678777" } ] } ] }

Email properties

EMAIL properties are for values that contain an email address. These properties will be displayed as mailto links.

// Example custom email property { "results": [ { "properties": [ { "label": "Email address", "dataType": "EMAIL", "value": "hobbes.baron@gmail.com" } ] } ] }

LINK properties display hyperlinks and open in a new window. You can specify a linkLabel, otherwise the URL itself will be displayed. 

// Example custom link property { "results": [ { "properties": [ { "label": "Link property", "dataType": "LINK", "value": "https://www.hubspot.com", "linkLabel": "Test link" } ] } ] }

Numeric properties

NUMERIC properties display numbers. 

// Example custom datetime property { "results": [ { "properties": [ { "label": "Number", "dataType": "NUMERIC", "value": "123.45" } ] } ] }

Status properties

STATUS properties display as colored indicators. To define a status property, the integration must provide an optionType that describes the possible statuses. Statuses include:

  • DEFAULT: Grey
  • SUCCESS: Green
  • WARNING: Yellow
  • DANGER: Red
  • INFO: Blue
// Example custom datetime property { "results": [ { "properties": [ { "label": "Status", "dataType": "STATUS", "value": "Errors occurring", "optionType": "DANGER" } ] } ] }

String properties

STRING properties display text.

// Example custom datetime property { "results": [ { "properties": [ { "label": "First name", "dataType": "STRING", "value": "Tim Robinson" } ] } ] }

Custom actions

Na guia Ações personalizadas, você pode definir os URLs base que serão solicitados quando um usuário clicar em um botão de ação. Você pode incluir vários URLs de ação para várias ações no seu cartão do CRM. As ações do cartão devem chamar um endpoint especificado nesta guia.
private-app-create-crm-card-custom-actions-tabAs solicitações incluirão um cabeçalho X-HubSpot-Signature. Consulte solicitar assinaturas para obter mais informações.

Os URLs de ação são acessados no campo uri em uma ação. Semelhante à solicitação de busca de dados, os hooks de ação incluirão um conjunto padrão de parâmetros de consulta. Você pode incluir outros parâmetros de consulta, adicionando um campo associatedObjectProperties na ação.

A resposta irá variar dependendo do tipo de ação. Saiba mais sobre os tipos de ação.

Action types

Iframe actions

IFRAME actions will open a modal containing an iframe pointing at the provided URL. 

// Example iframe action { "type": "IFRAME", "width": 890, "height": 748, "uri": "https://example.com/iframe-contents", "label": "Edit", "associatedObjectProperties": [ "some_crm_property" ] }

When the user is done completing an action inside the iframe, the modal should close and return the user to the CRM record they started from. To close the modal, the integration can use window.postMessage to signal to the CRM that the user is done. The following messages are accepted:

  • {"action": "DONE"}: the user has successfully competed the action.
  • {"action": "CANCEL"}: the user has canceled the action.
// Example iframe close message window.parent.postMessage(JSON.stringify({"action": "DONE"}), "*");

Action hook actions

ACTION_HOOK actions send a server-side request to the integrator. The only UI a users sees for this action is a success or error message. This type of action is useful for simple operations that require no further input from the user.

// Example action hook action { "type": "ACTION_HOOK", "httpMethod": "POST", "uri": "https://example.com/action-hook", "label": "Example action", "associatedObjectProperties": [ "some_crm_property" ] }

The httpMethod can be set to  GET, POST, PUT, DELETE, or PATCH If using GET or DELETE, the associatedObjectProperties values will be appended to the request URL as query parameters. Otherwise, the properties will be sent in the request body.

// Example iframe close message window.parent.postMessage(JSON.stringify({"action": "DONE"}), "*");

Confirmation actions

As ações CONFIRMATION_ACTION_HOOK se comportam como as ações ACTION_HOOK, 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.

// Example action hook action { "type": "CONFIRMATION_ACTION_HOOK", "httpMethod": "POST", "uri": "https://example.com/action-hook", "label": "Example action", "associatedObjectProperties": [ "some_crm_property" ], "confirmationMessage": "Are you sure you want to run example action?", "confirmButtonText": "Yes", "cancelButtonText": "No" }

O httpMethod pode ser definido como  GET, POST, PUT, DELETE ou PATCH Se estiver usando GET ou DELETE, os valores de associatedObjectProperties serão anexados ao URL da solicitação como parâmetros de consulta. Caso contrário, as propriedades serão enviadas no corpo da solicitação.


Este artigo foi útil?
Este formulário deve ser usado apenas para fazer comentários sobre esses artigos. Saiba como obter ajuda para usar a HubSpot..