Webservice HKD EED

Die Schnittstelle bzw. den Webservice on-site-roles finden Sie in iX-Haus plus erst nach der Lizenzierung unter Schnittstellen > Webservice HKD EED.

Mit der Einführung der EED (Energy Efficiency Directive, in überarbeiteter Fassung durch die Europäische Kommission am 14. Juli 2021 vorgelegt und in Deutschland als Energieeffizienz-Richtlinie im Rahmen der novellierten Heizkostenverordnung zum 01.12.2021 übernommen) haben Nutzer mit funkfernablesbaren Zählern ein Recht darauf, aktuelle Informationen zu ihrem Heizkostenverbrauch zu erhalten. Da die Heizkostendienste aktuelle Daten zu Nutzerwechseln benötigen, wurde seitens der Arbeitsgemeinschaft Heiz- und Wasserkostenverteilung ARGE HeiWaKo der Webservice on-site-roles spezifiziert, den Heizkostendienstleister und Softwarehersteller für eigene Schnittstellen verwenden können.

Der Webservice on-site-roles überträgt aktuelle Nutzerdaten, damit die Erstellung von Verbrauchsinformationen für aktuelle Nutzer seitens des Heizkostendienstleisters erfolgen kann. Die Übermittlung der Daten an den Heizkostendienstleister erfolgt regelmäßig bei Änderungen. Die Datenlieferung per Webservice on-site-roles ist nur möglich, wenn bereits der L/M-Sätze im klassischen ARGE-Datentausch durchgeführt worden sind.

Bitte stimmen Sie die Datenlieferungen je Messdienst individuell ab. Insbesondere ist zu klären, ob die Rollen S-BIR und S-BVA vom Messdienstleister unterstützt werden und inwieweit Abfragen einzeln oder zusammen erfolgen sollen.

Bislang konnte der Webservice on-site-roles mit dem Messdienstleistern Techem, ISTA, Brunata und Kalorimeta erfolgreich durchgeführt werden.

Voraussetzungen

Wie mache ich es?

Aktuelle Daten des Heizkostendienstes anzeigen

Aktuelle Daten zum Heizkostendienst übertragen

Konfiguration in iX-Haus

Konfiguration im Scheduler

Startdatum für Übertragung setzen

Statusabfrage beim HKD

Was brauche ich dazu?

Katalog Heizkostendienste

Unbeschränkter Zugang: iX-Haus plus > Schnittstellen > Webservice HKD EED > Katalog > Heizkostendienste
Beschränkter Zugang: iX-Haus > Fachadministration > Kataloge > Heizkostendienste

Der Katalog in iX-Haus plus basiert auf dem iX-Haus Katalog Heizkostendienste, in welchem jedoch nicht alle Felder angeboten werden. Der Katalog in iX-Haus plus ist mit den Abschnitten Webservice: on-site-roles und Webservice: Dokumente erweitert. Der Katalog Heizkostendienste kann somit an zwei Stellen aufgerufen werden und bietet nur beim Aufruf unter iX-Haus plus alle Optionen.

Bitte beachten Sie, dass ein Katalogeintrag aktiviert sein muss und die korrekte Version des vereinbarten Datentauschs (2.1 oder 3.x) zugeordnet ist.
Wenn bei einem Heizkostendienst mehrere Kundennummern hinterlegt sind, können eine Reihe von einheitlichen Übertragungsparametern gleichzeitig erfasst werden.

