Comment utiliser les formulaires avec jQuery ?

Lorsque vous manipulez des valeurs de saisie de formulaire via val() ou prop(), vous devez déclencher un événement de modification avec change() ou trigger('change') pour enregistrer correctement la modification.

Étant donné que les formulaires HubSpot sont restitués après la création du DOM, vous devez déclencher la manipulation après le chargement de la fenêtre ou modifier l'intégration pour utiliser le paramètre onFormReady.

Update fields when page finishes loading: $(window).load(function(){ $('input[value="checkbox_1"]').prop('checked', true).change(); $('input[name="firstname"]').val('Brian').change(); }); Modified embed code to update fields when form builds: hbspt.forms.create({ portalId: 'XXXXXX', formId: 'aa8b5b4a-62ac-461b-a387-XXXXXXXXXXX', onFormReady: function($form, ctx){ $('input[value="checkbox_1"]').prop('checked', true).change(); $('input[name="firstname"]').val('Brian').change(); } });

Comment formater des horodatages pour les API de HubSpot ?

Les valeurs horaires seront représentées au format ISO 8601 dans les réponses, mais les API accepteront l'un ou l'autre des deux formats pour les valeurs de date et d'heure :
  • Chaîne formatée conformément à la norme ISO 8601 : selon le type de données, il s'agira de l'un de ces deux formats différents :
    • Pour les valeurs qui indiquent une date spécifique, le format de date complet sera utilisé : AAAA-MM-JJ (par exemple, 2020-02-29)
    • Pour les valeurs qui indiquent une date et une heure spécifiques, les données complètes ainsi que les heures, les minutes, les secondes et une fraction décimale de seconde seront utilisées : AAAA-MM-JJThh:mm:ss.sTZD (par exemple, 2020-02-29T03:30:17.000Z). Toutes les heures sont définies selon le fuseau horaire UTC afin que les valeurs utilisent toujours le désignateur UTC « Z ».
  • Horodatage UNIX en millisecondes : valeurs d'horodatage en millisecondes, qui sont représentées en temps UTC. Par exemple, la valeur de l'horodatage 1427997766000 se traduit par 2 avr 2015 18:02:46 UTC ou 2 avril 2015, 2:02:46 PM EDT (heure avancée de l'Est).

Propriétés de date et d'heure dans le CRM de HubSpot

HubSpot dispose de deux types de propriétés d'objet de CRM pour stocker des temps : date et datetime.

  • Les propriétés de date (y compris les propriétés de sélecteur de date créées dans HubSpot) stockent la date, mais pas l'heure. Les propriétés de date affichent la date à laquelle elles sont définies, quelle que soit la définition du fuseau horaire du compte ou de l'utilisateur. Pour les valeurs depropriété de date, il est recommandé d'utiliser le format de date complète ISO 8601. Si vous utilisez le format d'horodatage UNIX, vous devez utiliser un horodatage EPOCH en millisecondes (autrement dit, la valeur doit être définie sur minuit UTC pour la date). Par exemple, pour représenter le 1er mai 2015 dans l'un ou l'autre format :
    • IOS 8601 : 2015-05-01
    • Horodatage EPOCH en millisecondes : 1430438400000

Remarque : si vous utilisez un horodatage Unix pour une propriété de date et que vous essayez de définir une valeur qui ne correspond pas minuit UTC, une erreur sera renvoyée.

  • Les propriétés datetime tockent à la fois la date et l'heure. L'un ou l'autre format d'horodatage sera accepté. Dans HubSpot, les propriétés datetime sont affichées en fonction du fuseau horaire de l'utilisateur. Ainsi, la valeur sera convertie selon le fuseau horaire local de l'utilisateur. Étant donné que les propriétés de sélecteur de dates créées dans HubSpot sont créées en tant que propriétés de date, la seule façon de créer une propriété datetime consiste à utiliser les API. Si votre intégration doit stocker des heures spécifiques, vous pouvez créer des propriétés datetime personnalisées à l'aide des points de terminaison de propriété.

Que dois-je savoir concernant les messages d'erreur d'API ?

Sauf mention contraire, la plupart des points de terminaison de HubSpot renverront une réponse 200 OK en cas de réussite. Tous les points de terminaison qui renvoient un code de statut différent indiqueront la réponse renvoyée dans leurs documentations respectives.

En outre, HubSpot propose plusieurs réponses d'erreur communes à plusieurs API :

  • 401 Unauthorized - Renvoyée lorsque l'authentification est non valide. Consultez notre présentation de l'authentification pour plus de détails sur l'authentification des demandes d'API.
  • 403 Forbidden - Renvoyée lorsque l'authentification fournie ne possède pas les autorisations nécessaires pour accéder à l'URL spécifique. Par exemple, un jeton OAuth qui dispose uniquement d'un accès au contenu recevra une réponse 403 lors de l'accès à l'API de transactions (qui nécessite l'accès aux contacts).
  • 429 Too many requests - Renvoyée lorsque votre compte ou application dépasse ses limites quant aux API. Pour en savoir plus sur ces limites, cliquez ici.
  • 502/504 timeouts - HubSpot dispose de limites de traitement afin d'empêcher une dégradation des performances pour un client. Ces réponses indiquent que ces limites ont été atteintes. Vous ne verrez normalement que les réponses d'expiration lorsque vous effectuez un grand nombre de demandes sur une période prolongée. Si vous obtenez l'une de ces réponses, vous devez suspendre vos demandes pendant quelques secondes, puis réessayer.

