Plattform-API Referenz

Die Plattform-API stellt alle Shop-Daten über HTTP bereit. Alle Endpunkte beginnen mit /api2/v1/ und erfordern einen API-Schlüssel als Bearer-Token.

Allgemeines

Paginierungsformat

Listenendpunkte geben eine einheitliche Hülle zurück:

{
  "data": [ ... ],
  "meta": {
    "page": 1,
    "per_page": 50,
    "total": 243,
    "total_pages": 5
  }
}

Fehlerformat

{ "error": "Fehlerbeschreibung" }

Status	Bedeutung
`400`	Pflichtfeld fehlt oder Validierungsfehler
`401`	API-Schlüssel fehlt oder ungültig
`403`	Schlüssel hat keine Schreibberechtigung
`404`	Ressource nicht gefunden
`409`	Konflikt (z. B. Kategorie mit Produkten löschen)

Produkte

Produkte auflisten

GET /api2/v1/products

Parameter	Typ	Standard	Beschreibung
`page`	number	1	Seitennummer
`per_page`	number	50	Einträge pro Seite (max. 200)
`search`	string	—	Suche nach Name oder SKU
`status`	string	—	Status filtern (z. B. `active`, `draft`)
`category_id`	number	—	Nach Kategorie-ID filtern

curl https://ihr-shop.de/api2/v1/products?search=bett&status=active \
  -H "Authorization: Bearer <schlüssel>"

Einzelnes Produkt

GET /api2/v1/products/:id

Gibt vollständige Produktdaten zurück: Bilder, Varianten, Attribute, SEO-Felder.

Produkt erstellen

POST /api2/v1/products
Content-Type: application/json

Pflichtfelder: name, price. Der URL-Slug wird automatisch generiert.

{ "name": "Zirbenbett Alpin", "price": 2190.00 }

Produkt aktualisieren

PUT /api2/v1/products/:id

Nur die übermittelten Felder werden geändert. Gibt das vollständig aktualisierte Produkt zurück.

Produkt löschen

DELETE /api2/v1/products/:id

{ "deleted": true, "id": 42, "name": "Zirbenbett Alpin" }

Bestellungen

Bestellungen auflisten

GET /api2/v1/orders

Parameter	Typ	Beschreibung
`status`	string	Nach Bestellstatus filtern
`date_from`	ISO-Datum	Zeitraum-Beginn (z. B. `2026-01-01`)
`date_to`	ISO-Datum	Zeitraum-Ende (inklusive 23:59:59)

curl "https://ihr-shop.de/api2/v1/orders?status=processing&date_from=2026-01-01" \
  -H "Authorization: Bearer <schlüssel>"

Einzelne Bestellung

GET /api2/v1/orders/:id

Gibt vollständige Bestelldaten zurück: Positionen, Adressen, Zahlungsmethode, Steuer, Statusverlauf.

Bestellstatus aktualisieren

PUT /api2/v1/orders/:id
Content-Type: application/json

{ "status": "completed", "note": "Versandt per DHL" }

Ungültige Statusübergänge (z. B. von completed zurück auf pending) geben 400 mit den erlaubten Übergängen zurück. Erfordert read_write-Schlüssel.

Bestellungen können über diese API weder erstellt noch gelöscht werden.

Kategorien

Kategorien auflisten

GET /api2/v1/categories

Parameter	Typ	Standard	Beschreibung
`page`	number	1	Seitennummer
`per_page`	number	50	Einträge pro Seite

Einzelne Kategorie

GET /api2/v1/categories/:id

Gibt Unterkategorien, übergeordnete Breadcrumb-Kette und SEO-Felder zurück.

Kategorie erstellen

POST /api2/v1/categories
Content-Type: application/json

{ "name": "Massivholzbetten" }

Der URL-Slug wird automatisch generiert.

Kategorie aktualisieren

PUT /api2/v1/categories/:id

Gibt { category, diff } zurück.

Kategorie löschen

DELETE /api2/v1/categories/:id

Gibt 409 zurück, wenn die Kategorie noch Unterkategorien oder zugewiesene Produkte hat. Entfernen oder verschieben Sie diese zuerst.

Kunden

Kunden auflisten

GET /api2/v1/customers

Parameter	Typ	Beschreibung
`search`	string	Suche nach Name oder E-Mail
`is_b2b`	boolean	`true` = nur B2B-Kunden, `false` = nur Privatkunden
`page`	number	Seitennummer
`per_page`	number	Einträge pro Seite

E-Mail-Adressen werden in der Listenansicht maskiert (z. B. s***@example.com). Die vollständige E-Mail steht nur in der Detailansicht zur Verfügung.

Einzelner Kunde

GET /api2/v1/customers/:id

Gibt vollständige Kontaktdaten, Adressen, die letzten 10 Bestellungen, B2B-Gruppeninfo und Notizen zurück.

Kunden können über diese API weder erstellt, bearbeitet noch gelöscht werden.

Lagerbestand (Inventory)

Lagerbestand abrufen

GET /api2/v1/inventory/stock

Gibt pro Zeile zurück: Produktname, Lager, Gesamtmenge, reservierte Menge, verfügbare Menge.

Artikel unter Mindestbestand

GET /api2/v1/inventory/low-stock?threshold=3

Sortiert nach Dringlichkeit (niedrigste verfügbare Menge zuerst).

Bestandskorrektur erstellen

