Cartes CRM

Demandes de récupération de données

Comme mentionné dans l'onglet Vue d'ensemble, HubSpot effectue une demande de récupération de données à votre application lorsqu'un utilisateur consulte la fiche d'informations de CRM associée. Ces demandes sont envoyées à l'élément fetch/targetUrl spécifié de la carte avec une charge utile fournissant des informations pour la fiche d'informations de CRM associée.

Les réponses peuvent contenir jusqu'à 5 propriétés de carte. Si plusieurs propriétés de carte sont disponibles pour un objet de CRM spécifique, votre application peut rediriger vers celles-ci.

Notez que la demande expirera après 5 secondes. Dans ce délai, la connexion doit être effectuée en 3 secondes. 

Exemple de demande de récupération de données :

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

Avec un en-tête :

X-HubSpot-Signature: <some base64 string>

L'en-tête X-HubSpot-Signature  permet de vérifier qu'une demande provient bien de HubSpot. Consultez les signatures de demande pour plus d'informations.

Paramètres de demande :

• userId : l'ID d'utilisateur numérique du client qui demande les données.
• userEmail : l'adresse HubSpot de l'utilisateur qui demande les données.
• portalId : l'ID de compte HubSpot du client qui demande les données. Le compte et le portail sont utilisés de manière interchangeable. 
• associatedObjectId : l'ID de l'objet actuel, en fonction de associatedObjectType. Il s'agira de companyId, dealId, contact vID ou objectId pour les tickets.
• associatedObjectType : le type d'objet pour lequel l'utilisateur demande des données (contact, company, deal ou ticket). Il s'agira de l'un des éléments associatedHubSpotObjectTypes fourni pour ce type de fiche d'informations.
• Et les valeurs pour l'un des éléments associatedHubSpotObjectTypeProperties demandés. Si l'une des propriétés de demande n'est pas définie pour l'objet actuel, elle ne sera pas répertoriée dans la chaîne de demande. Dans l'exemple ci-dessus, le domaine de propriété d'entreprise est inclus. Les propriétés de demande peuvent être définies dans l'interface utilisateur des paramètres de l'application, comme vous pouvez le voir dans la capture d'écran ci-dessous : 

Exemple de réponse :

Définitions :

• results : une liste comprenant jusqu'à 5 propriétés de carte valides. 
• results[].objectId : un ID unique pour cet objet. Cette propriété est obligatoire.
• results[].title : le titre de cet objet. Cette propriété est obligatoire.
• results[].link : l'URI que l'utilisateur peut suivre pour obtenir plus de détails sur cet objet. Cette propriété est facultative, mais si tous les objets n'ont pas de lien, vous devez fournir une valeur nulle.
• results[].properties : une liste des propriétés personnalisées qui ne sont pas définies dans les paramètres de la carte. Vous pouvez utiliser cette liste pour afficher les propriétés uniques d'un objet spécifique. Ces propriétés seront affichées dans l'ordre dans lequel elles sont fournies, mais après les propriétés définies dans les paramètres de la carte. Cette propriété est facultative.
• results[].actions : une liste des actions disponibles qu'un utilisateur peut effectuer pour cet objet. Consultez les types d'action pour obtenir des détails sur les actions. Cette propriété est facultative.
• totalCount : le nombre total de propriétés de carte disponibles, s'il y a plus de 5 propriétés associées à l'objet de CRM demandé. Cette propriété est facultative.
• allItemsLink : un URI affichant toutes les propriétés de carte associées à l'objet de CRM demandé, s'il y en a plus de 5. Cette propriété est facultative.
• itemLabel : le libellé à utiliser dans le lien Afficher plus, par exemple Afficher plus de tickets. Cette propriété est facultative et si elle n'est pas fournie, elle sera définie par défaut sur le titre de la carte.
• settingsAction : une action d'iFrame donnant aux utilisateurs la possibilité de mettre à jour les paramètres de l'application. Consultez les types d'action pour obtenir des détails sur les actions. Cette propriété est facultative.
• primaryAction : l'action principale pour un type de fiche d'informations, généralement une action de création. Consultez les types d'action pour obtenir des détails sur les actions. Cette propriété est facultative.
• secondaryActions : une liste d'actions affichées au niveau de la carte. Consultez les types d'action pour obtenir des détails sur les actions. Cette propriété est facultative.

Outre les propriétés ci-dessus, l'intégrateur peut fournir des valeurs pour les propriétés définies dans les paramètres de la carte. Dans l'exemple ci-dessus, la propriété JSON créée

"created":"2016-08-04"

fournit une valeur pour cet objet pour la propriété created prédéfinie.

Gérer les hooks d'action 

Lorsqu'un utilisateur clique sur une action définie comme un hook d'action, HubSpot envoie une demande à l'aide de la méthode URI et HTTP indiquée dans la définition d'action.

Exemple de demande :

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

Avec un en-tête :

X-HubSpot-Signature: <some base64 string>

Paramètres de demande :

• userId : l'ID d'utilisateur numérique du client qui demande les données.
• userEmail : l'adresse utilisateur HubSpot du client qui demande les données.
• associatedObjectId : l'ID de l'objet actuel, en fonction de associatedObjectType. Il s'agira de companyId, dealId, contact vID ou objectId pour les tickets.
• associatedObjectType : le type d'objet pour lequel l'utilisateur demande des données (contact, company, deal ou ticket).
• portalId : l'ID de compte (également appelé HubID) du client qui demande les données.
• Et les valeurs pour l'un des éléments associatedObjectProperties demandés. Si l'une des propriétés de demande n'est pas définie pour l'objet actuel, elle ne sera pas répertoriée dans la chaîne de demande. Dans l'exemple ci-dessus, le domaine de propriété d'entreprise est inclus.

