OCPI-2.2.1-Module erklärt: Locations, Sessions, CDRs, Tariffs und mehr

OCPI (Open Charge Point Interface) ist das Protokoll, mit dem Ladenetze und E-Mobility-Provider Standorte, Ladevorgänge, Preise und Abrechnungsdatensätze austauschen. Version 2.2.1 ist heute die in Europa am häufigsten umgesetzte Version. Wer ein CSMS an einen Roaming-Partner oder Hub anbindet, verbringt die meiste Zeit in ihren Modulen.

Dieser Leitfaden erklärt jedes Modul, wer Daten sendet und empfängt und wo Integrationen typischerweise scheitern. Für den Überblick lesen Sie zuerst, was OCPI ist und wie es sich von OCPP unterscheidet.

Aufbau von OCPI 2.2.1

OCPI ist ein REST/JSON-Protokoll. Jede Partei stellt HTTPS-Endpunkte bereit und ruft die Endpunkte der Gegenseite auf. Module sind nach Zweck gruppiert und bestehen jeweils aus zwei Interfaces: Der Sender besitzt die Daten, der Receiver speichert sie oder handelt danach. Ein CPO ist etwa Sender für Locations und Receiver für Tokens.

Version 2.2 brachte ausdrückliche Unterstützung für Hubs, Rollen und neue Module, 2.2.1 korrigierte und präzisierte 2.2. Spätere Versionen wie 2.3.0 ergänzen Funktionen, doch 2.2.1 bleibt die gemeinsame Basis bei Hubs und Partnern.

Konfigurationsmodule

Versions

Das Versions-Modul teilt dem Partner mit, welche OCPI-Versionen Sie unterstützen und welche Endpunkte mit welchen Rollen es je Version gibt. Es ist stets der erste Aufruf einer Integration.

Credentials und Registrierung

Credentials stellt die sichere Verbindung her. Partei A erhält ein Token (oft Token A) auf separatem Weg, ruft den Versions-Endpunkt von Partei B auf und sendet per POST die eigenen Zugangsdaten mit einem neuen Token B. Partei B antwortet mit Token C, das A künftig für alle Aufrufe nutzt. Das Credentials-Objekt listet außerdem die Rollen jeder Partei wie CPO, EMSP oder HUB mit Ländercode und Party-ID.

Funktionale Module im Überblick

Locations

Locations folgt einer dreistufigen Hierarchie: Eine Location (Standort) enthält EVSEs, jede EVSE enthält Stecker. EVSEs tragen den Status, den Fahrer in Apps sehen, etwa AVAILABLE, CHARGING oder OUTOFORDER, und brauchen eine korrekt formatierte EVSE-ID. Stecker beschreiben Standard, Bauform, Stromart, Spannung, Stromstärke und die gültigen Tarif-IDs.

Pushen Sie Statusänderungen sofort an Partner. Ein Ladepunkt, der in einer Partner-App frei erscheint, tatsächlich aber gestört ist, erzeugt verärgerte Fahrer und Supportfälle.

Sessions

Mit dem Sessions-Modul zeigt der EMP dem Fahrer den Live-Fortschritt: geladene kWh, Startzeit und bisherige Kosten. Der CPO legt die Session beim Ladestart an und aktualisiert sie während des Ladens. Für die Abrechnung werden Sessions nicht verwendet, das übernehmen CDRs.

CDRs

Ein CDR ist der endgültige, unveränderliche Datensatz eines Ladevorgangs: Identität, Standort, Start- und Endzeit, Energie, Ladeperioden, angewandte Tarife und Gesamtbetrag. CDRs werden einmal erstellt und nicht aktualisiert; Korrekturen erfolgen über einen Gutschrift-CDR. Mehr dazu in unserem Leitfaden zu Ladedatensätzen.

Tariffs

Tariffs beschreibt Preisbestandteile wie ENERGY, TIME, PARKING_TIME und FLAT mit Einschränkungen nach Uhrzeit, Wochentag, minimalen oder maximalen kWh und Leistungsbereichen. Die Struktur ist mächtig, aber leicht falsch zu nutzen. Veröffentlichen Sie Tarife, die exakt ergeben, was Sie abrechnen, sonst beanstanden Partner die CDRs. Zur kommerziellen Gestaltung siehe Tarifmodelle.

Tokens

Tokens ist die Liste gültiger Fahrerkennungen des EMP, meist RFID-UIDs und App-Tokens. Der CPO kann Tokens lokal zwischenspeichern und für unbekannte Tokens eine Echtzeit-Autorisierung anfragen. Ein gutes CSMS nutzt den Cache, wenn der Partner langsam oder offline ist, kombiniert mit der RFID-Autorisierung der Ladestation.

Commands

Mit Commands bittet ein EMP den CPO um START_SESSION, STOP_SESSION, RESERVE_NOW, CANCEL_RESERVATION oder UNLOCK_CONNECTOR. Befehle laufen asynchron: Der CPO bestätigt zunächst die Annahme und sendet das tatsächliche Ergebnis an eine Response-URL, sobald die Station antwortet. Intern übersetzt das CSMS dies in OCPP-Nachrichten wie RemoteStartTransaction.

ChargingProfiles

ChargingProfiles erlaubt einem Smart-Charging-Dienstleister, für eine laufende Session ein Limit zu setzen, das aktive Profil zu lesen oder zu löschen. Auch hier sind Ergebnisse asynchron. Sinnvoll ist das, wenn ein Energiedienstleister statt des CPO das Laden optimiert.

HubClientInfo

Sind Sie über einen Hub angebunden, zeigt HubClientInfo, welche anderen Parteien verbunden und erreichbar sind. So vermeiden Sie Anfragen an Partner, die offline sind.

Push, Pull und Paginierung

Die meisten Module unterstützen Push (der Sender ruft bei jeder Änderung den Receiver auf) und Pull (der Receiver ruft Listen regelmäßig ab). Pull nutzt date_from, date_to, offset und limit; Paginierungsinformationen kommen in den Headern Link, X-Total-Count und X-Limit zurück. Nutzen Sie Push für Echtzeit-Updates und Pull als Sicherheitsnetz für verpasste Nachrichten.

OCPI-Statuscodes

Typische Stolperfallen

• Token-Kodierung: OCPI 2.2 erwartet das Token Base64-kodiert im Authorization-Header; Abweichungen führen zu stillen 401-Fehlern.
• Zeitzonen: Alle Zeitstempel sind UTC; lokale Öffnungszeiten gehören in das Zeitzonenfeld der Location.
• Party-IDs: Ländercode und Party-ID müssen in jedem Objekt passen, sonst lehnen Partner ab.
• Tarifabweichungen: Lässt sich der CDR-Betrag nicht aus dem veröffentlichten Tarif nachrechnen, entstehen Streitfälle.
• Fehlende Wiederholungen: Gescheiterte Pushs müssen wiederholt werden, regelmäßige Pulls schließen Lücken.

Häufig gestellte Fragen

Üreticy unterstützt OCPI-Roaming neben OCPP 1.6J, 2.0.1 und 2.1, mit vollständigen Nachrichten-Logs je Partner. Plattform entdecken oder mit unserem Team sprechen.