REST-API v1

Überblick

Die API bildet dieselben Objekte ab wie das Dashboard: ein Modell ist die Stammdaten-Ebene eines Produkts, ein Pass gehört zu genau einer physischen Batterie. Ereignisse und Messwerte hängen am Pass. Alles läuft über eine Basis-URL, alle Antworten sind JSON, auch Fehler.

Schritt 1: Schlüssel anlegen

API-Schlüssel entstehen ausschließlich im Dashboard und ausschließlich durch ein Konto mit der Rolle Admin. Der Inhaber hat immer Admin.

1. Integrationen öffnen

   Im Dashboard links in der Navigation unter Verwaltung auf Integrationen. Nur Admins sehen diesen Punkt.

2. API-Schlüssel erstellen

   Im Bereich API-Zugang auf die Schaltfläche API-Schlüssel erstellen. Bezeichnung vergeben, die das System benennt, etwa SAP-Nord-Prod.

3. Modus und Berechtigungen wählen

   Test für die Entwicklung, Live für den Produktivbetrieb. Dazu eine Vorlage oder einzelne Berechtigungen, und optional ein Ablaufdatum von 30, 90 oder 365 Tagen.

4. Klartext einmal sichern

   Der Schlüssel wird genau einmal angezeigt. Gespeichert wird nur ein SHA-256-Hash, deshalb kann ihn niemand nachträglich auslesen, auch wir nicht.

curl -s https://app.batteriepasswerk.com/api/v1/me \
  -H "Authorization: Bearer bpw_test_a1b2c3d4…"

Anmelden und Schlüssel anlegen Öffnet das Dashboard direkt im Bereich Integrationen. Ohne Anmeldung landen Sie erst auf der Login-Seite und danach automatisch dort.

Den Schlüssel wie ein Passwort behandeln: nicht in Repositories, nicht im Frontend, nicht in Logs. Geht er verloren, im Dashboard rotieren - der alte wird sofort ungültig, der neue erscheint einmalig.

Schritt 2: Erster Aufruf

GET /me ist der Verbindungstest. Die Antwort nennt Firma, Tarif, Modus, die wirksamen Berechtigungen, das Rate-Limit und das freie Kontingent im laufenden Vertragsjahr. Wenn dieser Aufruf funktioniert, stimmen Schlüssel, Header und Netzwerkweg.

export BPW_API_KEY="bpw_test_…"

curl -s https://app.batteriepasswerk.com/api/v1/me \
  -H "Authorization: Bearer $BPW_API_KEY"

Schritt 3: In der Konsole ausprobieren

Im Dashboard unter Integrationen führt ein Link zur API-Konsole. Dort wählen Sie einen Endpunkt aus der OpenAPI-Beschreibung, füllen Parameter aus, senden mit Ihrer Anmeldung statt mit einem Schlüssel und lesen die Antwort als klappbaren JSON-Baum. Jeder Aufruf lässt sich als cURL kopieren und direkt ins Terminal übernehmen. Schreibende Aufrufe laufen dort standardmäßig als Dry-Run.

Authentifizierung

Jede Anfrage trägt den Header Authorization mit dem Schema Bearer. Es gibt zwei Schlüsselarten, erkennbar am Präfix.

Zusätzlich akzeptiert die API das Sitzungs-Token eines angemeldeten Dashboard-Nutzers. Die Berechtigungen ergeben sich dann aus der Rolle. Das ist der Weg der API-Konsole und nicht für Integrationen gedacht. Fehlt der Header oder ist der Schlüssel ungültig, antwortet die API 401 mit WWW-Authenticate. Nach 30 Fehlversuchen je IP und Minute folgt 429.

Live, Test und Dry-Run

Es gibt bewusst keine getrennte Sandbox-Datenbank. Ein Test-Schlüssel arbeitet auf Ihren echten Stammdaten und prüft Berechtigungen, Pflichtfelder, Seriennummern und Kontingente wie im Ernstfall, speichert aber nichts.

Auch ein Live-Schlüssel kann eine einzelne Anfrage als Probe senden: Header X-BPW-Dry-Run: true. Die Antwort-Header X-BPW-Mode und X-BPW-Dry-Run nennen immer den tatsächlich gültigen Zustand.

Berechtigungen