Feld	Erklärung
`Lfd. Nr.`	Laufende Nummer zur Differenzierung des Dienstes.
`Heizkostendienst`	Der Heizkostendienst, für den die Daten erfasst werden sollen. Hier werden alle hinterlegten und aktivierten Heizkostendienste angeboten.
`Heizkostendienst ID`	Voreingestellte Nummer aus der Übersicht der ARGE „Tabelle U“
`Version`	Auswahl der passenden Version zur korrekten Übertragung des gewünschten Dateiformats nach Anforderung des HKD.
`Deakiviert`	Kontrollfeld zur Deaktivierung nicht relevanter HKDs.
`E898 verwenden`	Kontrollfeld zur Aktivierung des Austauschs von E898-Datensätzen.
Webservice: on-site-roles
`Bereit für on-site-roles Protokoll`	Generelle Einstellung, ob eine Übertragung stattfinden soll.
`Basispfad für die API ‚on-site-roles‘`	Die URL für den Server. Diese Information stellt der Heizkostendienstleister.
`Keine E-Mail-Übertragung`	Wenn diese Option aktiviert ist, werden keine beim Nutzer hinterlegten E-Mail-Adressen per Webservice übertragen.
`Keine S-BIR Übertragung`	Wenn diese Option aktiviert ist, wird keine Rolle `S-BIR` (Abrechnungsempfänger) per Webservice übertragen. Beim Heizkostendienstleister ist zu erfragen, ob diese Rolle übertragen werden kann. Immer übertragen wird die Rolle `S-COR` (Verbrauchsinformationsempfänger).
`Keine S-BVA Übertragung`	Wenn diese Option aktiviert ist, wird keine Rolle S-BVA (Abrechnungsempfänger Leerstand) per Webservice übertragen. Beim Heizkostendienstleister ist zu erfragen, ob diese Rolle übertragen werden kann. Immer übertragen wird die Rolle S-COR (Verbrauchsinformationsempfänger).
`Kein GET-Befehl`	Für den Fall, dass ein Heizkostenanbieter das GET-Kommando in der Rest-API nicht unterstützt, kann über den Schalter `Kein GET-Befehl` ein entsprechender Betriebsmodus aktiviert werden. In der Folge wird bei einer Übertragung nicht mehr abgefragt, welche Daten beim HKD für eine Fläche bereits bekannt sind und alle Daten werden stets komplett übertragen. Da zum Erzeugen von Lösch- oder Aktualisierungsanfragen zwingend die über den GET-Befehl angeforderten Daten benötigt werden, können bei Aktivierung des Schalters grundsätzlich nur Abrufanfragen gesendet werden, so dass der jeweilige HKD den aktuellen Datenstand manuell erarbeiten muss. Um diese Arbeit zu erleichtern und insbesondere beendete Belegungen erkennen zu können, werden zusätzlich Daten für in den letzten zwölf Monaten ausgelaufene Belegungen gesendet. Hinweis: Wir empfehlen, diesen Schalter nur in Absprache mit dem Heizkostendienst zu aktivieren.
Komprimierte Übertragung	Wenn diese Option aktiviert ist, werden die Abfragen für jeden Nutzer zusammengefasst geliefert. Das Standardprogrammverhalten ist die Lieferung einzelner Abfragen (jeweils pro Nutzer den Befehl für ein Insert, ein Update oder ein Delete).
Webservice: Dokumente	Dieser Abschnitt ist vorbereitend für zukünftige Funktionen und wird aktuell noch nicht genutzt.
`Bereit für Webservice Dokumente`	Über Webservice Dokumente können HKD-Daten per API mit dem HKI'S ausgetauscht werden. (In iX-Haus noch nicht im Einsatz befindliche Funktion.)
`Basispfad für die API ‚Webservice Dokumente‘`	Die URL für den Server. Diese Information stellt der Heizkostendienstleister. (In iX-Haus noch nicht im Einsatz befindliche Funktion.)
`Min. Start Datum`	Mit diesem Feld kann eine Sonderbehandlung aktiviert werden, wenn das Start-Datum einer Flächenbelegung beim Heizkostendienst systembedingt nicht frei vergeben werden darf. Dieses Feld wird nur in Ausnahmefällen benötigt und sollte daher nach Absprache mit dem HKD gesetzt werden.

Katalog HKD Webservice Server

Zugang: iX-Haus plus > Schnittstellen > Webservice HKD EED > Katalog > HKD Webservice Server

Feld	Erklärung
`Heizkostendienst`	Der Heizkostendienst, für den die Daten erfasst werden sollen. Hier werden alle hinterlegten und aktivierten Heizkostendienste angeboten.
`Kundennummer`	Das Ausfüllen des Feldes ist optional. Werden Objekte beim Heizkostendienst unter unterschiedlichen Kundennummern geführt und sind je Kundennummer unterschiedliche Login-Daten vorhanden, können diese hiermit unterschieden werden.
`Login`	Login Kennung. Diese Information stellt der Heizkostendienstleister.
`Passwort`	Passwort. Diese Information stellt der Heizkostendienstleister.

Modul HKD Webservice on-site-roles

Zugang: iX-Haus plus > Schnittstellen > Webservice HKD EED > HKD Webservice on-site-roles