L'en-tête X-HubSpot-Signature permet à l'intégrateur de vérifier qu'une demande provient bien de HubSpot. Consultez les signatures de demande pour plus d'informations.

Exemple de réponse :

{"message": "Successfully deleted object"}

HubSpot essaiera d'analyser les réponses aux hooks d'action en tant que JSON et recherchera une propriété de message. L'utilisateur recevra un message de réussite ou d'échec.

Le code de statut de réponse 2XX affichera un message de réussite et 4XX ou 5XX affichera un message d'erreur.

Types d'action

Les sections suivantes fournissent des informations sur chaque type d'action qui peut être spécifié.

Actions d'iFrame

Lorsqu'un utilisateur clique sur une action d'iFrame, une boîte de dialogue modale avec un iFrame pointant sur l'URL fournie sera ouverte.

Exemple d'iFrame :

Définitions :

• type : doit être IFRAME pour indiquer qu'il s'agit d'une action d'iFrame.
• width, height : les dimensions souhaitées de l'iFrame.
• uri : l'URI ouvert dans l'iFrame.
• label : le libellé affiché dans le menu déroulant des actions.
• associatedObjectProperties : Une liste des propriétés sur le contact, l'entreprise, la transaction ou le ticket associé(e). Les valeurs de propriété pour l'objet actuel seront ajoutées à l'URI en tant que paramètres de demande lors de l'ouverture de l'iFrame.

Signaler la fermeture de la fenêtre modale

Lorsque l'utilisateur finalise une action d'iFrame, la fenêtre modale doit se fermer et rediriger l'utilisateur vers l'écran de CRM initial. Pour fermer la boîte de dialogue modale, l'application peut utiliser window.postMessage. Les messages suivants sont acceptés :

• {"action": "DONE"} - L'utilisateur a correctement finalisé l'action.
• {"action": "CANCEL"} - L'utilisateur a annulé l'action.

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

Remarque : les fenêtres modales d'iFrame consultées via une action d'iFrame auront une largeur adaptable. 

Actions de hook d'action

Les actions de hook d'action envoient une demande côté serveur à une application. La seule interface utilisateur qu'un utilisateur voit pour cette action est un message de réussite ou d'erreur. Ce type d'action est utile pour des opérations simples qui ne nécessitent pas d'entrée utilisateur supplémentaire.

Exemple d'action de hook d'action :

Définitions :

• type : doit être ACTION_HOOK pour indiquer qu'il s'agit d'une action de hook d'action.
• httpMethod : la méthode HTTP à utiliser lors de la demande. Cela peut être GET, POST, PUT, DELETE ou PATCH.
• uri : l'URI de la demande à effectuer.
• label : le libellé à afficher dans le menu déroulant des actions.
• associatedObjectProperties : Une liste des propriétés sur le contact, l'entreprise, la transaction ou le ticket associé(e). Si httpMethod est GET ou DELETE, ces valeurs de propriété seront ajoutées à l'URI de la demande comme paramètres de demande. Autrement, elles seront envoyées en tant que corps de demande JSON.

Consultez Gérer les hooks d'action pour plus de détails sur la mise en œuvre du point de terminaison d'action.

Actions de confirmation

Les actions de confirmation ont un comportement identique à celui des hooks d'action, à 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.

Définitions :

• type : doit être ACTION_HOOK pour indiquer qu'il s'agit d'une action de hook d'action.
• httpMethod : la méthode HTTP à utiliser lors de la demande. Cela peut être GET, POST, PUT, DELETE ou PATCH.
• uri : l'URI de la demande à effectuer.
• label : le libellé à afficher dans le menu déroulant des actions.
• associatedObjectProperties : Une liste des propriétés sur le contact, l'entreprise, la transaction ou le ticket associé(e). Si httpMethod est GET ou DELETE, ces valeurs de propriété seront ajoutées à l'URI de la demande comme paramètres de demande. Autrement, elles seront envoyées en tant que corps de demande JSON.

Consultez Gérer les hooks d'action pour plus de détails sur la mise en œuvre du point de terminaison d'action.

Actions de confirmation

Les actions de confirmation ont un comportement identique à celui des hooks d'action, à 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.

Définitions :

• type : doit être CONFIRMATION_ACTION_HOOK pour indiquer qu'il s'agit d'une action de hook d'action de confirmation.
• httpMethod : la méthode HTTP à utiliser lors de la demande. Cela peut être GET, POST, PUT, DELETE ou PATCH.
• uri : l'URI de la demande à effectuer.
• label : le libellé à afficher dans le menu déroulant des actions.
• associatedObjectProperties : Une liste des propriétés sur le contact, l'entreprise, la transaction ou le ticket associé(e). Si httpMethod est GET ou DELETE, ces valeurs de propriété seront ajoutées à l'URI de la demande comme paramètres de demande. Autrement, elles seront envoyées en tant que corps de demande JSON.
• confirmationMessage : le message à afficher à l'utilisateur dans la boîte de dialogue de confirmation.
• confirmButtonText : le texte du bouton OK. Il est facultatif, car le texte de bouton sera par défaut défini sur « OK ».
• cancelButtonText : le texte du bouton Annuler. Il est facultatif, car le texte de bouton sera par défaut défini sur « Annuler ».

Consultez Gérer les hooks d'action pour plus de détails sur la mise en œuvre du point de terminaison d'action.