🔌 Schnittstelle (API) v1.0

🔑 Anmeldung & Schlüssel

Jede Anfrage braucht deinen persönlichen API-Schlüssel im Kopf (Header) der Anfrage: X-API-Key: dein-schluessel Deinen Schlüssel erzeugst und verwaltest du in der Plattform unter Menü → Konto → Meine Daten → API-Zugang. Behandle ihn wie ein Passwort: Wer den Schlüssel hat, kann in deinem Namen arbeiten. Bei Verdacht auf Missbrauch einfach einen neuen erzeugen – der alte wird damit sofort ungültig. Du siehst und bearbeitest über die API ausschließlich deine eigenen Websites und Daten. Erlaubt sind bis zu 1000 Anfragen pro Stunde.

⚠️ Fehler & Status-Codes

Fehler kommen immer als JSON mit einer verständlichen Meldung: {"ok": false, "fehler": "Artikel 123 nicht gefunden"} Die wichtigsten Status-Codes: 200 (alles gut), 201 (angelegt), 400 (Eingabe fehlerhaft), 401 (Schlüssel fehlt oder ist falsch), 403 (gehört dir nicht), 404 (gibt es nicht), 429 (zu viele Anfragen – kurz warten).

📦 Die Objekte und ihre Felder

Artikel

Bestellung

Rechnung

POST /api/v1/clearing/nachrichten

EDI-Datei einliefern

Liefert eine EDI-Datei ins Clearing Center ein (Kanal „api“). Die Nachrichtenart wird automatisch erkannt – bei EDIFACT verbindlich aus dem UNH-Segment. Nur für Konten, die als Clearing-Teilnehmer freigeschaltet sind.

curl -X POST https://DEINE-PLATTFORM/api/v1/clearing/nachrichten \
  -H "X-API-Key: dein-schluessel" -F "datei=@katalog.edi"

Antwort: {"ok": true, "daten": {"id": 12, "typ": "PRICAT", "format": "edifact", "status": "verarbeitet"}}

GET /api/v1/websites

Eigene Websites auflisten

Liefert alle deine Websites mit Shop-Status. Die id brauchst du für alle weiteren Aufrufe.

Antwort: {"ok": true, "daten": [{"id": 9, "titel": "B&W Haarliebhaber", "slug": "b-w-haarliebhaber-f57612", "domain": "", "shop_aktiv": true, "shop_modus": "shop"}]}

GET /api/v1/websites/{website_id}/artikel

Artikel einer Website auflisten

Alle Artikel, auch unsichtbare.

Antwort: {"ok": true, "daten": [{"id": 12, "name": "Herrenhaarschnitt", "preis": 24.9, "kategorie": "Herren", "aktiv": true, …}]}

POST /api/v1/websites/{website_id}/artikel

Artikel anlegen

Legt einen neuen Artikel an. Nur name ist Pflicht.

curl -X POST https://DEINE-PLATTFORM/api/v1/websites/9/artikel \
  -H "X-API-Key: dein-schluessel" -H "Content-Type: application/json" \
  -d '{"name": "Haarwachs", "preis": 12.9, "kategorie": "Produkte"}'

Antwort: {"ok": true, "daten": {"id": 31, "name": "Haarwachs", …}}

PATCH /api/v1/artikel/{artikel_id}

Artikel ändern

Ändert nur die Felder, die du mitschickst – alles andere bleibt.

Antwort: {"ok": true, "daten": {"id": 31, "preis": 14.5, …}}

DELETE /api/v1/artikel/{artikel_id}

Artikel löschen

Endgültig – zum bloßen Verstecken lieber PATCH mit {"aktiv": false}.

Antwort: {"ok": true}

GET /api/v1/websites/{website_id}/bestellungen

Bestellungen auflisten

Neueste zuerst. Mit ?status=neu (oder in_arbeit, erledigt, storniert) filterst du.

curl https://DEINE-PLATTFORM/api/v1/websites/9/bestellungen?status=neu \
  -H "X-API-Key: dein-schluessel"

Antwort: {"ok": true, "daten": [{"id": 4, "name": "Max Käufer", "summe": 49.8, "status": "neu", "bezahlt": false, …}]}

GET /api/v1/bestellungen/{bestellung_id}

Eine Bestellung abrufen

Alle Details inklusive Positionen.

Antwort: {"ok": true, "daten": {"id": 4, "positionen": [{"name": "Herrenhaarschnitt", "preis": 24.9, "menge": 2}], …}}

PATCH /api/v1/bestellungen/{bestellung_id}

Bestellung bearbeiten

Status setzen, Zahlungseingang markieren oder die interne Notiz schreiben.

curl -X PATCH https://DEINE-PLATTFORM/api/v1/bestellungen/4 \
  -H "X-API-Key: dein-schluessel" -H "Content-Type: application/json" \
  -d '{"status": "erledigt", "bezahlt": true}'

Antwort: {"ok": true, "daten": {"id": 4, "status": "erledigt", "bezahlt": true, …}}

POST /api/v1/bestellungen/{bestellung_id}/rechnung

Rechnung aus Bestellung erstellen

Erstellt die Rechnung an deinen Käufer. Gibt es schon eine, bekommst du die vorhandene zurück (es entsteht nie eine doppelte). Mit hinterlegtem sevDesk-Token wird sie automatisch als Entwurf an dein sevDesk übergeben.

Antwort: {"ok": true, "daten": {"id": 2, "nummer": "S9-0002", "summe": 49.8, "status": "offen", …}}

GET /api/v1/websites/{website_id}/rechnungen

Rechnungen auflisten

Alle Rechnungen dieser Website, neueste zuerst.

Antwort: {"ok": true, "daten": [{"id": 2, "nummer": "S9-0002", "status": "offen", …}]}