Nutzer-Management-API (ARGE/bved "on-site-roles")

Einführung

Verwendungszweck

Übermitteln Sie Nutzer- bzw. Bewohnerwechsel an KALO für die korrekte Erstellung der unterjährigen Verbrauchsinformation (UVI). Was ist die unterjährige Verbrauchsinformation (UVI)

Weiterhin können Sie mithilfe der Schnittstelle Ihren Datenstand selbstständig ohne manuellen Eingriff durch KALO einsehen und pflegen:

Datenstand abfragen
Datenstand bearbeiten
Daten löschen
Neue Daten einfügen

Mehr erfahren über die Anfragemethoden oder Beispielszenarien.

Allgemeine Info zur API

Wir haben den Webservice „on-site-roles“ von der Arbeitsgemeinschaft Heiz- und Wasserkostenabrechnung (ARGE) bzw. Bundesverband für Energie- und Wasserdatenmanagement (bved) umgesetzt. Hier können Sie die Webservice-Definition und dazugehörige Dokumente kostenlos herunterladen: https://bved.info/veroeffentlichungen/datenaustausch/

Bitte beachten Sie: KALO unterstützt aktuell nur die Rolle „S-COR” im Rahmen der unterjährigen Verbrauchsinformation (UVI). Alle anderen Rollen werden aktuell nicht verarbeitet und nicht gespeichert.

Erweiterte Dokumentation von KALO (Fehlermeldungen)

Über den ARGE/bved-Standard hinaus (siehe Dokumentation der ARGE/bved für die API „on-site-roles“) haben wir weitere sprechende Fehlermeldungen ergänzt, die Sie dabei unterstützen, die Implementierung durchzuführen.

Erfahren Sie mehr über die Fehlermeldungen des ARGE/bved-Standards sowie zusätzliche KALO-Fehlermeldungen.

Authentifizierung (Basic Auth)

Wir unterstützen Basic Auth für die Authentifizierung, entsprechend der Definition im ARGE/bved-Standard „on-site-roles“ (siehe Dokumentation der ARGE/bved für die API „on-site-roles“ ).

Ihre Zugangsdaten erhalten Sie auf Anfrage per E-Mail von uns. Kontaktieren Sie uns gerne über unser Kontaktformular.

Endpunkte

GET https://api.kalo.de/arge/on-site-roles/v1/billingunits/{mscnumber-billingunit}/on-site-roles/data-delivery/{dataDeliveryId}

GET https://api.kalo.de/arge/on-site-roles/v1/billingunits/{mscnumber-billingunit}/residentialunits/{mscnumber-residentialunit}/on-site-roles

POST https://api.kalo.de/arge/on-site-roles/v1/billingunits/{mscnumber-billingunit}/residentialunits/{mscnumber-residentialunit}/on-site-roles

Anfragemethoden

Wie in der Dokumentation der ARGE/bved beschrieben können Sie unterschiedliche Datenänderungen über die Schnittstelle selbst ausführen bzw. KALO mitteilen. Im Folgenden beschreiben wir, wie Sie vorgehen müssen:

Datenstand abfragen („GET“-Anfrage)

„GET"--Anfrage: Datenstand abfragen

Mittels einer „GET“-Anfrage ist es möglich, den Nutzerdatenstand Ihrer Liegenschaften bei der KALO einzusehen.

Eine solche Anfrage an uns würde beispielsweise wie folgt aussehen:

CODE

GET {Basispfad}/billingunits/123456/residentialunits/1234/on-site-roles

Sie würden also zu der Liegenschaft “123456” die aktuellen Nutzerdaten zu der Nutzeinheit (Wohnung) “1234” erhalten. Es wird keine Historie ausgegeben.

Datenstand bearbeiten („POST”-Anfrage)

„Post“-Anfrage: Datenstand bearbeiten

Nehmen Sie Änderungen am Datenstand vor, nachdem Sie ihn abgefragt und ggf. Fehler festgestellt haben (siehe oben „GET“-Anfrage). Dazu wird eine „POST”-Anfrage verwendet. Hier sehen Sie ein Beispiel für eine solche POST-Anfrage

CODE

POST {Basispfad}/billingunits/123456/residentialunits/1234/on-site-roles/

