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>`). Alle fünf EN-18219-Schemas lösen zum selben öffentlichen Viewer auf. 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}/registry-upiAdresse eines Batteriepasses für das EU DPP Registry abrufen
Liefert die eindeutige Produktkennung (UPI), die in das Online-Formular des EU DPP Registry eingefügt wird, für einen veröffentlichten **Batteriepass**, als `{ upi, preparedAt }`. Der Wirtschaftsakteur registriert den Pass auf der Website des Registry mit seinem eigenen EU Login (Product group: Batteries; Granularity: Item). TracePass bereitet die Adresse vor und hält fest, dass es das getan hat; es reicht nie etwas beim Registry ein.
/api/v1/registry/upload-fileUpload-Datei für das EU DPP Registry zu Batteriepässen erstellen
Erstellt die XML-Datei, die der Wirtschaftsakteur auf der Website des EU DPP Registry hochlädt (DPP Registration → upload a file), für die von Ihnen genannten **Batteriepässe**, bis zu 100 pro Aufruf. Die Registrierung ist eine eigene Handlung des Wirtschaftsakteurs mit seinem eigenen EU Login; TracePass bereitet die Datei vor und reicht sie nie ein.
/api/v1/passports/{id}/registrationErgebnis des EU DPP Registry für einen Batteriepass erfassen
Erfasst, was der Wirtschaftsakteur von der Website des EU DPP Registry zu einem veröffentlichten **Batteriepass** meldet. TracePass hält die Angabe des Wirtschaftsakteurs fest und prüft sie nicht beim Registry nach. Der Body hat eine von zwei Formen, gewählt über `environment`.
/api/v1/passports/{id}/registrationIrrtümlich erfasstes Ergebnis des EU DPP Registry zurücknehmen
Löscht ein mit `POST /api/v1/passports/{id}/registration` erfasstes Ergebnis; der Pflicht-Query-Parameter `environment` sagt, welches. Im EU DPP Registry selbst ändert sich dadurch nichts: Korrigiert wird, was TracePass zum Pass festhält. Die Rücknahme wird protokolliert.
/api/v1/passports/{id}/place-on-marketBatteriepass an die API eines Registers nach EN 18222 senden
Sendet einen veröffentlichten **Batteriepass** an ein Register, das den Aufruf `registerDPP` nach EN 18222 annimmt, mit dem für Ihr Konto eingerichteten Zugang zur Register-API (ein API-Schlüssel oder ein Bearer-Token), der Eintrag erfolgt also mit Ihren eigenen Zugangsdaten. Nur Batteriepässe.
/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, es sei denn, der Pass wurde an einen neuen Anbieter weitergeleitet. 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}/mark-for-deletionPass zur Löschung markieren
**Schritt eins von zwei.** Ein Pass wird in zwei Schritten gelöscht: hier zur Löschung markieren, dann `DELETE /api/v1/passports/{id}` aufrufen (ein nie veröffentlichter Pass im Status `draft` oder `in_review` kann direkt gelöscht werden). Die Löschung ist ein Soft Delete: Es wird nichts vernichtet, aber der Pass verschwindet aus der API und von allen öffentlichen Oberflächen. Wer den QR-Code scannt, sieht eine Seite mit dem Hinweis, dass der Pass beendet ist, und die maschinenlesbaren Formate antworten mit `410 Gone`.
/api/v1/passports/{id}Pass löschen
**Ein zur Löschung markierter Pass → Soft Delete.** Ein Pass, der veröffentlicht wurde, wird in zwei Schritten gelöscht: zuerst `POST /api/v1/passports/{id}/mark-for-deletion`, dann dieses DELETE. Es wird nichts vernichtet: Der Pass verschwindet aus der API (jeder v1-Aufruf dazu antwortet ab dann mit `404`) und von allen öffentlichen Oberflächen. Wer den QR-Code scannt, sieht eine Seite mit dem Hinweis, dass der Pass beendet ist, und die maschinenlesbaren Formate antworten mit `410 Gone`. Gibt den Pass mit `status: "deleted"` zurück und sendet den `passport.deleted`-Webhook.
/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? }`). 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 Pass zurück, zuletzt empfangene zuerst (nach `receivedAt`). 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`.
/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`.