Die Hauptansicht zum Modul (Grid) erreichen Sie über die Auswahl HKD Webservice on-site-roles. In der Hauptansicht werden alle Flächen mit Daten für die Heizkostendienstleister angezeigt. Neben den in den Flächen erfassten Daten zum Heizkostendienstleister (u. a. Kundennummer, Ordnungsnummer) sind drei Datumswerte wichtig:

Startdatum der Übertragung: Das Datum gibt vor, ab wann eine Fläche mit dem Webservice übertragen werden darf. Das Feld finden Sie im Flächenstamm unter Heizkosten als Verbrauchsinformationen EED ab:
Letzter Abgleich: Bei einer erfolgreichen Übertragung der Daten zum Server des Heizkostendienstes wird das Datum Letzter Abgleich automatisch gesetzt.
Letzte Änderung der iX-Haus Daten: Bei jedem Datensatz in iX-Haus und iX-Haus Plus wird automatisch gespeichert, wann der Datensatz zum letzten Mal verändert worden ist. In dieser Spalte werden die Änderungsdaten aus allen verknüpften Datensätzen ausgewertet und der größte Datumswert ausgegeben.

In der Spalte Status der Übertragung wird zu jedem Datensatz der letzte Status der Übertragung dargestellt. In Fällen, in denen die aktuellen Daten für eine Fläche manuell oder über ein Testsystem an den Heizkostendienst übertragen werden, wird bei einem anschließenden Abgleich der Daten erkannt, dass die Daten bereits validiert sind. Es werden in diesem Fall keine neuen Daten übertragen und der Status der Übertragung wird bei einem erfolgreichen Abgleich auf OK gesetzt.

Per Doppelklick öffnen Sie eine Detailsicht zu einer Fläche. In der Detailansicht existieren zu jeder Fläche Register mit weiteren Daten.

Die Spalte PM Nummer enthält den 20-stelligen Ordnungsbegriff, der seitens iX-Haus vorgegeben und verwendet wird (ARGE-Ordnungsbegriff Auftraggeber). Der HKD-Ordnungsbegriff enthält den 13-stelligen Ordnungsbegriff des Heizkostendienstleisters. Die Ordnungsbegriffe Auftraggeber und Heizkostendienstleister entstammen der ARGE-Definition während PM Nummer und HKD Ordnungsnummer Begrifflichkeiten aus on-site-roles-Definitionen sind.

Spalte	Beschreibung
`Objekt`	Objektnummer und Bezeichnung
`Fläche`	Flächennummer und Bezeichnung
`letzter Abgleich`	Datum des letzten erfolgreichen Datenabgleichs zum Server des Heizkostendienstes im Format TT.MM.JJJJ
`letzte Änderung der iX-Haus Daten`	Datum der letzten Stammdatenänderung im Format TT.MM.JJJJ Datum der letzten Änderung des Datensatzes in iX-Haus oder iX-Haus plus. (Technisch ermittelter größter Datumswert lt. Auswertung der Änderungsdaten aus allen verknüpften Datensätzen. Die Änderung muss nicht zwangsläufig zu einer Änderung der sichtbaren bzw. zu übertragender Daten führen).
`Startdatum der Übertragung (S-COR)`	Datum der Datenübertragung via S-COR (Personendaten) im Format TT.MM.JJJJ
`Heizkostendienst`	Name des Heizkostendienstes
`HKD Kundennummer`	Kundennummer beim Heizkostendienst
`HKD Ordnungsnr`	Ordnungsnummer, entspricht i. d. R. dem 13-stelligen Ordungsbegriff des Heizkostendiensts. Datensätze ohne Ordnungsnummer erhalten eine laufende Nummer mit negativem Vorzeichen.
`Status der Übertragung`	Letzter Status der Übertragung. Die Funktionen Sortieren, Filtern und Gruppieren werden unterstützt.
`Anzahl Übertragungen`	Zahl, Summe der Spalten `Anzahl Übertragungen(In Bearbeitung)`, `Anzahl Übertragungen(Ohne Status)`, `Anzahl Übertragungen(OK)` und `Anzahl Übertragungen(Probleme)`.
`Anzahl Übertragungen(In Bearbeitung)`	Zahl
`Anzahl Übertragungen(Ohne Status)`	Zahl, noch nicht übertragene.
`Anzahl Übertragungen(OK)`	Zahl, erfolgreich übertragene.
`Anzahl Übertragungen(Probleme)`	Zahl, Übertragungen mit Fehlermeldungen Beachten Sie die weiterführenden Hinweise hierzu aus der Detailsicht zu einer betroffenen Fläche im Register `Status der Übertragung` bzw. aus dem Protokoll im Modul `Schnittstellenadministration`.

