REST API v1

REST API Dokumentation

Automatisieren Sie Ihren Batteriepass-Workflow. Produkte per REST API erstellen, aktualisieren, veröffentlichen und exportieren. Die Pass-Abruf-Endpunkte sind an den Methoden und REST-Vorgaben der EN 18222:2026 ausgerichtet; die vollständige Konformitätsprüfung einschließlich abhängiger Normen ist noch offen.

Authentifizierung

Scale-Plan erforderlich. Den Schlüssel erstellen Sie in Ihren Organisationseinstellungen.

Authorization: Bearer dpp_live_...

Basis-URL

120 Anfragen/Minute pro Organisation.

https://app.dpphero.com/api/v1

Kurzbeispiel

curl -X POST https://app.dpphero.com/api/v1/products \
  -H "Authorization: Bearer dpp_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "LFP Module 48V",
    "serial_number": "BAT-2025-001",
    "battery_category": "industrial",
    "manufacturing_date": "2025-06-15",
    "battery_mass": 45.5
  }'

Verfügbare Endpunkte

Alle Endpunkte erfordern einen Bearer Token (API-Schlüssel). Verfügbar im Scale-Tarif.

Produkte

GET/products
POST/products
GET/products/{id}
PATCH/products/{id}
DELETE/products/{id}
POST/products/{id}/image
DELETE/products/{id}/image
POST/products/{id}/files

Batteriezustand

Dynamische BMS-Daten wie Ladezustand, Zyklenanzahl und Kapazitätsverlust per API aktualisieren.

GET/products/{id}/condition
PATCH/products/{id}/condition

Massen-Import

POST/products/bulk

Export

GET/products/{id}/export/json
GET/products/{id}/export/gefeg-json
GET/products/{id}/export/pdf
POST/products/{id}/preprint-qr
GET/products/{id}/export/qr

Organisation

GET/organization
GET/facilities
GET/audit-log

Listen, Filter und Seiten

GET /products liefert seitenweise. page ab 1, per_page 1 bis 100 (Vorgabe 25). Dazu filtern Sie nach status und battery_category, suchen mit search und sortieren nach created_at, updated_at oder name, je aufsteigend oder absteigend. Die Antwort nennt total und total_pages.

GET /products?page=1&per_page=25&sort=created_at&order=desc

Maschinenlesbare Spezifikation

Die komplette Schnittstelle als OpenAPI-Dokument, ohne Anmeldung abrufbar. Damit erzeugen Sie Client-Code oder laden die Sammlung in Ihr Werkzeug.

openapi.json

GS1 Digital Link

Pässe sind auch über die GS1-Kennungen adressierbar: GTIN und Seriennummer zusammen bezeichnen genau eine Batterie, so wie der GS1 Digital Link es vorsieht. Wie die GTIN dabei geschrieben wird, steht bei den betroffenen Endpunkten; welche das sind, zeigt die vollständige Dokumentation im Konto.

Fehler- und Statuscodes

Jeder Fehler kommt als JSON-Objekt mit gleichbleibendem Aufbau. Bei 429 nennt der Retry-After-Kopf die Wartezeit in Sekunden.

400validation_errorEingabe unvollständig oder falsch; details nennt das Feld
401unauthorizedAPI-Schlüssel fehlt oder ist ungültig
403forbiddenSchlüssel darf diese Ressource nicht ansprechen
403plan_requiredFunktion gehört zu einem anderen Tarif
404not_foundRessource gibt es nicht in Ihrer Organisation
409conflictWert ist bereits vergeben, etwa eine doppelte Kennung
429rate_limit_exceededZu viele Anfragen; Retry-After beachten
500internal_errorFehler auf unserer Seite; correlation_id an den Support geben
{
  "error": {
    "code": "validation_error",
    "message": "...",
    "details": { "name": ["Required"] },
    "correlation_id": "..."
  }
}

Die correlation_id steht zusätzlich im X-Correlation-Id-Kopf. Nennen Sie sie im Support-Fall, dann finden wir denselben Vorgang in unseren Protokollen wieder.

Vollständige Dokumentation

Die komplette API-Referenz mit Felddefinitionen, Beispiel-Payloads, Fehlercodes, Auto-Fill-Regeln und dem vollständigen Produkt-Schema steht in Ihrem Dashboard zur Verfügung.

Tarife ansehenFür die Dokumentation einloggen

Was Sie vor der ersten Anfrage wissen sollten

Authentifizierung

Jede Anfrage trägt ein Bearer-Token im Authorization-Kopf. Die REST-API gehört zum Scale-Tarif; in den kleineren Tarifen arbeiten Sie über die Oberfläche oder den CSV-Import.

Seitenweises Lesen

Listen-Endpunkte geben nicht alles auf einmal zurück. Sie steuern das über page (ab 1, Standard 1) und per_page (1 bis 100, Standard 25). Die Antwort trägt page, per_page, total und total_pages. Sie brauchen also nicht zu raten, wann Schluss ist. Sortiert wird über sort (created_at, updated_at oder name) und order (asc oder desc). Gefiltert wird über status, battery_category und search.

Noch keine Webhooks

Ereignis-Benachrichtigungen gibt es derzeit nicht. Änderungen holen Sie über einen Abruf ab. Sinnvoll ist eine Sortierung nach updated_at und eine Beschränkung auf den Zeitraum seit Ihrem letzten Lauf. Wir schreiben das hin, statt es zu verschweigen. So bauen Sie Ihre Anbindung nicht auf eine Zusage, die es nicht gibt.

Der Export folgt dem Battery-Passport-Datenmodell in Version 2.0. Was in welchem Feld steht, entscheidet die Feld-Registry der Anwendung, nicht der Aufruf. Die Endpunkt-Beschreibungen oben und der Doku-Tab im Konto stammen aus derselben Quelle. Sie laufen deshalb nicht auseinander.