Cartes CRM

Dans une application publique, vous pouvez créer des cartes CRM personnalisées pour afficher des informations provenant d'autres systèmes sur les fiche d'informations de contacts, d'entreprises, de transactions et de tickets HubSpot. Chaque application peut inclure jusqu'à 25 cartes CRM.

Remarque : les cartes CRM référencées dans cet article sont différentes des cartes personnalisées que vous pouvez créer en tant qu'extensions d'interface utilisateur avec des projets. Les cartes CRM incluses dans cet article sont destinées à être utilisées avec des applications publiques, et non des applications privées créées avec des projets.

Exemple de cas d'utilisation : vous créez une intégration pour le marketplace des applications pour votre logiciel de suivi des bogues. Vous voulez faire apparaître les bogues suivis sur les fiches d'informations de contacts afin que les conseillers du support puissent les référencer lorsque vous travaillez avec les clients. Votre application peut définir une carte personnalisée qui affiche ces informations sur la fiche d'informations de contact HubSpot.
CRM_Card_1Les cartes peuvent être définies dans les paramètres de fonctionnalité de votre application. Une fois que l'application est installée et qu'un utilisateur consulte les fiches d'informations du CRM cibles, HubSpot effectue une demande sortante à l'application, récupère les données pertinentes et les affiche dans une carte sur la page de la fiche d'informations. Les applications peuvent également spécifier des actions personnalisées que l'utilisateur peut effectuer en fonction de ces informations. Par exemple, votre application peut inclure une action qui ouvre une fenêtre glissante pour afficher sa propre interface utilisateur dans HubSpot.

CRM_card_diagram

Exigences des domaines

Pour créer des cartes CRM personnalisées, votre application doit demander les domaines OAuth requis pour modifier les fiches d'informations de CRM dans lesquelles votre carte apparaîtra. Par exemple, pour qu'une carte CRM apparaisse sur les fiches d'informations de contacts, l'application doit avoir les paramètres crm.objects.contacts.read et crm.objects.contacts.write. Si vous devez supprimer ultérieurement les paramètres d'objets CRM de votre application, vous devrez d'abord supprimer toutes les cartes existantes pour ces types d'objets.

Consultez la documentation OAuth pour plus de détails sur les domaines et la configuration de l'URL d'autorisation pour votre application.

Créer une carte CRM

Vous pouvez créer des cartes CRM pour votre application via l'API ou en modifiant votre application dans votre compte de développeur. Pour en savoir plus sur la configuration d'une carte via l'API, consultez l'onglet Points de terminaison en haut de l'article.

Pour créer une carte CRM à l'aide de l'interface utilisateur de HubSpot :

    • Dans votre compte de développeur de HubSpot, accédez à Apps dans la navigation principale.
    • Sélectionnez l'application à laquelle vous souhaitez ajouter une carte.
    • Dans le menu latéral de gauche, sélectionnez Cartes CRM.
    • Cliquez sur Créer une carte CRM dans l'angle supérieur droit.
      private-app-create-crm-card

Découvrez ci-dessous les options de configuration dans chaque onglet.

Demande de données

Lorsqu'un utilisateur HubSpot affiche une fiche d'informations CRM dans laquelle la carte CRM est activée, HubSpot formulera une demande de récupération de données à l'intégration. Cette demande est faite à l'URL cible spécifiée, qui comprend un ensemble de paramètres de requête par défaut, ainsi que des paramètres supplémentaires contenant des données de propriété telles que spécifiées dans les paramètres de la carte. 

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

  • Dans le champ URL de récupération des données, saisissez l'URL à partir de laquelle vous allez récupérer les données. Dans l'API, cette URL est ajoutée au champ targetUrl

  • Dans la section Types de fiches d'informations cibles, cliquez pour activer les options afin de sélectionner les fiches d'informations CRM dans lesquelles la carte apparaîtra. Ensuite, utilisez les menus déroulants Propriétés envoyées par HubSpot pour sélectionner les propriétés HubSpot qui seront incluses en tant que paramètres de requête dans l'URL de la requête. Dans l'API, chaque type de fiche d'informations et ses propriétés correspondantes sont ajoutés en tant qu'objets dans le tableau objectTypes.
// Example data fetch configuration { "title": "New CRM Card", "fetch": { "targetUrl": "https://www.example.com/demo-fetch", "objectTypes": [ { "name": "contacts", "propertiesToSend": [ "firstname", "email", "lastname" ] } ] } ... }

Exemple de demande

La configuration ci-dessus entraînerait l'envoi par HubSpot de sa requête GET comme suit.

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

L'ID de l'utilisateur HubSpot qui a chargé la fiche d'informations CRM.

userEmail
Default

L'adresse e-mail de l'utilisateur qui a chargé la fiche d'informations CRM.

associatedObjectId
Default

L'ID de la fiche d'informations CRM qui a été chargée.

associatedObjectType
Default

Le type de fiche d'informations CRM qui a été chargée (par exemple, contact, entreprise, transaction).

portalId
Default

L'ID du compte HubSpot dans lequel la fiche d'informations CRM a été chargée.

firstname
Custom

Le prénom du contact, tel que spécifié dans le menu déroulant Propriétés envoyées par HubSpot (dans l'application) et le tableau propertiesToSend (API).

type de client
Custom

L'adresse e-mail du contact, tel que spécifié dans le menu déroulant Propriétés envoyées par HubSpot (dans l'application) et le tableau propertiesToSend (API).

