Verbrauchsdaten-API (bved "consumption-data", ehemals ARGE)

Über die Verbrauchsdaten-API können Sie Verbräuche für die unterjährige Verbrauchsinformation (UVI) von KALO abfragen.

Hierfür haben wir den vom Bundesverband für Energie- und Wasserdatenmanagement (bved), ehemals Arbeitsgemeinschaft Heiz- und Wasserkostenabrechnung (ARGE), definierten Webservice „consumption-data” bei uns umgesetzt.

Die Webservice-Definition und dazugehörige Dokumente stehen auf folgender Website zum Download bereit: bved.info/datenaustausch (ARGE/bved consumption-data v1.1)

Endpunkte

Sie greifen auf die Endpunkte der API über HTTPS zu (port 443). Jeder Aufruf muss die Hauptversionsnummer im API Endpunktpfad enthalten. Die aktuelle Version ist v1 für ARGE/bved consumption-data v1.1.

https://api.kalo.de/arge/consumptions/v1/

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

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

Token Refresh

Ein Refresh des Tokens wird derzeit nicht unterstützt. Nach Ablauf der Gültigkeit müssen Sie einen neuen Token am Tokenendpunkt erstellen.

Weitere Informationen zur Authentifizierung unter OpenID Connect | openid.net und in der OPENIDC Spezifikation

Basic Auth

Sie können alternativ unsere Endpunkte mit Ihren Zugangsdaten per Basic Auth aufrufen.

Anfragen

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.

Jede Anfrage muss die http header accept: application/json und Authorization: Bearer ****** oder Authorization: Basic ****** enthalten.

GET /billingunits/{mscnumber}/consumptions/periods

CODE

curl -X 'GET' \
  'https://api.kalo.de/arge/consumptions/v1/billingunits/{mscnumber}/consumptions/periods' \
  --header 'accept: application/json' \
  --header 'Authorization: Bearer ******'

GET /billingunits/{mscnumber}/consumptions/periods/{period}

CODE

curl -X 'GET' \
  'https://api.kalo.de/arge/consumptions/v1/billingunits/{mscnumber}/consumptions/periods/{period}' \
  --header 'accept: application/json' \
  --header 'Authorization: Bearer ******'

Antworten

Format

Antworten können entweder leer oder ein JSON-Objekt sein. Im Erfolgsfall erhalten Sie ein JSON-Objekt, das je nach Endpunkt unterschiedlich ist.

Antwortobjekt

JSON

{
  "billingunit": {
    "reference": {
      "mscnumber": "123456789",
      "pmnumber": "XY-12345-00"
    },
    "periods": [
      {
        "period": "2021-06",
        "update": "2022-05-09T09:04:55.772Z"
      }
    ]
  }
}

HTTP-Antwortcodes

Folgende Antwortcodes erhalten Sie von uns:

Antwortcode	Status	Beschreibung
200	OK	Die Anfrage ist erfolgreich. Die Bedeutung eines Erfolgs hängt von der HTTP-Methode ab: `GET`: Die Ressource wurde geholt und wird im Nachrichtentext übertragen.
400	Bad request	Der Server konnte die Anfrage aufgrund einer ungültigen Anfrage nicht ausführen.
401	Unauthorized	Eine gültige Authentifizierung ist erforderlich, um die angeforderte Antwort zu erhalten.
404	Not Found	Der Server kann die angeforderte Ressource nicht finden.
500	Internal Server Error	Der Server kann die Anfrage nicht beantworten aufgrund interner, weiterführende Systemprobleme.
501 / 405	Not Implemented	Die Anfragemethode wird vom Server nicht unterstützt und kann nicht bearbeitet werden.
503	Temporarily not available	Die Anfragemethode wird vom Server nicht unterstützt und kann nicht bearbeitet werden.

KALO IP-Adresse

Hier finden Sie die aktuelle statische IP-Adresse. Wir behalten uns vor die IP-Adresse in Zukunft zu ändern oder den IP-Bereich anzupassen.

CODE

193.102.14.238