Développeurs
Deux API
API de gestion des passeports
/openapi.jsonPour l’entreprise qui détient les passeports : lister les modèles et les exemplaires (par curseur, avec updatedSince pour la synchronisation), créer des exemplaires, des plages et des copies de modèles, mettre à jour les données d’un exemplaire, publier (un exemplaire ou en arrière-plan) et obtenir les codes QR. Authentification par clé API.
Référence : API de gestion des passeportsAPI DPP (EN 18222)
/openapi-dpp.jsonAPI Life Cycle et Fine Granular conforme à l’EN 18222 : lire les passeports à votre niveau d’accès, rechercher des identifiants de passeports par identifiant de produit, enregistrer des événements (réparation, état de santé, statut) avec un jeton d’accès OAuth 2.0. Les données publiques se lisent sans jeton.
Référence : API DPP (EN 18222)
Lire un passeport
Chaque adresse de passeport répond en JSON lorsque vous le demandez – aucune clé nécessaire pour les données publiques. Les en-têtes contiennent la version, son SHA-256 et la signature Ed25519, de sorte que vous pouvez vérifier ce que vous lisez avec nos clés publiques.
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", … }, … }Comment fonctionnent les API
Authentification
Les clés API sont créées par le propriétaire de l’entreprise dans Entreprise → Clés API et affichées une seule fois. Envoyez-les sous la forme Authorization: Bearer bcp_live_…. Portées : items:read, items:write (lit aussi), items:publish, qr:read.
Les clients OAuth 2.0 (client credentials) sont créés par le propriétaire de l’entreprise pour ses partenaires, ou par la plateforme pour les autorités et les tiers approuvés. Obtenez un jeton avec POST /oauth/token (grant_type=client_credentials) ; il est valable 15 minutes. Portées : dpp:read, dpp:search, dpp:write.
Limites et erreurs
60 requêtes par minute par clé API (en-têtes X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset) et 120 par minute par client OAuth ou, sans jeton, par adresse. Au-delà de la limite : HTTP 429 avec Retry-After.
L’API de gestion des passeports répond aux erreurs par un objet error contenant code, message et details ; l’API DPP répond par statusCode, payload et result avec les codes d’état de l’EN 18222.
Les mises à jour de l’API DPP acceptent un en-tête Idempotency-Key : la même clé avec la même requête dans les 24 heures renvoie la première réponse et ne crée pas de seconde version.
Passeports publics
Chaque passeport a une adresse permanente (GS1 Digital Link /01/{GTIN}/21/{serial} ou /id/{operator}/{model}/{serial}). Avec Accept: application/json ou ?format=json, elle renvoie le JSON de la dernière version pour votre niveau d’accès ; ?version=N une version donnée ; /versions la liste.
Chaque version est signée : X-Passport-SHA256 contient le SHA-256 du JSON canonique RFC 8785 de la version complète, X-Passport-Signature sa signature Ed25519 sur cette chaîne hexadécimale et X-Passport-Key-Id la clé qui l’a signée. Les clés publiques et le schéma sont listés sous Descriptions lisibles par machine.
Webhooks
Au lieu d’interroger l’API en continu, ajoutez un point de terminaison dans Entreprise → Webhooks. Les événements – 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 – sont envoyés en POST au format JSON avec les en-têtes X-Webhook-Id, X-Webhook-Timestamp et X-Webhook-Signature = v1= + HMAC-SHA256 hexadécimal de timestamp.body avec votre secret. Répondez 2xx dans les 10 secondes ; les envois échoués sont retentés pendant 24 heures.
Descriptions lisibles par machine
- Clés de signature publiques (JWKS)/.well-known/batterycompliance-signing-key.json
- Schéma JSON du passeport/schema/battery-passport/2.0.0
- OpenAPI 3.1 – API de gestion des passeports/openapi.json
- OpenAPI 3.1 – API DPP/openapi-dpp.json
Obtenir une clé API
Inscrivez votre entreprise, puis créez une clé dans Entreprise → Clés API. Les clés sont affichées une seule fois et conservées uniquement sous forme d’empreinte.