Outre ces erreurs générales, les réponses d'erreur de HubSpot sont conçues pour être concises et lisibles. La plupart des points de terminaison ne renvoient pas les codes d'erreur, mais une réponse JSON avec des détails sur l'erreur. Plus de détails concernant les erreurs spécifiques à chaque point de terminaison sont disponibles sur les pages de documentation des points de terminaison.

Remarque : les champs dans l'exemple de réponse ci-dessous doivent être traités comme facultatifs dans n'importe quelle analyse d'erreur. Les champs spécifiques inclus peuvent varier selon les API. Toute analyse d'erreur doit permettre l'absence de champs spécifiques de la réponse.

{"status":"error","message":"This will be a human readable message with details about the error.","errors":[{"message":"This will be a message with additional details about the error","in":"name"}],"category":"VALIDATION_ERROR","correlationId":"a43683b0-5717-4ceb-80b4-104d02915d8c"}

Les API de HubSpot prennent-elles en charge les demandes CORS/AJAX ?

En règle générale, les API de HubSpot ne prennent pas en charge les demandes cross-origin AJAX (CORS). Effectuer la demande côté client à l'aide de JavaScript exposerait l'authentification que vous utilisez pour la demande. Pour utiliser JavaScript/AJAX, vous devrez effectuer la demande (à l'exclusion de toute authentification) à un serveur externe qui pourrait ensuite ajouter l'authentification nécessaire et effectuer les demandes aux API de HubSpot côté serveur.

Les exceptions à cette règle sont :

Comment les adresses e-mail sont-elles vérifiées par HubSpot ?

HubSpot vérifie les adresses e-mail utilisées pour tout processus qui crée ou met à jour une fiche d'informations de contact. Cela inclut l'utilisation des points de terminaison des contacts pour créer ou mettre à jour un contact ainsi que les soumissions de formulaires ou les événements.

Ces processus ne vérifient pas la validité de l'adresse e-mail elle-même (comme le ferait un formulaire intégré), mais plutôt son format. En plus de la validité conformément à la norme RFC 2822, HubSpot applique les restrictions suivantes concernant les adresses e-mail :

  • Les parties locales de l'adresse ne peuvent pas inclure de guillemets. (par exemple, "Test Email"@hubspot.com n'est pas valide).
  • La partie du domaine doit se terminer dans un TLD valide, comme indiqué sur https://data.iana.org/TLD/tlds-alpha-by-domain.txt (cela survient après la gestion des TLD unicode. Par conséquent, user@email.삼성 est une adresse e-mail valide).

Comment configurer plusieurs valeurs pour les propriétés de case à cocher ?

Lorsque vous configurez plusieurs valeurs pour une propriété de case à cocher, les valeurs doivent être séparées par un point-virgule (;).
Exemple : 'value1;value2;value5'

Lors de la mise à jour d'une fiche d'informations via les points de terminaison d'objet de CRM, la valeur de la propriété doit être une seule chaîne avec toutes les valeurs séparées par un point-virgule :

{
  "properties":
    {
      "example_property": "value1;value3;value4"
    }
}

Pour les points de terminaison des formulaires, assurez-vous que les points-virgules sont également encodés en URL :

...&example_property=value1%3Bvalue2%3Bvalue4

Existe-t-il des limites quant aux fiches d'informations de contact ?

HubSpot présente quelques limites en matière de fiches d'informations de contact et de soumissions de formulaires pour les fiches d'informations de contact :

  1. Une limite de 250 identités associées par contact s'applique.
    • Si vous essayez de fusionner deux contacts et que le contact résultant compte plus de 250 identités, vous recevrez une erreur.
  2. Les contacts sont limités à 1 000 soumissions de formulaires. Les soumissions au-delà de cette limite seront supprimées :
    • Les données de formulaire ne mettront pas à jour la fiche d'informations de contact.
    • La soumission elle-même ne s'affichera pas pour la fiche d'informations de contact, dans les données form-submissions à partir des points de terminaison des contacts ou dans la chronologie du contact.
    • La soumission ne sera pas évaluée pour l'inscription à une liste ou les workflows.
    • La soumission ne s'affichera pas dans la liste des soumissions pour la consultation du formulaire dans HubSpot.

