Pässe
Pässe erstellen, aktualisieren, suspendieren, archivieren und massenimportieren. Inklusive parties-Block für Wirtschaftsakteurs-Ketten.
/api/v1/passportsPass anlegen
Erstellt einen einzelnen Digitalen Produktpass. Der Pass ist an ein Produkt gebunden (productId) und durch eine GS1 GTIN + eine innerhalb dieser GTIN eindeutige Seriennummer identifiziert. Neue Pässe starten im Status `draft` — Felder werden über nachfolgende PATCH-Aufrufe befüllt und der Pass wird nach Abschluss der Prüfung über das Dashboard veröffentlicht.
/api/v1/passports/{id}Einzelnen Pass lesen
Liest einen Pass per ID. Die Standardantwort enthält den vollständigen Pass — übersetzbare Felder tragen ihren `sourceLocale` und eine `translations`-Karte pro Locale. Mit `?lang=<locale>` löst der Server jedes Feld über die Public-Viewer-Kette auf (Viewer-Locale-Übersetzung → Quelllocale-Wert → Englisch → erste angewandte → universelle Quelle) und gibt einen aufgelösten Wert pro Feld zurück; die `translations`-Karte entfällt bei lang-aufgelösten Antworten.
/api/v1/passportsPässe auflisten
Paginierte Liste der Pässe des Workspaces. Filter nach `productId`, `status` oder Freitextsuche über GTIN und Seriennummer. Wird gegen das tägliche Passport-Lese-Budget gezählt (`maxV1PassportsPerDay`); die Antwort-Items verwenden dieselbe Form wie der Einzel-Lese-Endpoint, aber auf die Listing-Felder gekürzt.
/api/v1/passports/{id}/fields/{key}Einzelnes Feld in einem Pass aktualisieren
Patcht ein einzelnes Feld auf einem Pass. Der Wert wird gegen den Feldschlüssel validiert (muss in der Vorlage des Passes vorhanden sein) und mit einem Audit-Trail-Eintrag persistiert, der mit `via API key <prefix>` gekennzeichnet ist. Bevorzugen Sie das gegenüber dem Schreiben der gesamten `fields`-Karte, wenn Sie nur eine Zahl aktualisieren müssen — das ist ein kleinerer Schreibvorgang und der Audit-Eintrag ist das, was Dashboard-Prüfer sehen.
/api/v1/passports/{id}/parties/{role}Wirtschaftsakteurs-Partei upsert
Erstellt oder ersetzt die Party für eine Rolle auf einem Pass. Das Pfad-Segment role bestimmt den Slot — `manufacturer`, `importer`, `authorisedRepresentative`, `distributor`, `recycler`, `producerResponsibilityOrg`. Zweimaliges Senden derselben Rolle ist ein Upsert: der bestehende Block wird atomar ersetzt.
/api/v1/passports/{id}/suspendPass suspendieren
Reversibles Suspendieren. Der öffentliche Viewer schaltet auf die Suspended-Seite (HTTP 423 mit strukturiertem Body); QR-Scans sterben effektiv, ohne dass die URL auf 404 geht. Verwenden Sie das für Rückrufe, Streitigkeiten, interne Holds oder Qualitätsuntersuchungen. Erneut veröffentlichen über das Dashboard nach der Klärung.
/api/v1/passports/{id}/archivePass archivieren (unumkehrbar)
**Unumkehrbar.** Der öffentliche Viewer gibt 404 zurück, die GS1-Digital-Link-URL löst nicht mehr auf, der QR-Code stirbt endgültig. Nur für Produkte verwenden, die nie ausgeliefert wurden — das Archivieren eines Passes für ein Produkt, das bereits bei Kunden ist, zerstört jeden QR-Scan, den sie je damit machen werden.
/api/v1/passports/batchPässe im Batch erstellen
Erstellt bis zu 100 Pässe in einem Aufruf. Jedes Element trägt dieselbe Body-Form wie die Einzel-Create-Endpoint (`{ productId, gs1: { gtin, serialNumber }, parties?, confirmOverage? }`). Teilerfolg pro Element — jedes bekommt seinen eigenen Status im Antwort-Array.