X-Sitter API

Überblick über die REST-API von X-Sitter – Tokens, Rechte, Logistiker und Mandanten, seitenweise Abfrage, Fehler

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_...`

Schritt für Schritt

Anleitungen: Bestand abfragen und Artikel lesen und pflegen.

Was die API kann

Bereich	Adressen	Für wen
Bestand	`GET /api/v1/stock`, `GET /api/v1/stock/{id}`	Logistiker und Mandanten (Mandanten nur, wenn ihr Logistiker es erlaubt)
Artikel	`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:

Melde dich in X-Sitter an, klicke oben rechts auf deinen Namen und dann auf Einstellungen.
Wähle im Menü links API Zugang. Fehlt der Eintrag, hat dein Benutzer kein Recht dafür; frag den Administrator deiner Firma.
Trage im Bereich API-Token eine Bezeichnung ein, an der du später erkennst, wofür der Token ist (z. B. „ERP-Anbindung“).
Optional: Setze unter Gültig bis ein Datum. Leer bedeutet unbegrenzt.
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.
Klicke auf Token anlegen.
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.

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.

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:

"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.

Fehler

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

{
  "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).