API für Ladestationen und Webhooks: Ein Praxisleitfaden

Ladedaten bleiben selten in der Ladeplattform. Die Finanzabteilung möchte die Energiekosten in der Buchhaltung sehen, Fuhrparkverantwortliche wollen den Verbrauch pro Fahrzeug neben den Telematikdaten, und die Geschäftsführung möchte Ladekennzahlen in denselben Dashboards wie alles andere. Jeden Monat CSV-Dateien zu kopieren, funktioniert eine Weile – skaliert aber nicht.

Eine API für Ladestationen löst dieses Problem, indem andere Systeme Ladedaten lesen und automatisch auf Ladeereignisse reagieren können. Dieser Leitfaden erklärt, warum und wo sich eine Integration lohnt, worin sich REST-APIs und Webhooks unterscheiden, welche Daten typischerweise verfügbar sind, wie Sie Webhooks mit HMAC-Signaturen absichern und wie Sie eine Integration sicher einführen. Er enthält ein allgemeines Pseudocode-Beispiel, das Sie in jede Programmiersprache übertragen können.

Warum Ladedaten integrieren?

Ein Lademanagementsystem (CSMS) ist die maßgebliche Quelle für Ladevorgänge, Energie und den Status der Ladestationen. Andere Systeme benötigen Teile dieser Daten:

• ERP und Buchhaltung: Ladekosten pro Standort, Abteilung oder Kostenstelle ohne manuelle Erfassung verbuchen.
• Fuhrparkmanagement: Energie pro Fahrzeug und pro Fahrer den Fahrzeugdaten hinzufügen. Wie die Kostenzuordnung funktioniert, zeigt unser Leitfaden zum Lademanagement für Flotten.
• Business Intelligence (BI): Auslastungs- und Energiedaten mit anderen Unternehmensdaten in einem Reporting-Tool zusammenführen.
• Immobilien- und Facility-Systeme: Ladeenergie Mietern, Bewohnern oder Hotelgästen zuordnen.
• Interne Benachrichtigungen: einen Disponenten informieren, wenn ein Fahrzeug fertig geladen ist, oder ein Ticket eröffnen, wenn eine Ladestation eine Störung meldet.

Eine Integration beseitigt wiederkehrende Handarbeit, reduziert Übertragungsfehler und macht Daten schneller verfügbar.

REST-API oder Webhooks?

Die meisten Ladeplattformen bieten zwei sich ergänzende Integrationswege.

In der Praxis nutzen robuste Integrationen beides. Webhooks liefern Ereignisse schnell, und ein regelmäßiger REST-Aufruf gleicht die Daten ab und schließt Lücken, zum Beispiel wenn Ihr Endpunkt wegen Wartungsarbeiten nicht erreichbar war.

Typische Daten in einer API für Ladestationen

• Ladevorgänge: Start- und Endzeit, Ladestation, Ladepunkt, Energie in kWh, Kennung (Karte), Fahrer und Kennzeichen, sofern verfügbar.
• Ladestationen und Ladepunkte: Kennungen, Standort, OCPP-Version, aktueller Status.
• Fahrer und Karten: welche Karte zu welchem Fahrer gehört und ob sie aktiv oder gesperrt ist.
• Fahrzeuge: Kennzeichen und die damit verknüpften Fahrer.
• Energieübersichten: Summen pro Ladestation, Fahrer, Fahrzeug oder Zeitraum.

Die genauen Ressourcen, Feldnamen und Filter unterscheiden sich je nach Plattform – arbeiten Sie daher immer mit der offiziellen API-Dokumentation.

Webhook-Sicherheit: Signaturen, Idempotenz und Wiederholungen

Ein Webhook-Endpunkt ist eine öffentliche URL. Jeder, der sie kennt, kann Anfragen daran senden. Drei Praktiken machen die Verarbeitung von Webhooks sicher und zuverlässig.

1. Die HMAC-Signatur prüfen

Bei der HMAC-Signierung teilen sich die Plattform und Ihr System ein Geheimnis. Für jede Zustellung berechnet die Plattform mit diesem Geheimnis einen HMAC-SHA256-Wert über den Request-Body und sendet ihn in einem Signatur-Header. Ihr System berechnet denselben Wert und vergleicht beide. Stimmen sie überein, stammt die Anfrage von jemandem, der das Geheimnis kennt, und der Body wurde unterwegs nicht verändert.

• Berechnen Sie den HMAC über den unveränderten Request-Body, genau so, wie er empfangen wurde. Wird JSON geparst und neu serialisiert, können sich Leerzeichen oder die Reihenfolge der Schlüssel ändern und die Signatur ungültig machen.
• Vergleichen Sie Signaturen mit einer Funktion, die in konstanter Zeit arbeitet, um Timing-Angriffe zu vermeiden.
• Bewahren Sie das Geheimnis wie ein Passwort auf: in einem Secrets-Manager oder einer Umgebungsvariable, niemals im Quellcode.
• Enthalten die signierten Daten einen Zeitstempel, lehnen Sie alte Zustellungen ab, um Replay-Angriffe einzudämmen.

2. Handler idempotent gestalten

