Connecter les données du passeport à vos systèmes.

Quatre objets et quatre voies d’échange de données. Un fichier CSV suffit pour commencer ; l’API REST sert à l’exploitation courante.

1. EntrepriseVotre compte avec utilisateurs et formule
2. ModèleDonnées de base, une fois par modèle
3. PasseportUne batterie avec numéro de série et adresse propre
4. ÉvénementRéparation, réaffectation ou déchet

La voie habituelle depuis l’ERP : exporter une liste et la téléverser dans un modèle. Chaque nouveau numéro de série reçoit un passeport.

Material;Serialnummer;Fertigungsdatum;Charge;Werk;Status
BX-48V;SN-0001;01.03.2027;L2027-03;Essen;frei
BX-48V;SN-0002;01.03.2027;L2027-03;Essen;frei
BX-48V;SN-0003;02.03.2027;L2027-03;Essen;frei

Ce qui se passe au téléversement

• Un aperçu s’affiche d’abord ; rien n’est encore enregistré.
• Les lignes erronées sont signalées avec leur numéro et ignorées.
• Les doublons du fichier et les numéros déjà présents dans ce modèle sont ignorés.
• Les passeports ne sont créés qu’après votre confirmation, en une seule opération. L’import figure dans le journal d’audit.

Vérifiez un export avant de vous connecter. Les règles sont les mêmes que pour l’import dans l’application.

Pour chaque modèle, la liste de tous les passeports se télécharge en UTF-8 avec BOM, séparée par des points-virgules. Identifiants et adresses reviennent ainsi dans l’ERP, le MES ou l’impression d’étiquettes. Le téléchargement nécessite une connexion.

Seriennummer;Pass-ID;Pass-URL;Herstelldatum;Charge;Herstellort;Status
SN-0001;7KM2XQ9RTA;https://app.digitalbatterypass.eu/p/7KM2XQ9RTA;2027-03-01;L2027-03;Essen;Original

Chaque passeport a une adresse fixe. Un code QR, un lien dans un manuel ou une entrée d’ERP n’ont besoin de rien d’autre.

https://app.digitalbatterypass.eu/p/{PASS-ID}
https://app.digitalbatterypass.eu/p/{PASS-ID}?lang=en

• L’identifiant comporte 10 caractères et évite ceux qui prêtent à confusion comme 0, O, 1, I et L.
• Le code QR ne contient que cette adresse. Si les données changent, il reste valable.
• Dans l’application, le code est disponible par passeport en SVG et PNG, ainsi que des planches d’étiquettes à imprimer.
• Sans connexion, la page du passeport n’affiche que les données publiques. Les moteurs de recherche sont priés de ne pas l’indexer.
• Avec un GTIN, il existe aussi un lien GS1 Digital Link.

Créer vos étiquettes à partir de l’export

# pip install "qrcode[pil]"
import csv
import qrcode

with open("paesse_BX-48V.csv", encoding="utf-8-sig", newline="") as f:
    for row in csv.DictReader(f, delimiter=";"):
        qrcode.make(row["Pass-URL"]).save(f'{row["Pass-ID"]}.png')

Passeport en JSON au format UE

La même adresse fournit la page aux personnes et le JSON selon le schéma UE 1.0.0 aux programmes, sans connexion et avec les seules données publiques. Si des données obligatoires manquent, elles manquent aussi dans le JSON et le registre refuserait le passeport.

curl -H "Accept: application/json" https://app.digitalbatterypass.eu/p/{PASS-ID}
curl https://app.digitalbatterypass.eu/p/{PASS-ID}?format=json

L’application utilise 67 champs selon le schéma officiel UE pour les batteries, version 1.0.0. Envoyez les champs multiples sous forme de liste ; GET /fields fournit les valeurs autorisées. Les catégories sont lmt, industrie, ev, sli et geraet.

Créez modèles et passeports directement depuis l’ERP, le MES ou le BMS et signalez des événements. JSON sur HTTPS, authentification par clé. Adresse de base : https://app.digitalbatterypass.eu/api/v1

En production, l’API REST fait partie de l’offre Enterprise. Avec Pro, vous n’envoyez que les mesures BMS. Les clés de test sont disponibles dans toutes les offres.

Démarrer en trois étapes

1. Connectez-vous en tant qu’administrateur et ouvrez Paramètres, puis Clés API.
2. Créez une clé de test. Elle ne s’affiche qu’une fois ; conservez-la comme un mot de passe.
3. Vérifiez la connexion avec GET /me. Si l’API répond, la clé et le chemin réseau sont corrects.

export BATTERYPASS_KEY="bp_test_..."

curl -s https://app.digitalbatterypass.eu/api/v1/me \
  -H "Authorization: Bearer $BATTERYPASS_KEY"

Les clés de test répondent avec le statut 200 et dry_run: true. Elles lisent les vraies données sans rien modifier.

Points de terminaison

Exemple : créer des passeports depuis l’ERP

