Programiści

Połącz swój ERP lub systemy produkcyjne: twórz i publikuj paszporty baterii, odczytuj je i aktualizuj przez API DPP zgodne z EN 18222 oraz odbieraj zdarzenia przez webhooki. Dostęp do API jest wliczony w każdy plan, także Free.

Dwa API

API zarządzania paszportami
/openapi.json
Dla firmy, która jest właścicielem paszportów: lista modeli i pozycji (kursorem, z updatedSince do synchronizacji), tworzenie pozycji, zakresów i kopii modeli, aktualizacja danych pozycji, publikacja (jednej pozycji lub w tle) i pobieranie kodów QR. Uwierzytelnianie kluczem API.
Dokumentacja: API zarządzania paszportami
API DPP (EN 18222)
/openapi-dpp.json
API Life Cycle i Fine Granular zgodne z EN 18222: odczyt paszportów na Twoim poziomie dostępu, wyszukiwanie identyfikatorów paszportów po identyfikatorze produktu, rejestrowanie zdarzeń (naprawa, stan zdrowia, status) z tokenem dostępu OAuth 2.0. Dane publiczne można czytać bez tokenu.
Dokumentacja: API DPP (EN 18222)

Odczytaj paszport

Każdy adres paszportu odpowiada JSON-em na żądanie – klucz nie jest potrzebny dla danych publicznych. Nagłówki zawierają wersję, jej SHA-256 i podpis Ed25519, więc możesz sprawdzić odczytane dane z naszymi kluczami publicznymi.

$ 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", … }, … }

Długie wartości są skrócone. Z tokenem dostępu ten sam adres zwraca pola Twojego poziomu dostępu, a X-Passport-Access-Level go nazywa.

Uwierzytelnianie

Klucze API tworzy właściciel firmy w Firma → Klucze API i są pokazywane jednorazowo. Wysyłaj je jako Authorization: Bearer bcp_live_…. Zakresy: items:read, items:write (także odczyt), items:publish, qr:read.

Klientów OAuth 2.0 (client credentials) tworzy właściciel firmy dla swoich partnerów albo platforma dla organów i zatwierdzonych osób trzecich. Token uzyskasz przez POST /oauth/token (grant_type=client_credentials); jest ważny 15 minut. Zakresy: dpp:read, dpp:search, dpp:write.

Limity i błędy

60 żądań na minutę na klucz API (nagłówki X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset) i 120 na minutę na klienta OAuth lub, bez tokenu, na adres. Po przekroczeniu limitu: HTTP 429 z Retry-After.

API zarządzania paszportami odpowiada na błędy obiektem error z polami code, message i details; API DPP odpowiada polami statusCode, payload i result z kodami statusu z EN 18222.

Aktualizacje API DPP przyjmują nagłówek Idempotency-Key: ten sam klucz z tym samym żądaniem w ciągu 24 godzin zwraca pierwszą odpowiedź i nie tworzy drugiej wersji.

Paszporty publiczne

Każdy paszport ma stały adres (GS1 Digital Link /01/{GTIN}/21/{serial} lub /id/{operator}/{model}/{serial}). Z Accept: application/json lub ?format=json zwraca JSON najnowszej wersji dla Twojego poziomu dostępu; ?version=N – wskazaną wersję; /versions – listę.

Każda wersja jest podpisana: X-Passport-SHA256 zawiera SHA-256 kanonicznego JSON według RFC 8785 pełnej wersji, X-Passport-Signature jej podpis Ed25519 tego ciągu szesnastkowego, a X-Passport-Key-Id klucz, którym podpisano. Klucze publiczne i schemat są wymienione w sekcji Opisy do odczytu maszynowego.

Webhooki

Zamiast odpytywać, dodaj punkt końcowy w Firma → Webhooki. Zdarzenia – 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 – są wysyłane metodą POST jako JSON z nagłówkami X-Webhook-Id, X-Webhook-Timestamp i X-Webhook-Signature = v1= + szesnastkowy HMAC-SHA256 z timestamp.body z Twoim sekretem. Odpowiedz 2xx w ciągu 10 sekund; nieudane dostarczenia są ponawiane przez 24 godziny.

Opisy do odczytu maszynowego

Publiczne klucze podpisu (JWKS)/.well-known/batterycompliance-signing-key.json
Schemat JSON paszportu/schema/battery-passport/2.0.0
OpenAPI 3.1 – API zarządzania paszportami/openapi.json
OpenAPI 3.1 – API DPP/openapi-dpp.json

Uzyskaj klucz API

Zarejestruj firmę, a następnie utwórz klucz w Firma → Klucze API. Klucze są pokazywane jednorazowo i przechowywane wyłącznie jako skrót.

Zacznij za darmo Skontaktuj się