Jeder Schlüssel trägt genau die Berechtigungen, die das anfragende System braucht. Fehlt eine, antwortet die Route 403 mit dem Code insufficient_scope.

GET /me, GET /field-catalog und GET /openapi.json brauchen keine Berechtigung. Vorlagen im Dashboard: Nur lesen (alle read-Berechtigungen), ERP-Synchronisation, BMS-Telemetrie (lesen und melden), Alle, Eigene; das Dashboard erklärt zu jeder Berechtigung die freigeschalteten Endpunkte. Höchstens zehn aktive Schlüssel je Firma; jede Aktion an einem Schlüssel steht mit Person und Zeitpunkt im Audit-Trail.

Tarife

Die Prüfung läuft bei jedem einzelnen Aufruf, nicht nur beim Anlegen des Schlüssels. Ein Tarifwechsel wirkt sofort: Nach einem Wechsel von Enterprise auf Pro behält ein Live-Schlüssel nur noch telemetry:read und telemetry:write.

In Aufbewahrungs-Tarifen antworten alle schreibenden Routen 403 mit tenant_read_only. Telemetrie setzt zusätzlich den Tarif Pro oder höher voraus, unabhängig vom Schlüsselmodus.

Anfragen und Antworten

Einzelobjekte kommen direkt als JSON-Objekt, Listen im Envelope mit data, has_more und next_cursor.

Zeit

Zeitstempel sind ISO 8601 in UTC mit Millisekunden, Kalenderdaten YYYY-MM-DD. Eingaben werden normalisiert; ein Datum wie 2026-02-30 wird abgelehnt.

null gegen fehlend

Bei POST und PATCH bleibt ein nicht geliefertes Feld unverändert, null leert das Feld. Leere Zeichenketten werden zu null.

Unbekannte Felder

Werden abgelehnt, nicht ignoriert. Ein Tippfehler im ERP fällt sofort auf, statt still Daten zu verlieren.

Kennungen

UUID in Kleinschreibung. Der übliche Weg vom ERP-Datensatz zum Objekt führt über GET /passes?serial=… oder GET /models?code=…

Zeichensatz und Caching

UTF-8, Content-Type application/json. Alle Antworten tragen Cache-Control: no-store.

Antwort-Header

Fehler

Jeder Fehler nutzt denselben Envelope. type gruppiert grob nach HTTP-Status, code ist stabil und für Programmlogik gedacht, message ist englisch und kann sich ändern. param nennt das erste betroffene Feld, im Stapel etwa items[3].serial, details listet alle. Wiederholen Sie 429 und 5xx mit Backoff, 4xx nie automatisch.

HTTP/1.1 400 Bad Request
X-Request-Id: req_7f3c9a21e4b84c60

{
  "error": {
    "type": "invalid_request",
    "code": "validation_failed",
    "message": "One or more fields are invalid.",
    "param": "energy_kwh",
    "details": [
      { "param": "energy_kwh", "code": "invalid_type", "message": "energy_kwh must be a number." },
      { "param": "gtin", "code": "invalid_gtin", "message": "gtin must be a valid GS1 GTIN." }
    ],
    "request_id": "req_7f3c9a21e4b84c60"
  }
}

Pagination

Listen liefern höchstens 200 Einträge je Seite, Standard 50. Sortiert wird nach Erstellzeitpunkt absteigend, bei Telemetrie nach Messzeitpunkt. Der Cursor ist opak und arbeitet auf Zeitstempel und Kennung, nicht auf Offsets: Datensätze, die während des Durchlaufs entstehen, verschieben nichts und werden nicht übersprungen. Für den inkrementellen Abgleich merken Sie sich den größten updated_at der letzten Seite und senden ihn beim nächsten Lauf als updated_since.

import requests

BASE = "https://app.batteriepasswerk.com/api/v1"
H = {"Authorization": f"Bearer {KEY}"}

def iterate(path, **params):
    cursor = None
    while True:
        r = requests.get(f"{BASE}{path}", headers=H,
                         params={**params, "limit": 200, "cursor": cursor})
        r.raise_for_status()
        page = r.json()
        yield from page["data"]
        if not page["has_more"]:
            return
        cursor = page["next_cursor"]

