Razvojni programeri
Dva API-ja
API za upravljanje putovnicama
/openapi.jsonZa poduzeće koje je vlasnik putovnica: popis modela i jedinica (kursorom, s updatedSince za sinkronizaciju), izrada jedinica, raspona i kopija modela, ažuriranje podataka jedinice, objava (jedne jedinice ili u pozadini) i dohvat QR kodova. Autentifikacija API ključem.
Referenca: API za upravljanje putovnicamaDPP API (EN 18222)
/openapi-dpp.jsonLife Cycle i Fine Granular API prema EN 18222: čitanje putovnica na vašoj razini pristupa, pretraživanje ID-jeva putovnica prema ID-ju proizvoda, bilježenje događaja (popravak, stanje starosti, status) pristupnim tokenom OAuth 2.0. Javni podaci mogu se čitati bez tokena.
Referenca: DPP API (EN 18222)
Pročitajte putovnicu
Svaka adresa putovnice odgovara JSON-om kada ga zatražite – za javne podatke ključ nije potreban. Zaglavlja nose inačicu, njezin SHA-256 i Ed25519 potpis, pa ono što čitate možete provjeriti prema našim javnim ključevima.
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", … }, … }Kako API-ji funkcioniraju
Autentifikacija
API ključeve izrađuje vlasnik poduzeća u Poduzeće → API ključevi i prikazuju se jednom. Šaljite ih kao Authorization: Bearer bcp_live_…. Opsezi: items:read, items:write (uključuje i čitanje), items:publish, qr:read.
OAuth 2.0 klijente (client credentials) izrađuje vlasnik poduzeća za svoje partnere, a platforma za tijela i odobrene treće strane. Token dobivate s POST /oauth/token (grant_type=client_credentials); vrijedi 15 minuta. Opsezi: dpp:read, dpp:search, dpp:write.
Ograničenja i pogreške
60 zahtjeva u minuti po API ključu (zaglavlja X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset) i 120 u minuti po OAuth klijentu ili, bez tokena, po adresi. Iznad ograničenja: HTTP 429 sa Retry-After.
API za upravljanje putovnicama na pogreške odgovara objektom error s poljima code, message i details; DPP API odgovara poljima statusCode, payload i result sa statusnim kodovima iz EN 18222.
Ažuriranja DPP API-ja prihvaćaju zaglavlje Idempotency-Key: isti ključ s istim zahtjevom unutar 24 sata vraća prvi odgovor i ne izrađuje drugu inačicu.
Javne putovnice
Svaka putovnica ima trajnu adresu (GS1 Digital Link /01/{GTIN}/21/{serial} ili /id/{operator}/{model}/{serial}). Uz Accept: application/json ili ?format=json vraća JSON najnovije inačice za vašu razinu pristupa; ?version=N zadanu inačicu; /versions popis.
Svaka inačica je potpisana: X-Passport-SHA256 nosi SHA-256 kanonskog JSON-a cijele inačice prema RFC 8785, X-Passport-Signature njegov Ed25519 potpis nad tim heksadecimalnim nizom, a X-Passport-Key-Id ključ kojim je potpisana. Javni ključevi i shema navedeni su pod Strojno čitljivi opisi.
Webhookovi
Umjesto ispitivanja dodajte krajnju točku u Poduzeće → Webhookovi. Događaji – 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 – šalju se POST-om kao JSON sa zaglavljima X-Webhook-Id, X-Webhook-Timestamp i X-Webhook-Signature = v1= + heksadecimalni HMAC-SHA256 od timestamp.body s vašom tajnom. Odgovorite 2xx u roku od 10 sekundi; neuspjele isporuke ponavljaju se 24 sata.
Strojno čitljivi opisi
- Javni ključevi za potpis (JWKS)/.well-known/batterycompliance-signing-key.json
- JSON shema putovnice/schema/battery-passport/2.0.0
- OpenAPI 3.1 – API za upravljanje putovnicama/openapi.json
- OpenAPI 3.1 – DPP API/openapi-dpp.json
Nabavite API ključ
Registrirajte svoje poduzeće, zatim izradite ključ u Poduzeće → API ključevi. Ključevi se prikazuju jednom i pohranjuju samo kao sažetak.