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

Einführung

Zweck und Anwendungsbereich

Die Nutzer-Management-API (bved "on-site-roles") erlaubt Ihnen, Nutzer- bzw. Bewohnerwechsel an KALO zu übermitteln und damit eine wichtige Voraussetzung für die Erstellung der unterjährigen Verbrauchsinformation (UVI) zu erfüllen. Was ist die unterjährige Verbrauchsinformation (UVI)

Weiterhin können Sie mithilfe der API Ihren Nutzerdatenstand selbstständig, d.h. ohne Eingriff durch KALO, einsehen und pflegen. Im Detail gehören dazu:

aktuellen Nutzerdatenstand abfragen
Nutzerdatenstand bearbeiten (zum Beispiel Ein-/Auszüge hinterlegen)
Nutzerdaten löschen
Neue Nutzerdaten einfügen

Mehr erfahren über die Endpunkte oder Beispielszenarien „S-COR“ (Nutzer bzw. Bewohner)

Über diese API

Die Nutzer-Management-API ist eine HTTP REST-API nach dem Webservice-Standard „on-site-roles“ vom Bundesverband für Energie- und Wasserdatenmanagement (bved), ehemals Arbeitsgemeinschaft Heiz- und Wasserkostenabrechnung (ARGE). Die dazugehörige API-Definition und Dokumente können Sie hier kostenlos herunterladen: Dokumentation der bved für die API „on-site-roles v1.1“

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.

Bitte beachten Sie: Die Felder Telefonnummer, Steuernummer und E-Mail-Adresse werden derzeit nicht gespeichert.

Über diese API-Dokumentation

Die nachfolgende Dokumentation bietet Informationen zur Implementierung der API. Mit dieser Dokumentation möchten wir Sie bei der optimalen Nutzung der Nutzer-Management-API v1.1 für die UVI unterstützen.

Erfahren Sie mehr über Fehlermeldungen.

Authentifizierung

Wir bieten Ihnen die Authentifizierung über Bearer Token (OpenIDConnect) oder Basic Auth an, um sowohl den IT-Sicherheitsanforderungen zeitgemäßer Anwendungen zu genügen als auch der brancheneinheitlichen Spezifikation der API.

Ihre API-Zugangsdaten erhalten Sie von Ihrem KALO-Kundenbetreuer aus dem Bereich digitale Lösungen.

Bearer Token (OpenIdConnect)

Sie können die Endpunkte mit einen gültigen Bearer JWT-Token aufrufen. Diesen erhalten Sie über den folgenden OpenID-Token-Endpunkt:

POST https://meine.kalo.de/auth/realms/arge-api/protocol/openid-connect/token

Ersetzen Sie bitte den HTTP Authorization header mit Ihren API-Zugangsdaten (Benutzername:Passwort) im Base64 Format.

CODE

curl --location --request POST 'https://meine.kalo.de/auth/realms/arge-api/protocol/openid-connect/token' \
--header 'Authorization: Basic ******='\
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials'

OpenID Discovery Configuration (.well-known-configuration)

https://meine.kalo.de/auth/realms/arge-api/.well-known/openid-configuration

Basic Auth

Als alternative Authentifizierungsmethode wird HTTP Basic Auth entsprechend der Definition im bved-Standard „on-site-roles“ unterstützt. (siehe bved-Dokumentation für die API „on-site-roles v1.1“ )

Ihre API-Zugangsdaten erhalten Sie auf Anfrage per E-Mail von uns. Kontaktieren Sie uns dafür bitte über unser Kontaktformular.

Endpunkte

Basispfad

Pfad für das Produktivsystem:

https://api.kalo.de/arge/on-site-roles/v1/

Pfad für das Testsystem:

Den Zugriffspfad für die Testumgebung erhalten Sie aus Sicherheitsgründen nur persönlich im Rahmen der Testplanung.

Bitte beachten Sie: Die sogenannte „MSC Number Billingunit“, also die Liegenschaftsnummer im Messdienstleistersystem (auf Englisch „measure service company number “), ist Bestandteil jeder API-Anfrage. Die API unterstützt 9-stellige alphanumerische Nummern, wie sie branchenüblich sind. Das schließt Nummern mit führenden Nullen ein.

Verfügbare Endpunkte im Überblick

Wie in der bved-Dokumentation beschrieben, können Sie unterschiedliche Nutzerdatenänderungen über die Schnittstelle selbst ausführen bzw. KALO mitteilen.

Nutzerwechsel bzw. Nutzerdatenänderungen werden wie folgt an KALO übermittelt.