Webhooks werden in der Regel nach dem Prinzip „mindestens einmal“ zugestellt. Dasselbe Ereignis kann zweimal ankommen, zum Beispiel wenn Ihre Antwort im Netzwerk verloren ging. Speichern Sie eine Kennung jedes verarbeiteten Ereignisses – etwa eine Event-ID, sofern der Payload eine enthält, oder eine Kombination aus Session-ID und Ereignistyp – und ignorieren Sie Duplikate.

3. Schnell antworten und Wiederholungen einplanen

Geben Sie schnell einen Erfolgsstatus (einen 2xx-Code) zurück und erledigen Sie aufwendige Verarbeitung in einem Hintergrundjob. Langsame Handler können in ein Timeout laufen und erneute Zustellungen auslösen. Prüfen Sie in der Dokumentation der Plattform, wie Wiederholungen ablaufen, und gleichen Sie Verpasstes mit geplanten REST-Aufrufen ab.

Beispielablauf mit Pseudocode

Das folgende Beispiel zeigt einen allgemeinen Webhook-Handler, der die Signatur prüft, Duplikate aussortiert und ein Ereignis „Ladevorgang beendet“ zur Verarbeitung in eine Warteschlange stellt. Header-Name, Ereignisnamen und Payload-Felder sind Platzhalter; verwenden Sie die Werte aus der API-Dokumentation Ihrer Plattform.

function handle_webhook(request):    raw_body  = request.raw_body            # Bytes, vor jedem JSON-Parsing    received  = request.header(SIGNATURE_HEADER)   # siehe API-Dokumentation    secret    = env("WEBHOOK_SECRET")    expected  = hex(hmac_sha256(key = secret, message = raw_body))    if not constant_time_equals(expected, received):        return response(status = 401)    event = json_parse(raw_body)    event_key = event.id or (event.session_id + ":" + event.type)    if processed_events.contains(event_key):        return response(status = 200)       # Duplikat, bereits verarbeitet    processed_events.add(event_key)    queue.push(event)                       # aufwendige Verarbeitung erfolgt später    return response(status = 200)function worker(event):    if is_session_stopped(event):        cost_center = lookup_cost_center(event.driver, event.vehicle)        erp.post_energy(cost_center, event.energy_kwh, event.ended_at)function nightly_reconciliation():    sessions = api.get_sessions(date = yesterday)   # REST-API, API-Schlüssel    for session in sessions:        if not erp.has_session(session.id):            erp.post_energy(...)

Die meisten Programmiersprachen bieten eine HMAC-SHA256-Funktion und eine Vergleichsfunktion mit konstanter Laufzeit in ihrer Standardbibliothek oder in einem etablierten Kryptografie-Paket. Nutzen Sie diese, statt eigene zu schreiben.

Integration mit Üreticy

Üreticy bietet eine REST-API mit API-Schlüsseln, die Sie im Dashboard anlegen und verwalten, sowie HMAC-signierte Webhooks für Ereignisse wie „Ladevorgang gestartet“ und „Ladevorgang beendet“. Die öffentliche API-Dokumentation beschreibt die Ressourcen, Ereignistypen, Payloads und den Signatur-Header für die Prüfung.

Da Üreticy Ladestationen mit OCPP 1.6J, 2.0.1 und 2.1 in einem Dashboard verwaltet, kann eine einzige Integration einen gemischten Ladestationsbestand abdecken. Mehr dazu auf der Seite Lade-API und Webhooks.

Tipps für die Einführung

1. Mit einem Anwendungsfall beginnen. Zum Beispiel die monatliche Energie pro Kostenstelle, die an das ERP-System übergeben wird.
2. Separate API-Schlüssel pro Integration nutzen. So können Sie eine Integration widerrufen, ohne andere zu beeinträchtigen.
3. Nur die minimal nötigen Rechte vergeben. Eine Reporting-Integration sollte keine Konfiguration ändern können.
4. Mit echten Ladevorgängen testen. Vergleichen Sie die API-Ergebnisse vor dem Go-live mit dem Dashboard und den exportierten Berichten.
5. Jede Webhook-Zustellung protokollieren. Erfassen Sie Zeitpunkt, Ereignistyp und das Ergebnis der Signaturprüfung, um die Fehlersuche zu vereinfachen.
6. Schlüsselrotation einplanen. Klären Sie, wie Sie API-Schlüssel und Webhook-Geheimnisse ohne Ausfallzeit austauschen.
7. Die Integration überwachen. Lösen Sie einen Alarm aus, wenn ungewöhnlich lange keine Webhooks eintreffen oder der Abgleich Lücken findet.

Wenn Sie Ladeplattformen vergleichen, gehört die Qualität von API und Webhooks auf die Checkliste. Eine vollständige Bewertungsliste finden Sie in unserem Leitfaden zur Auswahl von OCPP-Software.

Häufig gestellte Fragen

Verbinden Sie Ladevorgänge über eine REST-API und HMAC-signierte Webhooks mit Ihrem ERP-, Fuhrpark- oder BI-System. Entdecken Sie die Lade-API von Üreticy oder lesen Sie die API-Dokumentation.