Mit der X-Sitter API liest und änderst du die Daten deiner Firma direkt aus deinem eigenen System, zum Beispiel aus deinem ERP, deinem Onlineshop oder einer Tabellenkalkulation. Alle Anfragen gehen an dieselbe Adresse und antworten in JSON.

| | |
|---|---|
| **Adresse** | `https://app.x-sitter.com/api/v1` |
| **Format** | JSON (UTF-8) |
| **Authentifizierung** | Token im Header `Authorization: Bearer xst_...` |

!!!primary Schritt für Schritt
Anleitungen: [Bestand abfragen](stock.md) und [Artikel lesen und pflegen](articles.md).
!!!

## Was die API kann

| Bereich | Adressen | Für wen |
|---|---|---|
| [**Bestand**](stock.md) | `GET /api/v1/stock`, `GET /api/v1/stock/{id}` | Logistiker und Mandanten (Mandanten nur, wenn ihr Logistiker es erlaubt) |
| [**Artikel**](articles.md) | `GET`, `POST /api/v1/articles`, `GET`, `PATCH`, `DELETE /api/v1/articles/{id}` | Logistiker und Mandanten (Löschen nur der Logistiker) |
| **Lagerplätze** | `GET`, `POST /api/v1/spots`, `GET`, `PUT`, `DELETE /api/v1/spots/{id}` | Nur Logistiker |

## Token anlegen

Jede Anfrage braucht einen Token. Du legst ihn selbst in X-Sitter an:

1. Melde dich in X-Sitter an, klicke oben rechts auf deinen Namen und dann auf **Einstellungen**.
2. Wähle im Menü links **API Zugang**. Fehlt der Eintrag, hat dein Benutzer kein Recht dafür; frag den Administrator deiner Firma.
3. Trage im Bereich **API-Token** eine **Bezeichnung** ein, an der du später erkennst, wofür der Token ist (z. B. „ERP-Anbindung“).
4. Optional: Setze unter **Gültig bis** ein Datum. Leer bedeutet unbegrenzt.
5. Hake die **Rechte** an, die der Token braucht, und nur diese. X-Sitter bietet nur Rechte an, die dein Benutzer auch in X-Sitter selbst hat.
6. Klicke auf **Token anlegen**.
7. Der Token (er beginnt mit `xst_`) wird **genau einmal** angezeigt. Kopiere ihn sofort und hinterlege ihn in deinem System. X-Sitter speichert nur einen Hash und kann ihn dir später nicht mehr anzeigen.

Die Liste darunter zeigt alle Tokens deiner Firma mit ihren Rechten, ihrem Ablaufdatum und wann sie **Zuletzt benutzt** wurden. Dort kannst du einen Token jederzeit **sperren** (und wieder **aktivieren**) oder **löschen**. Ein gelöschter Token funktioniert sofort nicht mehr.

!!!warning Behandle den Token wie ein Passwort
Wer den Token hat, kommt mit dessen Rechten an die Daten deiner Firma. Schick ihn nicht per E-Mail oder Chat, leg ihn nicht in öffentlich erreichbaren Code (z. B. JavaScript im Browser oder ein öffentliches Git-Repository) und lege für jedes angebundene System einen eigenen Token an. Ist ein Token in falsche Hände geraten, lösche ihn und lege einen neuen an.
!!!

## Rechte

Jeder Token bekommt seine Rechte beim Anlegen. Fehlt ihm das Recht für eine Adresse, antwortet die API mit `403 scope_missing` und nennt das fehlende Recht.