Zusätzlich müssen Sie hier auch den Request-Body Ihrer Anfrage im „JSON”-Format füllen. Ein solcher Body könnte wie folgt aussehen.

In diesem Beispiel wird das Auszugsdatum eines Nutzers bzw. Bewohners mit einem „UPDATE” gesetzt und ein neuer Bewohner wird mittels „INSERT” eingefügt. Es besteht auch die Möglichkeit, wie im ARGE-Standard beschrieben, ein „DELETE” durchzuführen.

CODE

{
   "timestamp": "2022-05-16T10:17:17Z",
   "billingunit":{
      "reference":{
         "pmnumber":"654321",
         "mscnumber":"123456"
      },
      "residentialunit":{
         "reference":{
            "pmnumber":"654321",
            "mscnumber":"1234"
         },
         "roles":[
            {
               "change":"UPDATE",
               "role":"S-COR",
               "from":"2018-05-01",
               "to":"2022-05-31",
               "partner":{
                  "pmnumber":"12345611"
               }
            },
            {
               "change":"INSERT",
               "role":"S-COR",
               "from":"2022-06-01",
               "to":"2022-12-31",
               "partner":{
                  "pmnumber":"12345612"
               }
            }
         ],
         "partners":[
            {
               "reference":{
                  "pmnumber":"12345611"
               },
               "name":"Mustermann",
               "firstname":"Max",
			   "commercial": "NON_COMMERCIAL",
               "phonenumbers":[
                  {
                     "number":"0176-55555555",
                     "type":"MOBILE"
                  }
               ]
            },
            {
               "reference":{
                  "pmnumber":"12345612"
               },
               "name":"Musterfrau",
               "firstname":"Meike",
			   "commercial": "NON_COMMERCIAL",
               "phonenumbers":[
                  {
                     "number":"0176-66666666",
                     "type":"MOBILE"
                  }
               ]
            }
         ]
      }
   }
}

Bei der Rolle “S-COR” muss in diesem Fall die Rolle gelöscht und mit den korrekten Daten neu angelegt werden.

Anfrage überprüfen („Data-Delivery-ID”)

Data-Delivery-ID: Anfrage überprüfen

Nach jeder erfolgreich übermittelten „POST”-Anfrage erhalten Sie von uns eine „Data-Delivery-ID” als Antwort. Diese bestätigt, dass Ihre Anfrage bei uns eingegangen ist. Gleichzeitig dient sie dazu, den Status dieser Anfrage jederzeit eigenständig überprüfen zu können.

Beispiel:

„GET“-Anfrage:

Die „Data-Delivery-ID” ist am Ende der URL zu finden.

CODE

GET {Basispfad}/billingunits/123456/on-site-roles/data-delivery/ccbe102e-169f-4160-bba1-197e53aasb99

Eine Antwort würde beispielsweise wie folgt aussehen:

Data-Delivery-ID-Antwort „FAIL"

CODE

{
	"status": "FAIL",
	"roleMessages": [
		{
			"role": "S-COR",
			"from": "2022-06-16",
			"to": "9999-12-31",
			"partner": {
				"pmnumber": "654321",
				"mscnumber": null
			},
			"key": OSR-KALO,
			"message": "There is no matching role in the update target."
		}
	],
	"partnerMessages": null
}

Dieses Beispiel zeigt, dass diese Anfrage nicht verarbeitet werden konnte, da die gesendeten Daten der Rolle für ein „UPDATE” nicht mit der zu bearbeitenden Rolle übereinstimmten: "There is no matching role in the update target."

Data-Delivery-ID-Antwort "SUCCESS"

Ihre Anfrage war erfolgreich, wenn Sie den Status "SUCCESS" in Ihrer „Data-Delivery-ID” sehen. Sie können und sollten sicherheitshalber Ihre gewünschte Datenänderung erneut mit einer „GET”-Anfrage einsehen und überprüfen. Siehe oben „GET“-Anfrage.

Sollte Sie nicht erfolgreich gewesen sein, wiederholen Sie bitte die zuvor beschriebenen Schritte, bis der gewünschten Datenstand erreicht ist.