curl -X POST https://app.digitalbatterypass.eu/api/v1/passports/batch \
  -H "Authorization: Bearer $BATTERYPASS_KEY" \
  -H "Idempotency-Key: erp-4711" \
  -H "Content-Type: application/json" \
  -d '{
  "model_code": "BX-48V",
  "on_conflict": "skip",
  "items": [
    { "serial": "SN-0001", "manufactured_at": "2027-03-01", "batch": "L2027-03" },
    { "serial": "SN-0002", "manufactured_at": "2027-03-01", "batch": "L2027-03" }
  ]
}'

import os
import requests

res = requests.post(
    "https://app.digitalbatterypass.eu/api/v1/passports/batch",
    headers={
        "Authorization": f"Bearer {os.environ['BATTERYPASS_KEY']}",
        "Idempotency-Key": "erp-4711",
    },
    json={
        "model_code": "BX-48V",
        "on_conflict": "skip",
        "items": [{"serial": "SN-0001", "manufactured_at": "2027-03-01"}],
    },
    timeout=30,
)
res.raise_for_status()
print(res.json()["created"])

const res = await fetch("https://app.digitalbatterypass.eu/api/v1/passports/batch", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BATTERYPASS_KEY}`,
    "Idempotency-Key": "erp-4711",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model_code: "BX-48V",
    on_conflict: "skip",
    items: [{ serial: "SN-0001", manufactured_at: "2027-03-01" }],
  }),
});
if (!res.ok) throw new Error(`HTTP ${res.status}`);
console.log((await res.json()).created);

<?php
$ch = curl_init("https://app.digitalbatterypass.eu/api/v1/passports/batch");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("BATTERYPASS_KEY"),
        "Idempotency-Key: erp-4711",
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "model_code" => "BX-48V",
        "on_conflict" => "skip",
        "items" => [["serial" => "SN-0001", "manufactured_at" => "2027-03-01"]],
    ]),
]);
echo curl_exec($ch);

Réponse

HTTP/1.1 201 Created
X-Request-Id: req_4f7a91c2d03e8b56

{
  "created": 1,
  "skipped": 1,
  "skipped_serials": ["SN-0002"],
  "items": [
    {
      "id": "7KM2XQ9RTA",
      "serial": "SN-0001",
      "status": "original",
      "url": "https://app.digitalbatterypass.eu/p/7KM2XQ9RTA"
    }
  ]
}

Erreurs

HTTP/1.1 422 Unprocessable Entity

{
  "error": {
    "code": "invalid_serial",
    "message": "Serial number is missing or contains invalid characters.",
    "field": "items[3].serial",
    "request_id": "req_a03c5e17b92d4f68"
  }
}

Limites

Vous prévoyez plus de 100 000 passeports par an ? Parlons-en à l’avance.

Chaque clé ne reçoit que les droits nécessaires. S’il en manque un, l’API répond 403 et insufficient_scope. Dans l’application, vous choisissez un modèle : Tous les droits, ERP, BMS ou Lecture seule.

Les listes arrivent par pages avec data, has_more et next_cursor. Transmettez next_cursor comme cursor. Les champs inconnus sont refusés pour révéler les fautes de frappe. Avec PATCH, un champ absent reste inchangé et null le vide.

Deux clients légers sans dépendances : ils répètent les requêtes en sécurité, parcourent les listes et découpent les gros volumes en appels de 1 000 passeports. Ce sont des fichiers uniques à copier dans votre projet. La console API se trouve dans l’application sous Paramètres, Clés API. Les bibliothèques font partie de l’offre Enterprise.

from batterypass import Batterypass

bp = Batterypass("bp_test_...")
print(bp.me()["organization"]["plan"])

items = [{"serial": f"SN-{i:06}"} for i in range(5000)]
print(bp.create_passports_all("BX-48V", items))

for passport in bp.list_all("/passports", model_code="BX-48V"):
    print(passport["serial"], passport["url"])

import { Batterypass } from "./batterypass.mjs";

const bp = new Batterypass({ apiKey: process.env.BATTERYPASS_KEY });
console.log((await bp.me()).organization.plan);

const items = Array.from({ length: 5000 }, (_, i) => ({ serial: `SN-${i}` }));
console.log(await bp.createPassportsAll("BX-48V", items));

for await (const passport of bp.listAll("/passports", { model_code: "BX-48V" })) {
  console.log(passport.serial, passport.url);
}

Consignez les modules, cellules ou BMS installés dans une batterie. Un numéro de série ne peut être installé qu’une fois à la fois par passeport. Lors d’un remplacement, l’ancienne pièce reste enregistrée avec sa date de retrait.

curl -X POST https://app.digitalbatterypass.eu/api/v1/passports/7KM2XQ9RTA/components \
  -H "Authorization: Bearer $BATTERYPASS_KEY" -H "Content-Type: application/json" \
  -d '{"kind": "module", "label": "Modul 1", "serial": "M-0001", "supplier": "Zellwerk GmbH"}'

curl -X POST https://app.digitalbatterypass.eu/api/v1/passports/7KM2XQ9RTA/components/12/replace \
  -H "Authorization: Bearer $BATTERYPASS_KEY" -H "Content-Type: application/json" \
  -d '{"serial": "M-0002", "note": "Modul nach Defekt getauscht"}'

Les types autorisés sont pack, rack, module, cell, bms et other.

Signalez les données du BMS, une à une ou jusqu’à 1 000 mesures avec items. Lisez la série avec since et until. Les mesures sont disponibles à partir de la formule Pro. Elles apparaissent dans l’application et pour les ayants droit, pas sur la page publique.

curl -X POST https://app.digitalbatterypass.eu/api/v1/passports/7KM2XQ9RTA/telemetry \
  -H "Authorization: Bearer $BATTERYPASS_KEY" -H "Content-Type: application/json" \
  -d '{"recorded_at": "2027-03-01T10:00:00Z", "soh_pct": 94.5, "cycle_count": 120}'

Téléversez rapports d’essai, déclarations de conformité et documents similaires dans le modèle : PDF, PNG ou JPG jusqu’à 10 Mo. Via l’API, vous lisez la liste et obtenez un lien de téléchargement valable 15 minutes. Chaque fichier a une somme de contrôle SHA-256.

curl -s "https://app.digitalbatterypass.eu/api/v1/certificates?model_code=BX-48V" -H "Authorization: Bearer $BATTERYPASS_KEY"
curl -s https://app.digitalbatterypass.eu/api/v1/certificates/42 -H "Authorization: Bearer $BATTERYPASS_KEY"

Demandez des valeurs aux fournisseurs. Ils reçoivent un e-mail avec un lien valable 30 jours et ne saisissent que les champs demandés, sans compte. Les valeurs n’arrivent dans le modèle qu’après votre validation. Disponible à partir de Starter, 20 demandes maximum par heure.

curl -X POST https://app.digitalbatterypass.eu/api/v1/supplier-requests \
  -H "Authorization: Bearer $BATTERYPASS_KEY" -H "Content-Type: application/json" \
  -d '{"model_code": "BX-48V", "supplier_name": "Zellwerk GmbH", "supplier_email": "daten@zellwerk.example",
       "fields": ["chemistry", "composition_cathode"], "message": "Bitte bis Monatsende"}'

curl -s "https://app.digitalbatterypass.eu/api/v1/supplier-requests?status=submitted" -H "Authorization: Bearer $BATTERYPASS_KEY"
curl -X POST https://app.digitalbatterypass.eu/api/v1/supplier-requests/7/accept -H "Authorization: Bearer $BATTERYPASS_KEY"

Indiquez dans le modèle un GTIN avec un chiffre de contrôle valide. L’adresse GS1 issue du GTIN et du numéro de série mène alors à la page du passeport et figure dans l’API comme gs1_link. Vos codes QR contiennent toujours l’adresse fixe, mais vous pouvez créer vos codes à partir du lien GS1. Le GTIN s’obtient auprès de GS1.

https://app.digitalbatterypass.eu/01/{GTIN}/21/{SERIENNUMMER}
https://app.digitalbatterypass.eu/01/04012345678901/21/SN-0001

GET /audit renvoie toutes les modifications journalisées, par pages et éventuellement depuis une date avec since. Les modifications via l’API portent le nom de la clé. Dans l’application, les administrateurs voient aussi les derniers appels.

L’application crée la paire de clés de votre compte de service. La clé privée reste chiffrée chez nous. La clé publique va dans le registre. Votre entreprise doit d’abord y être vérifiée avec un cachet qualifié.

Seuls les passeports publiés et complets sont soumis, par lots de 100 maximum. L’application et l’API affichent le statut. Le registre lit l’adresse du passeport en JSON ; avec son jeton d’accès, il reçoit aussi les vues protégées. Les jetons invalides sont refusés.

Conçu d’après les documents techniques de la Commission du 30/10/2026 et testé sur notre propre serveur de test. Le test dans le vrai registre reste à faire.

curl -X POST https://app.digitalbatterypass.eu/api/v1/registry/submissions \
  -H "Authorization: Bearer $BATTERYPASS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model_code":"LMT-48V"}'

curl https://app.digitalbatterypass.eu/api/v1/registry/submissions \
  -H "Authorization: Bearer $BATTERYPASS_KEY"

Avec publish: false, vous créez des brouillons. Ils ne sont pas accessibles publiquement tant que vous ne les publiez pas. Chaque modification des données de base devient une nouvelle version liée par hachage à la précédente. Sous /p/ID/proof, chacun peut recalculer l’état public.

POST /api/v1/passports/batch        {"model_code":"LMT-48V","publish":false,"items":[...]}
POST /api/v1/passports/PASS-ID/publish
GET  /api/v1/models/42/versions
GET  /p/PASS-ID/proof

La version majeure figure dans le chemin. Dans la v1, seuls des champs et des points de terminaison sont ajoutés. Prévu mais pas encore disponible : webhooks.

Réponses courtes pour l’intégration.