Konnektoren
Schemaobjekte
Die SQL- und Dateibrücke
Das OAuth 2.0 Verfahren
Gesperrte Datensätze

HubSpot Konnektor

Der HubSpot Konnektor ermöglicht die Anbindung von Syncler an die HubSpot REST API.
Damit lassen sich Kundendaten, Deals, Unternehmen, Produkte, Dateien und weitere Objekte aus HubSpot lesen, bearbeiten oder anlegen.
Die Verbindung kann über eine öffentliche OAuth-App oder eine Private App hergestellt werden.

Funktionen

  • Verbindung über REST API
  • Zugriff auf zentrale HubSpot-Objekte: Kontakte, Unternehmen, Deals, Produkte, Line Items, Dateien, Benutzer, Eigentümer
  • Unterstützung von Verknüpfungen (Associations) zwischen Datensätzen
  • Upload und Download von Dateien (über das Files API)
  • Automatische Berücksichtigung von Rate Limits und Wiederholungsversuchen
  • Unterstützung von Custom Fields aus HubSpot
  • Nutzung der Search-Endpunkte für gezielte Datenabfragen

Voraussetzungen

Bevor Sie den Konnektor einrichten, stellen Sie sicher:

  • Sie haben ein aktives HubSpot-Konto mit API-Zugriff.
  • Bei Nutzung der öffentlichen App:
    • Eine registrierte App mit Client-ID, Secret und Redirect-URL existiert.
    • Die benötigten OAuth-Scopes sind in HubSpot freigegeben.
  • Alternativ: Sie verwenden eine Private App mit einem Access Token.

Für die Nutzung der privaten App führen Sie bitte folgende Schritte aus. Rufen Sie mit administrativen Rechten das Einstellungsmenü in Ihrem Account auf. Im Bereich Integrationen müssen Sie eine private App erstellen. Klicken Sie dazu unter "Private Apps" auf "Private App erstellen". Vergeben Sie einen Namen in den grundlegenden Informationen. Unter "Bereiche" müssen Sie die Berechtigungen für die App konfigurieren. Nur freigegebene Bereiche und Funktionen können genutzt werden.

Einrichtung

1. Neues System anlegen

Legen Sie in Syncler ein neues System mit dem Konnektor „HubSpot“ an.

2. Verbindung konfigurieren

Einstellung Beschreibung
API URL Standard: https://api.hubapi.com
OAuth URL URL für die Autorisierung, z. B. https://app-eu1.hubspot.com/oauth/authorize
Client ID / Secret Zugangsdaten Ihrer HubSpot-App
Redirect URL URL, an die HubSpot nach der Autorisierung zurückkehrt
OAuth Scopes Kommagetrennte Liste der benötigten Berechtigungen (z. B. crm.objects.contacts.read,crm.objects.deals.write)
Private Access Token Nur erforderlich bei Nutzung einer Private App (anstelle von OAuth)

Nach der Einrichtung generiert Syncler automatisch einen Access Token und ggf. einen Refresh Token.
Diese werden intern gespeichert und bei Bedarf automatisch erneuert.

Unterstützte Objekte

Der HubSpot-Konnektor stellt verschiedene Objekte zur Verfügung:

  • Kontakte (Contacts)
  • Unternehmen (Companies)
  • Deals (Deals)
  • Produkte (Products)
  • Line Items (Line_Items)
  • Benutzer (Users)
  • Eigentümer (Owners)
  • Dateien (Files)

Zusätzlich können Verknüpfungen zwischen Datensätzen (z. B. Kontakt ↔ Unternehmen oder Deal ↔ Line Item) automatisch erkannt und verwaltet werden.

Datenzugriff

Lesen von Daten

Daten werden in der Regel über die Search-Endpunkte (v3) der HubSpot API abgefragt.
Für große Datenmengen ist zu beachten:

  • Der Search-Endpunkt ist auf 10.000 Datensätze pro Anfrage begrenzt.
  • Wird dieses Limit erreicht, erfolgt eine automatische Nachladung mit Offset.
  • Dies wird mit einem automatischen Filter auf die ID und einer Sortierung nach ID erreicht.

Datenfilter erfordern eine Json-Angabe der Suchbedingungen.

    {  
        "filterGroups":[  
            {  
                "filters":[  
                    {  
                        "propertyName": "firstname",  
                        "operator": "EQ",  
                        "value": "Alice"  
                    }  
                ]  
            }  
        ]  
    }

Schreiben von Daten

Das Erstellen, Aktualisieren und Löschen von Datensätzen erfolgt über die jeweiligen v3-Endpoints:

  • POST für neue Datensätze
  • PATCH für Aktualisierungen
  • DELETE für Löschvorgänge

Dateien können über das Files API hochgeladen werden.
Dabei werden Inhalte im Base64-Format übergeben.

Assoziationen (Verknüpfungen)

HubSpot erlaubt verschiedene Zuordnungen, z. B.:

  • Contact ↔ Company
  • Deal ↔ Line Item
  • Company ↔ Deal

Diese Verknüpfungen werden in Syncler als ObjectGroups dargestellt und können beim Schreiben automatisch angelegt oder entfernt werden.

Besonderheiten & Hinweise

  • Die API-Limits liegen bei etwa 150 Requests pro Sekunde, bei Suchvorgängen sind 5 Anfragen pro Sekunde erlaubt.
  • Wird ein Limit erreicht, pausiert der Konnektor automatisch und wiederholt die Anfrage.
  • Felder mit dem Typ Checkbox oder Enumeration werden automatisch in Syncler in auswählbare Listenfelder umgewandelt.
  • Bei Schreibvorgängen prüft der Konnektor Pflichtfelder und Feldlängen automatisch.