Vývojári
Dve API
API na správu pasov
/openapi.jsonPre spoločnosť, ktorá pasy vlastní: výpis modelov a položiek (podľa kurzora, s updatedSince na synchronizáciu), vytváranie položiek, rozsahov a kópií modelov, aktualizácia údajov položky, zverejnenie (jednej položky alebo na pozadí) a získanie QR kódov. Overenie kľúčom API.
Referencia: API na správu pasovDPP API (EN 18222)
/openapi-dpp.jsonLife Cycle a Fine Granular API podľa EN 18222: čítanie pasov na vašej úrovni prístupu, vyhľadávanie ID pasov podľa ID výrobku, zaznamenávanie udalostí (oprava, stav batérie, status) s prístupovým tokenom OAuth 2.0. Verejné údaje možno čítať bez tokenu.
Referencia: DPP API (EN 18222)
Prečítať pas
Každá adresa pasu odpovedá vo formáte JSON, keď si ho vyžiadate – pre verejné údaje netreba kľúč. Hlavičky nesú verziu, jej SHA-256 a podpis Ed25519, takže prečítané môžete overiť voči našim verejným kľúčom.
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", … }, … }Ako API fungujú
Overovanie
Kľúče API vytvára vlastník spoločnosti v časti Spoločnosť → Kľúče API a zobrazia sa raz. Posielajte ich ako Authorization: Bearer bcp_live_…. Rozsahy: items:read, items:write (aj čítanie), items:publish, qr:read.
Klientov OAuth 2.0 (client credentials) vytvára vlastník spoločnosti pre svojich partnerov alebo platforma pre orgány a schválené tretie strany. Token získate cez POST /oauth/token (grant_type=client_credentials); platí 15 minút. Rozsahy: dpp:read, dpp:search, dpp:write.
Limity a chyby
60 požiadaviek za minútu na kľúč API (hlavičky X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset) a 120 za minútu na klienta OAuth alebo, bez tokenu, na adresu. Po prekročení limitu: HTTP 429 s Retry-After.
API na správu pasov odpovedá na chyby objektom error s poľami code, message a details; DPP API odpovedá poľami statusCode, payload a result so stavovými kódmi normy EN 18222.
Aktualizácie DPP API akceptujú hlavičku Idempotency-Key: rovnaký kľúč s rovnakou požiadavkou do 24 hodín vráti prvú odpoveď a nevytvorí druhú verziu.
Verejné pasy
Každý pas má trvalú adresu (GS1 Digital Link /01/{GTIN}/21/{serial} alebo /id/{operator}/{model}/{serial}). S Accept: application/json alebo ?format=json vráti JSON najnovšej verzie pre vašu úroveň prístupu; ?version=N danú verziu; /versions zoznam.
Každá verzia je podpísaná: X-Passport-SHA256 nesie SHA-256 kanonického JSON podľa RFC 8785 celej verzie, X-Passport-Signature jej podpis Ed25519 nad týmto hexadecimálnym reťazcom a X-Passport-Key-Id kľúč, ktorým bola podpísaná. Verejné kľúče a schéma sú uvedené v časti Strojovo čitateľné popisy.
Webhooky
Namiesto opakovaného dopytovania pridajte koncový bod v časti Spoločnosť → Webhooky. Udalosti – 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 – sa odosielajú metódou POST ako JSON s hlavičkami X-Webhook-Id, X-Webhook-Timestamp a X-Webhook-Signature = v1= + hexadecimálny HMAC-SHA256 z timestamp.body s vaším tajomstvom. Odpovedzte 2xx do 10 sekúnd; neúspešné doručenia sa opakujú 24 hodín.
Strojovo čitateľné popisy
- Verejné podpisové kľúče (JWKS)/.well-known/batterycompliance-signing-key.json
- Schéma JSON pasu/schema/battery-passport/2.0.0
- OpenAPI 3.1 – API na správu pasov/openapi.json
- OpenAPI 3.1 – DPP API/openapi-dpp.json
Získajte kľúč API
Zaregistrujte svoju spoločnosť a potom vytvorte kľúč v časti Spoločnosť → Kľúče API. Kľúče sa zobrazia raz a ukladajú sa iba ako hash.