# 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" %} <mark style="color:red;">Mehr über</mark> <mark style="color:red;"></mark><mark style="color:red;">**Mitarbeiter**</mark><mark style="color:red;">-Einstellungen erfahren Sie</mark> [hier.](https://docs.desk4.de/einstellungen/mitarbeiter/mitarbeiter)
{% endhint %}

{% hint style="warning" %} <mark style="color:red;">**Die komplette Dokumentation der API Schnittstelle für desk4, finden Sie unter folgenden Link:**</mark> [**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.**&#x20;

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`

<figure><img src="https://901075246-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBlYqQ7S4FQO2M6oDBNFF%2Fuploads%2FZjdFherNjCyYEJ4mUk5q%2Fgrafik.png?alt=media&#x26;token=20ec1870-9ebf-4fec-a851-3be3d72b0f2a" alt=""><figcaption></figcaption></figure>

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" %} <mark style="color:red;">Um auf die Dokumentation der API zuzugreifen, rufen Sie folgenden Link auf:</mark> <https://demo.desk4.net/q/swagger/>
{% 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 <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)

{% file src="<https://901075246-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBlYqQ7S4FQO2M6oDBNFF%2Fuploads%2FCZezYmrIInQSban0DYSB%2FcreateCustomer.json?alt=media&token=36098eb5-da91-4334-88bf-c97acef39ddf>" %}
Benutzer anlegen
{% endfile %}

{% file src="<https://901075246-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBlYqQ7S4FQO2M6oDBNFF%2Fuploads%2FDIhXuKk98J71MzRSVlIG%2FcreateDocument.json?alt=media&token=bb53e0f9-c48e-4890-9f6f-e147ce003aab>" %}
Beleg anlegen
{% endfile %}

{% file src="<https://901075246-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBlYqQ7S4FQO2M6oDBNFF%2Fuploads%2F97LNcBUeqW1pjgGDp7nN%2FcreateProduct.json?alt=media&token=3c457430-b2f0-4d48-ad68-b657c6a00814>" %}
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.