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.
| 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); 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
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). 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 für beide, mit den Hashes
canonical_hashundpublic_hashund derkey_id; - den BatteryPass-v2.0-Export und seinen Schema-Bericht (nur zur Information: Er blockiert keine Veröffentlichung).
| Operation | Liefert |
|---|---|
listPassportVersions | Versionsübersichten, die neueste zuerst. Mit at ist der erste Eintrag die Version, die zu diesem Zeitpunkt galt. |
getPassportVersion | Eine Version mit snapshot, public_document, beiden Signaturen und dem Bericht batterypass_v2. |
getPublicPassportVersion | 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 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.
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 | Das BatteryPass-v2.0-Dokument einer Version mit allen Zugriffsstufen, wie bei der Veröffentlichung gespeichert. Als Anhang gesendet. |
exportPassportPdf | Alle Zugriffsstufen mit markierten eingeschränkten Zeilen, der Signatur und dem QR-Code; lang=de oder lang=en. | |
| QR-Code | getPassportQr | 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 | Das signierte öffentliche Dokument der aktuellen Version, ohne Schlüssel. |
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).
EU-Register
getRegistrySubmissionStatus 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.
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.