# Inkrementell: nur was sich seit dem letzten Lauf geändert hat
for p in iterate("/passes", updated_since="2026-09-01T00:00:00Z"):
    print(p["serial"], p["lifecycle_status"])

Rate-Limits

Feste Fenster von 60 Sekunden. Jede Antwort nennt das verbleibende Kontingent, bei Überschreitung folgt 429 mit Retry-After. Ein Stapel mit 500 Pässen zählt als eine Anfrage, deshalb ist Massen-Serialisierung selten das Limit.

Idempotenz

Jeder POST nimmt den Header Idempotency-Key mit bis zu 255 Zeichen, etwa die Belegnummer aus dem ERP.

• Erste Ausführung: normale Verarbeitung, die Antwort wird 24 Stunden unter Firma, Schlüssel und Key gespeichert.
• Wiederholung mit identischer Anfrage: die gespeicherte Antwort, zusätzlich der Header Idempotent-Replayed: true, ohne erneute Ausführung.
• Wiederholung mit anderem Inhalt: 422 mit dem Code idempotency_key_reused.
• Gespeichert werden nur 2xx und 4xx. Nach 429 oder 5xx darf mit demselben Key erneut versucht werden.

# Erster Versuch läuft in einen Timeout - Ergebnis unbekannt
curl -X POST https://app.batteriepasswerk.com/api/v1/passes \
  -H "Authorization: Bearer $BPW_API_KEY" \
  -H "Idempotency-Key: los-2026-09-0042" \
  -H "Content-Type: application/json" \
  -d '{ "items": [ … ] }'

# Gefahrlose Wiederholung mit demselben Schlüssel
# → 201 mit derselben Antwort, zusätzlich: Idempotent-Replayed: true

Konto und Katalog

Achtzehn Endpunkte. Jeder nennt die nötige Berechtigung, die Parameter und ein vollständiges Beispiel. Alle Pfade sind relativ zur Basis-URL.

{
  "api_version": "v1",
  "mode": "test",
  "dry_run": true,
  "tenant": { "id": "8f21…c4", "name": "Muster GmbH", "plan": "enterprise" },
  "principal": {
    "kind": "api_key",
    "key": { "id": "0d4e…91", "label": "SAP-Nord-Prod", "prefix": "bpw_test_a1b2c3d4", "expires_at": null }
  },
  "scopes": ["models:read", "models:write", "passes:read", "passes:write", "telemetry:write", "certificates:read"],
  "read_only": false,
  "rate_limit": { "limit": 60, "window_seconds": 60 },
  "usage": {
    "contract_year_start": "2026-03-01T00:00:00.000Z",
    "models": { "used": 3, "max": null, "remaining": null },
    "passes": { "used": 18240, "quota": 25000, "quota_source": "plan",
                "remaining": 6760, "enforcement": "overage",
                "overage_units": 0, "overage_price_eur": 0.05, "blocked": false }
  },
  "server_time": "2026-09-09T08:14:02.118Z"
}

{
  "rules_version": 9,
  "categories": ["lmt", "bess", "ind", "ev", "device", "sli"],
  "sections": ["identity", "conformity", "carbon", "materials", "circularity", "performance", "dynamic"],
  "data": [
    {
      "key": "gtin",
      "section": "identity",
      "resource": "model",
      "fields": ["gtin"],
      "fill_rule": "all",
      "eu_datapoints": [1],
      "legal_ref": "BR Art. 77(3)",
      "applicability": "always",
      "blocker": true,
      "second_life_exempt": false,
      "condition_note": { "de": null, "en": null }
    }
  ]
}

{
  "openapi": "3.1.0",
  "info": { "title": "Batteriepasswerk REST API", "version": "1.0.0" },
  "servers": [{ "url": "https://app.batteriepasswerk.com/api/v1" }],
  "paths": { "/me": { "get": { "operationId": "getMe" } } }
}

Modelle

curl -s "https://app.batteriepasswerk.com/api/v1/models?category=bess&limit=2" \
  -H "Authorization: Bearer $BPW_API_KEY"

curl -s https://app.batteriepasswerk.com/api/v1/models/f76b5107-d6c3-4527-8d04-0c89209bede1 \
  -H "Authorization: Bearer $BPW_API_KEY"

