Batteriemodelle, Versionen und Einheiten
Wie BatteryPass Produkt, technische Stände und einzelne Batterien trennt und wo welcher Wert gespeichert ist.
BatteryPass hält Produktdaten auf drei Ebenen. Was alle Batterien eines Produkts gemeinsam haben, pflegen Sie einmal an der Modellversion; was sich von Batterie zu Batterie unterscheidet, gehört zur Einheit. Jede Einheit bekommt einen eigenen Pass, der bei der Veröffentlichung aus beiden Ebenen zusammengesetzt wird.
flowchart LR M["Batteriemodell: Name, SKU, GTIN, Kategorie"] --> VA["Modellversion A: abgelöst"] M --> VB["Modellversion B: freigegeben"] VA --> U1["Einheit SN-000184"] VB --> U2["Einheit SN-000417"] U2 --> P["Pass von SN-000417"]
Die drei Ebenen
| Ebene | Was sie ist | Wichtige Felder | Lesen mit |
|---|---|---|---|
Batteriemodell (BatteryModel) | Das Handelsprodukt | name, sku, gtin, category, archived_at | listBatteryModels, getBatteryModel |
Modellversion (ModelVersion) | Ein technischer Stand des Modells, etwa nach einem Zellwechsel | version_label, effective_from, status, unit_count, approved_at, registry_version | listModelVersions, getModelVersion |
Einheit (Battery) | Eine physische Batterie mit Seriennummer | serial_number, model_version_id, manufacturing_date, facility_id, battery_status, passport_status | listBatteries, getBattery, exportUnits |
Die category eines Modells (ev, lmt, industrial, stationary, industrial_without_bms) bestimmt,
welche Felder das Register für seine Batterien verlangt.
Status einer Modellversion
Eine Modellversion hat ein Startdatum, effective_from, und einen Status:
status | Bedeutung |
|---|---|
draft | In Vorbereitung. Einheiten einer Entwurfsversion lassen sich nicht veröffentlichen. |
approved | Der aktuelle technische Stand. Ein Modell hat höchstens eine freigegebene Version; die Freigabe erteilt ein Prüfer im Portal. |
superseded | Von einer späteren freigegebenen Version abgelöst. Sie bleibt lesbar und behält ihre Einheiten; deren veröffentlichte Pässe ändern sich nicht. |
Ein Enddatum gibt es nicht: Eine Version gilt ab ihrem effective_from, bis eine spätere Version übernimmt.
Wird eine Einheit im Portal oder per Tabellenimport ohne Angabe einer Version angelegt, ordnet BatteryPass ihr
die Version zu, die an ihrem Herstellungsdatum galt: die mit dem spätesten effective_from an oder vor diesem
Datum, wobei freigegebene und abgelöste Versionen Vorrang vor Entwürfen haben. Die Freigabe einer neuen Version
verschiebt keine bestehende Einheit. Mitglieder verschieben Einheiten
im Portal nach einer Vorschau der Auswirkungen auf eine andere Version; der veröffentlichte Pass einer
verschobenen Einheit wird dann update_needed (Pässe).
Welche Werte wo liegen
Das Feldregister ordnet jedes Feld einer Ebene zu. Sie lesen es mit
getRegistrySchema: Jedes Feld hat level mit dem Wert
model oder unit.
| Ebene | Typische Felder | Werte | Vollständigkeit |
|---|---|---|---|
| Modellversion | Hersteller, Masse, Garantie, Chemie und Zusammensetzung, gefährliche Stoffe, CO₂-Fußabdruck, Sorgfaltspflichten, Kreislauffähigkeit, Leistungskennwerte, Kennzeichnung und Konformitätserklärung, z. B. performance.nominal_voltage, materials.battery_chemistry | listModelVersionValues | getModelVersionCompleteness |
| Einheit | Seriennummer, Herstellungsdatum und -ort, Batteriestatus, Datum der Inbetriebnahme und die Zustandsdaten, z. B. identification.serial_number, condition.capacity_fade | listBatteryValues | getBatteryCompleteness |
Einige Registerfelder sind keine eigenen Werte, sondern Eigenschaften des Modells oder der Einheit selbst:
Produktname, SKU, GTIN und Kategorie des Modells; Seriennummer, Herstellungsdatum, Produktionsstätte,
Batteriestatus und Datum der Inbetriebnahme der Einheit. Sie lesen sie an BatteryModel und Battery.
Die Vollständigkeit einer Einheit enthält auch die Zusammenfassung ihrer Modellversion (model_version). Ein
Aufruf zeigt also, ob eine der beiden Ebenen die Veröffentlichung noch blockiert.
Kennungen
| Kennung | Wo | Regeln |
|---|---|---|
| GTIN | Am Batteriemodell | Mit 8, 12, 13 oder 14 Stellen angenommen, als GTIN-14 mit gültiger Prüfziffer gespeichert |
| Seriennummer | An der Einheit | Buchstaben, Ziffern, -, / und ., höchstens 50 Zeichen, eindeutig je Modell |
| GTIN und Seriennummer zusammen | Der Schlüssel der Einheit | Eindeutig über alle Organisationen; der GS1 Digital Link enthält genau dieses Paar |
Sobald die Kennungen gesperrt sind (für den Etikettendruck vor der Veröffentlichung oder bei der ersten
Veröffentlichung), ist identifiers_locked_at gesetzt; Seriennummer und GTIN des Modells lassen sich dann nicht
mehr ändern.
Second Life: Eine umgewidmete, wiederverwendete oder wiederaufbereitete Batterie ist eine neue Einheit. Sie
nennt das Original in predecessor_battery_id (das Original führt sie in successor_battery_ids) und bekommt
einen eigenen Pass.
Den Katalog lesen
Lesen Sie die Versionen eines Modells und dann die Einheiten einer Version:
curl -s "$BATTERYPASS_URL/api/v1/battery-models/$MODEL_ID/versions" \
-H "Authorization: Bearer $BATTERYPASS_API_KEY"
curl -s "$BATTERYPASS_URL/api/v1/batteries?model_version_id=$VERSION_ID&limit=200" \
-H "Authorization: Bearer $BATTERYPASS_API_KEY"listModelVersions liefert höchstens 200 Versionen, das späteste effective_from zuerst, ohne Cursor.
listBatteries ist nach Seriennummer sortiert und wird mit limit und cursor geblättert
(Paginierung); außerdem filtert es nach battery_model_id, passport_status,
serial_prefix und import_id.
Die API liest den Katalog, sie legt ihn nicht an und ändert ihn nicht. Modelle, Versionen und Einheiten legen Mitglieder im Portal oder per Tabellenimport an; Modellversionen geben Prüfer frei.