Nutzerdatenstand abfragen

Anfrage (HTTP GET): Datenstand abfragen

Mittels einer „GET“-Anfrage ist es möglich, den aktuellen Nutzerdatenstand Ihrer Liegenschaften pro Nutzeinheit (zum Beispiel der aktuelle Bewohner) bei der KALO für einen Abgleich der Datenstände einzusehen.

CODE

GET {Basispfad}/billingunits/012345678/residentialunits/012/on-site-roles

Sie würden also zu der Liegenschaft „012345678” die aktuellen Nutzerdaten zu der Nutzeinheit (Wohnung) „012” erhalten. Es wird keine Historie ausgegeben sondern nur der aktuelle Nutzerdatenstand.

Nutzerdatenstand übermitteln und bearbeiten

Anfrage (http POST): Datenstand bearbeiten

Nehmen Sie Änderungen am Nutzerdatenstand vor, nachdem Sie ihn abgefragt und ggf. Fehler festgestellt haben (siehe oben Nutzerdatenstand abfragen).

CODE

POST {Basispfad}/billingunits/012345678/residentialunits/012/on-site-roles/

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

Beispiel Nutzerwechsel in einer Nutzeinheit übermitteln

In diesem Beispiel eines Nutzerwechsels wird das Auszugsdatum (to) des alten Nutzers bzw. Bewohners mit einem „UPDATE” gesetzt. Der neue Nutzer (Bewohner) wird mittels „INSERT” eingefügt und zeitlich nach der Erstbelegung ohne Auszugsdatum, nur mit Startdatum (from) übergeben. Die Zuordnung der Nutzerrolle zum Nutzerpartner wird mit der Partner PM Number sichergestellt.

Wenn mehr als eine Rollenänderung in einer Anfrage umgesetzt werden soll, ist die Reihenfolge entscheidend. D.h. der Auszug eines Nutzer (UPDATE) muss in der Anfrage zwingend vor dem Einzug des nächsten Nutzers (INSERT) erfasst und übermittelt werden.

Bitte übermitteln Sie keine Nutzerdaten Rolle „S-COR” bei Leerständen.

CODE

{
   "timestamp": "2022-05-16T10:17:17Z",
   "billingunit":{
      "reference":{
         "pmnumber":"654321",
         "mscnumber":"012345678"
      },
      "residentialunit":{
         "reference":{
            "pmnumber":"654321",
            "mscnumber":"012"
         },
         "roles":[
            {
               "change":"UPDATE",
               "role":"S-COR",
               "from":"2018-05-01",
               "to":"2022-05-31",
               "partner":{
                  "pmnumber":"mieter-01"
               }
            },
            {
               "change":"INSERT",
               "role":"S-COR",
               "from":"2022-06-01",
               "partner":{
                  "pmnumber":"mieter-02"
               }
            }
         ],
         "partners":[
            {
               "reference":{
                  "pmnumber":"mieter-01"
               },
               "name":"Mustermann",
               "firstname":"Max",
			   "commercial": "NON_COMMERCIAL"
            },
            {
               "reference":{
                  "pmnumber":"mieter-02"
               },
               "name":"Musterfrau",
               "firstname":"Meike",
			   "commercial": "NON_COMMERCIAL"              
            }
         ]
      }
   }
}

Nutzer (Rollen) löschen

Anfrage (HTTP POST): Datenstand bearbeiten

Nutzer-Rollen können zum Beispiel für Datenkorrekturen mit dem Rollen-Change Event „DELETE” aus dem KALO-Datenbestand gelöscht werden.

CODE

POST {Basispfad}/billingunits/012345678/residentialunits/012/on-site-roles/

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

Beispiel: Nutzer aus einer Nutzeinheit entfernen, z.B. weil der Nutzer doch nicht eingezogen ist.

In diesem Beispiel zum Entfernen eines Nutzers wird das Change Event des Nutzers auf „DELETE” gesetzt.

Wenn mehr als eine Rollenänderung in einer Anfrage umgesetzt werden soll, ist die Reihenfolge entscheidend. D.h. das Löschen eines Nutzers (DELETE) muss in der Anfrage zwingend vor dem Einzug des nächsten Nutzers (INSERT) erfasst und übermittelt werden.

CODE