Bitte beachten Sie: Laut dem ARGE-Standard liegt es in Ihrer Verantwortung, den Status jeder Datenlieferung über die Schnittstelle abzufragen und mögliche Meldungen zu bearbeiten. Eine Datenlieferung, die zu einem FAIL führt, wird von KALO nicht verarbeitet.

Beispielszenarien

Im Folgenden finden Sie einige Beispielszenarien bzw. Use-Cases samt technischer Beispielanfragen („Request Body“) für die Rolle „S-COR“, also für den Empfänger der unterjährige Verbrauchsinformation (UVI).

Bitte beachten Sie: Aktuell unterstützt KALO keine Mehrfachbelegungen. Es kann nur eine Rolle vom Typen „S-COR“ zur Zeit aktiv sein. Ist es gewünscht eine neue Rolle anzulegen, muss die aktive Rolle vorher via „UPDATE” mit einem Auszugsdatum beendet werden (siehe Use Case Nr. 1).

Eine Überlappung der in den Rollen definierten Zeiträume ist damit nicht möglich.

Use Cases für die Rolle „S-COR“

Nr.	Name	Ist Zustand	Ziel	Beschreibung	Request Body
1	Lieferung Nutzerwechsel innerhalb einer Nutzeinheit.	Mustermann wohnt ohne Enddatum innerhalb einer Nutzeinheit.	Nutzerwechsel Mieter/Eigentümer.	Nutzer Mustermann zieht zum (DD.MM.JJJJ) aus, Folgenutzer Musterfrau (DD.MM.JJJJ) zieht ein.	JSON { "timestamp": "2022-05-16T10:17:17Z", "billingunit":{ "reference":{ "pmnumber":"123456", "mscnumber":"654321" }, "residentialunit":{ "reference":{ "pmnumber":"1234561", "mscnumber":"0001" }, "roles":[ { "change":"UPDATE", "role":"S-COR", "from":"2018-05-01", "to":"2022-05-31", "partner":{ "pmnumber":"12345611" } }, { "change":"INSERT", "role":"S-COR", "from":"2022-06-01", "to":"2022-12-31", "partner":{ "pmnumber":"12345612" } } ], "partners":[ { "reference":{ "pmnumber":"12345611" }, "name":"Mustermann", "firstname":"Max", "commercial": "NON_COMMERCIAL", "phonenumbers":[ { "number":"0176-55555555", "type":"MOBILE" } ] }, { "reference":{ "pmnumber":"12345612" }, "name":"Musterfrau", "firstname":"Meike", "commercial": "NON_COMMERCIAL", "phonenumbers":[ { "number":"0176-66666666", "type":"MOBILE" } ] } ] } } }
2	Bereits gelieferte Nutzerwechsel bearbeiten	Das Auszugsdatum von Musterfrau soll angepasst werden	Nutzerwechsel Mieter/Eigentümer anpassen.	Folgenutzer Musterfrau hat ein späteres Auszugsdatum (DD.MM.JJJJ) mitgeteilt. (Aufbauend auf Use Case Nr. 1)	JSON { "timestamp": "2022-05-16T10:17:17Z", "billingunit":{ "reference":{ "pmnumber":"123456", "mscnumber":"654321" }, "residentialunit":{ "reference":{ "pmnumber":"1234561", "mscnumber":"0001" }, "roles":[ { "change":"UPDATE", "role":"S-COR", "from":"2022-06-01", "to":"2023-07-31", "partner":{ "pmnumber":"12345612" } } ], "partners":[ { "reference":{ "pmnumber":"12345612" }, "name":"Mustermann", "firstname":"Meike", "commercial": "NON_COMMERCIAL", "phonenumbers":[ { "number":"0176-66666666", "type":"MOBILE" } ] } ] } } }
3	Bereits gelieferten Nutzerwechsel löschen.	Musterfrau zieht doch nicht mehr in die Nutzeinheit ein und soll wieder gelöscht werden.	Nutzerwechsel löschen.	Ursprünglich gelieferter Nutzerwechsel von Musterfrau soll wieder entfernt werden. (Aufbauend auf Use Case Nr. 2)	JSON { "timestamp": "2022-05-16T10:17:17Z", "billingunit":{ "reference":{ "pmnumber":"123456", "mscnumber":"654321" }, "residentialunit":{ "reference":{ "pmnumber":"1234561", "mscnumber":"0001" }, "roles":[ { "change":"DELETE", "role":"S-COR", "from":"2022-06-01", "to":"2023-07-31", "partner":{ "pmnumber":"12345612" } } ], "partners":[ { "reference":{ "pmnumber":"12345612" }, "name":"Mustermann", "firstname":"Meike", "commercial": "NON_COMMERCIAL", "phonenumbers":[ { "number":"0176-66666666", "type":"MOBILE" } ] } ] } } }

