Produkte API

Die Produkte-API erlaubt das Lesen, Erstellen, Aktualisieren und Löschen von Produkten. Lesende Endpunkte sind öffentlich zugänglich (für Produkt-Feeds); schreibende Endpunkte erfordern Admin-Authentifizierung.

Endpunkte

Produkte auflisten

GET /api2/admin/products

Gibt alle nicht-versteckten Produkte zurück. Dieser Endpunkt ist öffentlich (kein Auth-Token erforderlich) und wird für Produkt-Feeds wie Google Shopping genutzt.

Antwort:

[
  {
    "id": 42,
    "sku": "BEDIKB180X200",
    "name": "Zirbenbett Königstein",
    "price": 2490.00,
    "description": "Massives Zirbenbett...",
    "brand": "Bodensee Möbel"
  }
]

---

Produkt suchen

GET /api2/admin/products/search?q=zirbe&category=betten&limit=20&offset=0

Parameter	Typ	Beschreibung
q	string	Suchbegriff
category	string	Nach Kategorie filtern
limit	number	Anzahl Ergebnisse (Standard: 20)
offset	number	Seitenversatz für Paginierung

Erfordert Admin-Authentifizierung.

---

Produkt erstellen

POST /api2/admin/products
X-CSRF-Token: <csrf-token>
Content-Type: application/json

{
  "name": "Zirbenbett Königstein",
  "sku": "BEDIKB180X200",
  "price": 2490.00,
  "description": "Massives Zirbenbett aus Zirbenholz...",
  "categoryId": 3,
  "stock": 5,
  "isHidden": false
}

Die Produktanzahl wird gegen das Plan-Kontingent geprüft. Bei Erreichen des Limits wird 403 zurückgegeben.

SKU-Format: [Kategorie][Modell][Material][Größe] — Beispiel: BEDIKB180X200

Antwort (201):

{
  "id": 42,
  "sku": "BEDIKB180X200",
  "name": "Zirbenbett Königstein",
  "price": 2490.00,
  "createdAt": "2025-01-15T10:30:00Z"
}

---

Produkt abrufen

GET /api2/admin/products/{id}

Gibt das vollständige Produkt mit Kategorie, Bildern und Videos zurück.

Antwort:

{
  "id": 42,
  "sku": "BEDIKB180X200",
  "name": "Zirbenbett Königstein",
  "price": 2490.00,
  "description": "...",
  "category": {
    "id": 3,
    "name": "Betten",
    "slug": "betten"
  },
  "images": [
    {
      "id": 101,
      "url": "/uploads/bett-1.jpg",
      "alt": "Zirbenbett Vorderansicht",
      "sortOrder": 0
    }
  ],
  "videos": [],
  "stock": 5,
  "isHidden": false,
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-01-20T14:00:00Z"
}

---

Produkt aktualisieren

PATCH /api2/admin/products/{id}
X-CSRF-Token: <csrf-token>
Content-Type: application/json

{
  "price": 2690.00,
  "stock": 3,
  "isHidden": false
}

Nur explizit erlaubte Felder werden verarbeitet; unbekannte Felder werden stillschweigend ignoriert. Vor dem Speichern wird automatisch ein Versions-Snapshot angelegt. SEO-Metadaten werden nach dem Speichern automatisch aktualisiert.

---

Produkt löschen

DELETE /api2/admin/products/{id}
X-CSRF-Token: <csrf-token>

Löscht das Produkt inklusive aller Varianten, Kategoriezuordnungen und Bilder (Kaskaden-Löschung).

Antwort (200):

{ "success": true }

---

Produkte bulk-aktualisieren

POST /api2/admin/products/bulk-update
X-CSRF-Token: <csrf-token>
Content-Type: application/json

{
  "productIds": [42, 43, 44],
  "updates": {
    "isHidden": true
  },
  "changeReason": "Saisonende",
  "batchId": "batch-2025-01"
}

Verarbeitet Produkte nacheinander. Bei Fehlern bei einzelnen Produkten werden diese in errors[] gemeldet, aber bereits aktualisierte Produkte bleiben gespeichert (kein Rollback).

Antwort:

{
  "updated": 2,
  "errors": [
    { "productId": 44, "error": "Produkt nicht gefunden" }
  ]
}

---

Slug / SKU prüfen

GET /api2/admin/products/check-slug?slug=zirbenbett-koenigstein&excludeId=42
GET /api2/admin/products/check-slug?sku=BEDIKB180X200&excludeId=42

Prüft, ob ein Slug oder eine SKU bereits vergeben ist.

Antwort:

{ "exists": false }

---

Performance-Daten

GET /api2/admin/products/performance

Gibt Leistungsdaten der letzten 30 Tage zurück: meistverkaufte Produkte, Produkte mit geringem Lagerbestand und zuletzt angesehene Produkte.

---

Versionshistorie

Jedes PATCH erzeugt automatisch einen Versions-Snapshot.

GET /api2/admin/products/{id}/versions
GET /api2/admin/products/{id}/versions/{versionNumber}
GET /api2/admin/products/{id}/versions/compare?versionA=2&versionB=5
POST /api2/admin/products/{id}/versions/{versionNumber}/restore

---

Bilder verwalten

GET  /api2/admin/products/{id}/images
POST /api2/admin/products/{id}/images
DELETE /api2/admin/products/{id}/images/{imageId}

Bilder werden per Multipart-Upload hochgeladen. Maximale Dateigröße und erlaubte Formate sind in den Shop-Einstellungen konfiguriert.