Schnellstart

API-Schlüssel erstellen

Ein Eigentümer meldet sich im BatteryPass-Portal an, öffnet Einstellungen → API-Schlüssel und wählt API-Schlüssel erstellen. Geben Sie dem Schlüssel einen Namen, der das nutzende System nennt, und wählen Sie den Scope Lesen (read). Der Scope Zustandsdaten melden (condition) ist nur für Systeme gedacht, die Messwerte und Lebenszyklusereignisse melden.

Das Geheimnis beginnt mit bp_live_ und wird nur ein einziges Mal angezeigt. Legen Sie es sofort in Ihrem Secret-Speicher ab; später lässt es sich nicht mehr anzeigen. Schlüssel werden nur im Portal verwaltet, nicht über die API.

Zwei Umgebungsvariablen setzen

export BATTERYPASS_URL="https://batterypass.example.com"
export BATTERYPASS_API_KEY="bp_live_..."

BATTERYPASS_URL ist die BatteryPass-Adresse Ihrer Organisation ohne abschließenden Schrägstrich. Alle Beispiele dieser Dokumentation lesen diese beiden Variablen. Mehr dazu unter Umgebungen und Basis-URL.

Den ersten Aufruf senden

Listen Sie mit listBatteryModels die ersten fünf Batteriemodelle Ihrer Organisation auf:

curl -sS "$BATTERYPASS_URL/api/v1/battery-models?limit=5" \
  -H "Authorization: Bearer $BATTERYPASS_API_KEY"

{
  "items": [
    {
      "id": "0192f0a1-6c2e-7d4b-9a10-3e5f7b2c8d41",
      "name": "SolarVolt Home 10",
      "sku": "SV-H10",
      "gtin": "04012345000023",
      "category": "stationary",
      "archived_at": null,
      "row_version": 3,
      "created_at": "2026-01-08T09:12:44Z",
      "updated_at": "2026-03-02T15:40:10Z"
    }
  ],
  "next_cursor": null
}

Ein 401 bedeutet, dass der Header fehlt oder der Schlüssel unbekannt oder widerrufen ist; ein 403, dass dem Schlüssel der Scope read fehlt. Siehe Authentifizierung und Fehler.

Batteriemodelle im Code auflisten

const res = await fetch(`${process.env.BATTERYPASS_URL}/api/v1/battery-models?limit=50`, {
  headers: { Authorization: `Bearer ${process.env.BATTERYPASS_API_KEY}` },
});
if (!res.ok) throw new Error(`listBatteryModels: ${res.status} ${await res.text()}`);

const page: { items: { id: string; name: string; gtin: string | null }[]; next_cursor: string | null } =
  await res.json();
for (const model of page.items) console.log(model.name, model.gtin ?? '(keine GTIN)', model.id);
if (page.next_cursor) console.log('Weitere Modelle auf der nächsten Seite.');

Listen liefern höchstens limit Einträge und einen next_cursor; wie Sie alle Seiten lesen, zeigt Paginierung.

Den Pass einer Einheit lesen

Suchen Sie mit listBatteries eine Einheit mit veröffentlichtem Pass und lesen Sie dann ihren Pass mit getPassport:

BATTERY_ID=$(curl -sS "$BATTERYPASS_URL/api/v1/batteries?passport_status=published&limit=1" \
  -H "Authorization: Bearer $BATTERYPASS_API_KEY" | jq -r '.items[0].id')

curl -sS "$BATTERYPASS_URL/api/v1/batteries/$BATTERY_ID/passport" \
  -H "Authorization: Bearer $BATTERYPASS_API_KEY"

{
  "battery_id": "0192f0a3-1b7c-7e2a-8f45-6a9d0c3e5b12",
  "status": "published",
  "serial_number": "SV2027-000001",
  "gtin": "04012345000023",
  "passport_id": "urn:dpp:0192f3c4-7e1a-7b2c-9d3e-5f6a7b8c9d0e",
  "gs1_digital_link": "https://batterypass.example.com/01/04012345000023/21/SV2027-000001",
  "public_url": "https://batterypass.example.com/pass/0192f3c4-7e1a-7b2c-9d3e-5f6a7b8c9d0e",
  "first_published_at": "2026-03-10T08:30:00Z",
  "identifiers_locked_at": "2026-03-10T08:30:00Z",
  "row_version": 4
}

Die Antwort enthält außerdem current_version mit Versionsnummer, Hashes und Signaturschlüssel der aktuellen Version. Eine Einheit, die nie veröffentlicht wurde, hat einen Pass im Status draft ohne passport_id.

Den öffentlichen Pass ohne Schlüssel lesen

Die öffentliche Stufe eines veröffentlichten Passes braucht keinen Schlüssel. getPublicPassport erwartet den UUID-Teil von passport_id, ohne das Präfix urn:dpp::

PASSPORT_UUID=$(curl -sS "$BATTERYPASS_URL/api/v1/batteries/$BATTERY_ID/passport" \
  -H "Authorization: Bearer $BATTERYPASS_API_KEY" | jq -r '.passport_id | sub("^urn:dpp:"; "")')

curl -sS "$BATTERYPASS_URL/api/v1/public/passports/$PASSPORT_UUID" | jq '{passport_id, status, links}'

document ist die signierte öffentliche Projektion der aktuellen Version; verification enthält ihre Ed25519-Signatur. Pässe, die nicht öffentlich sind (zum Beispiel withdrawn), antworten mit ihrem Status und ohne document. Öffentliche Abrufe werden fünf Minuten zwischengespeichert und sind auf 300 Anfragen pro Minute und Client-Adresse begrenzt.