Produkte
Die Katalogebene — Produkte, Bilder, Chargen. Ein Produkt kann viele Pässe haben (einen pro serialisierter Einheit).
/api/v1/productsProdukt anlegen
Erstellt ein Produkt. Die Kategorienvorlage wird automatisch aus dem `category`-Slug aufgelöst — muss einer gesäten Kategorie entsprechen (z. B. `batteries`, `textiles`, `jewelry`). Modell-Strings sind innerhalb des Workspaces eindeutig.
/api/v1/products/{id}Einzelnes Produkt lesen
Liest ein Produkt per ID. Gibt das vollständige Dokument zurück, einschließlich Standard-Feldwerte, Bild-URLs, Template-Referenz und laufendem `passportCount`. Zählt als ein v1-Lesevorgang.
/api/v1/productsProdukte auflisten
Paginierte Liste aller Produkte des Workspaces, absteigend nach `createdAt` sortiert. Seitengröße max. 100. Filter nach Kategorie-Slug, Status (`active` / `archived`) oder Freitextsuche über name + model.
/api/v1/products/{id}Produkt aktualisieren
Patcht ein oder mehrere Produktfelder. Senden Sie nur die Schlüssel, die Sie ändern möchten — ausgelassene Felder bleiben unverändert. Die Ganz-Array-Semantik von `imageUrls` ist beabsichtigt: Das Kunden-CMS ist die kanonische Bildquelle, also ersetzt ein PATCH mit `imageUrls: ["a","b"]` die vorhandene Liste. Zum Anhängen eines einzelnen Bildes ohne Umschreiben nutzen Sie den Multipart-Upload-Endpoint.
/api/v1/products/{id}/imagesProduktbild hochladen
Lädt eine einzelne Bilddatei hoch (multipart/form-data, Feldname `file`) und hängt sie an das `imageUrls`-Array des Produkts an. Nützlich, wenn keine CDN-URL bereitsteht — das Bild landet in unserem R2-Bucket und die öffentliche URL wird in der Antwort zurückgegeben.
/api/v1/products/{id}/archiveProdukt archivieren
Soft-Archivierung. `Product.status` wechselt zu `archived`; das Produkt verschwindet aus den Standard-Listen (mit dem `?showArchived=true`-Filter weiterhin sichtbar). Bestehende Pässe lösen weiterhin auf — Archivieren blockiert die Erstellung NEUER Pässe gegen dieses Produkt fortan, es zerstört keinen QR-Code, der bereits bei Kunden ist.
/api/v1/products/{id}Produkt dauerhaft löschen
**Dauerhaft und unumkehrbar.** Entfernt die Produkt-Zeile + alle hochgeladenen Dokumente, deren einzige Referenz dieses Produkt war (Dokumente, die mit anderen Produkten/Pässen verknüpft sind, bleiben erhalten, nur ohne `productId`). Der R2-Speicher unter `<companyId>/products/<productId>/` wird bereinigt.