Umgebungen und Basis-URL
Wo die API Ihrer Organisation liegt, welche Adressen sie bedient und wie Sie gefahrlos testen.
Basis-URL
BatteryPass läuft je Instanz; einen gemeinsamen, globalen API-Host gibt es nicht. Ihre Basis-URL ist die
BatteryPass-Adresse Ihrer Organisation, also dieselbe Adresse, unter der Sie das Portal nutzen, zum Beispiel
https://batterypass.example.com. Die API liegt unter /api/v1 auf dieser Adresse.
Adressen
| Pfad auf Ihrer BatteryPass-Adresse | Was | Authentifizierung |
|---|---|---|
/api/v1/... | Die Integrations-API | API-Schlüssel |
/api/v1/public/... | Öffentliche Abrufe von Pässen | Keine |
/api/v1/openapi.json, /api/v1/openapi.yaml | Der veröffentlichte Vertrag | Keine |
/01/{gtin}/21/{serial} | GS1-Digital-Link-Resolver, das Ziel der QR-Codes | Keine |
/pass/{passportId} | Öffentliche Passseite für Browser | Keine |
/.well-known/batterypass/keys.json | Öffentliche Signaturschlüssel (JWK-Set) zum Prüfen von Passsignaturen | Keine |
/docs/ | Diese Dokumentation | Keine |
Eine Instanz kann einen eigenen Resolver-Host in ihre QR-Codes drucken. Übernehmen Sie den Digital Link einer
Einheit aus dem Feld gs1_digital_link von
getPassport, statt ihn selbst zusammenzusetzen. Siehe
GS1 Digital Link.
Konventionen
- HTTPS. Senden Sie Anfragen und vor allem Schlüssel nur über HTTPS.
- JSON. Request- und Response-Bodys sind UTF-8-JSON; senden Sie zu einem Body
Content-Type: application/json. Bodys sind standardmäßig auf 1 MiB begrenzt (413 payload_too_large), unbekannte Eigenschaften werden abgelehnt. - Zeitpunkte (
date-time) sind UTC nach RFC 3339, z. B.2026-10-24T02:00:00Z. Senden Sie Zeitpunkte mit Zeitzonenversatz; UTC ist die sicherste Wahl. - Datumsangaben (
date, z. B.occurred_on,manufacturing_date) haben die FormYYYY-MM-DDohne Zeitzone. - IDs sind UUID-Strings. Die dauerhafte Passkennung ist
urn:dpp:{uuid}; öffentliche Routen erwarten nur die UUID.
Client einrichten
Alle Beispiele lesen zwei Umgebungsvariablen:
| Variable | Wert |
|---|---|
BATTERYPASS_URL | Ihre BatteryPass-Adresse ohne abschließenden Schrägstrich, z. B. https://batterypass.example.com |
BATTERYPASS_API_KEY | Ein API-Schlüssel Ihrer Organisation, bp_live_... |
export BATTERYPASS_URL="https://batterypass.example.com"
export BATTERYPASS_API_KEY="bp_live_..."Bewahren Sie den Schlüssel in einem Secret-Speicher oder der Secret-Verwaltung Ihrer Plattform auf, nicht im Quellcode oder in Dateien, die Sie committen. Siehe Sichere Schlüsselverwaltung.
Testen
BatteryPass hat keine öffentliche Sandbox. Testen Sie in einer Umgebung, in der Fehler keinen Schaden anrichten:
- Eine eigene Testorganisation oder eine eigene BatteryPass-Instanz mit eigenen Schlüsseln. Daten sind immer nach Organisation getrennt; ein Testschlüssel sieht oder ändert also nie Produktionsdaten. Bitten Sie die Betreiber Ihrer BatteryPass-Instanz, sie einzurichten.
- Schreibzugriffe nicht gegen die Produktion testen. Eine Zustandsmeldung per Schlüssel kann einen öffentlichen Pass je nach Einstellung der Organisation sofort neu veröffentlichen, und Lebenszyklusereignisse lassen sich über die API nicht löschen.
- Auf Öffentliches achten. Pässe, die in einer Testorganisation veröffentlicht werden, sind ebenfalls öffentlich, unter denselben Adressen. Verwenden Sie für Testdaten keine GTINs echter Produkte und drucken oder verteilen Sie keine QR-Codes aus Tests.
- Konfiguration trennen. Halten Sie Test- und Produktionswerte von
BATTERYPASS_URLundBATTERYPASS_API_KEYauseinander und geben Sie Testschlüsseln nur die Scopes, die der Test braucht.