Dokumenten-API (ARGE/bved "Webservice Dokumente")

Über die Dokumenten-API können Sie die unterjährigen Verbrauchsinformation (UVI) von KALO als PDF-Dokument abfragen.

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

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

Systeme

Produktion (live)
https://api.kalo.de/arge

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

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.

Referenzen

Sie erhalten in den Metadaten der Dokumente eine Referenz auf den aktuellen Nutzer (resident) der Nutzeinheit über die Sie das Dokument zuordnen können.

Die “from”- und “to”-Daten beziehen sich auf den Zeitraum für den das Dokument erstellt wurde.

Beispiel: Verbrauchsinformation Oktober 2022

{
  "retype": "resident",
  "mscnumber": "0990012340001"
  "pmnumber": "0123/05544/0001"
  "from": "2022-10-01"
  "to": "2022-10-31"
}

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.

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

Liste verfügbarer Dokumente abfragen

GET /documents/out

Liefert die Liste der verfügbaren Dokumente. Dokumente, deren Empfang über PUT /documents/out/{documentid}/status bereits bestätigt wurde, sind nicht in der Liste enthalten.

Anfrage

Jede Anfrage muss den Header accept: application/json und den Header Authorization: Bearer ****** oder Authorization: Basic ****** enthalten.

curl -X 'GET' \
  'https://api.kalo.de/arge/documents/v1/documents/out?offset=0&limit=100' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer ******'

Antwort

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

Mit der documentid können Sie ein Dokument über die weiteren Endpunkte abrufen.

{
  "_links": {
    "self": {
      "href": "/arge/documents/v1/documents/out?offset=0&limit=100"
    },
    "next": {
      "href": "/arge/documents/v1/documents/out?offset=100&limit=100"
    }
  },
  "documents": [
    {
      "filename": "Filename.pdf",
      "doctype": "UVI-E",
      "mimetype": "application/pdf",
      "propertymanagement": "",
      "metadata": [
        {
          "reftype": "resident",
          "mscnumber": "0991234560001",
          "pmnumber": "00789    M 012345",
          "from": "2022-01-01",
          "to": "2022-01-31"
        }
      ],
      "_links": {
        "self": {
          "href": "/arge/documents/v1/documents/out/{documentid}/data"
        }
      },
      "documentid": "asdadHasr35rqreqerFASFDAass2"
    }
  ]
}

Dokument abfragen

GET /documents/out/{documentid}/data

Erhalten Sie ein Dokument anhand einer documentid ohne Metadaten.

Anfrage

curl -X 'GET' \
  'https://api.kalo.de/arge/documents/v1/documents/out/4270_1_14286c7b-ea03-3b80-be55-d5d2a204ae01_2022_5_e316df8048cf2187734fc08ba9a64320c9722164a4c478d91bec281bf67256a0/data' \
  -H 'accept: application/pdf' \
  -H 'Authorization: Basic ******'

Antwort

Format

Als Antwort erhalten Sie das angeforderte PDF als Datei.

Anzahl verfügbarer Dokumente abrufen

GET /documents/out/count

Liefert die Anzahl der Dokumente, die über die Anfrage GET /documents/out bereitgestellt werden. Dokumente, deren Empfang über PUT /documents/out/{documentid}/status bereits bestätigt wurde, gehen nicht in die Zählung ein.

Anfrage

Jede Anfrage muss den Header accept: application/json und den Header Authorization: Bearer ****** oder Authorization: Basic ****** enthalten.

curl -X 'PUT' \
  'https://api.kalo.de/arge/documents/v1/documents/out/count' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic ******'

Antwort

In der Antwort wird die Anzahl der Dokumente als Wert von “count” geliefert.

{
  "count": 23
}

Dokument Empfang bestätigen

PUT /documents/out/{documentid}/status

Mit dieser Anfrage wird der Empfang eines Dokumentes bestätigt. Derart bestätigte Dokumente werden in der Antwort der Anfragen GET /documents/out und GET /documents/out/count nicht mehr berücksichtigt.

Anfrage

Jede Anfrage muss den Header Authorization: Bearer ****** oder Authorization: Basic ****** enthalten.

curl -X 'PUT' \
  'https://api.kalo.de/arge/documents/v1/documents/out/1234_1_14286c7b-ea03-3b80-be55-d5d2a2a4af01_2022_5_e316df8048cf2187734fc08ba9a64320c9722164a4c478d91bes425f67256a0/status' \
  -H 'Authorization: Basic ******'

Antwort

Als Antwort wird nur ein HTTP Antwortcode geliefert.

Nicht implementierte Endpunkte

Die folgenden Endpunkte sind derzeit nicht implementiert. Sprechen Sie bei Fragen hierzu gerne mit Ihrem KALO-Kundenbetreuer aus dem Bereich digitale Lösungen.

Dokumente senden

POST /documents/in

Dokument mit Metadaten abrufen

GET /documents/out/{documentid}

HTTP Antwortcodes

Folgende Antwortcodes erhalten Sie von uns:

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.

193.102.14.238