{
   "timestamp": "2022-05-16T10:17:17Z",
   "billingunit":{
      "reference":{
         "pmnumber":"654321",
         "mscnumber":"012345678"
      },
      "residentialunit":{
         "reference":{
            "pmnumber":"654321",
            "mscnumber":"012"
         },
         "roles":[
            {
               "change":"DELETE",
               "role":"S-COR",
               "from":"2022-06-01",
               "partner":{
                  "pmnumber":"mieter-02"
               }
            }
         ],
         "partners":[
            {
               "reference":{
                  "pmnumber":"mieter-02"
               },
               "name":"Musterfrau",
               "firstname":"Meike",
			   "commercial": "NON_COMMERCIAL"              
            }
         ]
      }
   }
}

Ergebnis der Nutzerdatenstandübermittlung abrufen (Data-Delivery Status)

Data-Delivery-ID: Anfrage überprüfen

Anfrage

Der Data-Delivery Status (Ergebnis der Nutzerdatenübermittlung) ist mit dem Data-Delivery Endpunkt und der „Data-Delivery-ID” abzufragen.

CODE

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

Eine fehlgeschlagene Bearbeitung / Übermittlung der Nutzerdaten sieht wie folgt aus:

Data-Delivery Status-Antwort „FAIL”

CODE

{
	"status": "FAIL",
	"roleMessages": [
		{
			"role": "S-COR",
			"from": "2018-06-01",
			"to": "2022-02-30",
			"partner": {
				"pmnumber": "654321",
				"mscnumber": "mieter-02"
			},
			"key": OSR-kalo,
			"message": "role is overlapping with another role"
		}
	],
	"partnerMessages": null
}

Für die Fehleranalyse verwenden Sie bitte die Tabelle im Abschnitt Data-Delivery-Status-Fehlermeldungen

Data-Delivery Status-Antwort „SUCCESS"

Ihre Anfrage war erfolgreich, wenn Sie den Status „SUCCESS" in Ihrer „Data-Delivery Ergebnisabfrage / Statusantwort” sehen.

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 bved-Standard liegt es in Ihrer Verantwortung, den Status jeder Datenlieferung über die Schnittstelle abzufragen und mögliche Meldungen zu bearbeiten. Im Falle von Fehlern korrigieren Sie bitte die im Data-Delivery Status angegebenen Fehler und übermitteln Sie die Nutzerdaten erneut.

Datenlieferungen mit dem Status “FAIL” werden von KALO nicht verarbeitet.

Beispielszenarien „S-COR“ (Nutzer bzw. Bewohner)

Im Folgenden finden Sie einige Beispielszenarien bzw. Use-Cases samt technischer Beispielanfragen („Request Body“) für die Rolle S-COR, welche den Empfänger der unterjährigen Verbrauchsinformation (UVI) – sprich den Nutzer oder Bewohner (Mieter oder Eigentümer) – repräsentiert.

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

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

	Name	Ist Zustand	Beschreibung	Request Body
1	Übermittlung Nutzerwechsel innerhalb einer Nutzeinheit.	Mustermann wohnt ohne Enddatum innerhalb einer Nutzeinheit.	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":"099654321" }, "residentialunit":{ "reference":{ "pmnumber":"1234561", "mscnumber":"001" }, "roles":[ { "change":"UPDATE", "role":"S-COR", "from":"2018-05-01", "to":"2022-05-31", "partner":{ "pmnumber":"011" } }, { "change":"INSERT", "role":"S-COR", "from":"2022-06-01", "partner":{ "pmnumber":"022" } } ], "partners":[ { "reference":{ "pmnumber":"011" }, "name":"Mustermann", "firstname":"Max", "commercial": "NON_COMMERCIAL" }, { "reference":{ "pmnumber":"022" }, "name":"Musterfrau", "firstname":"Meike", "commercial": "NON_COMMERCIAL" } ] } } }
2	Bereits übermittelte Nutzerwechsel bearbeiten	Das Auszugsdatum von Musterfrau soll angepasst werden	Folgenutzer Meike 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":"099654321" }, "residentialunit":{ "reference":{ "pmnumber":"1234561", "mscnumber":"001" }, "roles":[ { "change":"UPDATE", "role":"S-COR", "from":"2022-06-01", "to":"2023-07-31", "partner":{ "pmnumber":"022" } } ], "partners":[ { "reference":{ "pmnumber":"022" }, "name":"Mustermann", "firstname":"Meike", "commercial": "NON_COMMERCIAL" } ] } } }`
3	Bereits übermittelte Nutzerwechsel löschen.	Musterfrau zieht doch nicht mehr in die Nutzeinheit ein und soll wieder gelöscht werden.	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":"099654321" }, "residentialunit":{ "reference":{ "pmnumber":"1234561", "mscnumber":"001" }, "roles":[ { "change":"DELETE", "role":"S-COR", "from":"2022-06-01", "to":"2023-07-31", "partner":{ "pmnumber":"022" } } ], "partners":[ { "reference":{ "pmnumber":"022" }, "name":"Mustermann", "firstname":"Meike", "commercial": "NON_COMMERCIAL" } ] } } }`