Si vous avez dépassé ces limites en raison de tests, nous vous recommandons de supprimer les contacts de test et de créer une nouvelle fiche d'informations de test. L'utilisation de la même adresse e-mail dans le nouveau contact ne restaurera pas le contact supprimé et les soumissions de formulaires avec l'adresse e-mail seront associées à la nouvelle fiche d'informations.

Comment envoyer des e-mails transactionnels ?

HubSpot prend en charge deux méthodes d'envoi d'e-mails transactionnels : l'API SMTP et l'API d'envoi unique.

Utilisation de l'API SMTP

L'API SMTP n'envoie pas directement d'e-mails. Elle est utilisée uniquement pour obtenir les identifiants de connexion pour le serveur SMTP de HubSpot. Après avoir reçu un jeton et un mot de passe à l'aide de l'API SMTP, vous devez utiliser ces identifiants pour vous connecter au serveur SMTP de HubSpot et envoyer l'e-mail sur SMTP. Les informations de connexion (nom d'hôte et port) pour le serveur SMTP sont disponibles sur la page de documentation. L'e-mail et les liens seront entourés de balises afin de contribuer au suivi des e-mails de HubSpot. Autrement, vous devrez créer la totalité du contenu de l'e-mail.

Utilisation de l'API d'envoi unique

L'API d'envoi unique utilise des e-mails selon des modèles créés dans l'outil E-mails de HubSpot ainsi qu'une API POST au format JSON pour envoyer des e-mails. Tout d'abord, vous devez créer un e-mail dans HubSpot et sélectionner Enregistrer pour l'API d'envoi unique lors du choix du destinataire.  Une fois l'e-mail créé, vous pouvez utiliser l'API pour envoyer l'e-mail à un contact, en définissant les détails du destinataire (y compris les propriétés du contact ou personnalisées dans l'e-mail) dans le corps de la demande de l'API.  Pour en savoir plus sur le format de cette demande JSON, consultez la page de documentation.

Comment s'abonner aux mises à jour d'API ?

Les mises à jour des API et des outils de développeur de HubSpot sont effectuées par le biais de notre journal des modifications pour les développeurs.

Vous pouvez utiliser le formulaire sur la gauche pour vous abonner aux mises à jour. Sélectionnez la fréquence Instantané pour obtenir des notifications immédiates. Dans le cas contraire, sélectionnez l'une des autres fréquences pour obtenir un récapitulatif des mises à jour selon la fréquence définie.

Comment gérer la confidentialité et la conformité juridique lors de l'utilisation de la plateforme HubSpot ?

Suivi de la base juridique pour le traitement dans HubSpot

En vertu du RGPD, les entreprises ne peuvent utiliser et traiter les données de contacts sans raison légale et doivent conserver des copies de leur consentement ainsi que prouver la légitimité de leur traitement.

La propriété de contact Base juridique pour le traitement des données de contact vous permet de collecter, d'effectuer le suivi et de stocker la base juridique qui autorise le traitement via un contrat, un intérêt légitime et/ou le consentement de vos contacts HubSpot.

Lorsque vous accédez aux données des contacts via les points de terminaison des contacts, cette propriété utilise le nom hs_legal_basis. À l'instar de toute autre propriété de contact, le contact avec cette propriété définie sera accessible via l'API. La propriété peut également être définie ou mise à jour pour les fiches d'informations de contact via l'API.

Toutefois, les options de propriété ne peuvent pas être modifiées via l'API. Elles peuvent être uniquement mises à jour depuis HubSpot, mais il est possible d'extraire les options personnalisées qui ont été définies pour la propriété via les points de terminaison des propriétés de contact. Étant donné que les comptes HubSpot individuels ne peuvent pas utiliser les paramètres par défaut, il est recommandé d'utiliser ces points de terminaison pour obtenir les options de propriété.

Pour en savoir plus sur cette propriété et sur la façon dont elle peut être utilisée dans HubSpot, veuillez consulter cet
article de base de connaissances.

Gestion des suppressions de contacts conformément à la confidentialité

Les utilisateurs HubSpot peuvent supprimer définitivement une fiche d'informations de contact pour répondre à la législation en matière de confidentialité. Veuillez consulter cet article de la base de connaissances pour en savoir plus.

Vous pouvez vous abonner au type d'abonnement contact.privacyDeletion pour recevoir des notifications de webhook lorsqu'un utilisateur effectue une suppression de contact conformément à la confidentialité. Consultez la vue d'ensemble des webhooks pour plus de détails sur les webhooks et la gestion de ces notifications.

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é.