Richtlinien zur API-Nutzung

HubSpot überwacht aufmerksam die Nutzung unserer öffentlich-APIs, um jedem Benutzer ein erstklassiges Erlebnis zu gewährleisten. Alle Entwickler von Apps und Integrationen müssen die Richtlinie zur akzeptablen Nutzung und die API-Bedingungen von HubSpot einhalten. HubSpot behält sich das Recht vor, APIs im Laufe der Zeit zu ändern oder einzustellen. Updates werden jedoch stets im Voraus über das Änderungsprotokoll für Entwickler bereitgestellt.

Authentifizierung und Sicherheit

Für optimale Sicherheit müssen alle Apps das OAuth-Protokoll von HubSpot direkt verwenden oder sie müssen das Zugriffstoken Ihrer App verwenden, wenn Sie eine private App erstellen. Apps sind für die Speicherung von Time-to-live (TLS)-Daten und die Aktualisierung von Benutzerzugriffstoken gemäß diesem Protokoll verantwortlich. Wenn ein Zugriffstoken generiert wird, enthält es einen expires_in-Parameter, der angibt, wie lange es für API-Aufrufe verwendet werden kann, bevor es aktualisiert wird. Unauthorized (401)-Anfragen sind kein zulässiger Indikator, dass ein neues Zugriffstoken abgerufen werden muss.

Private Apps

So zeigen Sie die API-Nutzung für eine private App an:

• Klicken Sie in Ihrem HubSpot-Account in der Hauptnavigationsleiste auf das Zahnrad-Symbol.
• Gehen Sie in der linken Seitenleiste zu Integrationen > Private Apps.
• Klicken Sie auf den Namen der privaten App.
• Klicken Sie auf der Seite mit den App-Details auf die Registerkarte Protokolle.
• Überprüfen Sie die in der Tabelle aufgeführten API-Aufrufe. Sie können auch die Suchleiste, Filter und Datumsauswahlen verwenden, um die angezeigten API-Aufrufe weiter zu verfeinern.

Erfahren Sie mehr über das Überprüfen der API-Nutzung in privaten Apps.

Öffentliche Apps, die OAuth verwenden

So zeigen Sie die API-Nutzung für eine öffentliche App an, die OAuth verwendet:

• Gehen Sie in Ihrem Entwickler-Account in der Hauptnavigationsleiste zu Apps.
• Klicken Sie auf den Namen der App.
• Gehen Sie in der linken Seitenleiste zu Monitoring.
• Verwenden Sie die Registerkarten, um verschiedene Typen von Anfragen anzuzeigen, die an oder von der App vorgenommen werden. Beim Anzeigen dieser Protokolle können Sie auf eine einzelne Anfrage klicken, um weitere Informationen anzuzeigen.

Erfahren Sie mehr über das Überwachen der API-Nutzung für öffentliche Apps.

Apps, die OAuth verwenden

Bei OAuth-Apps ist jeder HubSpot-Account, der Ihre App installiert, auf 100 Anfragen pro 10 Sekunden beschränkt. Dies schließt die Suche-API aus, wie im Abschnitt Sonstige Beschränkungen unten erläutert. Beschränkungen im Zusammenhang mit dem API-Add-on gelten nicht.

Private Apps

Jede private App unterliegt den Richtlinien zur API-Nutzung von HubSpot. Die Anzahl der Aufrufe, die Ihre private App durchführen kann, hängt von Ihrem Account-Abonnement ab und davon, ob Sie das API-Add-on erworben haben:

• Sie können bis zu 100 Apps pro Entwickler-Account erstellen
• Sie können bis zu 20 private Apps pro HubSpot-Account erstellen.
• Sie können bis zu 1.000 Webhook-Abonnements pro App erstellen
• Sie können bis zu 25 CRM-Erweiterungseinstellungen pro App erstellen
• Sie können bis zu 750 Chronik-Event-Typen pro App erstellen
• Sie können bis zu 500 Eigenschaften pro Chronik-Event-Typ erstellen
• Bei Such-API-Endpunkten gibt es eine Ratenbeschränkung von vier Anfragen pro Sekunde pro Authentifizierungstoken

Weitere Informationen zu Leistungsbeschränkungen und Preisen finden Sie hier.

Eine App oder eine Integration, die über die Ratenbeschränkungen hinausgeht, erhält eine 429-Fehlerantwort für alle nachfolgenden API-Aufrufe. Anfragen, die zu einer Fehlerantwort führen, sollten nicht mehr als 5 % Ihrer gesamten täglichen Anfragen ausmachen. Wenn Sie Ihre App im HubSpot App Marketplace listen möchten, muss sie unter 5 % liegen, um zertifiziert zu werden. 

Die 429-Antwort weist das folgende Format auf: 

 message und policyName geben an, welche Beschränkung Sie (entweder täglich oder Sekunden) erreicht haben.

Die tägliche Beschränkung wird auf der Grundlage Ihrer Zeitzoneneinstellung um Mitternacht zurückgesetzt.

In der folgenden Tabelle sind die Ratenbeschränkungen-Header aufgeführt, die in der Antwort jeder API-Anfrage an HubSpot enthalten sind, vorbehaltlich der unter der Tabelle aufgeführten Ausnahmen.

Mithilfe dieses Endpunkts können Sie auch die Anzahl der Aufrufe überprüfen, die während des aktuellen Tags verbraucht wurden.

Wenn Sie die TEN_SECONDLY_ROLLING-Beschränkung erreichen, sollten Sie die Anfragen, die Ihre Anwendung vornimmt, unter diese Beschränkung drosseln. Neben dem Drosseln von Anfragen sollten Sie auch folgende Vorschläge beachten (diese sind auch hilfreich, wenn Sie die tägliche Beschränkung erreichen).

Wenn Sie trotz Umsetzung dieser Vorschläge weiterhin die Aufrufbeschränkungen erreichen, bitten Sie in HubSpots Entwicklerforen nach Unterstützung. Sie sollten so viele Details wie möglich über die die von Ihnen genutzten APIs angeben: wie Sie diese verwenden und welche Beschränkung Sie erreichen.

Wenn Ihre Website oder App bei jedem Laden von Seiten Daten von HubSpot verwendet, sollten diese Daten im Cache gespeichert und von dort geladen werden, anstatt jedes Mal von den HubSpot-APIs angefordert zu werden. Wenn Sie wiederholt Aufrufe vornehmen, um Einstellungen von Ihrem Account für einen Batch-Auftrag abzurufen (z. B. wenn Sie Ihre Objekteigenschaften, zuständigen Mitarbeiter oder Einstellungen für ein Formular abrufen), sollten diese Einstellungen wenn möglich ebenfalls im Cache gespeichert werden.

Wenn Sie über ein HubSpot Marketing Enterprise-Abonnement verfügen, können Sie Webhook-Aktionen in Workflows verwenden, damit Daten für Kontaktdatensätze an Ihr System gesendet werden. Webhooks können in jedem Workflow als Aktion ausgelöst werden. Daher können Sie beliebige Workflow-Startbedingungen als das Kriterium verwenden, über das Kontaktdaten an Ihr System gesendet werden. Weitere Informationen zur Verwendung von Webhooks finden Sie hier, Beispiel-Webhook-Daten finden Sie hier. Webhook-Aufrufe, die über Workflows getätigt werden, werden nicht auf die API-Ratenbeschränkung angerechnet.