# Pässe und Versionen > Der Pass einer Einheit, seine Status, seine signierten und unveränderlichen Versionen, die Unterschiede zwischen ihnen und die Exporte. Jede Einheit hat genau einen Pass. Jede Veröffentlichung fügt eine nummerierte Version hinzu, die sich danach nie mehr ändert. Ändern sich die Daten einer Einheit, wird der Pass erneut veröffentlicht und bekommt eine neue Version; die alten Versionen bleiben als Historie des Passes lesbar. ## Der Pass Den Pass einer Einheit lesen Sie mit [`getPassport`](https://passport.kabin.sh/docs/de/api-reference/passports/get-passport). | Feld | Bedeutung | | --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `passport_id` | Die dauerhafte Kennung `urn:dpp:{uuid}`, vergeben beim Sperren der Kennungen oder bei der ersten Veröffentlichung. Öffentliche Operationen erwarten den UUID-Teil als `passportId`. | | `status` | Siehe unten. | | `gs1_digital_link` | Der Link im QR-Code ([GS1 Digital Link](https://passport.kabin.sh/docs/de/concepts/digital-link)); fest, sobald die Kennungen gesperrt sind. | | `gtin`, `serial_number` | Die Kennungen der Einheit, wie sie gesperrt wurden. | | `current_version` | Zusammenfassung der Version, die gerade online ist. | | `first_published_at`, `identifiers_locked_at` | Wann der Pass zum ersten Mal online ging und wann seine Kennungen festgelegt wurden. | | `public_url` | Die öffentliche Passseite, sobald veröffentlicht. | | `withdrawn_at`, `withdrawn_reason` | Gesetzt, wenn der Pass offline genommen wurde. | Eine Einheit, deren Kennungen nicht gesperrt sind und die nie veröffentlicht wurde, hat einen Pass im Status `draft` ohne `passport_id`. ## Status ```mermaid stateDiagram-v2 [*] --> draft draft --> qr_locked: Kennungen gesperrt draft --> published: erste Veröffentlichung qr_locked --> published: erste Veröffentlichung published --> update_needed: Daten oder Register geändert update_needed --> published: erneut veröffentlicht published --> withdrawn: mit Begründung zurückgezogen ``` | `status` | Online | Bedeutung | | ------------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `draft` | Nein | Noch nichts veröffentlicht, keine Kennung. | | `qr_locked` | Nein | Kennungen gesperrt, damit Etiketten vor der ersten Veröffentlichung gedruckt werden können. Öffentliche Abfragen liefern den Status ohne Inhalt. | | `published` | Ja | Die aktuelle Version ist öffentlich. | | `update_needed` | Ja | Weiter mit der aktuellen Version online, muss aber erneut veröffentlicht werden: Das Register hat sich geändert, die Einheit wurde einer anderen Modellversion zugeordnet, oder eine automatische Veröffentlichung von Zustandsdaten wurde blockiert. | | `withdrawn` | Nein | Von einem Admin oder Inhaber mit Begründung offline genommen. Öffentliche Abfragen liefern den Status ohne Inhalt. | | `suspended`, `deleted_recycled` | Nein | Im Vertrag für später vorgesehen; die aktuelle Version setzt sie nicht. | ## Versionen Eine Version entsteht durch eine Veröffentlichung. Prüfer veröffentlichen im Portal mit einer Begründung; Zustandsdaten können eine Version auch automatisch veröffentlichen ([Zustandsdaten und Lebenszyklus](https://passport.kabin.sh/docs/de/concepts/condition-and-lifecycle)). Unveränderter Inhalt erzeugt keine neue Version. Jede Version speichert unveränderlich: - den **Snapshot**: jedes Feld beider Ebenen in jeder Zugriffsstufe, mit Wert, Einheit, Status und Herkunft (Quelle, Revision, Prüfer, Prüf- oder Messzeitpunkt, Dokumente); - das **öffentliche Dokument**: die Projektion des Snapshots auf die Stufe `public`; - eine [Signatur](https://passport.kabin.sh/docs/de/concepts/signatures) für beide, mit den Hashes `canonical_hash` und `public_hash` und der `key_id`; - den BatteryPass-v2.0-Export und seinen Schema-Bericht (nur zur Information: Er blockiert keine Veröffentlichung). | Operation | Liefert | | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------ | | [`listPassportVersions`](https://passport.kabin.sh/docs/de/api-reference/passports/list-passport-versions) | Versionsübersichten, die neueste zuerst. Mit `at` ist der erste Eintrag die Version, die zu diesem Zeitpunkt galt. | | [`getPassportVersion`](https://passport.kabin.sh/docs/de/api-reference/passports/get-passport-version) | Eine Version mit `snapshot`, `public_document`, beiden Signaturen und dem Bericht `batterypass_v2`. | | [`getPublicPassportVersion`](https://passport.kabin.sh/docs/de/api-reference/public/get-public-passport-version) | Den öffentlichen Pass, wie er zum Zeitpunkt `at` war, ohne Schlüssel. | Eine Übersicht enthält `version_no`, `published_at`, `reason`, `published_by_name` (fehlt, wenn das System veröffentlicht hat), `registry_version`, die Hashes, `key_id` und `valid_until`. `valid_until` wird gesetzt, sobald eine spätere Version diese ablöst; gültig zum Zeitpunkt `t` ist also die Version mit `published_at ≤ t < valid_until`. ## Unterschiede zwischen Versionen [`getPassportVersionDiff`](https://passport.kabin.sh/docs/de/api-reference/passports/get-passport-version-diff) vergleicht zwei signierte Snapshots Feld für Feld. Standardmäßig vergleicht es eine Version mit ihrer Vorgängerin; `against` nennt eine andere Versionsnummer. | `fields[].change` | Bedeutung | | ----------------- | ------------------------------------------------------------------------ | | `added` | Das Feld hat in dieser Version einen Wert und hatte vorher keinen. | | `removed` | Das Feld hatte vorher einen Wert und hat jetzt keinen. | | `changed` | Der Wert hat sich geändert. | | `provenance` | Gleicher Wert, neuere Revision: erneut freigegeben oder erneut gemessen. | Jede Änderung hat `before` und `after` mit Wert, Einheit, Zugriffsstufe, Quelle, Revision, `measured_at` und den Titeln der Dokumente. `metadata[]` listet Änderungen an `model_version`, `registry_version`, `category`, `facility`, `operator` und `predecessor`. ```bash title="cURL" curl -s "$BATTERYPASS_URL/api/v1/batteries/$BATTERY_ID/passport/versions/3/diff" \ -H "Authorization: Bearer $BATTERYPASS_API_KEY" ``` ## Exporte | Export | Operation | Inhalt | | ----------------- | -------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | BatteryPass JSON | [`exportPassportJson`](https://passport.kabin.sh/docs/de/api-reference/passports/export-passport-json) | Das BatteryPass-v2.0-Dokument einer Version mit allen Zugriffsstufen, wie bei der Veröffentlichung gespeichert. Als Anhang gesendet. | | PDF | [`exportPassportPdf`](https://passport.kabin.sh/docs/de/api-reference/passports/export-passport-pdf) | Alle Zugriffsstufen mit markierten eingeschränkten Zeilen, der Signatur und dem QR-Code; `lang=de` oder `lang=en`. | | QR-Code | [`getPassportQr`](https://passport.kabin.sh/docs/de/api-reference/passports/get-passport-qr) | Der GS1 Digital Link als PNG (`size` 128 bis 2048 Pixel, Standard 512) oder SVG (`format=svg`). Erst nach dem Sperren der Kennungen; vorher `409 conflict`. | | Öffentliches JSON | [`getPublicPassport`](https://passport.kabin.sh/docs/de/api-reference/public/get-public-passport) | Das signierte öffentliche Dokument der aktuellen Version, ohne Schlüssel. | > [!WARNING] > BatteryPass JSON und PDF enthalten die eingeschränkten Zugriffsstufen. Behandeln Sie diese Dateien vertraulich > und veröffentlichen Sie sie nicht; für alle gedacht ist das öffentliche JSON > ([Zugriffsstufen](https://passport.kabin.sh/docs/de/concepts/access-tiers)). ## EU-Register [`getRegistrySubmissionStatus`](https://passport.kabin.sh/docs/de/api-reference/passports/get-registry-submission-status) meldet die Registrierung des Passes im EU-Register. Das EU-Register bietet Wirtschaftsakteuren noch keine Schnittstelle; BatteryPass übermittelt deshalb nichts, und der Zustand ist `not_available`. Ohne Bestätigung des Registers wird ein Pass nie als registriert angezeigt. > [!NOTE] > Veröffentlichen und das Sperren von Kennungen sind Portal-Aktionen für Prüfer, das Zurückziehen eines Passes > eine für Admins und Inhaber. Ein API-Schlüssel liest Pässe und ihre Versionen, veröffentlicht oder zieht aber > nie zurück.