Kūrėjams
Du API
Paso valdymo API
/openapi.jsonPasus turinčiai įmonei: modelių ir vienetų sąrašai (pagal žymeklį, su updatedSince sinchronizavimui), vienetų, intervalų ir modelių kopijų kūrimas, vienetų duomenų atnaujinimas, skelbimas (vieno vieneto ar fone) ir QR kodų gavimas. Autentifikuojama API raktu.
Nuoroda: Paso valdymo APIDPP API (EN 18222)
/openapi-dpp.jsonGyvavimo ciklo ir smulkiagrūdis API pagal EN 18222: skaitykite pasus savo prieigos lygiu, ieškokite paso ID pagal gaminio ID, registruokite įvykius (remontas, būklė, būsena) su OAuth 2.0 prieigos raktu. Viešus duomenis galima skaityti be rakto.
Nuoroda: DPP API (EN 18222)
Perskaitykite pasą
Kiekvienas paso adresas atsako JSON, kai to paprašote – vieviems duomenims raktas nereikalingas. Antraštėse yra versija, jos SHA-256 ir Ed25519 parašas, todėl perskaitytą galite patikrinti pagal mūsų viešuosius raktus.
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", … }, … }Kaip veikia API
Autentifikavimas
API raktus sukuria įmonės savininkas skiltyje Company → API keys ir parodo vieną kartą. Siųskite juos kaip Authorization: Bearer bcp_live_…. Apimtys: items:read, items:write (taip pat skaito), items:publish, qr:read.
OAuth 2.0 klientus (client credentials) savo partneriams sukuria įmonės savininkas, o institucijoms ir patvirtintoms trečiosioms šalims – platforma. Raktą gaukite per POST /oauth/token (grant_type=client_credentials); jis galioja 15 minučių. Apimtys: dpp:read, dpp:search, dpp:write.
Limitai ir klaidos
60 užklausų per minutę vienam API raktui (antraštės X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset) ir 120 per minutę vienam OAuth klientui arba, be rakto, vienam adresui. Viršijus limitą: HTTP 429 su Retry-After.
Paso valdymo API klaidas grąžina kaip error objektą su code, message ir details; DPP API grąžina statusCode, payload ir result su EN 18222 būsenos kodais.
DPP API atnaujinimai priima antraštę Idempotency-Key: tas pats raktas su ta pačia užklausa per 24 valandas grąžina pirmąjį atsakymą ir nesukuria antros versijos.
Vieši pasai
Kiekvienas pasas turi nuolatinį adresą (GS1 Digital Link /01/{GTIN}/21/{serial} arba /id/{operator}/{model}/{serial}). Su Accept: application/json arba ?format=json grąžina naujausios versijos JSON jūsų prieigos lygiui; ?version=N – nurodytą versiją; /versions – sąrašą.
Kiekviena versija pasirašyta: X-Passport-SHA256 turi pilnos versijos RFC 8785 kanoninio JSON SHA-256, X-Passport-Signature – jo Ed25519 parašą šiai šešioliktainei eilutei, o X-Passport-Key-Id – raktą, kuriuo pasirašyta. Viešieji raktai ir schema išvardyti skiltyje Mašininiu būdu skaitomi aprašai.
Webhooks
Užuot nuolat klausinėję, pridėkite galinį tašką skiltyje Company → Webhooks. Įvykiai – 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 – siunčiami POST kaip JSON su antraštėmis X-Webhook-Id, X-Webhook-Timestamp ir X-Webhook-Signature = v1= + šešioliktainis timestamp.body HMAC-SHA256 su jūsų paslaptimi. Atsakykite 2xx per 10 sekundžių; nepavykę pristatymai kartojami 24 valandas.
Mašininiu būdu skaitomi aprašai
- Viešieji pasirašymo raktai (JWKS)/.well-known/batterycompliance-signing-key.json
- Paso JSON schema/schema/battery-passport/2.0.0
- OpenAPI 3.1 – paso valdymo API/openapi.json
- OpenAPI 3.1 – DPP API/openapi-dpp.json
Gaukite API raktą
Užregistruokite savo įmonę, tada sukurkite raktą skiltyje Company → API keys. Raktai rodomi vieną kartą ir saugomi tik kaip maišos reikšmė.