curl -s -X POST https://app.batteriepasswerk.com/api/v1/models \
  -H "Authorization: Bearer $BPW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: erp-model-4711" \
  -d '{
        "code": "BESS-10",
        "category": "bess",
        "name": "Home Storage 10",
        "chemistry": "LFP",
        "energy_kwh": 10.2,
        "nominal_voltage_v": 51.2,
        "gtin": "04012345678901",
        "ce_marked": true,
        "separate_collection": true
      }'

curl -s -X PATCH https://app.batteriepasswerk.com/api/v1/models/f76b5107-… \
  -H "Authorization: Bearer $BPW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "co2_kg_per_kwh": 61.4, "co2_study_url": "https://example.org/lca.pdf" }'

curl -s -X POST https://app.batteriepasswerk.com/api/v1/models/validate \
  -H "Authorization: Bearer $BPW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "code": "BESS-10", "category": "bess", "energy_kwh": 10.2 }'

Pässe

curl -s "https://app.batteriepasswerk.com/api/v1/passes?serial=SN-000123" \
  -H "Authorization: Bearer $BPW_API_KEY"

curl -s https://app.batteriepasswerk.com/api/v1/passes/ffdad688-745f-475e-aaaa-e23112c0f041 \
  -H "Authorization: Bearer $BPW_API_KEY"

curl -s -X POST https://app.batteriepasswerk.com/api/v1/passes \
  -H "Authorization: Bearer $BPW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: los-2026-09-0042" \
  -d '{
        "items": [
          { "model_id": "f76b5107-…", "serial": "SN-000123", "batch": "B04", "production_date": "2026-09-01" },
          { "model_id": "f76b5107-…", "serial": "SN-000124", "batch": "B04", "production_date": "2026-09-01" }
        ],
        "on_conflict": "skip"
      }'

curl -s -X PATCH https://app.batteriepasswerk.com/api/v1/passes/ffdad688-… \
  -H "Authorization: Bearer $BPW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "ready" }'

Lebenszyklus-Ereignisse

{
  "data": [
    { "id": "9c2e…41a7", "pass_id": "ffdad688-…", "event_type": "market",
      "event_date": "2026-09-05", "note": null, "source": "api",
      "created_at": "2026-09-05T09:12:44.201Z" }
  ],
  "has_more": false,
  "next_cursor": null
}

curl -s -X POST https://app.batteriepasswerk.com/api/v1/passes/ffdad688-…/events \
  -H "Authorization: Bearer $BPW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "event_type": "secondlife", "event_date": "2031-04-18" }'

Telemetrie

{
  "data": [
    { "id": "7a41…c2", "pass_id": "ffdad688-…", "recorded_at": "2026-09-08T22:00:00.000Z",
      "soh_pct": 98.4, "soc_pct": 62, "cycle_count": 142, "negative_event": null,
      "created_at": "2026-09-08T22:00:03.774Z" }
  ],
  "has_more": true,
  "next_cursor": "eyJjIjoiMjAyNi0wOS0wOFQyMjowMDowMFoiLCJpIjoiN2E0MSJ9"
}

curl -s -X POST https://app.batteriepasswerk.com/api/v1/passes/ffdad688-…/telemetry \
  -H "Authorization: Bearer $BPW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "recorded_at": "2026-09-08T22:00:00Z",
        "soh_pct": 98.4,
        "soc_pct": 62,
        "cycle_count": 142,
        "temp_min_c": 11.2,
        "temp_max_c": 28.7
      }'

Nachweise

{
  "data": [
    { "id": "b2c8…19", "name": "UN 38.3 Testzusammenfassung", "type": "testreport",
      "issuer": "TÜV", "model_id": "f76b5107-…", "valid_until": "2027-05-30",
      "validity": "valid", "status": "accepted", "file_name": "un383.pdf",
      "file_size": 481221, "has_file": true }
  ],
  "has_more": false,
  "next_cursor": null
}

{
  "id": "b2c8…19",
  "name": "UN 38.3 Testzusammenfassung",
  "type": "testreport",
  "validity": "valid",
  "download_url": "https://…/storage/v1/object/sign/certs/…?token=…",
  "download_expires_at": "2026-09-09T08:36:02.000Z"
}

Lieferanten und Datenanfragen