| Recht in X-Sitter | Technischer Name | Erlaubt |
|---|---|---|
| Bestand: lesen | `stock:read` | `GET /api/v1/stock`, `GET /api/v1/stock/{id}` |
| Artikel: lesen | `articles:read` | `GET /api/v1/articles`, `GET /api/v1/articles/{id}` |
| Artikel: anlegen | `articles:create` | `POST /api/v1/articles` |
| Artikel: ändern | `articles:update` | `PATCH /api/v1/articles/{id}` |
| Artikel: löschen | `articles:delete` | `DELETE /api/v1/articles/{id}` (nur Logistiker) |
| Lagerplätze: lesen / anlegen / ändern / löschen | `spots:read`, `spots:create`, `spots:update`, `spots:delete` | `/api/v1/spots` (nur Logistiker) |

In der Oberfläche heißen die Gruppen *Artikel*, *Bestand* und *Lagerplätze*, die Rechte *lesen*, *anlegen*, *ändern* und *löschen*.

## Logistiker und Mandanten

X-Sitter unterscheidet zwei Arten von Firmen:

- **Logistiker:** betreibt das Lager und verwaltet die Artikel seiner Kunden.
- **Mandant:** ein Kunde eines Logistikers, dessen Ware dort gelagert und versendet wird.

Ein Token gilt immer für die Firma, in der er angelegt wurde. Als **Mandant** musst du sonst nichts tun: Du siehst automatisch nur deine eigenen Artikel und deren Bestand.

Als **Logistiker** kannst du deinen Token auch im Namen eines deiner Mandanten verwenden. Schick die Firmennummer des Mandanten im Header `X-Company` (oder im Parameter `company`). Die Rechte bleiben die deines Tokens.

```bash
curl https://app.x-sitter.com/api/v1/stock \
  -H "Authorization: Bearer xst_YOUR_TOKEN" \
  -H "X-Company: 27"
```

## Listen seitenweise abrufen

Adressen, die Listen liefern, antworten seitenweise. `page` wählt die Seite, `per_page` die Anzahl der Einträge je Seite (Standard 25, höchstens 500). `meta` sagt dir, wie viele Einträge und Seiten es insgesamt gibt:

```json
"meta": { "page": 1, "per_page": 25, "total": 312, "total_pages": 13 }
```

Frag so lange die nächste Seite ab, bis `page` gleich `total_pages` ist. Ein Beispiel findest du in der Anleitung [Bestand abfragen](stock.md#schritt-5-alle-seiten-abrufen).

## Fehler

Geht etwas schief, antwortet die API mit einem passenden HTTP-Status und immer derselben Struktur:

```json
{
  "error": {
    "code": "scope_missing",
    "message": "The token has no right for stock:read.",
    "details": { "scope": "stock:read" }
  }
}
```

Werte in deinem Programm den `code` aus, nicht den Text der `message`. Der Text kann sich ändern.

| Status | Bedeutung | Häufige Codes |
|---|---|---|
| 400 | Die Anfrage kann nicht gelesen werden, z. B. hat ein Parameter das falsche Format | `invalid_parameter`, `invalid_json`, `invalid_company` |
| 401 | Kein Token geschickt, oder er ist unbekannt, gesperrt oder abgelaufen | `missing_token`, `invalid_token` |
| 403 | Der Token darf das nicht | `scope_missing`, `company_not_allowed`, `stock_not_visible` |
| 404 | Unter dieser Adresse gibt es nichts | `article_not_found`, `spot_not_found`, `route_not_found` |
| 405 | Die Methode passt nicht zur Adresse (der Header `Allow` nennt die erlaubten) | `method_not_allowed` |
| 409 | Gerade nicht möglich, z. B. ist die Artikelnummer schon vergeben | `article_number_taken`, `spot_in_use` |
| 422 | Ein Wert im Request-Body wird nicht akzeptiert | `invalid_article_value`, `invalid_spot_value` |
| 500 | Fehler auf dem Server | `internal_error` |

Bei einem 500 versuch es nach einer kurzen Pause noch einmal. Kommt der Fehler immer wieder, wende dich über **Ticket erstellen** in der Fußzeile von X-Sitter an den Support und schick Uhrzeit, Adresse und Antwort mit (aber niemals den Token).