API-Zugang

Login und Anmeldung

Um Zugriff auf die API zu erhalten, wird der Benutzer als API-Benutzer (Checkbox im Kopfmenü anhaken) gekennzeichnet.

Über diesen Haken öffnet sich die REST-Schnittstelle. Hier kann man nun anhaken, welche Rechte der API Benutzer haben soll.

Für den API Benutzer sollte keine Berechtigungs-Gruppe eingestellt sein.

Mehr über Mitarbeiter-Einstellungen erfahren Sie hier.

Die komplette Dokumentation der API Schnittstelle für desk4, finden Sie unter folgenden Link: https://demo.desk4.net/q/swagger/

Mit dem API-Benutzer können Sie anschließend ein WebToken zur Authentifizierung erzeugen. Ein erzeugter Webtoken ist 30 Minuten gültig.

In den Body müssen dafür die Benutzerdaten nach folgendem Schema eingefügt werden:

{
"userName": "admin",
"password": "admin",
"branchID": 1,
"killExistingSession": true
}

Beachten Sie, dass die korrekte Methode ausgewählt sein muss (in diesem Fall „Post“).

API Pfad: https://demo.desk4.net/rest/v1/session/webtoken

Das erhaltene WebToken fügen Sie nun im Header in der Form „Bearer +WebToken“ als Value und „Autorization“ als Key ein, um so auf die API zugreifen zu können.

Um auf die Dokumentation der API zuzugreifen, rufen Sie folgenden Link auf: https://demo.desk4.net/q/swagger/

Alternativ können Sie auch die URL Ihrer desk4 Instanz für „demo.desk4.net“ einsetzen.

OAuth2 Authentifizierung

Um sich über OAuth2 an der desk4 API anzumelden, verwenden Sie bitte folgende URL, um ein Access Token zu erhalten:

https://meine-firma.desk4.cloud/rest/v1/session/token

Erforderliche Parameter

• Grant Type: client_credentials

• Client ID: Benutzername des API-Users in desk4

• Client Secret: Passwort des API-Users in desk4

• Authentication: Im Request-Body übergeben

Hinweis

Das Access Token wird für alle weiteren API-Anfragen benötigt und muss im HTTP-Header mitgeschickt werden (z. B. Authorization: Bearer <AccessToken>).

Optimistic Locking

Die desk4 Cloud Warenwirtschaft API verwendet Optimistic Locking, um parallele Änderungen an Datensätzen konsistent zu verwalten und Datenverlust zu verhindern.

Grundprinzip

• Jeder Datensatz besitzt eine Versionsnummer (version).

• Bei jedem Lesezugriff wird die aktuelle Versionsnummer mitgeliefert.

• Beim Speichern muss dieselbe Versionsnummer mitgeschickt werden.

• Nach erfolgreichem Speichern wird die Versionsnummer automatisch um +1 erhöht.

• Wird versucht, einen Datensatz mit einer veralteten Versionsnummer zu speichern, gibt die API einen Fehler zurück.

Typischer Ablauf

1. Objekt lesen

   • API liefert den Datensatz inklusive Feld version.

   • Beispiel: version = 1

2. Objekt ändern

   • Änderungen am Datensatz vornehmen.

   • Beim Speichern die aktuelle Version mitsenden.

3. Speichern

   • Die Datenbank prüft, ob die übermittelte version noch aktuell ist.

   • Wenn ja → Änderungen werden übernommen, version erhöht sich auf 2.

   • Wenn nein → Fehler, da ein anderer Prozess oder Nutzer das Objekt zwischenzeitlich geändert hat.

Fehlermeldung bei Versionskonflikt

Wenn ein Datensatz mit einer veralteten Version gespeichert wird, erscheint eine Meldung.

Das bedeutet:

• Ein anderer Client oder Prozess hat den Datensatz geändert.

• Ihre Daten basieren nicht mehr auf der neuesten Version.

Best Practices für API-Anwender

1. Immer die aktuelle Version mitsenden Verwenden Sie beim Update genau die version, die Sie beim letzten Lesen erhalten haben.

2. Konflikte behandeln

   • Prüfen Sie beim Fehler, ob ein Versionskonflikt vorliegt.

   • Laden Sie in diesem Fall den Datensatz erneut von der API.

   • Entscheiden Sie, ob Sie:

     • Ihre Änderungen erneut anwenden und speichern (mit der neuen version), oder

     • die fremden Änderungen übernehmen.

Beispiel Daten (JSON)

737B

createCustomer.json

Benutzer anlegen

2KB

createDocument.json

Belege erstellen

477B

createProduct.json

Artikel anlegen

desk4 API in n8n mit OAuth2 nutzen

Mit n8n.io kannst du die desk4 API über die OAuth2-Authentifizierung anbinden.

---

Neue API-Credentials anlegen

1. Öffne n8n und gehe zu Credentials.

2. Wähle New Credential → OAuth2 API.

3. Trage folgende Werte ein:

   • Grant Type: Client Credentials

   • Access Token URL:

     https://meine-firma.desk4.cloud/rest/v1/session/token

   • Client ID: Benutzername des desk4 API-Users

   • Client Secret: Passwort des desk4 API-Users

   • Authentication: Body

---

Verbindung testen

1. Klicke in den Credentials auf Connect oder Test.

2. Wenn die Daten korrekt sind, erstellt n8n automatisch das Access Token.

3. Das Token wird intern von n8n gespeichert und bei jeder Anfrage automatisch mitgeschickt.

---

Verwendung in einem Workflow

1. Lege einen neuen Workflow an.

2. Füge einen HTTP Request Node hinzu.

3. Wähle bei Authentication die gerade erstellten desk4-OAuth2-Credentials.

4. Konfiguriere den Request:

   • Method: GET oder POST (je nach API-Endpoint)

   • URL: z. B.

     https://meine-firma.desk4.cloud/rest/v1/customer

5. Speichere und teste den Workflow.

---

Beispiel: Kundenliste abrufen

HTTP Request Node Konfiguration:

• Method: GET

• URL:

  https://meine-firma.desk4.cloud/rest/v1/customer

• Authentication: desk4 OAuth2-Credentials

Das Ergebnis liefert dir eine JSON-Liste aller Kunden aus deiner desk4-Warenwirtschaft.