Fehlerbehandlung

Hier finden Sie von der ARGE/bved standardisierte und zusätzliche KALO-benutzerspezifische Fehlermeldungen.

Eine vollständige Beschreibung der ARGE/bved-Standardfehlermeldungen finden Sie auf der ARGE/bved-Website im Abschnitt „Webservice on-site-roles“.

Alle Fehlermeldungen werden mit einem Schlüssel bzw. Key ausgegeben. Bei den von der ARGE/bved definierten Fehlermeldungen gibt es die synchrone und asynchrone Datenvalidierung.

OSR steht für „on-site-roles“

ARGE/bved-Standard

Stand: Februar 2024

Synchrone Validierung

Folgende Punkte werden sofort validiert und Fehler entsprechend synchron zurückgegeben:

Key	Fehlertext
OSR-1001	Ein in einer Rolle referenzierter Partner ist nicht Teil der Datenlieferung.
OSR-1002	Die E-Mail-Adresse eines Partners hat ein ungültiges Format.
OSR-1003	Die Telefonnummer eines Partners hat ein ungültiges Format.
OSR-1004	Das Beginn-Datum (`from`) fehlt bei Übermittlung der Änderung von Empfängern der Einzelabrechnung (`S-BIR` bzw. `S-BVA`).

Asynchrone Validierung

Bitte denken Sie daran, die Verarbeitung Ihres Auftrages mittels der erhaltenen Data Delivery ID auf den Status und eventuelle Fehlermeldungen zu überprüfen (vgl. dazu auch ARGE/bved Spezifikation, Punkt "(2) Asynchrone Validierung").

Bei einer asynchronen Verarbeitungen können folgende ARGE/bved-Keys zurückkommen. Diese können über die Data Delivery ID abgerufen werden.

Key	Fehlertext
OSR-2001	Die übermittelte Nummer der Abrechnungseinheit des Messdienstleisters ist nicht bekannt.
OSR-2002	Die übermittelte Nummer der Nutzeinheit des Messdienstleisters ist nicht bekannt oder passt nicht zur Abrechnungseinheit.
OSR-2003	Es gibt zeitliche Überlappungen von Rollen vom Typ `S-BIR` oder `S-BVA` für die Nutzeinheit.
OSR-2004	Es gibt Lücken ohne Rollen vom Typ `S-BIR` oder `S-BVA` für die Nutzeinheit.
OSR-2005	Es wurden Änderungen an Empfängern der Einzelabrechnung übermittelt, die schon abgeschlossene Abrechnungseinheiten betreffen.
OSR-2006	Es gibt für die gesendete Service-Rolle keinen Vertrag beim MSC und somit keine Vereinbarung, dass diese Daten gespeichert werden dürfen.
OSR-2007	Aktualisierung fehlgeschlagen - die gesendete Rolle mit Aktion `UPDATE` konnte anhand von Typ (`role`), `from`-Datum und der `pmnumber` des zugeordneten Partners nicht beim MSC identifiziert werden.

KALO-Fehlermeldungen

Stand: Februar 2024

Zusätzliche von KALO entwickelte Fehlermeldungen

Die Fehlermeldungen werden ausgegeben, wenn Sie den Verarbeitungsstand des Auftrages über die Data Delivery ID abfragen.

