Kehittäjille
Kaksi API:a
Passinhallinnan API
/openapi.jsonPassit omistavalle yritykselle: luettele mallit ja yksilöt (kursorilla, updatedSince-parametrilla synkronointiin), luo yksilöitä, sarjoja ja mallien kopioita, päivitä yksilön tietoja, julkaise (yksi yksilö tai taustalla) ja hae QR-koodit. Todennus API-avaimella.
Viite: Passinhallinnan APIDPP-API (EN 18222)
/openapi-dpp.jsonEN 18222 -standardia noudattava Life Cycle- ja Fine Granular -API: lue passit käyttötasollasi, hae passitunnisteita tuotetunnisteen perusteella, kirjaa tapahtumia (korjaus, toimintakunto, tila) OAuth 2.0 -käyttötunnuksella. Julkisia tietoja voi lukea ilman tunnusta.
Viite: DPP-API (EN 18222)
Lue passi
Jokainen passin osoite vastaa JSON-muodossa, kun sitä pyydät – julkisiin tietoihin ei tarvita avainta. Otsikot sisältävät version, sen SHA-256-tiivisteen ja Ed25519-allekirjoituksen, joten voit tarkistaa lukemasi julkisia avaimiamme vasten.
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", … }, … }Miten API:t toimivat
Todennus
Yrityksen omistaja luo API-avaimet kohdassa Company → API keys, ja ne näytetään kerran. Lähetä ne muodossa Authorization: Bearer bcp_live_…. Oikeudet: items:read, items:write (lukee myös), items:publish, qr:read.
OAuth 2.0 -asiakkaat (client credentials) luo yrityksen omistaja kumppaneilleen tai alusta viranomaisille ja hyväksytyille kolmansille osapuolille. Hae tunnus komennolla POST /oauth/token (grant_type=client_credentials); se on voimassa 15 minuuttia. Oikeudet: dpp:read, dpp:search, dpp:write.
Rajat ja virheet
60 pyyntöä minuutissa API-avainta kohden (otsikot X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset) ja 120 minuutissa OAuth-asiakasta kohden tai, ilman tunnusta, osoitetta kohden. Rajan ylittyessä: HTTP 429 ja Retry-After.
Passinhallinnan API vastaa virheisiin error-oliolla, jossa on code, message ja details; DPP-API vastaa kentillä statusCode, payload ja result EN 18222 -standardin tilakoodeilla.
DPP-API:n päivitykset hyväksyvät Idempotency-Key-otsikon: sama avain samalla pyynnöllä 24 tunnin kuluessa palauttaa ensimmäisen vastauksen eikä luo toista versiota.
Julkiset passit
Jokaisella passilla on pysyvä osoite (GS1 Digital Link /01/{GTIN}/21/{serial} tai /id/{operator}/{model}/{serial}). Otsikolla Accept: application/json tai parametrilla ?format=json se palauttaa uusimman version JSON-muodossa käyttötasollesi; ?version=N tietyn version; /versions luettelon.
Jokainen versio on allekirjoitettu: X-Passport-SHA256 sisältää koko version RFC 8785 -kanonisen JSON:in SHA-256-tiivisteen, X-Passport-Signature sen Ed25519-allekirjoituksen tämän heksamerkkijonon yli ja X-Passport-Key-Id allekirjoittaneen avaimen. Julkiset avaimet ja skeema on lueteltu kohdassa Koneluettavat kuvaukset.
Webhookit
Kyselyn sijaan lisää päätepiste kohdassa Company → Webhooks. Tapahtumat – 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 – lähetetään POST-pyyntönä JSON-muodossa otsikoilla X-Webhook-Id, X-Webhook-Timestamp ja X-Webhook-Signature = v1= + heksamuotoinen HMAC-SHA256 merkkijonosta timestamp.body salaisuudellasi. Vastaa 2xx 10 sekunnin kuluessa; epäonnistuneita toimituksia yritetään uudelleen 24 tuntia.
Koneluettavat kuvaukset
- Julkiset allekirjoitusavaimet (JWKS)/.well-known/batterycompliance-signing-key.json
- Passin JSON-skeema/schema/battery-passport/2.0.0
- OpenAPI 3.1 – passinhallinnan API/openapi.json
- OpenAPI 3.1 – DPP-API/openapi-dpp.json
Hanki API-avain
Rekisteröi yrityksesi ja luo sitten avain kohdassa Company → API keys. Avaimet näytetään kerran ja tallennetaan vain tiivisteenä.