lastname
Custom

Le nom du contact, tel que spécifié dans le menu déroulant Propriétés envoyées par HubSpot (dans l'application) et le tableau propertiesToSend (API).

Remarque : les requêtes expireront au bout de cinq secondes. Dans ce délai, la connexion doit être effectuée en trois secondes. 

Exemple de réponse

Vous trouverez ci-dessous un exemple de réponse que l'intégrateur pourrait fournir à la requête ci-dessus.

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" } }

Signatures de demande

Pour s'assurer que les requêtes proviennent bien de HubSpot, l'en-tête de requête suivant est inclus. Cet en-tête contiendra un hachage du secret de l'application pour votre application ainsi que les détails de la requête. 

X-HubSpot-Signature: <some base64 string>

Pour vérifier cette signature, effectuez les étapes suivantes :

  1. Créez une chaîne qui regroupe les éléments suivants : <app secret> + <HTTP method> + <URL> + <request body> (if present).
  2. Créez un hachage SHA-256 de la chaîne résultante.
  3. Comparez la valeur de hachage à la signature. Si elle est égale, la requête a été validée. Si elle ne correspond pas, cette requête peut avoir été modifiée en transit ou quelqu'un peut usurper les demandes à votre point de terminaison.

Propriétés de la carte

Dans l'onglet Propriétés de la carte, définissez toutes les propriétés personnalisées que vous souhaitez que HubSpot affiche sur la carte CRM. Une fois définie, l'intégration peut remplir ces propriétés en les incluant dans sa réponse.

    • Cliquez sur Ajouter une propriété pour ajouter une nouvelle propriété à afficher sur la carte. La charge utile que vous fournissez en réponse à l'appel d'extraction de données doit contenir des valeurs pour toutes ces propriétés.
    • Dans le panneau de droite, définissez le nom unique, le libellé d'affichage et le type de données de la propriété. Vous pouvez choisir parmi les types suivants : DeviseDateDatetimeE-mailLienNumériqueStatut et ChaîneDécouvrez-en davantage sur l'utilisation des types de propriétés d'extension.
    • Cliquez sur Ajouter pour enregistrer la propriété.
      private-app-create-crm-card-card-properties-tab

Lorsque HubSpot envoie sa requête de données, l'intégration peut fournir des valeurs pour ces propriétés dans sa réponse ainsi que d'autres valeurs dans chaque objet dans la propriété results. Outre les propriétés configurées dans cet onglet, l'intégration peut également inclure ses propres propriétés personnalisées sans avoir besoin de les définir dans les paramètres de la carte.

Par exemple, dans la réponse ci-dessous, les paramètres created et priority sont tous deux définis dans l'onglet Propriétés de la carte, tandis que le tableau properties envoie ses propres définitions et valeurs de propriétés. Ces propriétés spécifiques à l'objet doivent être définies par objet.

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

Lors de l'envoi de propriétés personnalisées, le champ dataType de chaque propriété peut être défini sur l'un des éléments suivants : CURRENCY, DATE, DATETIME, EMAIL, LINK, NUMERIC, STATUS, STRING. Selon le type de propriété, l'intégration peut devoir fournir des champs supplémentaires. Découvrez-en davantage ci-dessous sur chaque type de propriété.

Propriétés de devise

Les propriétés CURRENCY doivent inclure un paramètre currencyCode, qui doit être un code ISO 4217 valide. Cela garantira que l'utilisateur voit le symbole de devise et la mise en forme des chiffres corrects.

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

Propriétés de date

Les propriétés DATE doivent être au format aaaa-mm-jj. Ces propriétés seront affichées dans un format correspondant aux paramètres régionaux de l'utilisateur. Si vous devez inclure un horodatage, vous devez plutôt utiliser une propriété 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

Dans l'onglet Actions personnalisées, vous pouvez définir les URL de base qui seront demandées lorsqu'un utilisateur clique sur un bouton d'action. Vous pouvez inclure plusieurs URL d'action pour diverses actions dans votre carte CRM. Les actions de carte doivent appeler un point de terminaison spécifié dans cet onglet.
private-app-create-crm-card-custom-actions-tabLes demandes incluront un en-tête X-HubSpot-Signature. Consultez les signatures de requête pour plus d'informations.

Les URL d'action sont accessibles dans le champ uri d'une action. À l'instar de la demande de récupération de données, les hooks d'action incluront un ensemble par défaut de paramètres de requête. Vous pouvez inclure d'autres paramètres de requête en incluant un champ AssociatedObjectProperties dans l'action.

La réponse variera en fonction du type d'action. Découvrez-en davantage ci-dessous sur les types d'actions.

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

Les actions CONFIRMATION_ACTION_HOOK ont un comportement identique à celui des actions ACTION_HOOK, à l'exception d'une boîte de dialogue de confirmation affichée pour l'utilisateur avant l'exécution de la demande côté serveur.

// 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" }

La propriété httpMethod peut être définie sur  GET, POST, PUT, DELETE ou PATCH Si vous utilisez la propriété GET ou DELETE, les valeurs AssociatedObjectProperties seront ajoutées à l'URL de la requête en tant que paramètres de requête. Dans le cas contraire, les propriétés seront envoyées dans le corps de la requête.


Cet article vous a-t-il été utile ?
Ce formulaire est destiné à recueillir les avis sur la documentation pour les développeurs. Si vous souhaitez faire part de votre avis sur les produits HubSpot, veuillez le partager sur le forum des idéesde la communauté.