Razvijalci
Dva API-ja
API za upravljanje potnih listov
/openapi.jsonZa podjetje, ki je lastnik potnih listov: seznam modelov in izdelkov (po kazalcu, z updatedSince za sinhronizacijo), ustvarjanje izdelkov, obsegov in kopij modelov, posodabljanje podatkov izdelka, objava (enega izdelka ali v ozadju) in pridobivanje kod QR. Overjanje s ključem API.
Referenca: API za upravljanje potnih listovAPI DPP (EN 18222)
/openapi-dpp.jsonAPI Life Cycle in Fine Granular po EN 18222: branje potnih listov na vaši ravni dostopa, iskanje ID-jev potnih listov po ID-ju izdelka, beleženje dogodkov (popravilo, stanje staranja, stanje) z dostopnim žetonom OAuth 2.0. Javne podatke je mogoče brati brez žetona.
Referenca: API DPP (EN 18222)
Preberite potni list
Vsak naslov potnega lista odgovori z JSON, ko to zahtevate – za javne podatke ključ ni potreben. Glave vsebujejo različico, njen SHA-256 in podpis Ed25519, tako da lahko prebrano preverite z našimi javnimi ključi.
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 delujeta API-ja
Overjanje
Ključe API ustvari lastnik podjetja v Podjetje → Ključi API in se prikažejo enkrat. Pošiljajte jih kot Authorization: Bearer bcp_live_…. Obsegi: items:read, items:write (tudi bere), items:publish, qr:read.
Odjemalce OAuth 2.0 (client credentials) ustvari lastnik podjetja za svoje partnerje ali platforma za organe in odobrene tretje osebe. Žeton pridobite s POST /oauth/token (grant_type=client_credentials); velja 15 minut. Obsegi: dpp:read, dpp:search, dpp:write.
Omejitve in napake
60 zahtev na minuto na ključ API (glave X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset) in 120 na minuto na odjemalca OAuth ali brez žetona na naslov. Ob preseganju: HTTP 429 z Retry-After.
API za upravljanje potnih listov na napake odgovori z objektom error s code, message in details; API DPP odgovori s statusCode, payload in result s kodami stanja po EN 18222.
Posodobitve API DPP sprejemajo glavo Idempotency-Key: isti ključ z isto zahtevo v 24 urah vrne prvi odgovor in ne ustvari druge različice.
Javni potni listi
Vsak potni list ima stalen naslov (GS1 Digital Link /01/{GTIN}/21/{serial} ali /id/{operator}/{model}/{serial}). Z Accept: application/json ali ?format=json vrne JSON zadnje različice za vašo raven dostopa; ?version=N določeno različico; /versions seznam.
Vsaka različica je podpisana: X-Passport-SHA256 vsebuje SHA-256 kanoničnega JSON po RFC 8785 celotne različice, X-Passport-Signature njen podpis Ed25519 nad tem šestnajstiškim nizom in X-Passport-Key-Id ključ, ki je podpisal. Javni ključi in shema so navedeni pod Strojno berljivi opisi.
Webhooki
Namesto spraševanja dodajte končno točko v Podjetje → Webhooki. Dogodki – 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 pošljejo s POST kot JSON z glavami X-Webhook-Id, X-Webhook-Timestamp in X-Webhook-Signature = v1= + šestnajstiški HMAC-SHA256 vrednosti timestamp.body z vašo skrivnostjo. Odgovorite z 2xx v 10 sekundah; neuspele dostave se ponavljajo 24 ur.
Strojno berljivi opisi
- Javni podpisni ključi (JWKS)/.well-known/batterycompliance-signing-key.json
- Shema JSON potnega lista/schema/battery-passport/2.0.0
- OpenAPI 3.1 – API za upravljanje potnih listov/openapi.json
- OpenAPI 3.1 – API DPP/openapi-dpp.json
Pridobite ključ API
Registrirajte podjetje, nato ustvarite ključ v Podjetje → Ključi API. Ključi se prikažejo enkrat in se hranijo samo kot zgoščena vrednost.