Register Belegungen

Im Register Belegungen werden die Verträge für die aktuelle Fläche angezeigt. Bei Zeilen ohne einen Personeneintrag handelt es sich um einen Leerstand.

Spalte	Beschreibung
`Objekt`	Objektnummer und Bezeichnung
`Fläche`	Flächennummer und Bezeichnung
`PM Nummer`	20-stelliger Ordnungsbegriff iX-Haus zur Fläche (Ordnungsbegriff Auftragggeber)
`Beginn`	Beginn von Belegung oder Leerstand
`Ende`	Ende von Belegung oder Leerstand
`Per`	Objektnummer+Personennummer Anrede und Name des Nutzers. Bei Leerstand erfolgt hier keine Eintragung.
`letzte Änderung der iX-Haus Daten`	Datum der letzten Stammdatenänderung im Format TT.MM.JJJJ
`HKD Webservice on-site-roles`

Register Status der Übertragung

Das Register Status der Übertragung informiert detailliert über den Status der letzten Übertragung.

Spalte	Beschreibung
`Übertragungsnummer`	Übertragungsnummer, referenziert mit der Übertragungsnummer im Modul `Schnittstellenadministration`.
`Beschreibung`	Art der Übertagung
`Übertragung am`	Datum
`letzte Statusabfrage am`	Datum
`Status`
`Status Beschreibung`
`HKD Webservice on-site-roles`

Register weitere Empfänger

Im Register weitere Empfänger werden Sonderfälle wie weitere Bewohner, die ggf. übermittelt werden, aufgeführt. Derzeit bietet iX-Haus hier zwei Datenquellen an.

Bei einer WEG mit Objekt für die Sondereigentumsverwaltung werden hier zugeordnete Belegungen aus dem SEV-Objekt angezeigt. Die Verbindung der Flächen zwischen dem WEG-Objekt und dem SEV-Objekt muss dafür im Flächenstamm hinterlegt sein. (Flächenstammregister Übersicht, Felder Fläche WEG und Fläche SE). Die Felder sind nur bei einem entsprechendem Objekttyp (WEG mit Sondereigentum, WEG mit Garantiemiete) sichtbar.
Bei einer WEG ohne gesondertes SEV-Objekt (Objekttyp WEG) können im Flächenstamm im Register WEG Mieter Mieterdaten dokumentiert werden (verfügbar ab Version iX-Haus 20.21.0/KW50).

Spalte	Beschreibung
`Typ`
`PM Nummer`	20-stelliger Ordnungsbegriff iX-Haus zur Fläche (Ordnungsbegriff Auftragggeber)
`Beginn`
`Status`
`Ende`
`Name 1`	Name 1
`Name 2`	Name 2
`e-Mail`	E-Mail-Adresse
`Telefon 1`	Telefonnummer
`Telefon 2`	Telefonnummer
`Telefon 3`	Telefonnummer
`Commercial`	Checkbox
`Keine DSGVO-Einwilligung`	Checkbox Eine Sperre durch `Keine DSGVO-Einwilligung` bewirkt, dass solche Personen nicht an dem Datenaustausch teilnehmen und so z. B. nicht vom Heizkostendienst über einen möglichen Zugang zu den Ablesedaten informiert werden, da einer Weitergabe der erforderlichen Daten widersprochen wurde.
`letzte Änderung der iX-Haus Daten`	Datum der letzten Stammdatenänderung im Format TT.MM.JJJJ

Kontextmenübefehle

Markieren Sie die gewünschten Datensätze in der Listenansicht und öffnen Sie per Kontextmenü (rechte Maustaste) die weiteren Aktionen. Neben Standardmenüpunkten stehen fur die Tabelle HKD Webservice on-site-roles folgende Funktionen zur Verfügung:

`Setze Startdatum für Übertragung`	Mit der Funktion kann das Datum für die Übertragung bequem für mehrere Flächen eingetragen werden. Der Eintrag erfolgt im Flächenstamm unter Heizkosten als `Verbrauchsinformationen EED ab:`. Im Regelfall werden nur leere Felder verändert. Mit der Option `Überschreibe vorhandene Daten` werden auch bereits vorhandene Daten geändert.
`Anzeigen der aktuellen Daten vom HKD`	Hierbei handelt es sich um eine Diagnoseansicht für die Inbetriebnahme des Webservices für eine erste Kommunikation mit dem Server. Für die ausgewählten Flächen wird der Status beim Heizkostendienst (HKD) abgefragt und die erhaltenen Daten in einer Textbox im Rohformat angezeigt. Mit der Funktion kann geprüft werden, ob die Kommunikation mit dem Server funktioniert, der Login-Name und das Passwort richtig sind und ob die URL korrekt ist. Der Zugriff verändert die gespeicherten Daten nicht. Die angezeigten Daten werden im JSON-Format angezeigt.
`Übertrage aktuelle Daten zum HKD`	Mit dieser Funktion werden die Daten der markierten Flächen übertragen. Eine Übertragung läuft in mehreren Phasen ab. Es wird zuerst anhand der Datumswerte geprüft, ob eine Übertragung erforderlich ist. Wenn sich die lokalen Daten seit der letzten erfolgreichen Übertragung nicht verändert haben, wird die Fläche nicht erneut übertragen. Im nächsten Schritt wird der IST-Stand der Informationen zur Fläche beim HKD abgefragt und es findet ein Abgleich der Daten statt. Je nach Vergleichsergebnis werden die übertragenen Daten und Rollen gelöscht, aktualisiert oder neu angelegt. Dieser Schritt kann mit dem Modul `Scheduler` automatisch für alle Flächen eines HKD ausgeführt werden. Bei der Datenübertragung werden Daten zur Einheit (`Ordnungsbegriff des Heizkostendienstes`, `Ordnungsbegriff iX-Haus`) und zum Nutzer an den Heizkostendienstleister gesendet. Die Nutzerdaten werden dabei im Sinne der EU-DSGVO auf ein Minimum beschränkt. Übertragen werden der Name des Hauptnutzers, der Vertragsbeginn und ggf. ein Vertragsende. Kontaktdaten, wie Telefonnummern werden nicht übertragen. Eine Besonderheit stellen E-Mailadressen dar. Diese werden übertragen, können aber über die Konfiguration des Webservice von einer Übertragung ausgenommen werden. Der jeweilige Status der Daten und die übertragenen Kommandos an den Webservice werden in der Schnittstellenadministration dokumentiert. Beim Übertragen von Daten an Heizkostendienste hat sich gezeigt, dass E-Mail-Adressen aus iX-Haus oft nicht dem erwarteten Format entsprechen und teilweise für Zusatzinformationen oder Erklärungstexte verwendet werden. Vor einer Übertragung findet daher eine Syntaxprüfung statt. Für das on-site-roles-Interface werden die entsprechenden Daten nach bestimmten Kriterien abgeglichen. Wenn keine gültige E-Mail-Adresse erkannt wird, bleibt das Feld leer. Wenn eine E-Mail-Adresse mit Zusatzinfos erkannt wird, wird diese ohne Zusatz übertragen. Bei mehreren E-Mail-Adressen wird die erste verwendet. In beiden Fällen werden die Daten im Log der Schnittstellenadministration dokumentiert. Die Originaldaten werden dabei nicht verändert.
`Statusabfrage beim HKD`	Mit dieser Funktion wird der Status der markierten Datensätze (Flächen) abgefragt. Der jeweilige Status der letzten Abfrage wird abgerufen und der Eintrag zum Status im Datensatz aktualisiert. Dieser Schritt kann mit dem `Scheduler` automatisch für alle Flächen eines HKD ausgeführt werden. Die Prüfung, ob eine Fläche neu übertragen werden darf, berücksichtigt deren Status. Wenn ein noch nicht abgefragter Status vorliegt, erfolgt keine erneute Übertragung. Ergab die zuletzt durchgeführte Statusabfrage einen Fehler, kann eine erneute Übertragung erfolgen. Übertragungen mit dem Status `OK` werden ohne vorherige Änderung der betreffenden iX-Haus-Daten nicht erneut übertragen.