Aqbeż għall-kontenut ewlieni
Battery Compliance
Ibda b’xejn
Menu

Żviluppaturi

Qabbad l-ERP jew is-sistemi tal-produzzjoni tiegħek: oħloq u ippubblika passaporti tal-batteriji, aqrahom u aġġornahom permezz ta’ API DPP li ssegwi l-EN 18222, u rċievi avvenimenti b’webhook. L-aċċess għall-API huwa inkluż f’kull pjan, inkluż Free.

Żewġ API

  • API tal-ġestjoni tal-passaporti

    /openapi.json

    Għall-kumpanija li għandha l-passaporti: elenka mudelli u oġġetti (b’cursor, b’updatedSince għas-sinkronizzazzjoni), oħloq oġġetti, firxiet u kopji ta’ mudelli, aġġorna d-data tal-oġġetti, ippubblika (oġġett wieħed jew fl-isfond) u ikseb kodiċijiet QR. Awtentikata b’ċavetta API.

    Referenza: API tal-ġestjoni tal-passaporti

  • API DPP (EN 18222)

    /openapi-dpp.json

    API Life Cycle u Fine Granular li ssegwi l-EN 18222: aqra passaporti fil-livell ta’ aċċess tiegħek, fittex ID tal-passaporti skont l-ID tal-prodott, irreġistra avvenimenti (tiswija, stat tas-saħħa, stat) b’token ta’ aċċess OAuth 2.0. Id-data pubblika tista’ tinqara mingħajr token.

    Referenza: API DPP (EN 18222)

Aqra passaport

Kull indirizz ta’ passaport iwieġeb b’JSON meta titlobha – ma tinħtieġ l-ebda ċavetta għad-data pubblika. Il-headers iġorru l-verżjoni, l-SHA-256 tagħha u l-firma Ed25519, biex tkun tista’ tiċċekkja dak li qrajt maċ-ċwievet pubbliċi tagħna.

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", … }, … }
Valuri twal huma mqassra. B’token ta’ aċċess l-istess indirizz jirritorna l-oqsma tal-livell ta’ aċċess tiegħek u X-Passport-Access-Level isemmih.

Kif jaħdmu l-API

Awtentikazzjoni

Iċ-ċwievet API jinħolqu mis-sid tal-kumpanija f’Company → API keys u jidhru darba biss. Ibgħathom bħala Authorization: Bearer bcp_live_…. Skopijiet: items:read, items:write (jaqra wkoll), items:publish, qr:read.

Il-clients OAuth 2.0 (client credentials) jinħolqu mis-sid tal-kumpanija għas-sħab tiegħu, jew mill-pjattaforma għall-awtoritajiet u partijiet terzi approvati. Ikseb token b’POST /oauth/token (grant_type=client_credentials); huwa validu għal 15-il minuta. Skopijiet: dpp:read, dpp:search, dpp:write.

Limiti u żbalji

60 talba fil-minuta għal kull ċavetta API (headers X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset) u 120 fil-minuta għal kull client OAuth jew, mingħajr token, għal kull indirizz. Meta jinqabeż il-limitu: HTTP 429 b’Retry-After.

L-API tal-ġestjoni tal-passaporti twieġeb l-iżbalji b’oġġett error ta’ code, message u details; l-API DPP twieġeb statusCode, payload u result bil-kodiċijiet tal-istat tal-EN 18222.

L-aġġornamenti tal-API DPP jaċċettaw header Idempotency-Key: l-istess ċavetta bl-istess talba fi żmien 24 siegħa tirritorna l-ewwel tweġiba u ma toħloq l-ebda verżjoni oħra.

Passaporti pubbliċi

Kull passaport għandu indirizz permanenti (GS1 Digital Link /01/{GTIN}/21/{serial} jew /id/{operator}/{model}/{serial}). Bi Accept: application/json jew ?format=json jirritorna l-JSON tal-aħħar verżjoni għal-livell ta’ aċċess tiegħek; ?version=N verżjoni partikolari; /versions il-lista.

Kull verżjoni hija ffirmata: X-Passport-SHA256 iġorr l-SHA-256 tal-JSON kanoniku RFC 8785 tal-verżjoni sħiħa, X-Passport-Signature il-firma Ed25519 tiegħu fuq dik il-kordi esadeċimali u X-Passport-Key-Id iċ-ċavetta li ffirmatu. Iċ-ċwievet pubbliċi u l-iskema huma elenkati taħt Deskrizzjonijiet li jinqraw mill-magni.

Webhooks

Minflok tistaqsi l-API kontinwament, żid endpoint f’Company → Webhooks. L-avvenimenti – 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 – jintbagħtu b’POST bħala JSON bil-headers X-Webhook-Id, X-Webhook-Timestamp u X-Webhook-Signature = v1= + HMAC-SHA256 esadeċimali ta’ timestamp.body bis-sigriet tiegħek. Wieġeb 2xx fi żmien 10 sekondi; il-kunsinni li jfallu jerġgħu jiġu pprovati għal 24 siegħa.

Deskrizzjonijiet li jinqraw mill-magni

Ikseb ċavetta API

Irreġistra l-kumpanija tiegħek, imbagħad oħloq ċavetta f’Company → API keys. Iċ-ċwievet jidhru darba biss u jinħażnu biss bħala hash.

Ibda b’xejnKellimna