Fehlerbehandlung

Hier finden Sie eine Übersicht an Fehlermeldungen, wie sie einerseits in der bved-Dokumentation enthalten sind sowie darüberhinausgehend von uns definierte Fehlermeldungen und ihre Behandlung.

Zur bved-Dokumentation: https://bved.info/datenaustausch/spezifikationen

HTTP-Antwortcodes

Folgende Standard HTTP-Antwortcodes erhalten Sie von uns:

Antwortcode	Status	Fehlerbeschreibung und Behebungsempfehlung
200	OK	Die Anfrage ist erfolgreich. Die Ressource wird als Antwort zurückgeliefert.
400	Bad request	Der Server konnte die Anfrage aufgrund einer ungültigen Anfrage nicht ausführen. Weitere Details zur Ursache wird in der Fehlerantwort mitgeteilt.
401	Unauthorized	Eine gültige Authentifizierung ist erforderlich, um die angeforderte Antwort zu erhalten.
403	Forbidden	Ihr API Zugang hat nicht die Berechtigung um diese Nutzerdaten abzufragen oder zu ändern. Kontaktieren Sie ggf. den KALO Kunden-Support
404	Not Found	Der Server kann die angeforderte Ressource nicht finden. Weitere Details zur Resource finden Sie in der Antwortfehlermeldung.
412	Precondition Failed	Die Anfrage bzw. die zu übermittelnde Datenstruktur enthält nicht die notwendigen Nummern (Msc/ Pm Number) oder ein anderer Rollentyp, als der unterstützte S-COR wurde übermittelt, angefragt.
429	To Many Requests	Ihre Anfragen von der gleichen Aufrufer IP-Adresse wurde aus Sicherheitsgründen geblockt (rate limiting). Versuchen Sie die Anfragen sequentiell verteilt zu stellen.
500	Internal Server Error	Der Server kann die Anfrage nicht beantworten aufgrund eines internen Fehlers.
501 / 405	Not Implemented	Die Anfragemethode wird vom Server nicht unterstützt und kann nicht bearbeitet werden.
503	Temporarily not available	Der Webservice steht kurzfristig nicht zur Verfügung. Versuchen Sie es zu einem späteren Zeitpunkt noch einmal oder kontaktieren Sie den Kunden Support.

Fehlermeldungen

Stand: Mai 2025

Synchrone Validierung

Fehlermeldung + Fehlerbeschreibung

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

Fehlermeldung	Fehlerbeschreibung
no S-COR role found	Es werden nur Anfragen oder Übermittlungen von Rollen des Typs 'S-COR' unterstützt.
no partner found	Zur Rolle wurde kein Partner angegeben.
name is missing	In der Rolle wurde kein Partnername angegeben.
from is missing	In der Rolle wurde kein Nutzungsstart (Einzugsdatum) angegeben.
The given msc billing number 012345 is incorrect	Die angefragte msc billingunit number ist nicht korrekt siehe MSC Number Billingunit

Asynchrone Validierung (Data-Delivery Status)

Fehlermeldung + Fehlerbeschreibung bei Data Delivery ID Abfrage

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

CODE

{
  "status": "FAIL",
  "roleMessages": [
    {
      "role": "S-COR",
      "from": "2025-05-01",
      "to": "9999-12-31",
      "partner": {
        "pmnumber": "712345 123456-4455"
      },
      "key": "OSR-kalo",
      "message": "role is overlapping with another role"
    }
  ],
  "partnerMessages": []
}

Key	Fehlermeldung	Fehlerbeschreibung
OSR-kalo	Role not supported	Die Rolle wird aktuell nicht unterstützt.
OSR-kalo	role is overlapping with another role	Die Rolle kann nicht geändert werden, da sie sich zeitlich mit dem vorhandenen, aktuellen Nutzer und dessen Nutzungszeitraum überschneidet.
OSR-kalo	resource_not_found	Die Rolle konnte anhand der partner reference pmnumber in der billingunit nicht beim Messdienstleister KALO gefunden bzw. identifiziert werden.

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 bved Spezifikation, Punkt "(2) Asynchrone Validierung").

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