Sviluppatori
Due API
API di gestione dei passaporti
/openapi.jsonPer l’azienda titolare dei passaporti: elenca modelli ed elementi (per cursore, con updatedSince per la sincronizzazione), crea elementi, intervalli e copie di modelli, aggiorna i dati degli elementi, pubblica (un elemento o in background) e ottieni i codici QR. Autenticata con una chiave API.
Riferimento: API di gestione dei passaportiAPI DPP (EN 18222)
/openapi-dpp.jsonAPI Life Cycle e Fine Granular conforme a EN 18222: leggi i passaporti al tuo livello di accesso, cerca gli ID dei passaporti per ID del prodotto, registra eventi (riparazione, stato di salute, stato) con un token di accesso OAuth 2.0. I dati pubblici si leggono senza token.
Riferimento: API DPP (EN 18222)
Leggi un passaporto
Ogni indirizzo di passaporto risponde con JSON quando lo richiedi – nessuna chiave necessaria per i dati pubblici. Le intestazioni riportano la versione, il suo SHA-256 e la firma Ed25519, così puoi confrontare ciò che leggi con le nostre chiavi pubbliche.
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", … }, … }Come funzionano le API
Autenticazione
Le chiavi API sono create dal titolare dell’azienda in Azienda → Chiavi API e mostrate una sola volta. Inviale come Authorization: Bearer bcp_live_…. Ambiti: items:read, items:write (include la lettura), items:publish, qr:read.
I client OAuth 2.0 (client credentials) sono creati dal titolare dell’azienda per i suoi partner, o dalla piattaforma per autorità e terzi approvati. Ottieni un token con POST /oauth/token (grant_type=client_credentials); è valido per 15 minuti. Ambiti: dpp:read, dpp:search, dpp:write.
Limiti ed errori
60 richieste al minuto per chiave API (intestazioni X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset) e 120 al minuto per client OAuth o, senza token, per indirizzo. Oltre il limite: HTTP 429 con Retry-After.
L’API di gestione dei passaporti risponde agli errori con un oggetto error composto da code, message e details; l’API DPP risponde con statusCode, payload e result con i codici di stato di EN 18222.
Gli aggiornamenti dell’API DPP accettano un’intestazione Idempotency-Key: la stessa chiave con la stessa richiesta entro 24 ore restituisce la prima risposta e non crea una seconda versione.
Passaporti pubblici
Ogni passaporto ha un indirizzo permanente (GS1 Digital Link /01/{GTIN}/21/{serial} oppure /id/{operator}/{model}/{serial}). Con Accept: application/json o ?format=json restituisce il JSON dell’ultima versione per il tuo livello di accesso; ?version=N una versione data; /versions l’elenco.
Ogni versione è firmata: X-Passport-SHA256 contiene lo SHA-256 del JSON canonico RFC 8785 dell’intera versione, X-Passport-Signature la sua firma Ed25519 su quella stringa esadecimale e X-Passport-Key-Id la chiave che l’ha firmata. Le chiavi pubbliche e lo schema sono elencati in Descrizioni leggibili dalle macchine.
Webhook
Invece di interrogare l’API, aggiungi un endpoint in Azienda → Webhook. Gli eventi – 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 – vengono inviati con POST come JSON con le intestazioni X-Webhook-Id, X-Webhook-Timestamp e X-Webhook-Signature = v1= + HMAC-SHA256 esadecimale di timestamp.body con il tuo segreto. Rispondi 2xx entro 10 secondi; le consegne non riuscite vengono ritentate per 24 ore.
Descrizioni leggibili dalle macchine
- Chiavi di firma pubbliche (JWKS)/.well-known/batterycompliance-signing-key.json
- Schema JSON del passaporto/schema/battery-passport/2.0.0
- OpenAPI 3.1 – API di gestione dei passaporti/openapi.json
- OpenAPI 3.1 – API DPP/openapi-dpp.json
Ottieni una chiave API
Registra la tua azienda, poi crea una chiave in Azienda → Chiavi API. Le chiavi vengono mostrate una sola volta e conservate solo come hash.