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/passports/{id}/qrPass-QR rendern
Liefert einen frisch gerenderten QR-Code für den Pass, der dessen effektive Bezeichner-URI kodiert. Bei GS1-Pässen ist dies die GS1-Digital-Link-URI (`/01/<gtin>/21/<serial>`); bei ISO 15459 der Resolver-Pfad; bei iec61406-, did- und doi-Pässen der `/x/<scheme>/<encodedValue>`-Resolver-Pfad (z. B. `https://id.tracepass.eu/x/did/<encodedDid>`). Der Resolver-Host schreibt `/x/*` zu `/p/x/*` um, sodass derselbe Viewer alle fünf EN-18219-Schemas bedient. Nutzen Sie dies, wenn Sie unseren Renderer wollen (konsistente Quiet Zone, Fehlerkorrektur, optionales Branding), statt die URI selbst zu kodieren. Standard ist `image/svg+xml`; `?format=png` liefert ein PNG und `?format=json` einen `{ result: "<svg>" }`-Wrapper zum Einbetten.
/api/v1/passports/{id}/compliancePass-Konformität prüfen
Liefert ein dreistufiges Konformitätsurteil für einen Pass — `compliant`, `compliant_with_warnings` oder `incomplete` — zusammen mit regulierungsbezogenen Findings, sodass eine Integration einen Pass prüfen, die genannten Lücken beheben und erneut aufrufen kann, um zu bestätigen. Diese Kette prüfen → beheben → verifizieren ist der Zweck: Die Antwort sagt dem KI-Agenten genau, was als Nächstes zu setzen ist.
/api/v1/passports/{id}/registry-readinessRegistry-Bereitschaft des Passes prüfen
Liefert, ob ein Pass die **formale Einreichungsprüfung des EU DPP Registry** bestehen würde — `{ ready, findings[] }`. Dies ist die *mechanische* Vorabprüfung des Registry, verschieden von und ergänzend zum substanziellen `/compliance`-Urteil: Ein Pass kann Registry-bereit sein, ohne substanziell konform zu sein, und umgekehrt. Rufen Sie sie vor der Einreichung beim Registry auf, um formale Lücken früh zu erkennen.
/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 die Zugangsdaten nennt (`via API key <prefix>` oder `via OAuth app <client>`) und, wenn der Header `X-Source` gesetzt ist, den aufrufenden Client, z. B. `(mcp)`. 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/{id}Pass dauerhaft löschen
**Dauerhaft und unumkehrbar** — die Pass-Zeile plus alle kaskadierten Abhängigkeiten werden aus der Datenbank entfernt. Die Kaskade umfasst KI-Extraktionen, Agent-Session-Zustand, ausschließlich an diesen Pass gebundene Lieferantenanfragen, Scan- und Serviceereignisse sowie hochgeladene Dokumente, deren einzige Referenz dieser Pass war (Dokumente, die mit anderen Pässen/Produkten geteilt werden, bleiben erhalten). Der R2-Speicher unter dem Ordner des Passes wird ebenfalls bereinigt.
/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.
/api/v1/passports/{id}/snapshotsPassport-Snapshots auflisten
Gibt eine seitenweise Liste von Unveränderlichkeits-**Snapshots** eines Passes zurück, neueste zuerst. Ein Snapshot wird bei der Veröffentlichung und nach jeder Änderung eines veröffentlichten, ausgesetzten, abgelaufenen oder archivierten Passes geschrieben — Feldwerte, Übersetzungen, Beteiligte, Statuswechsel, Lieferantenantworten, KI-Schreibvorgänge, Wiederherstellungen —, sofern sich der Inhalt des Passes tatsächlich geändert hat (EN 18221:2026, 4.2). Jeder Eintrag enthält die Snapshot-ID, Versionsnummer, Grund (z. B. `published`, `field_edit`, `status_change`, `baseline`), den Verursacher (`actor`, sofern bekannt), Zeitstempel, Content-Hash und ob der Hash noch stimmt — `hashValid: false` zeigt eine At-Rest-Manipulation an.
/api/v1/passports/{id}/snapshots/{snapshotId}Passport-Snapshot abrufen
Gibt den vollständigen Archiv-Datensatz für einen Unveränderlichkeits-**Snapshot** zurück: den vollständigen JSON-LD-Payload genau so, wie der Pass bei Erstellung des Snapshots war — bei der Veröffentlichung oder nach jeder Änderung an einem veröffentlichten, ausgesetzten, abgelaufenen oder archivierten Pass —, die Snapshot-Metadaten (Version, Grund, `actor` — wer die Änderung verursacht hat — und Zeitstempel) und die Content-Hash-Re-Verifizierung. Für die zu einem bestimmten Datum gültige Fassung verwenden Sie `?at=` bei **Passport-Snapshots auflisten**. `hashValid: false` bedeutet, dass der gespeicherte Payload seit der Snapshot-Erstellung geändert wurde — ein Indiz für At-Rest-Manipulation.
/api/v1/passports/{id}/condition-flagsKlassifizierungs-Flags lesen
Gibt das aufgelöste **Condition Profile** für einen Pass zurück — `Record<flagKey, { value, status, source }>`. Condition Flags sind von einem Prüfer genehmigte Ja/Nein-Fakten über ein Produkt, die bedingte rechtliche Pflichten auslösen. Für Batteriepässe nach Verordnung (EU) 2023/1542 sind die registrierten Flags: `hasBMS` (Batteriemanagementsystem vorhanden), `rechargeable` (Batterie ist aufladbar), `externalStorageOnly` (Art. 8-Ausnahme gilt), und `isStationaryBess` (stationäres Batterie-Energiespeichersystem). Kategorien ohne registrierte Flags geben ein leeres Profil zurück.
/api/v1/passports/{id}/condition-flagsKlassifizierungs-Flags setzen
Schreibt ein oder mehrere Condition Flags auf einen Pass. Der Anfragekörper ist `Record<flagKey, boolean | null>` — `true` oder `false` setzt das Flag; `null` löscht es. Nur Schlüssel, die für die Kategorie des Passes registriert sind, werden akzeptiert; unbekannte Schlüssel geben 400 mit den gültigen Schlüsseln für diese Kategorie zurück.
/api/v1/passports/{id}/measurementsMesswerte erfassen
**Nur für Batteriepässe** (Verordnung (EU) 2023/1542 Art. 77, Anhang XIII Punkt 4 — Nutzungsdaten). Der Pass muss veröffentlicht sein; ein Entwurf oder ausgesetzter Pass gibt 422 `passport_not_active` zurück. Ein Nicht-Batteriepass gibt 422 `not_a_battery` zurück. Senden Sie 1–500 Messwerte pro Aufruf, jeweils als `{ fieldKey, value, measuredAt, externalId?, unit? }` — `measuredAt` ist ein ISO-8601-Zeitstempel, der nicht in der Zukunft liegen darf; `value` darf serialisiert **maximal 16 KB** groß sein (ein größerer Wert gibt 400 `invalid_value` zurück). Die akzeptierten `fieldKey`s sind die Nutzungsdatenfelder aus Anhang XIII Punkt 4: `stateOfHealth`, `stateOfCertifiedEnergy`, `remainingCapacity`, `remainingPowerCapability`, `remainingRoundTripEfficiency`, `evolutionOfSelfDischargeRate`, `currentInternalResistancePack`, `capacityFade`, `powerFade`, `internalResistanceIncrease`, `dynamicRatedCapacity`, `dynamicPowerCapability`, `dynamicInternalResistance`, `dynamicEnergyRoundTripEfficiency`, `dynamicExpectedLifetimeCycles`, `numberOfFullEquivalentChargingCycles`, `numberOfChargingEvents`, `currentStateOfCharge`, `negativeEvents`, `temperatureConditionsHistorical`.
/api/v1/passports/{id}/measurementsMesswerthistorie abrufen
Gibt den vollständigen Messwert-Verlauf für einen Batteriepass zurück, neueste zuerst (nach `measuredAt`). Jeder Eintrag ist ein `PassportMeasurement`-Objekt mit `_id`, `passportId`, `fieldKey`, `value`, `measuredAt`, `receivedAt`, `externalId?`, `unit?`, `materialized` (ob dieser Eintrag zum aktuellen Feldwert des Passes wurde) und `source`. **Nur Batteriepässe** — ein Nicht-Batteriepass gibt 422 `not_a_battery` zurück.
/api/v1/passports/{id}/measurements/latestAktuelle Messwerte abrufen
Gibt den neuesten Messwert für jedes der akzeptierten Nutzungsdatenfelder aus Anhang XIII Punkt 4 zurück. Die Antwort ist `{ data: { <fieldKey>: LatestMeasurement | null } }` — alle akzeptierten Schlüssel sind immer vorhanden; ein Schlüssel ist `null`, wenn für das betreffende Feld noch kein Messwert eingegangen ist. Eine `LatestMeasurement` enthält `value`, `measuredAt` sowie optional `unit` und `externalId`. **Nur Batteriepässe** — ein Nicht-Batteriepass gibt 422 `not_a_battery` zurück.