API-Referenz
Jede Operation des veröffentlichten Vertrags, mit Playground und Codebeispielen.
Die Referenz wird beim Bau dieser Seiten aus dem veröffentlichten Vertrag der Integrations-API erzeugt (OpenAPI 3.0). Sie zeigt genau die Operationen, die ein API-Schlüssel oder ein öffentlicher Aufruf nutzen kann; die Operationen des Portals sind nicht Teil davon (siehe Stabilität und Versionen).
Grundlagen
| Basis-URL | https://<Ihre BatteryPass-Adresse>/api/v1 (siehe Umgebungen) |
| Authentifizierung | Authorization: Bearer bp_live_… mit Scope read, condition oder import (Authentifizierung) |
| Format | JSON, Zeitpunkte in UTC, IDs als UUID |
| Fehler | Problem Details nach RFC 9457 mit stabilem code (Fehler) |
| Listen | Keyset-Paginierung mit limit und cursor (Paginierung) |
| Grenzen | 429 rate_limited mit Retry-After (Ratenlimits) |
Playground
Jede Operationsseite hat einen Playground („Try in Playground“). Er sendet die Anfrage aus Ihrem Browser an
die BatteryPass-Instanz, auf der diese Dokumentation läuft. Ihr Schlüssel bleibt nur in diesem Tab
(sessionStorage) und wird ohne Cookies gesendet; nutzen Sie dafür einen Schlüssel mit Scope read.
Vertrag herunterladen
openapi.jsonundopenapi.yaml: der Stand, aus dem diese Dokumentation gebaut wurde./api/v1/openapi.jsonund/api/v1/openapi.yamlauf Ihrer BatteryPass-Adresse: der Stand, den Ihre Instanz gerade ausliefert.
Alle Operationen
Katalog
| Operation | Anfrage | Scope |
|---|---|---|
| Units (individual batteries) of the active organisation | GET /batteries | read |
| The units as a spreadsheet with the import's columns | GET /batteries/export | read |
| A unit | GET /batteries/{batteryId} | read |
| List the battery models of the active organisation | GET /battery-models | read |
| A battery model | GET /battery-models/{modelId} | read |
| Versions of a battery model, newest effective date first | GET /battery-models/{modelId}/versions | read |
| A model version | GET /model-versions/{versionId} | read |
Werte
| Operation | Anfrage | Scope |
|---|---|---|
| Registry evaluation of the unit-level fields | GET /batteries/{batteryId}/completeness | read |
| Current unit-level values of a unit | GET /batteries/{batteryId}/values | read |
| All revisions of one unit-level value, newest first | GET /batteries/{batteryId}/values/{fieldKey}/history | read |
| Registry evaluation of the model-level fields | GET /model-versions/{versionId}/completeness | read |
| Current model-level values of a version | GET /model-versions/{versionId}/values | read |
| All revisions of one model-level value, newest first | GET /model-versions/{versionId}/values/{fieldKey}/history | read |
Nachweise
| Operation | Anfrage | Scope |
|---|---|---|
| The evidence library, newest first | GET /evidence | read |
| One document with its revisions and where it is used | GET /evidence/{evidenceId} | read |
| Download the file | GET /evidence/{evidenceId}/download | read |
Pässe
| Operation | Anfrage | Scope |
|---|---|---|
| The passport of a unit | GET /batteries/{batteryId}/passport | read |
| The QR code of the unit's GS1 Digital Link | GET /batteries/{batteryId}/passport/qr | read |
| The passport's registration with the EU registry | GET /batteries/{batteryId}/passport/registration | read |
| The published versions of a unit's passport, newest first | GET /batteries/{batteryId}/passport/versions | read |
| One published version with its signed snapshot and validation report | GET /batteries/{batteryId}/passport/versions/{versionNo} | read |
| The BatteryPass v2.0 export of a version (all tiers) | GET /batteries/{batteryId}/passport/versions/{versionNo}/batterypass-v2 | read |
| What changed from an earlier version to this one | GET /batteries/{batteryId}/passport/versions/{versionNo}/diff | read |
| A PDF of a version with every tier, restricted rows tagged, the signature and the QR code | GET /batteries/{batteryId}/passport/versions/{versionNo}/pdf | read |
Lebenszyklus
| Operation | Anfrage | Scope |
|---|---|---|
| The condition data of a unit (the registry's dynamic fields) | GET /batteries/{batteryId}/condition | read |
| Report measured condition data (merge) | PATCH /batteries/{batteryId}/condition | condition |
| The lifecycle of a unit, newest first | GET /batteries/{batteryId}/lifecycle-events | read |
| Record an event in the life of a unit | POST /batteries/{batteryId}/lifecycle-events | condition |
Feldregister
| Operation | Anfrage | Scope |
|---|---|---|
| Version, content hash and status of the field registry in use | GET /registry | read |
| The editor schema of a battery category | GET /registry/schema | read |
| The registry in use and how many of the organisation's passports need an update | GET /registry/status | read |
Standorte
| Operation | Anfrage | Scope |
|---|---|---|
| Manufacturing facilities of the active organisation | GET /facilities | read |
Öffentlich
| Operation | Anfrage | Scope |
|---|---|---|
| The public passport of a unit, looked up by GTIN and serial number | GET /public/dpps/by-product-id/{productId} | public |
| The public passport (current version) | GET /public/passports/{passportId} | public |
| A public document of a public passport | GET /public/passports/{passportId}/documents/{documentId} | public |
| Check the signatures of a version on the server | GET /public/passports/{passportId}/verify | public |
| The public passport as it was at a point in time | GET /public/passports/{passportId}/version | public |
Änderungen
| Operation | Anfrage | Scope |
|---|---|---|
| The organisation's changes, oldest first, for polling | GET /changes | read |
Importe
| Operation | Anfrage | Scope |
|---|---|---|
| Imports of the active organisation, newest first | GET /imports | import |
| Upload a spreadsheet of units | POST /imports | import |
| One import with its mapping and summary | GET /imports/{importId} | import |
| Map the columns of an import | PUT /imports/{importId}/mapping | import |
| Start validating every row of an import | POST /imports/{importId}/validate | import |