Batteriepass-Daten an Ihre Systeme anbinden.

Vier Objekte und vier Wege für den Datenaustausch. Für den Einstieg reicht eine CSV-Datei, für den Dauerbetrieb gibt es die REST-API.

1. FirmaIhr Konto mit Nutzern und Paket
2. ModellStammdaten, einmal je Batteriemodell
3. PassEine Batterie mit Seriennummer und eigener Adresse
4. EreignisReparatur, Umnutzung oder Abfall

Der übliche Weg aus dem ERP: Liste exportieren und bei einem Modell hochladen. Für jede neue Seriennummer entsteht ein Pass.

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

Was beim Hochladen passiert

• Zuerst erscheint eine Vorschau, gespeichert wird noch nichts.
• Fehlerhafte Zeilen werden mit Zeilennummer gemeldet und übersprungen.
• Doppelte Seriennummern in der Datei und bereits vorhandene Nummern dieses Modells werden übersprungen.
• Erst nach Ihrer Bestätigung entstehen die Pässe, in einem einzigen Vorgang. Der Import steht im Audit-Trail.

Prüfen Sie einen Export, bevor Sie sich anmelden. Es gelten dieselben Regeln wie beim Import in der App.

Bei jedem Modell lässt sich die Liste aller Pässe herunterladen, im Format UTF-8 mit BOM und mit Semikolon getrennt. So kommen Pass-IDs und Adressen zurück in ERP, MES oder Etikettendruck. Der Download setzt eine Anmeldung voraus.

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

Jeder Pass hat eine feste Adresse. Mehr braucht ein QR-Code, ein Link aus dem Handbuch oder ein Eintrag im ERP nicht.

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

• Die Pass-ID hat 10 Zeichen und meidet verwechselbare Zeichen wie 0, O, 1, I und L.
• Der QR-Code enthält nur diese Adresse. Ändern sich die Daten, bleibt er gültig.
• In der App gibt es den Code je Pass als SVG und PNG sowie Etikettenbögen zum Drucken.
• Die Pass-Seite zeigt ohne Anmeldung nur die öffentlichen Angaben. Suchmaschinen sollen sie nicht aufnehmen.
• Mit hinterlegter GTIN gibt es zusätzlich einen GS1 Digital Link.

Eigene Etiketten aus dem Export erzeugen

# 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')

Pass als JSON im EU-Format

Dieselbe Adresse liefert Menschen die Seite und Programmen JSON nach dem EU-Schema 1.0.0, ohne Anmeldung und nur mit den öffentlichen Angaben. Fehlen Pflichtangaben, fehlen sie auch im JSON und das Register würde den Pass ablehnen.

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

Die App nutzt 67 Felder nach dem offiziellen EU-Datenschema für Batterien, Fassung 1.0.0. Mehrfachfelder senden Sie als Liste, die erlaubten Werte liefert GET /fields. Die Kategorien sind lmt, industrie, ev, sli und geraet.

Legen Sie Modelle und Pässe direkt aus ERP, MES oder BMS an und melden Sie Ereignisse. JSON über HTTPS, Anmeldung per Schlüssel. Basisadresse: https://app.digitalbatterypass.eu/api/v1

Im Echtbetrieb gehört die REST-API zum Paket Enterprise. Mit Pro senden Sie nur Messwerte aus dem BMS. Testschlüssel gibt es in jedem Paket.

In drei Schritten starten

1. Melden Sie sich als Administrator an und öffnen Sie Einstellungen, dann API-Schlüssel.
2. Erstellen Sie einen Testschlüssel. Er wird nur einmal angezeigt, bewahren Sie ihn wie ein Passwort auf.
3. Prüfen Sie die Verbindung mit GET /me. Antwortet die API, stimmen Schlüssel und Netzwerkweg.

export BATTERYPASS_KEY="bp_test_..."

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

Testschlüssel antworten mit Status 200 und dry_run: true. Sie lesen echte Daten, ändern aber nichts.

Endpunkte

Beispiel: Pässe aus dem ERP anlegen

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);

Antwort

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"
    }
  ]
}

Fehler

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"
  }
}

Grenzen

Planen Sie mehr als 100.000 Pässe im Jahr? Stimmen Sie das bitte vorab mit uns ab.

