Vývojáři
Dvě API
API pro správu pasů
/openapi.jsonPro společnost, která pasy vlastní: výpis modelů a položek (po kurzorech, s updatedSince pro synchronizaci), vytváření položek, řad a kopií modelů, aktualizace údajů položky, zveřejnění (jedné položky nebo na pozadí) a získání kódů QR. Ověřuje se klíčem API.
Reference: API pro správu pasůAPI pro DPP (EN 18222)
/openapi-dpp.jsonAPI Life Cycle a Fine Granular podle EN 18222: čtení pasů na vaší úrovni přístupu, vyhledávání ID pasů podle ID výrobku, zaznamenávání událostí (oprava, technický stav, stav) s přístupovým tokenem OAuth 2.0. Veřejné údaje lze číst bez tokenu.
Reference: API pro DPP (EN 18222)
Přečíst pas
Každá adresa pasu odpoví formátem JSON, když o něj požádáte – pro veřejné údaje není klíč potřeba. Hlavičky nesou verzi, její SHA-256 a podpis Ed25519, takže můžete přečtené ověřit podle našich veřejných klíčů.
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", … }, … }Jak API fungují
Ověření
Klíče API vytváří vlastník společnosti v části Společnost → Klíče API a zobrazí se jednou. Odesílejte je jako Authorization: Bearer bcp_live_…. Rozsahy: items:read, items:write (také čtení), items:publish, qr:read.
Klienty OAuth 2.0 (client credentials) vytváří vlastník společnosti pro své partnery, nebo platforma pro orgány a schválené třetí strany. Token získáte pomocí POST /oauth/token (grant_type=client_credentials); platí 15 minut. Rozsahy: dpp:read, dpp:search, dpp:write.
Limity a chyby
60 požadavků za minutu na klíč API (hlavičky X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset) a 120 za minutu na klienta OAuth nebo, bez tokenu, na adresu. Po překročení limitu: HTTP 429 s Retry-After.
API pro správu pasů odpovídá na chyby objektem error s položkami code, message a details; API pro DPP odpovídá položkami statusCode, payload a result se stavovými kódy podle EN 18222.
Aktualizace API pro DPP přijímají hlavičku Idempotency-Key: stejný klíč se stejným požadavkem do 24 hodin vrátí první odpověď a nevytvoří druhou verzi.
Veřejné pasy
Každý pas má trvalou adresu (GS1 Digital Link /01/{GTIN}/21/{serial} nebo /id/{operator}/{model}/{serial}). S Accept: application/json nebo ?format=json vrací JSON nejnovější verze pro vaši úroveň přístupu; ?version=N danou verzi; /versions seznam.
Každá verze je podepsána: X-Passport-SHA256 nese SHA-256 kanonického JSON podle RFC 8785 celé verze, X-Passport-Signature její podpis Ed25519 nad tímto hexadecimálním řetězcem a X-Passport-Key-Id klíč, který ji podepsal. Veřejné klíče a schéma jsou uvedeny v části Strojově čitelné popisy.
Webhooky
Místo opakovaných dotazů přidejte koncový bod v části Společnost → Webhooky. Události – 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 – se odesílají metodou POST jako JSON s hlavičkami X-Webhook-Id, X-Webhook-Timestamp a X-Webhook-Signature = v1= + hexadecimální HMAC-SHA256 z timestamp.body s vaším tajným klíčem. Odpovězte kódem 2xx do 10 sekund; neúspěšná doručení se opakují 24 hodin.
Strojově čitelné popisy
- Veřejné podpisové klíče (JWKS)/.well-known/batterycompliance-signing-key.json
- Schéma JSON pasu/schema/battery-passport/2.0.0
- OpenAPI 3.1 – API pro správu pasů/openapi.json
- OpenAPI 3.1 – API pro DPP/openapi-dpp.json
Získat klíč API
Zaregistrujte svou společnost a poté vytvořte klíč v části Společnost → Klíče API. Klíče se zobrazí jednou a ukládají se pouze jako otisk.