{
  "data": [
    {
      "id": "3f0c…9a",
      "name": "Zellwerk GmbH",
      "email": "einkauf@zellwerk.example",
      "created_at": "2026-09-09T08:12:40.211Z",
      "updated_at": "2026-09-09T08:12:40.211Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

{
  "data": [
    {
      "id": "b7d2…41",
      "supplier_id": "3f0c…9a",
      "supplier_name": "Zellwerk GmbH",
      "supplier_email": "einkauf@zellwerk.example",
      "model_id": "0d1f…c8",
      "model_code": "BESS-10",
      "supplier_type": "cell",
      "status": "delivered",
      "fields": [{ "key": "cobalt_pct", "label": "Kobalt-Anteil", "unit": "%" }],
      "due_date": "2026-10-15",
      "invited_at": "2026-09-09T08:12:41.030Z",
      "expires_at": "2026-11-08T08:12:41.030Z",
      "delivered_at": "2026-09-12T14:03:07.512Z",
      "last_reminder_at": null,
      "reminder_count": 0,
      "created_at": "2026-09-09T08:12:41.030Z",
      "updated_at": "2026-09-12T14:03:07.512Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

curl -s -X POST https://app.batteriepasswerk.com/api/v1/supplier-requests \
  -H "Authorization: Bearer $BPW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: erp-po-4711-cells" \
  -d '{
        "supplier_name": "Zellwerk GmbH",
        "email": "einkauf@zellwerk.example",
        "model_id": "0d1f…c8",
        "supplier_type": "cell",
        "due_date": "2026-10-15",
        "fields": [
          { "key": "cobalt_pct", "label": "Kobalt-Anteil", "unit": "%", "label_en": "Cobalt share" }
        ]
      }'

{
  "id": "b7d2…41",
  "supplier_name": "Zellwerk GmbH",
  "model_code": "BESS-10",
  "status": "delivered",
  "fields": [{ "key": "cobalt_pct", "label": "Kobalt-Anteil", "unit": "%" }],
  "submissions": [
    {
      "field_key": "cobalt_pct",
      "value": "6.2",
      "file_name": null,
      "file_size": null,
      "submitted_at": "2026-09-12T14:03:07.512Z"
    }
  ]
}

Audit-Trail

curl -s "https://app.batteriepasswerk.com/api/v1/audit?entity_type=pass&since=2026-09-01T00:00:00Z&limit=100" \
  -H "Authorization: Bearer $BPW_API_KEY"

Modell-Felder

Alle schreibbaren Felder eines Modells in snake_case, identisch mit der Benennung im Dashboard. Die Spalte EU nennt die Nummer des offiziellen EU-Datenpunkts, soweit das Feld einem zugeordnet ist. Zeichenketten sind auf 4000 Zeichen begrenzt. Nur lesbar sind id, readiness, readiness_detail, created_at, updated_at und public_url.

Pass-Felder

Schreibbar beim Anlegen sind model_id, serial, status, batch und production_date; danach per PATCH noch status, batch und production_date. Alles Übrige gehört dem Server.

Ereignistypen und abgeleiteter Status

Telemetrie-Felder

Mindestens ein Messwert oder negative_event je Aufruf. Werte außerhalb des Bereichs antworten 400 mit out_of_range und dem betroffenen Feld in param.

Webhooks

Die API ist Pull, Webhooks sind Push. Signierte Ereignisse erreichen Ihr System, sobald sie eintreten: pass.created, model.updated, supplier.delivered und cert.expiring. Signatur per HMAC-SHA256, Wiederholung bei Fehlern. Bewährtes Muster: den Webhook als Anstoß nehmen und die betroffene Ressource anschließend über die API laden, damit die Wahrheit immer aus der API kommt. Aufrufe über die API lösen dieselben Webhooks aus wie Eingaben im Dashboard.

Versionierung und Changelog

Die Version steht im Pfad. Innerhalb von v1 kommen nur Felder und Endpunkte hinzu; bestehende Felder, Fehlercodes und Bedeutungen bleiben. Entfällt etwas, kündigen wir es mindestens zwölf Monate vorher hier, im OpenAPI-Dokument und per E-Mail an die Admins an und betreiben die Nachfolgeversion parallel unter /v2.

Häufige Fragen

Stand 9. September 2026 · API-Version 1.1.0 · Keine Rechtsberatung · Verbindlich ist der Verordnungstext