POST /api2/v1/inventory/adjustments
Content-Type: application/json

{
  "productId": 42,
  "warehouseId": 1,
  "quantity": -5,
  "reason": "Beschädigt"
}

Gibt Vorher/Nachher-Mengen zurück. Negative Endmengen (unter 0) werden abgelehnt (400). Erfordert read_write-Schlüssel.

Lager auflisten

GET /api2/v1/inventory/warehouses

Gibt jedes Lager mit Gesamtartikelanzahl und Gesamtmenge zurück. Keine Paginierung.

Blog

Beiträge auflisten

GET /api2/v1/blog

Parameter	Typ	Beschreibung
`search`	string	Volltextsuche im Titel
`status`	string	Status filtern (z. B. `published`, `draft`)
`page`	number	Seitennummer
`per_page`	number	Einträge pro Seite

Einzelner Beitrag

GET /api2/v1/blog/:id

Beitrag erstellen

POST /api2/v1/blog
Content-Type: application/json

{ "title": "Die Vorteile von Zirbenholz", "status": "draft" }

Beitrag aktualisieren

PUT /api2/v1/blog/:id

Das Löschen von Blog-Beiträgen ist über diese API nicht möglich.

Seiten

Seiten auflisten

GET /api2/v1/pages?status=published

Einzelne Seite

GET /api2/v1/pages/:id

Gibt Sektionsanzahl mit zurück. Seiten-IDs sind Strings (z. B. "home", "about").

Seite erstellen

POST /api2/v1/pages
Content-Type: application/json

{ "title": "Über uns" }

Seite aktualisieren / löschen

PUT /api2/v1/pages/:id
DELETE /api2/v1/pages/:id

Löschen gibt 409 zurück, wenn die Seite untergeordnete Inhalte (Sektionen) enthält.

Medien

Medien auflisten

GET /api2/v1/media

Parameter	Typ	Beschreibung
`search`	string	Suche im Dateinamen
`mime_type`	string	MIME-Typ filtern (z. B. `image/jpeg`)
`needs_metadata`	boolean	Nur Dateien ohne Metadaten anzeigen
`page`	number	Seitennummer
`per_page`	number	Einträge pro Seite

Metadaten aktualisieren

PUT /api2/v1/media/:id
Content-Type: application/json

{ "alt": "Zirbenbett Detailansicht", "title": "Kopfteil Nahaufnahme" }

Datei löschen

DELETE /api2/v1/media/:id

Entfernt Datei auf dem Server und den Datenbankeintrag.

Neue Dateien können nur über die Medienbibliothek im Admin-Bereich hochgeladen werden.

Einstellungen

Einstellungen lesen

GET /api2/v1/settings

Gibt 404 zurück, wenn der Shop noch keine Einstellungen konfiguriert hat.

Einstellungen aktualisieren

PUT /api2/v1/settings
Content-Type: application/json

Alle Felder sind optional. Gibt das vollständig aktualisierte Einstellungs-Objekt zurück.

Versand

Versandzonen auflisten

GET /api2/v1/shipping/zones

Jede Zone enthält die Anzahl der darin konfigurierten Versandmethoden.

Zone erstellen / aktualisieren / löschen

POST /api2/v1/shipping/zones
PUT  /api2/v1/shipping/zones/:id
DELETE /api2/v1/shipping/zones/:id

{ "name": "Deutschland" }

Versandmethode erstellen / aktualisieren / löschen

POST /api2/v1/shipping/methods
PUT  /api2/v1/shipping/methods/:id
DELETE /api2/v1/shipping/methods/:id

Pflichtfelder beim Erstellen: name, methodType, zoneId.

{ "name": "Standard", "methodType": "flat_rate", "zoneId": 2 }

SEO & Weiterleitungen

SEO-Einstellungen lesen / aktualisieren

GET /api2/v1/seo/settings
PUT /api2/v1/seo/settings

PUT arbeitet als Upsert — legt die Einstellungen an, falls noch keine vorhanden sind.

SEO-Regeln

GET    /api2/v1/seo/rules?is_active=true
POST   /api2/v1/seo/rules
PUT    /api2/v1/seo/rules/:id
DELETE /api2/v1/seo/rules/:id

Pflichtfelder beim Erstellen: ruleName, targetType, createdBy.

URL-Weiterleitungen

GET    /api2/v1/seo/redirects?search=alte-url&enabled=true
POST   /api2/v1/seo/redirects
PUT    /api2/v1/seo/redirects/:id
DELETE /api2/v1/seo/redirects/:id

{ "source": "/alte-seite", "destination": "/neue-seite" }

Übersetzungen

Übersetzungen auflisten

GET /api2/v1/translations?entity_type=product&language_code=en

Parameter	Typ	Beschreibung
`entity_type`	string	Entitätstyp (z. B. `product`, `category`)
`language_code`	string	Sprachcode (z. B. `en`, `fr`)
`page`	number	Seitennummer
`per_page`	number	Einträge pro Seite

Übersetzung erstellen oder aktualisieren

POST /api2/v1/translations
Content-Type: application/json

{
  "entityType": "product",
  "entityId": 42,
  "languageCode": "en",
  "data": { "name": "Zirben Bed Alpine", "description": "..." }
}

Verwendet Upsert-Semantik — aktualisiert eine bestehende Übersetzung oder legt eine neue an.

Übersetzung löschen

DELETE /api2/v1/translations/:id