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

Haufe X360 Konnektor

Der Haufe X360 Konnektor verbindet Syncler mit dem ERP-System Haufe X360 Cloud oder einer lokalen On-Premises-Installation.
Über den Konnektor können Datenobjekte wie Geschäftspartner, Kontakte, Belege oder Artikel gelesen, geschrieben und gelöscht werden.
Die Kommunikation erfolgt über eine REST-API auf Basis eines definierten Endpunkts.

Voraussetzungen

Für die Verbindung mit Haufe X360 werden folgende Voraussetzungen benötigt:

  • Eine verbundene Applikation in Haufe X360 mit OAuth-Autorisierung
  • Eine gültige Client-ID, ein Client-Secret und eine Redirect-URL
  • Ein konfigurierter API-Endpunkt mit Zugriffsrechten auf die gewünschten Entitäten
  • Bei produktiven Umgebungen: ein „gleitender Ablaufzeitpunkt“ für den Token, damit ein kontinuierlicher Zugriff gewährleistet ist

Einrichtung

1. Verbundene Applikation in Haufe X360 erstellen

  1. Öffnen Sie in Haufe X360 das Menü „SM303010“.
  2. Legen Sie eine neue verbundene Applikation an.
  3. Vergeben Sie einen Namen und wählen Sie als Flow den Typ „Authorization Code“.
  4. Fügen Sie unter der Registerkarte Redirect URIs die Adresse ein: 
    https://admin.syncler.com/oauth-callback.html
  5. Speichern Sie die Applikation.
    • Erst jetzt wird die Client-ID angezeigt.
    • Erzeugen Sie anschließend einen Geheimschlüssel (Shared Secret) und übernehmen Sie den Wert sofort, da er später nicht erneut ausgelesen werden kann.
  6. Verwenden Sie für produktive Systeme den „gleitenden Ablaufzeitpunkt“ für Tokens, um eine dauerhafte Verbindung zu gewährleisten.

2. Konnektor in Syncler anlegen

  1. Legen Sie in Syncler ein neues System mit dem Typ „Haufe X360“ an.

  2. Im Abschnitt OAuth Authorization tragen Sie die folgenden Werte ein:

    Feld Beschreibung
    Client ID Wert aus der verbundenen Applikation
    Client Secret Generierter Geheimschlüssel
    Redirect URL Die verwendete Redirect-URI
    Scopes api offline_access
    Authorization URL Autorisierungsendpunkt der X360-Instanz, z. B. https://isv.haufe-x360.app/identity/connect/authorize?response_type=code

  3. Im Abschnitt Haufe X360 Einstellungen konfigurieren Sie:

    Feld Beschreibung
    ERP Instanz URL URL Ihrer X360-Instanz, z. B. https://isv.haufe-x360.app/
    Endpunkt Name des gewünschten API-Endpunkts (z. B. Default)
    Version API-Version, z. B. 23.200.001
    Firma Mandantenname
    Entitäten mit Custom-Feldern Kommagetrennte Liste von Objekten, für die benutzerdefinierte Felder geladen werden sollen

  4. Speichern Sie den Konnektor.
    Beim Speichern prüft Syncler die Verbindung und lädt das Schema der gewählten Instanz.

Objekte und Datenstruktur

Das Schema des Haufe X360 Konnektors enthält sowohl Datenobjekte als auch Aktionsobjekte.
Jedes Schemaobjekt kann über Syncs gelesen, geschrieben oder zur Ausführung von Aktionen verwendet werden.

Stammdaten

  • BusinessAccount (Geschäftspartner)
    Wird automatisch um die Objekte Attributes, MainAddress, MainContact, DefaultLocationSettings und ShippingAddress erweitert.

  • Contact (Kontaktpersonen)
    Enthält die Zusatzobjekte Attributes und Address.

Über den Parameter expand können bei Bedarf weitere Objekte als kommagetrennte Liste übergeben werden, um zusätzliche Details zu laden.

Aktionen

Aktionen werden durch das Schreiben eines Aktionsobjekts ausgelöst.
Sie sind einer Entität zugeordnet und benötigen die ID des betroffenen Datensatzes.

Beispiel:
Die Aktion

ConvertBusinessAccountToCustomer

erstellt aus einem Geschäftspartner einen Kundendatensatz.

Zusätzliche Parameter der Aktionen sind jeweils in der Beschreibung des Schemaobjekts enthalten.

Besondere Datenstruktur

Einige API-Responses enthalten sogenannte bereitgestellte Daten.
Diese befinden sich nicht direkt als Eigenschaften des Objekts, sondern innerhalb des Feldes value.
Neben dem eigentlichen Wert kann dieses Feld auch ein Fehlerobjekt (error) enthalten.
Wenn Fehler beim Schreiben auftreten, werden sie von Syncler gesammelt und im Protokoll angezeigt.

Hinweise zur Nutzung

  • Aktualisieren Sie das Schema nach Änderungen in Haufe X360, insbesondere nach dem Hinzufügen neuer Felder.
  • Verwenden Sie zur Systempflege eindeutige Endpunkte, da jeder Endpunkt die verfügbaren Objekte und Aktionen bestimmt.
  • Für produktive Umgebungen wird empfohlen, die Tokenlaufzeit auf „gleitend“ zu stellen, um Verbindungsabbrüche zu vermeiden.
  • Beachten Sie, dass Custom-Felder nur für die im Feld „Entitäten mit Custom-Feldern“ angegebenen Objekte geladen werden.