Règles d'utilisation des API

HubSpot suit attentivement l'utilisation de nos API publiques pour assurer une expérience de qualité pour chaque utilisateur. Tous les développeurs d'applications et d'intégrations doivent respecter la Politique d'utilisation acceptable de HubSpot et les Conditions générales relatives aux API. Même si HubSpot se réserve le droit de modifier ou de désapprouver les API au fil du temps, nous en informerons toujours les développeurs à l'avance via notre changelog.

Authentification et sécurité

Pour une sécurité optimale, toutes les applications doivent utiliser directement le protocole OAuth de HubSpot ou le jeton d'accès de votre application si vous créez une application privée. Les applications sont chargées de stocker des données time-to-live (TTL) et d'actualiser les jetons d'accès des utilisateurs conformément à ce protocole. Lorsqu'un jeton d'accès est généré, il inclura un paramètre expires_in indiquant la durée durant laquelle il peut être utilisé pour effectuer des appels d'API avant l'actualisation. Les requêtes Unauthorized (401) ne sont pas un indicateur valide qu'un nouveau jeton d'accès doit être récupéré.

Vérification de l'utilisation des API

Applications privées et applications utilisant OAuth

Utilisez Suivi des appels d'API dans les paramètres de l'application.

Intégrations utilisant des clés d'API

Remarque : À compter du 30 novembre 2022, les clés d'API HubSpot ne pourront plus être utilisées comme méthode d'authentification pour accéder aux API HubSpot. En outre, à compter du 15 juillet 2022, les comptes sans clé d'API HubSpot déjà générée ne pourront plus en créer.

Au lieu de cela, vous devrez utiliser un jeton d'accès d'application privée ou OAuth pour authentifier les appels d'API. Découvrez-en davantage sur cette modification et sur la migration d'une intégration de clé d'API pour utiliser une application privée à la place.

Utilisez GET /integrations/v1/limit/daily* pour vérifier combien d'appels d'API ont été effectués pour le jour en cours et quand la limite sera réinitialisée. Le jour en cours s'étend de minuit à minuit, en fonction des paramètres de fuseau horaire du compte connecté. 

* Un appel vers ce point de terminaison est comptabilisé dans vos limites quotidiennes d'API.

 

Paramètres obligatoires Description Fonctionnement
Clé d'API HubSpot La clé d'API pour le compte HubSpot dont vous vérifiez l'utilisation des API. hapikey= utilisé dans l'URL

Exemple d'URL GET :

https://api.hubapi.com/integrations/v1/limit/daily?hapikey=demo

Les données renvoyées par ce point de terminaison seront mises en cache pendant cinq minutes. Vérifiez les champs fetchStatus et collectedAt dans la réponse pour déterminer si cela provient d'un cache.

Exemple de réponse :

// [ { "name": "api-calls-daily", "usageLimit": 1000000, "currentUsage": 31779, "collectedAt": 1560189939285, "fetchStatus": "SUCCESS", "resetsAt": 1560204000000 } ]

Le champ resetsAt est un horodatage Unix (en millisecondes) du temps de réinitialisation de la limite. La limite se réinitialise à minuit en fonction du fuseau horaire du compte.

Exemple de réponse du cache :

// [ { "name": "api-calls-daily", "usageLimit": 1000000, "currentUsage": 31779, "collectedAt": 1560189939285, "fetchStatus": "CACHED", "resetsAt": 1560204000000 } ]

Lorsque la réponse provient du cache, fetchStatus sera "CACHED" et collectedAt sera un horodatage Unix en millisecondes indiquant le moment de la dernière mise à jour du cache.

Limitation des appels d'API

Applications utilisant OAuth

Les applications utilisant OAuth ne sont soumises qu'à une limite de 100 requêtes toutes les 10 secondes (à l'exception de l'API de recherche, comme indiqué ci-dessous dans « Autres limites »). Les limites liées au module complémentaire d'API ne s'appliquent pas.

Applications privées

Chaque application privée est soumise aux directives sur l'utilisation des API HubSpot. Le nombre d'appels que votre application privée peut effectuer dépend de l'abonnement de votre compte et de l'achat du module complémentaire API :

  Niveau du produit Toutes les 10 secondes Par jour
Applications privées

(Tout abonnement Hub)

Gratuit et Starter

100/application privée 250 000/compte
 

(Tout abonnement Hub)

Pro et Entreprise

150/application privée 500 000/compte
Applications privées avec le module complémentaire API

(Tout abonnement Hub)

Gratuit, Starter, Pro et Entreprise

200/application privée 1 000 000/compte

Intégrations utilisant des clés d'API

Les intégrations utilisant des clés d'API sont soumises aux limites quotidiennes ci-dessous (à l'exception de l'API de recherche, comme indiqué ci-dessous dans « Autres limites »). Ces limites quotidiennes se réinitialisent à minuit en fonction des paramètres de fuseau horaire du compte connecté. 

 

Niveau du produit

Limites

Gratuit et Starter

Rafale : 100/10 secondes

Quotidien : 250 000

Pro et Entreprise

Rafale : 150/10 secondes

Quotidien : 500 000 

Module complémentaire d'API (tous les niveaux)

Rafale : 200/10 secondes 

Quotidien : 1 000 000

 

Réponses d'erreur

