> For the complete documentation index, see [llms.txt](https://docs.desk4.de/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.desk4.de/faq/api-zugang.md). # 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. {% hint style="warning" %} Mehr über **Mitarbeiter**-Einstellungen erfahren Sie [hier.](/einstellungen/mitarbeiter/mitarbeiter.md) {% endhint %} {% hint style="warning" %} **Die komplette Dokumentation der API Schnittstelle für desk4, finden Sie unter folgenden Link:** [**https://demo.desk4.net/q/swagger/**](https://demo.desk4.net/q/swagger/) {% endhint %} 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 „Authorization“ als Key ein, um so auf die API zugreifen zu können. ![](https://901075246-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBlYqQ7S4FQO2M6oDBNFF%2Fuploads%2FVKcKeApJpX6vrqg518UO%2FUse_WebToken_Postman.png?alt=media\&token=b862cde8-5815-433c-955e-04397d3e02a9) {% hint style="warning" %} Um auf die Dokumentation der API zuzugreifen, rufen Sie folgenden Link auf: {% endhint %} 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 `). ## 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. ## Datensätze aktualisieren (API V1) In der aktuellen Version der API (V1) werden beim Speichern **keine Teilaktualisierungen** unterstützt. Es reicht also nicht aus, nur die geänderten Felder zu übermitteln. Stattdessen muss immer das **vollständige Objekt** gesendet werden. {% hint style="warning" %} Senden Sie beim Speichern immer den kompletten Datensatz zurück, auch die Felder, die Sie nicht geändert haben. So vermeiden Sie, dass bestehende Daten verloren gehen. {% endhint %} ### Vorgehen beim Aktualisieren 1. **Vollständiges Objekt abrufen**\ Laden Sie den Datensatz vor jeder Änderung über die API. Die Antwort enthält alle Felder sowie die aktuelle `version`. 2. **Änderungen im abgerufenen Objekt vornehmen**\ Passen Sie nur die gewünschten Felder an und lassen Sie alle übrigen Felder unverändert im Objekt. 3. **Gesamtes Objekt speichern**\ Senden Sie das komplette Objekt inklusive aller unveränderten Felder und der aktuellen `version` an die API zurück. {% hint style="info" %} **Ausblick auf API V2:** Die Version 2 der API befindet sich derzeit in Entwicklung. Dort wird dieses Verhalten verbessert. Sobald V2 verfügbar ist, wird diese Dokumentation entsprechend ergänzt. {% endhint %} ## Beispiel Daten (JSON) {% file src="/files/Z6v29jxxp3fMszYdtTEj" %} Benutzer anlegen {% endfile %} {% file src="/files/4QeEUz4JSY2Y9T60dtN5" %} Beleg anlegen {% endfile %} {% file src="/files/fzuZNajXR31eT07Ke152" %} Artikel anlegen {% endfile %} ## desk4 API in n8n mit OAuth2 nutzen Mit **n8n.io** können Sie die **desk4 API** über die OAuth2-Authentifizierung anbinden. *** ### Neue API-Credentials anlegen 1. Öffnen Sie n8n und gehen Sie zu **Credentials**. 2. Wählen Sie **New Credential → OAuth2 API**. 3. Tragen Sie 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. Klicken Sie 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. Legen Sie einen neuen Workflow an. 2. Fügen Sie einen **HTTP Request Node** hinzu. 3. Wählen Sie bei **Authentication** die gerade erstellten desk4-OAuth2-Credentials. 4. Konfigurieren Sie den Request: * **Method:** GET oder POST (je nach API-Endpoint) * **URL:** z. B. ``` https://meine-firma.desk4.cloud/rest/v1/customer ``` 5. Speichern und testen Sie 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 Ihnen eine JSON-Liste aller Kunden aus Ihrer desk4-Warenwirtschaft.