Jeder Schlüssel bekommt nur die Rechte, die das System braucht. Fehlt eines, antwortet die API mit 403 und insufficient_scope. In der App wählen Sie eine Vorlage: Alle Rechte, ERP, BMS oder Nur lesen.

Listen kommen seitenweise mit data, has_more und next_cursor. Den Wert von next_cursor geben Sie als cursor mit. Unbekannte Felder werden abgelehnt, damit Tippfehler sofort auffallen. Bei PATCH bleibt ein fehlendes Feld unverändert, null leert es.

Zwei schlanke Clients ohne Abhängigkeiten: Sie wiederholen Anfragen sicher, blättern selbst durch Listen und teilen große Mengen in Aufrufe zu je 1.000 Pässen. Beide sind einzelne Dateien zum Kopieren in Ihr Projekt. Die API-Konsole finden Sie in der App unter Einstellungen, API-Schlüssel. Die Bibliotheken gehören zum Paket 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);
}

Halten Sie fest, welche Module, Zellen oder BMS in einer Batterie verbaut sind. Eine Seriennummer kann je Pass nur einmal gleichzeitig verbaut sein. Beim Tausch bleibt das alte Teil mit Ausbaudatum erhalten.

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"}'

Erlaubte Arten sind pack, rack, module, cell, bms und other.

Melden Sie Daten aus dem BMS, einzeln oder bis zu 1.000 Messungen mit items. Lesen lässt sich die Reihe mit since und until. Messwerte gibt es ab dem Paket Pro. Sie erscheinen in der App und für Berechtigte, nicht auf der öffentlichen Pass-Seite.

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}'

Prüfberichte, Konformitätserklärungen und ähnliche Dokumente laden Sie in der App beim Modell hoch: PDF, PNG oder JPG bis 10 MB. Über die API lesen Sie die Liste und holen einen Download-Link, der 15 Minuten gilt. Jede Datei hat eine SHA-256-Prüfsumme.

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"

Fragen Sie Werte bei Zulieferern an. Sie erhalten eine E-Mail mit einem 30 Tage gültigen Link und tragen nur die angefragten Felder ein, ohne Konto. Gelieferte Werte landen erst nach Ihrer Freigabe im Modell. Verfügbar ab dem Paket Starter, höchstens 20 Anfragen pro Stunde.

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"

Hinterlegen Sie beim Modell eine GTIN mit gültiger Prüfziffer. Dann führt die GS1-Adresse aus GTIN und Seriennummer auf die Pass-Seite und steht in der API als gs1_link. Ihre QR-Codes enthalten weiter die feste Pass-Adresse, Sie können aber eigene Codes aus dem GS1-Link erzeugen. Die GTIN selbst erhalten Sie von GS1.

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

GET /audit liefert alle protokollierten Änderungen der Firma, seitenweise und optional ab einem Zeitpunkt mit since. Änderungen über die API tragen den Namen des Schlüssels. In der App sehen Administratoren außerdem die letzten Aufrufe je Schlüssel.

Die App erstellt das Schlüsselpaar für Ihr Service-Konto. Der private Schlüssel bleibt verschlüsselt bei uns. Der öffentliche Schlüssel kommt ins Register. Ihre Firma muss dort vorher mit qualifiziertem Siegel verifiziert sein.

Eingereicht werden nur freigegebene, vollständige Pässe, in Stapeln zu höchstens 100. Den Status zeigen App und API. Das Register ruft die Pass-Adresse als JSON ab; mit seinem Zugriffstoken bekommt es auch die geschützten Sichten. Ungültige Tokens werden abgelehnt.

Gebaut nach den technischen Unterlagen der Kommission vom 30.10.2026 und gegen einen eigenen Prüfserver getestet. Der Test im echten Register steht noch aus.

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"

Mit publish: false entstehen Entwürfe. Sie sind öffentlich nicht erreichbar, bis Sie sie freigeben. Jede Änderung an den Stammdaten wird zur neuen Version und hängt per Hash an der vorherigen. Unter /p/ID/proof kann jeder den öffentlichen Stand nachrechnen.

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

Die Hauptversion steht im Pfad. Innerhalb von v1 kommen nur Felder und Endpunkte hinzu. Geplant, aber noch nicht vorhanden: Webhooks.

Kurze Antworten für die Anbindung.