Toute application ou intégration dépassant ses limites de taux recevra une réponse d'erreur 429 pour tous les appels d'API ultérieurs. Les demandes résultant d'une réponse d'erreur ne doivent pas dépasser 5 % de vos demandes quotidiennes. Si vous prévoyez de lister votre application dans le marketplace des applications, celle-ci doit rester sous cette limite de 5 % pour être certifiée. 

La réponse 429 sera au format suivant : 

//Example { "status": "error", "message": "You have reached your daily limit.", "errorType": "RATE_LIMIT", "correlationId": "c033cdaa-2c40-4a64-ae48-b4cec88dad24", "policyName": "DAILY", "requestId": "3d3e35b7-0dae-4b9f-a6e3-9c230cbcf8dd" }

message et policyNameindiqueront la limite que vous avez atteinte (quotidienne ou par seconde).

La limite quotidienne se réinitialise à minuit selon votre fuseau horaire.

Chaque demande d'API comprendra les en-têtes des limitations des appels d'API suivants dans la réponse. REMARQUE : Les en-têtes Daily et Daily-Remaining ne sont pas inclus pour les demandes autorisées via OAuth.

En-tête Description
X-HubSpot-RateLimit-Daily Le nombre d'appels d'API autorisés par jour.
X-HubSpot-RateLimit-Daily-Remaining Le nombre d'appels d'API encore autorisés pour le jour en cours.
X-HubSpot-RateLimit-Interval-Milliseconds La fenêtre de temps à laquelle s'appliquent les en-têtes X-HubSpot-RateLimit-Max et X-HubSpot-RateLimit-Remaining.

Par exemple, une valeur de 10 000 serait une fenêtre de 10 secondes.
X-HubSpot-RateLimit-Max Le nombre d'appels autorisés dans la fenêtre spécifiée dans X-HubSpot-RateLimit-Interval-Milliseconds.

Par exemple, si cet en-tête a une valeur de 100, et que l'en-tête X-HubSpot-RateLimit-Interval-Milliseconds est de 10 000, la limite appliquée sera de 100 appels pour 10 secondes.
X-HubSpot-RateLimit-Remaining  Le nombre d'appels d'API encore autorisés pour la fenêtre spécifiée dans X-HubSpot-RateLimit-Interval-Milliseconds.


Remarque
 : Les en-têtes X-HubSpot-RateLimit-Secondly et X-HubSpot-RateLimit-Secondly-Remaining sont toujours inclus et présentent des données précises. Cependant, la limite référencée par ces en-têtes n'est plus appliquée et ces deux en-têtes doivent être considérés comme obsolètes.

Vous pouvez également vérifier le nombre d'appels utilisés sur le jour en cours à l'aide de ce point de terminaison.

Si vous atteignez la limite TEN_SECONDLY_ROLLING, vous devez maintenir les demandes de votre application sous cette limite. Par ailleurs, si vous atteignez la limite quotidienne, consultez les suggestions ci-dessous.

Si vous atteignez toujours les limites d'appel, veuillez nous en informer sur nos forums des développeurs. Fournissez autant de détails que possible quant aux API utilisées, à leur utilisation et à la limite atteinte.

Données de cache pour les appels récurrents

Si votre site ou votre application utilise des données de HubSpot sur chaque chargement de page, ces données doivent être mises en cache et chargées à partir de ce cache au lieu d'être demandées à chaque fois à partir des API de HubSpot. Si vous effectuez des appels répétés pour obtenir des paramètres depuis votre compte pour un traitement par lot (comme l'obtention de propriétés d'objet, de propriétaires ou de paramètres pour un formulaire), ces paramètres doivent également être mis en cache, le cas échéant.

Utiliser des API de lot si possible

Si vous ne travaillez pas avec des données sensibles au temps, le regroupement dans des lots spécifiques peut s'avérer plus efficace. 

Si vous travaillez avec des objets de CRM (contacts, entreprises, transactions, etc.), des méthodes de lot sont disponibles. 

Utiliser des webhooks pour obtenir des données actualisées depuis HubSpot

Si vous disposez d'un abonnement HubSpot Marketing Entreprise, vous pouvez utiliser des actions de webhook dans les workflows pour obtenir des données pour les fiches d'informations de contact envoyées à votre système. Les webhooks peuvent être déclenchés en tant qu'action dans n'importe quel workflow, afin que vous puissiez utiliser les conditions initiales de workflow comme critères pour l'envoi des données de contact à votre système. Pour en savoir plus sur l'utilisation des webhooks, consultez cet article et des exemples de données de webhooks ici.

 

Limites de service

Découvrez-en davantage sur les limites de service et les tarifs ici.


Autres limites

  • Vous pouvez créer jusqu'à 100 applications par compte de développeur.
  • Vous pouvez créer jusqu'à 20 applications privées par compte HubSpot.
  • Vous pouvez créer jusqu'à 1 000 abonnements de webhook par application.
  • Vous pouvez créer jusqu'à 25 paramètres d'extension de CRM par application.
  • Vous pouvez créer jusqu'à 750 types d'événements chronologiques par application.
  • Vous pouvez créer jusqu'à 500 propriétés par type d'événement chronologique.
  • Les point de terminaison de l'API de recherche sont limités à quatre demandes par seconde par jeton d'authentification.

Documents associés

Vérifier l'utilisation de l'API dans l'application