Pässe exportieren

Alle Exporte sind einfache GET-Anfragen mit einem Schlüssel, der den Scope read hat. Sie kommen als Dateien mit dem Header Content-Disposition: attachment zurück, der einen fertigen Dateinamen mitbringt.

Ein / in einer Seriennummer wird in Dateinamen zu _.

Passexporte Schritt für SchrittLink zum Abschnitt kopieren

curl -sS "$BATTERYPASS_URL/api/v1/batteries/0192a3f0-5b7c-7d21-8e4f-6a2b9c1d3e5f/passport" \
  -H "Authorization: Bearer $BATTERYPASS_API_KEY" | jq '{status, passport_id, version: .current_version.version_no}'

BATTERY_ID=0192a3f0-5b7c-7d21-8e4f-6a2b9c1d3e5f
# -O -J speichert unter dem Namen aus Content-Disposition
curl -sS -OJ -H "Authorization: Bearer $BATTERYPASS_API_KEY" \
  "$BATTERYPASS_URL/api/v1/batteries/$BATTERY_ID/passport/versions/3/batterypass-v2"
curl -sS -OJ -H "Authorization: Bearer $BATTERYPASS_API_KEY" \
  "$BATTERYPASS_URL/api/v1/batteries/$BATTERY_ID/passport/versions/3/pdf?lang=de"
curl -sS -OJ -H "Authorization: Bearer $BATTERYPASS_API_KEY" \
  "$BATTERYPASS_URL/api/v1/batteries/$BATTERY_ID/passport/qr?format=svg"

// exports.mts: npx tsx exports.mts <battery-id>
import { writeFile } from 'node:fs/promises';
import { basename } from 'node:path';

const BASE = `${process.env.BATTERYPASS_URL}/api/v1`;
const headers = { Authorization: `Bearer ${process.env.BATTERYPASS_API_KEY}` };
const batteryId = process.argv[2];

async function download(path: string) {
  const res = await fetch(BASE + path, { headers });
  if (!res.ok) throw new Error(`${path}: ${res.status} ${(await res.json()).code}`);
  // Content-Disposition: attachment; filename=04012345000023-SV2027-000184-v3-de.pdf
  const match = /filename="?([^";]+)"?/.exec(res.headers.get('Content-Disposition') ?? '');
  const file = basename(match?.[1] ?? 'download');
  await writeFile(file, Buffer.from(await res.arrayBuffer()));
  console.log(file, res.headers.get('Content-Type'));
}

const passportRes = await fetch(`${BASE}/batteries/${batteryId}/passport`, { headers });
const passport = await passportRes.json();
const versionNo = passport.current_version?.version_no;
if (!versionNo) throw new Error(`passport is ${passport.status}: no published version yet`);

await download(`/batteries/${batteryId}/passport/versions/${versionNo}/batterypass-v2`);
await download(`/batteries/${batteryId}/passport/versions/${versionNo}/pdf?lang=de`);
await download(`/batteries/${batteryId}/passport/qr?format=svg`);

BatteryPass-JSONLink zum Abschnitt kopieren

exportPassportJson liefert den Export, der bei der Veröffentlichung der Version erzeugt und gespeichert wurde, im Format des BatteryPass-Ready Data Model v2.0. Er enthält alle Zugriffsstufen einschließlich eingeschränkter Werte; behandeln Sie die Datei vertraulich. Ob er das JSON-Schema des Datenmodells erfüllt, ist ein Hinweis und blockiert keine Veröffentlichung: Die Versionsübersicht trägt batterypass_v2_valid und batterypass_v2_issue_count, getPassportVersion den vollständigen Bericht in batterypass_v2.

PDFLink zum Abschnitt kopieren

exportPassportPdf erzeugt eine Version mit allen Stufen (eingeschränkte Zeilen mit ihrer Stufe gekennzeichnet), der Signatur und dem QR-Code. lang ist de (Standard) oder en. Wie das JSON enthält auch das PDF eingeschränkte Daten.

QR-CodeLink zum Abschnitt kopieren

getPassportQr erzeugt den QR-Code zum gs1_digital_link der Einheit (Fehlerkorrektur M, Ruhezone von vier Modulen).

Den QR-Code gibt es, sobald die Kennungen gesperrt sind, vor oder mit der ersten Veröffentlichung. Davor lautet die Antwort 409 conflict. Der Link darin ändert sich danach nie mehr; ein gedrucktes Etikett bleibt also auch für spätere Versionen gültig. Für viele Einheiten auf einmal siehe das Rezept QR-Etiketten für eine Charge.

Einheiten als TabelleLink zum Abschnitt kopieren

exportUnits liefert die Einheiten, die zu den Filtern passen, mit den Spalten des Tabellenimports: Modell, Version, die Felder der Einheit und jedes Feld auf Einheitsebene, das einen Wert hat. Ein Mitglied kann die Datei bearbeiten und im Portal wieder importieren.

curl -sS -OJ -H "Authorization: Bearer $BATTERYPASS_API_KEY" \
  "$BATTERYPASS_URL/api/v1/batteries/export?format=csv&passport_status=published&serial_prefix=SV2027-"

Eine Datei fasst höchstens 10 000 Einheiten. Bei mehr lautet die Antwort 400 validation_error auf filter (out_of_range): Schränken Sie die Filter ein, etwa nach Modellversion oder Seriennummernpräfix. In CSV-Dateien bekommt eine Zelle, die mit =, + oder @ beginnt oder mit - beginnt und keine Zahl ist, ein vorangestelltes ', damit Tabellenprogramme sie nicht als Formel ausführen; der Import entfernt es wieder.

FehlerLink zum Abschnitt kopieren