# 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.](/einstellungen/mitarbeiter/mitarbeiter.md)
{% 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="/files/fRnZTsElWvYWwbDPpkO4" 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.

![](/files/snGwsHp9jjNUIfepE8Pt)

{% 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="/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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.desk4.de/faq/api-zugang.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.