Verbrauchsdaten-API (ARGE/bved "consumption-data")

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

Hierfür haben wir den von der Arbeitsgemeinschaft Heiz- und Wasserkostenabrechnung (ARGE) bzw. Bundesverband für Energie- und Wasserdatenmanagement (bved) definierten Webservice “consumption-data” bei uns umgesetzt.

Die Webservice-Definition und dazugehörige Dokumente stehen auf folgender Website zum Download bereit: https://bved.info/veroeffentlichungen/datenaustausch/

Endpunkte

Sie greifen auf die Endpunkte der API über HTTPS zu (port 443). Jeder Aufruf muss die Versionsnummer im Pfad enthalten. Die aktuelle Version ist v1.1.

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

Authentifizierung

Wir bieten Ihnen die Authentifizierung über Bearer Token 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

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 ist derzeit nicht unterstützt. Nach Ablauf der Gültigkeit müssen Sie einen neuen Token beantragen.

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.

Allgemein

MSC Number

Die MSC Number muss zwingend 9-stellig sein. Sie erhalten die MSC Number in demselben Format wie in Ihrer Anfrage zurück.

Beispiel

000123456 → 000123456
099123456 → 099123456

Anfragen

Jede Anfrage muss die headers 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