Key	Fehlermeldung	Übersetzung und Details zum Fehler
OSR-Kalo	Role not supported	Die Rolle wird aktuell nicht unterstützt.
OSR-Kalo	The from field of the on-site-role is was not set. This is a mandatory field.	Das "Von" Feld (d.h. das “gültig ab” Datum) für die OSR wurde nicht gesetzt.
OSR-Kalo	No pmnumber set on partner-reference.	Die pmnumber muss noch gesetzt werden bei dem Partner. Damit ist der Ordnungsbegriff des "Property Managers" gemeint.
OSR-Kalo	Name of partner not set in site-role.	Die OSR benötigt die Angabe eines Partners (bzw. auch als Nutzer zu verstehen)
OSR-Kalo	First-Name of partner not set in site-role	Der Vornamen des Partners muss noch gesetzt werden.
OSR-Kalo	The given from date of the on-site-role is younger than the to date of its predecessor. Overlapping.	Das angegebene “gültig ab” Datum ist jünger als das “gültig bis” Datum des vorherigen OSR. Eine Überlappung wird nicht zugelassen.
OSR-Kalo	The given from-date is after or equals the to-date in on-site-role.	Das “gültig ab” Datum des OSR ist gleich oder liegt nach dem angegebenen “gültig bis” Datum.
OSR-Kalo	No active partner found for specified pmnumber. Update is only possible for the most recent role.	Für die pmnumber wurde kein aktiver Partner bzw. Nutzer gefunden. Ein Aktualisieren der Daten ist nur beim aktiven OSR einer Nutzeinheit möglich. Wenn Vorgänger bearbeitet werden sollen, bitte zuerst den aktiven OSR löschen, die gewünschten Änderungen übermitteln und dann den OSR wieder neu anlegen.
OSR-Kalo	No active partner found for specified pmnumber. Deletion is only possible for the most recent role.	Für die pmnumber wurde kein aktiver Partner bzw. Nutzer gefunden. Ein Löschen der Daten ist nur beim aktiven OSR einer Nutzeinheit möglich.
OSR-Kalo	Format problem detected with mscnumber of residential unit	Die Formatierung der von KALO abgespeicherten Nutzeinheitnummern stimmt nicht. Mögliche Fehlerursachen: Buchstaben eingemischt, nicht die richtige Nummerlänge, länger als 4-stellig.
OSR-Kalo	Format problem detected with mscnumber of billing unit	Die Formatierung der von KALO abgespeicherten Abrechnungseinheit stimmt nicht. KALO-Abrechnungseinheiten (AE) sind normalerweise 6-stellige Nummern, ein einzelnen Fällen auch 9-stellige Nummern (Präfix 099 plus 6-stellige AE-Nummer). Mögliche Fehlerursachen: Buchstaben eingemischt, nicht die richtige Nummerlänge, länger als 9-stellig.
OSR-Kalo	More than one residential unit found. Please contact the support.	Für die angegebene Nutzeinheit wurden mehrere Einträge gefunden. Bitte KALO kontaktieren.
OSR-Kalo	No on-site-roles found in residential unit.	Für die Nutzeinheit wurde keine OSR (kein Nutzer/Partner) gefunden.
OSR-Kalo	Residential unit not found.	Nutzeinheit konnte nicht gefunden werden.
OSR-Kalo	Deletion of role was not possible. Please contact the support.	Das Löschen der OSR war aus sonstigen oder unerwarteten Gründen nicht möglich. Bitte KALO kontaktieren.
OSR-Kalo	Update of role was not possible. Please contact the support.	Das Updaten der OSR war aus sonstigen oder unerwarteten Gründen nicht möglich. Bitte KALO kontaktieren.
OSR-Kalo	Insert of role was not possible. Please contact the support.	Das Einfügen der OSR war aus sonstigen oder unerwarteten Gründen nicht möglich. Bitte KALO kontaktieren.
OSR-Kalo	The partner referenced in a role is not sent in the same request.	Der Partner, welche in der Rolle der Anfrage referenziert wird, ist nicht derselbe. Bitte den request logisch und inhaltlich überprüfen.
OSR-Kalo	The email-address of a partner is not valid.	Ungültige E-Mail-Adresse.
OSR-Kalo	The phone number of a partner is not valid.	Ungültige Telefonnummer.
OSR-Kalo	The `from` date is missing in this case of billing recipient changes	Das “gültig ab” Datum des Rechnungsempfängers ist leer.
OSR-Kalo	mscnumber of billing unit in request body does not match with values in URL.	Die Messdienstleisternummer der Abrechnungseinheit (AE) aus der URL und in der Anfrage stimmen nicht miteinander überein. Bitte nochmal überprüfen.
OSR-Kalo	mscnumber of residential unit in request body does not match with values in URL.	Die Messdienstleisternummer der Nutzungseinheit (NE) aus der URL und in der Anfrage stimmen nicht miteinander überein. Bitte nochmal überprüfen.
OSR-Kalo	No supported role to process.	Der Request enthält keine der derzeit von KALO unterstützen Rollen und wurde deshalb nicht verarbeitet.
OSR-Kalo	To date in active role is empty, please update before inserting new role.	Das “gültig bis” Datum der aktiven OSR ist leer. Dieses muss jedoch erst gesetzt werden, bevor ein neuer OSR eingefügt werden kann.
OSR-Kalo	`from` date is missing in target role, cannot update. Please contact the support.	Das zu updatende OSR hat kein “gültig ab” Datum. Bitte KALO kontaktieren.
OSR-Kalo	Target `from` date is after or equal to specified `to` date. Please contact the support.	Das “gültig ab” Datum des zu ändernden Ziels ist gleich oder nach dem bereits definierten “gültig bis” Datum. Bitte KALO kontaktieren.
OSR-Kalo	`from` date of active role does not match new `from` date. You can only update currently active roles.	Das “gültig ab” Datum ist ein anderes als derzeit in der referenzierten OSR definiert. Das Update wurde nicht durchgeführt. Mögliche Fehlerursachen: Request falsch zusammengebaut, Request nicht auf die gewünschte OSR bezogen
OSR-Kalo	Active `from` date does not match delete `from` date. Deletion is not possible.	Das “gültig ab” Datum ist ein anderes, als derzeit in der referenzierten OSR definiert. Das Löschen wurde nicht durchgeführt. Mögliche Fehlerursachen: Request falsch zusammengebaut, Request nicht auf die referenzierte OSR bezogen
OSR-Kalo	There is no matching role in the update target.	Es wurde für das gewünschte Update keine übereinstimmende OSR gefunden.
OSR-Kalo	There is no matching role in the delete target.	Es wurde für das gewünschte Delete keine übereinstimmende OSR gefunden.
OSR-Kalo	Partner pmnumber not unique in residential unit.	Die pmnumber innerhalb einer Nutzungseinheit (NE) ist nicht eindeutig.
OSR-Kalo	Error on deleting last role of type S-BIR or S-BVA. At least one of these role types must be present.	Es wurde versucht die letzte Rolle vom Typ “S-BIR” oder “S-BVA” zu löschen. Dies ist nicht möglich, da mindestens eine Rolle dieser Art präsent sein muss.
OSR-Kalo	Could not find role for deletion in arge osr backend.	Die zu löschende Rolle konnte nicht in unserem Service gefunden werden.
OSR-Kalo	Change type missing in role.	Das Attribute “change” wurde in der Anfrage nicht gefüllt mit einer der folgenden Werten: UPDATE INSERT DELETE
OSR-Kalo	partner reference missing in role.	Zu der OSR muss ein Partner definiert sein.
OSR-Kalo	there is more than one role matching the target.	Zu der Anfrage wurden mehrere Zielrollen gefunden. Bitte genauer überprüfen und ggfs. KALO kontaktieren.
OSR-Kalo	Error on update: on site role not found.	Die zu verändernde Rolle konnte nicht gefunden werden.
OSR-Kalo	Error on insert: inserting role before current role not supported by the MSC.	Das Einfügen einer neuen Rolle, welche einen älteren Zeitraum hat als die zur Zeit aktive Rolle, ist nicht möglich.
OSR-Kalo	Error on insert or update: date overlap not supported by MSC.	Eine Überlappung der Zeiträume von mehreren Rollen wird nicht unterstützt.
OSR-Kalo	Update failed - the role to be updated cannot be identified at the MSC by attributes `role`, `from`, and the partner's `pmnumber`	Die zu ändernde Rolle konnte nicht identifiziert werden anhand der zur Verfügung gestellten Attribute.

Support und Kontakt

Sie benötigen Zugang zu einer unserer Schnittstellen oder haben ein Problem bei der Nutzung der APIs? Nutzen Sie gerne unser Kontaktformular, um uns Ihr Anliegen mitzuteilen. Unsere Experten nehmen schnellstmöglich Kontakt mit Ihnen auf.

Zum API-Kontaktformular