Entwickler
Zwei APIs
API zur Passverwaltung
/openapi.jsonFür das Unternehmen, dem die Pässe gehören: Modelle und Einheiten auflisten (per Cursor, mit updatedSince zur Synchronisation), Einheiten, Bereiche und Kopien von Modellen anlegen, Einheitendaten aktualisieren, veröffentlichen (eine Einheit oder im Hintergrund) und QR-Codes abrufen. Authentifizierung mit einem API-Schlüssel.
Referenz: API zur PassverwaltungDPP-API (EN 18222)
/openapi-dpp.jsonLife-Cycle- und Fine-Granular-API nach EN 18222: Pässe auf Ihrer Zugriffsstufe lesen, Pass-IDs über die Produkt-ID suchen, Ereignisse (Reparatur, Alterungszustand, Status) mit einem OAuth-2.0-Zugriffstoken erfassen. Öffentliche Daten können ohne Token gelesen werden.
Referenz: DPP-API (EN 18222)
Einen Pass lesen
Jede Passadresse antwortet mit JSON, wenn Sie danach fragen – für öffentliche Daten ist kein Schlüssel nötig. Die Header enthalten die Version, ihr SHA-256 und die Ed25519-Signatur, sodass Sie das Gelesene gegen unsere öffentlichen Schlüssel prüfen können.
curl -i -H "Accept: application/json" \https://batterycompliance.eu/id/BG123456789/EBIKE-48V/SN0001 HTTP/1.1 200 OKContent-Type: application/json; charset=utf-8X-Passport-Version: 3X-Passport-Access-Level: publicX-Passport-SHA256: bd4c49c7b04ac463…81146b938X-Passport-Signature: Tw0bRkvf+s3IS1MQ…MPZ7Dg==X-Passport-Key-Id: batterycompliance-2026-09-25Link: </schema/battery-passport/2.0.0>; rel="describedby" { "dppHeader": { "dppStatus": { "dppStatusValue": "active" }, … }, "identifiersAndProductData": { "batterySerialNumber": "SN0001", … }, … }Wie die APIs funktionieren
Authentifizierung
API-Schlüssel werden vom Unternehmensinhaber unter Unternehmen → API-Schlüssel angelegt und einmal angezeigt. Senden Sie sie als Authorization: Bearer bcp_live_…. Berechtigungsbereiche: items:read, items:write (liest auch), items:publish, qr:read.
OAuth-2.0-Clients (Client Credentials) werden vom Unternehmensinhaber für seine Partner angelegt oder von der Plattform für Behörden und freigegebene Dritte. Ein Token erhalten Sie mit POST /oauth/token (grant_type=client_credentials); es ist 15 Minuten gültig. Berechtigungsbereiche: dpp:read, dpp:search, dpp:write.
Grenzen und Fehler
60 Anfragen pro Minute und API-Schlüssel (Header X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset) und 120 pro Minute und OAuth-Client oder, ohne Token, pro Adresse. Über der Grenze: HTTP 429 mit Retry-After.
Die API zur Passverwaltung beantwortet Fehler mit einem error-Objekt aus code, message und details; die DPP-API antwortet mit statusCode, payload und result mit den Statuscodes von EN 18222.
Aktualisierungen der DPP-API akzeptieren einen Header Idempotency-Key: Derselbe Schlüssel mit derselben Anfrage innerhalb von 24 Stunden liefert die erste Antwort und erzeugt keine zweite Version.
Öffentliche Pässe
Jeder Pass hat eine dauerhafte Adresse (GS1 Digital Link /01/{GTIN}/21/{serial} oder /id/{operator}/{model}/{serial}). Mit Accept: application/json oder ?format=json liefert sie das JSON der neuesten Version für Ihre Zugriffsstufe; ?version=N eine bestimmte Version; /versions die Liste.
Jede Version ist signiert: X-Passport-SHA256 enthält das SHA-256 des kanonischen JSON nach RFC 8785 der vollständigen Version, X-Passport-Signature deren Ed25519-Signatur über diese Hex-Zeichenfolge und X-Passport-Key-Id den Schlüssel, der sie signiert hat. Die öffentlichen Schlüssel und das Schema sind unter Maschinenlesbare Beschreibungen aufgeführt.
Webhooks
Statt abzufragen, fügen Sie unter Unternehmen → Webhooks einen Endpunkt hinzu. Ereignisse – passport.published, publish_job.finished, item.lifecycle_recorded, access_request.created, passport.transferred, label_template.issued, dossier.ready, import_batch.assigned, import_batch.confirmed, import_batch.rejected – werden als JSON per POST gesendet, mit den Headern X-Webhook-Id, X-Webhook-Timestamp und X-Webhook-Signature = v1= + Hex-HMAC-SHA256 von timestamp.body mit Ihrem Geheimnis. Antworten Sie mit 2xx innerhalb von 10 Sekunden; fehlgeschlagene Zustellungen werden 24 Stunden lang wiederholt.
Maschinenlesbare Beschreibungen
- Öffentliche Signaturschlüssel (JWKS)/.well-known/batterycompliance-signing-key.json
- JSON-Schema des Passes/schema/battery-passport/2.0.0
- OpenAPI 3.1 – API zur Passverwaltung/openapi.json
- OpenAPI 3.1 – DPP-API/openapi-dpp.json
Einen API-Schlüssel erhalten
Registrieren Sie Ihr Unternehmen und legen Sie dann unter Unternehmen → API-Schlüssel einen Schlüssel an. Schlüssel werden einmal angezeigt und nur als Hash gespeichert.