QaaS Vehicles API
Welche Funktion erfüllt die GreenTrax Vehicles API?
Die GreenTrax Vehicles API automatisiert den Prozess zur Übermittlung von Fahrzeugscheinen sowie relevanten Fahrzeughalter-Daten und Angaben für die Mitteilung von Strommengen an das Umweltbundesamt im Rahmen der THG-Quote. In diesem Zusammenhang werden via API auch unterschiedliche Status der Fahrzeuge und Anträge übermittelt, um für euch ersichtlich zu machen, in welchem THG-Prozessschritt (Übermittlung, Prüfung durch GreenTrax, Prüfung durch das Umweltbundesamt) sich eine Fahrzeugregistrierung aktuell befindet.
THG-Prozessschritte für die Meldung von Strommengen aus elektrischen Fahrzeugen auf einen Blick
Abstecken des Projekt-Rahmens: vor der technischen Integration erörtern die beteiligten Parteien (GreenTrax, B2B-Partner und ggf. weitere Dienstleister auf Partnerseite), welche Systeme/Tools während des THG-Prozesses via API miteinander kommunizieren werden. Hierbei ist es euch freigestellt, eine Eingabemaske zum Einsammeln von Fahrzeugscheinen selbst zu entwickeln und via API mit unserem THG-Backend zu verbinden oder hierfür auf eine Standard-Eingabemaske von GreenTrax zurückzugreifen, welche bereits über eine API-Kompatibilität verfügt.
Im zweiten Schritt erfolgt die technische Integration der Systeme. Wir stellen euren technischen Ansprechpartnern hierfür verschiedene technische Dokumentationen zur Verfügung:
- QaaS Vehicles API Specification: https://qv.api.greentrax.de
- QaaS Vehicles API Manual: https://qv.api.greentrax.de/manual
- QaaS Vehicles API Documentation (Redoc): https://qv.api.greentrax.de/redoc
Die optionale Eingabemaske (Frontend) kann als Widget in die unternehmenseigene THG-Landingpage eingebaut werden. Hier hat es sich als hilfreich erwiesen, auf der Landingpage Informationen über die THG-Quote zu integrieren, um den Nutzern mehr Kontext zu liefern (wir unterstützen euch hier gerne mit Informationen und Formulierungen). Die Kernfunktion der Eingabemaske ist es, ein Bild der Vorderseite eines jeden Fahrzeugscheins zu erfassen und via API an das GreenTrax THG-Backend zu übermitteln. Des Weiteren können noch weitere Halter-Informationen über die Eingabemaske eingeholt werden.
Validierung: nach der Übermittlung eines jeden Fahrzeugscheins werden in unserem System alle für das UBA relevanten Daten technisch ausgelesen und am Ende noch einmal manuell bestätigt um die höchste Datenqualität zu gewährleisten. Mehr dazu unter dem Punkt “Validierung und Übermittlung der Fahrzeugscheine”.
UBA-Dokument: alle von uns erfolgreich geprüften Fahrzeugscheine, bzw. die daraus relevanten Informationen für den THG-Quotenhandel, werden in einem vom Umweltbundesamt vorgegebenen Excel-Dokument aggregiert. Mehr dazu unter dem Punkt “Validierung und Übermittlung der Fahrzeugscheine”.
UBA-Mitteilung: in regelmäßigen zeitlichen Abständen (monatlich oder quartärlich) werden diese Excel Dokumente zusammen mit einem geteilten SharePoint-Ordner und darin enthaltenen Fahrzeugscheinen sowie einem digital signierten PDF-Dokument mit der Gesamt-Strommenge der jeweiligen Meldung von uns an das Umweltbundesamt via Mail übermittelt.
UBA-Prüfung: Das Umweltbundesamt überprüft nach der Eingangsbestätigung alle übermittelten Fahrzeugscheine. Sollte ein elektrisches Fahrzeug beim Umweltbundesamt bereits für das Berichtsjahr gemeldet worden sein (beispielsweise über einen Drittanbieter im Markt), so wird der Fahrzeugschein vom Umweltbundesamt abgelehnt. Üblicherweise liegt die Ablehnungsrate bei <5%. Alle weiteren Fahrzeuge werden i.d.R. vom Umweltbundesamt bestätigt. Die Prüfung einer Meldung dauert aktuell (Stand Februar 2023) zwischen 10-14 Wochen. Nach Abschluss der Überprüfung erhalten wir vom Umweltbundesamt ein Dokument mit der bestätigten Gesamtmenge sowie einer Übersicht mit den Fahrzeugidentifikationsnummern (VINs) abgelehnter Fahrzeugscheine.
UBA-Status: auf Basis der UBA-Rückmeldung werden die Informationen aus der Prüfung der Fahrzeugscheine in unserem System angepasst. Diese Status können via API aus unserem System abgerufen werden.
THG-Quotenhandel: im Rahmen einer Kooperation mit uns, haben B2B-Partner die Option, den THG-Quotenhandel über uns abwickeln zu lassen oder diesen selbst durchzuführen. Grundlage eines jeden THG-Quotenhandels ist immer der UBA-Bescheid, aus welchem die anrechenbare Strommenge sowie die eingesparten Treibhausgasemissionen als Kilogramm CO2-Äquivalent hervorgehen. Sollte GreenTrax mit dem THG-Quotenhandel beauftragt worden sein, werden wir im jeweils nächsten Zyklus probieren, einen möglichst hohen Marktpreis für die Mengen zu erzielen. Sollte der B2B-Partner selbst den Handel abwickeln wollen, werden wir den UBA-Bescheid via Mail an unsere Ansprechperson übermitteln, woraufhin alle weiteren Schritte für den THG-Quotenhandel vom B2B-Partner eigenständig angestoßen werden müssen.
Gutschrift/Auszahlung: Sofern wir mit dem THG-Quotenhandel beauftragt worden sind, erfolgt eine Gutschrift/Auszahlung von uns auf das angegebene Geschäftskonto des B2B-Partners nach erfolgreichem THG-Quotenhandel. GreenTrax übernimmt eine Auszahlung an mögliche weitere Nutzer in der Kette, wie beispielsweise B2C-Kunden unserer B2B-Partner. Nach Auszahlung der THG-Quotenerlöse endet der THG-Prozess.
Validierung und Übermittlung der Fahrzeugscheine
Die meisten für das UBA relevanten Daten befinden sich auf der Vorderseite des zu übermittelnden Fahrzeugscheins (Anmerkung: bislang war es erforderlich sowohl Vorder- als auch Rückseite eines jeden Fahrzeugscheins zu übermitteln; ab sofort (Stand Dezember 2022) ist es lediglich erforderlich, die Vorderseite zu übermitteln). Die relevanten Angaben auf der Vorderseite des Fahrzeugscheins sind in rot gekennzeichnet:
Name des Inhabers der Zulassungsbescheinigung: Feld C.1.1. der vorgelegten Zulassungsbescheinigung Teil 1
Datum der Zulassung: Feld I der Zulassungsbescheinigung Teil 1
Fahrzeugidentifikationsnummer: Feld E der Zulassungsbescheinigung Teil 1
Antriebsart (Elektro): Es muss sich um ein reines Batterieelektrofahrzeug handeln (Code: 0004)
Fahrzeugklasse: Feld J der Zulassungsbescheinigung Teil 1. Beispiele: PKW (M1), LNF (N1), Bus (M3)
Nicht vom Fahrzeugschein ablesbar, aber trotzdem für das Umweltbundesamt relevant: Datum der Vereinbarung in Textform mit dem Inhaber der Zulassungsbescheinigung. Diese Information wird in der Regel beim Hochladen des Fahrzeugscheins generiert.
Nachdem die Vorderseite eines Fahrzeugscheins über die Eingabemaske hochgeladen wurde, wird dieser via API an das GreenTrax Backend übermittelt. Hier landet es in unserer sogenannten QaaS Service App; eine von uns entwickelte Software, die die Fahrzeugscheine elektronisch ausliest.
Sollten alle Angaben in dem jeweils ausgelesenen Fahrzeugschein mit den Vorgaben des Umweltbundesamtes kompatibel sein, so wird der Status des Fahrzeugscheins von “Pending” auf “Verified” gesetzt. Der Fahrzeugschein kann nun allen weiteren von uns akzeptierten Fahrzeugscheinen dem Umweltbundesamt gemeldet werden. Die Fälle, in denen ein Fahrzeugschein von uns abgelehnt wird, sind untenstehend aufgeführt und dann auch über die API abrufbar:
Duplicate: ein Fahrzeugschein mit der VIN wurde bereits hochgeladen und von uns geprüft
Unreadable: das hochgeladenen Dokument ist nicht lesbar
Wrong Fuel Code: beim Fahrzeug handelt es sich nicht um ein rein-elektrisches Fahrzeug mit dem Code 0004
Wrong Document Type: beim hochgeladenen Dokument handelt es sich nicht um einen Fahrzeugschein (Zulassungsbescheinigung Teil I)
Other Reason: Fahrzeugschein aus anderen Gründen abgelehnt
Alle übermittelten Fahrzeugscheine werden von unserer Software elektronisch ausgelesen und anschließend manuell von uns geprüft. Alle Angaben sowie der gesetzte Status werden in unserem System gespeichert. Mit Ende eines Validierungszyklus werden alle Daten in eine Excel-Tabelle überführt, welche dem Umweltbundesamt als Nachweis für die zu meldenden Fahrzeuge übermittelt werden. Wir geben unseren Partnern die Möglichkeit, eigenständig einen UBA-Report zu generieren, aus dem erkenntlich wird, welche Strommengen für einen bestimmten Zeitraum von uns an das Umweltbundesamt gemeldet werden. Somit erhalten B2B-Partner eine größere Planungssicherheit über registrierte und zu handelnde Mengen. Die Anleitung zur eigenständigen Generierung eines UBA-Reports findest du unter dem Abschnitt “How to Guide Datenabfrage”. Untenstehend befindet sich eine Beispielübersicht:
Kommunikation mit dem Umweltbundesamt und UBA-Bescheid
Die Kommunikation mit dem Umweltbundesamt, insb. die Meldung von Strommengen unserer B2B-Partner samt Übermittlung der Nachweise, ist einer der zentralen Bestandteile aller GreenTrax Services und somit auch des Produktes Quote-as-a-Service. Im Rahmen des Produktes QaaS Vehicles übermitteln wir in vordefinierten Zeitabständen die Excel-Gesamtübersicht mit allen zu meldenden Fahrzeugen und relevanten Angaben, eine signiertes Dokument mit der Gesamtstrommenge (Mitteilung der energetischen Menge gemäß § 8 Abs. 1 S. 1 38. BImSchV) sowie die Vorderseite eines jeden Fahrzeugscheins (Zulassungsbescheinigung Teil I) via SharePoint.
Nach Erhalt der Eingangsbestätigung dauert die Prüfung der Fahrzeugscheine beim Umweltbundesamt i.d.R. 8-12 Wochen. Nach erfolgter Prüfung erhält der Antragsteller einen UBA-Bescheid, in welchem die bestätigte (und erfolgreich geprüfte) Strommenge sowie die Fahrzeugidentifikationsnummern der nicht akzeptierten Fahrzeugscheine. In der Regel wird in diesem Zusammenhang auch ein Grund aufgeführt, warum Fahrzeugscheine nicht vom UBA akzeptiert worden sind - in bisher jedem uns bekannten Fall wurde der Grund aufgeführt, dass ein jeweiliger Fahrzeugschein beim Umweltbundesamt bereits gemeldet wurde.
Sofern ein B2B-Partner uns damit beauftragt hat, den THG-Quotenhandel abzuwickeln, stellt der UBA-Bescheid die Grundlage für die zu handelnden Mengen. Einem B2B-Partner ist aber auch freigestellt den Handel eigenständig zu übernehmen; in diesem Fall leiten wir den UBA-Bescheid via Mail an unsere Kontaktperson weiter. Untenstehend ist ein Beispiel-Bescheid aufgeführt:
Auf Basis der UBA-Bescheide werden wir den Status eines jeden gemeldeten Fahrzeugscheins in unserer Datenbank anpassen. Dieser UBA-Status kann von unserem B2B-Partner via der Vehicles API abgerufen werden.
Wie ist unsere QaaS Vehicles API aufgebaut und welche Informationen werden darüber ausgetauscht?
Die QaaS Vehicles API ermöglicht unseren B2B-Partnern, (1) Fahrzeugscheine, Fahrzeug- und Halter-Informationen an uns zu übermitteln, sowie (2) Informationen und Status der Fahrzeuge aus unserem System abzurufen.
In diesem Zusammenhang wirst du als Nutzer unserer API schnell auf die Begriffe GET, POST, PATCH und DELETE stoßen. Dies sind vier der gängigsten HTML-Befehle, um Informationen an einen Server zu übermitteln oder Informationen von einem Server abzurufen.
GET: Daten von einem Server abrufen
POST: Daten an einen Server übermitteln
PATCH: eine bestehende Information ändern bzw. updaten
DELETE: eine bestehende Information löschen
Die QaaS Vehicles API besteht aus vier unterschiedlichen Gruppen an Elementen (“vehicleregistrants”, “vehicles”, “ubarequests” und “ubaresponses”), welche jeweils unterschiedliche Informationen zum Gegenstand haben und auf Basis der beschriebenen HTML-Befehle funktionieren. Diese vier Gruppen sind untenstehend beschrieben:
vehicleregistrants: auf Kundenseite liegt die Kernfunktion dieses API-Bereichs darin, sogenannte “vehicleregistrants” an unser System zu übermitteln bzw. in unserem System anzulegen. Ein “vehicleregistrant” ist im Fall unseres Produktes QaaS in der Regel ein Unternehmen, welches entweder eigene Flottenfahrzeuge für die THG-Quote registrieren möchte oder die Registrierung von Fahrzeugen für Dritte (bspw. für private Endkunden mit Elektroauto) abwickelt. Der “vehicleregistrant” enthält unternehmensrelevante Informationen wie beispielsweise Adresse, Ansprechpartner und Mail-Adresse. Es ist erforderlich einen “vehicleregistrant” anzulegen, um nachvollziehen zu können, welche Fahrzeuge eurem Unternehmen für den THG-Quotenhandel zugerechnet werden.
vehicles: auf Kundenseite liegt die Kernfunktion dieses API-Bereichs darin, sogenannte “vehicles” an unser System zu übermitteln bzw. in unserem System anzulegen, welche wiederum dem “vehicleregistrant” des jeweiligen B2B-Partner zugeordnet werden. Ein “vehicle” kann ein jedes für den THG-Quotenhandel zugelassenes rein-elektrisches Fahrzeug sein; also beispielsweise Fahrzeuge der Klassen M1 (PKW), N1 (LNF) oder M3 (Bus). Mittels des API-Befehls “POST/vehicles” werden Fahrzeug-relevante Daten, wie die Vorderseite eines jeden Fahrzeugscheins, an uns übermittelt. Nach Erhalt der Fahrzeugscheine startet bei uns der Vorgang der Validierung. Hierbei liest unsere Validierungssoftware alle für den THG-Quotenhandel relevanten Informationen für das Umweltbundesamt aus. In diesem Kontext setzen wir auch einen Validierungsstatus in unserem System (bspw. “verified” oder “wrong fuel code”). Über die zugehörigen API-Befehle kann der B2B-Kunde jederzeit die ausgelesenen Fahrzeugdaten sowie den aktuellen Validierungsstatus abrufen.
ubarequests: auf Kundenseite liegt die Kernfunktion dieses API-Bereichs darin, zu definieren, wann die Abtretungserklärung eines Dritten (bspw. privater Elektroautohalter) an den B2B-Partner für die Registrierung eines Fahrzeugs für die THG-Quote erfolgt ist. Durch den Einbau eines Widerrufrechts hat der B2B-Kunde des Weiteren die Möglichkeit, den frühestmöglichen Zeitpunkt der Meldung eines Fahrzeugs beim Umweltbundesamt, festzulegen.
ubaresponses: auf Kundenseite liegt die Kernfunktion dieses API-Bereichs darin, Informationen zum Fahrzeug-Prüfungsstatus des Umweltbundesamtes aus unserem System abzurufen. Nachdem wir eine UBA-Mitteilung gemacht haben, dauert es in der Regel 8-12 Wochen bis zum Erhalt des UBA-Bescheids. Aus dem UBA-Bescheid geht hervor, welche Fahrzeuge vom UBA nicht akzeptiert wurden. Diesen Status passen wir direkt in unserer Datenbank an, sodass die Information via API abgerufen werden kann.