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

Dieser Webservice ist veraltet und wird nicht weiterentwickelt.

Für den Abruf der unterjährigen Verbrauchsinformation (UVI) als PDF stellen wir eine separate Implementation des ARGE/bved “Webservice Dokumente” bereit. Die Dokumentation dazu finden Sie hier: Dokumenten-API (ARGE/bved "Webservice Dokumente")

Über die Dokumenten-API können Sie DTA-Datensätze von KALO abfragen und an KALO senden.

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/dta

Hierbei handelt es sich um die Basis-URL, die mit den jeweiligen Endpunkten kombiniert werden muss (z.B. https://api.kalo.de/arge/dta + /v1/documents/out?offset=0&limit=100).

Authentifizierung

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

Basic Auth

Sie können unsere Endpunkte nur mit mit Ihren Zugangsdaten per Basic Auth aufrufen.
Im Header muss immer Authorization gesetzt werden.

**** = Username:Passwort (base64-codiert)

CODE

--header 'Authorization: Basic ****'

Wenn Sie für weitere Kunden berechtigt sind, kann der Header um die jeweilige Kundennummer ergänzt werden.

**** = Kundennummer

CODE

--header 'kd: ****'

Die Kundennummer, die Sie hier angeben ist die Kundennummer, für die Sie die Daten abfragen wollen.

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 Wohnzeitraum des jeweiligen Nutzers in der gegebenen Nutzeinheit.

Beispiel: Nutzerinformation Januar-Oktober 2022

JSON

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

Endpunkte

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

https://api.kalo.de/arge/dta/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 oder accept: application/xml und den Header Authorization: Basic ****** enthalten.

CODE

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

Antwort

Format

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

Antwortobjekt

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

JSON

{
  "links": {
    "self": {
      "href": "https://api.kalo.de/arge/dta/v1/documents/out?offset=0&limit=2"
    },
    "prev": null,
    "next": {
      "href": "https://api.kalo.de/arge/dta/v1/documents/out?offset=2&limit=2"
    }
  },
  "_links": {
    "self": {
      "href": "https://api.kalo.de/arge/dta/v1/documents/out?offset=0&limit=2"
    },
    "prev": null,
    "next": {
      "href": "https://api.kalo.de/arge/dta/v1/documents/out?offset=2&limit=2"
    }
  },
  "documents": [{
    "links": {
      "self": {
        "href": "https://api.kalo.de/arge/dta/v1/documents/out/200"
      }
    },
    "filename": "filename",
    "filesize": null,
    "filesizecompressed": null,
    "filedate": null,
    "doctype": "A",
    "doctypeversion": "3.05",
    "mimetype": "ZIP",
    "propertymanagement": "55555",
    "metadata": [{
      "reftype": "billingunit",
      "mscnumber": "9999",
      "pmnumber": null,
      "from": null,
      "to": null
    }, {
      "reftype": "residentialunit",
      "mscnumber": "1",
      "pmnumber": "1 M1",
      "from": "2019-07-01",
      "to": "2020-06-30"
    }, {
      "reftype": "residentialunit",
      "mscnumber": "2",
      "pmnumber": "1 M2",
      "from": "2019-07-01",
      "to": "2020-06-30"
    }],
    "hashvalue": null,
    "_links": {
      "self": {
        "href": "https://api.kalo.de/arge/dta/v1/documents/out/100"
      }
    },
    "documentid": "100",
    "content": null
  }, {
    "links": {
      "self": {
        "href": "https://api.kalo.de/arge/dta/v1/documents/out/200"
      }
    },
    "filename": "filename",
    "filesize": null,
    "filesizecompressed": null,
    "filedate": null,
    "doctype": "A",
    "doctypeversion": "3.07",
    "mimetype": "ZIP",
    "propertymanagement": "213257",
    "metadata": [{
      "reftype": "billingunit",
      "mscnumber": "9999",
      "pmnumber": null,
      "from": null,
      "to": null
    }, {
      "reftype": "residentialunit",
      "mscnumber": "1",
      "pmnumber": "1 M1",
      "from": "2020-07-01",
      "to": "2021-06-30"
    }, {
      "reftype": "residentialunit",
      "mscnumber": "2",
      "pmnumber": "1 M2",
      "from": "2020-07-01",
      "to": "2021-06-30"
    }],
    "hashvalue": null,
    "_links": {
      "self": {
        "href": "https://api.kalo.de/arge/dta/v1/documents/out/200"
      }
    },
    "documentid": "200",
    "content": null
  }]
}

Dokument abfragen

GET /documents/out/{documentid}/data

Erhalten Sie ein Dokument anhand einer documentid ohne Metadaten.

Anfrage

CODE

curl -X 'GET' \
  'https://api.kalo.de/arge/dta/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 oder accept: application/xml und den Header Authorization: Basic ****** enthalten.

CODE

curl -X 'GET' \
  'https://api.kalo.de/arge/dta/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.

JSON

{
  "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: Basic ****** enthalten.

CODE

curl -X 'PUT' \
  'https://api.kalo.de/arge/dta/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.

Dokumente senden

POST /documents/in

Anfrage

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

CODE

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

Antwort

Als Antwort wird ein HTTP Antwortcode geliefert sowie ein JSON Status Object

CODE

{
"statustype": OK | ERROR | WARNING ,
"code": '',
"message":''
}

Dokument mit Metadaten abrufen

GET /documents/out/{documentid}

Anfrage

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

CODE

curl -X 'GET' \
  'https://api.kalo.de/arge/dta/v1/documents/out/{documentid}' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic ******'

Antwort

Als Antwort wird ein HTTP Antwortcode 200 geliefert sowie ein JSON Status Object

JSON

{
  "links": {
    "self": {
      "href": "https://api.kalo.de/arge/dta/v1/documents/out/100"
    }
  },
  "filename": "Name of File",
  "filesize": null,
  "filesizecompressed": null,
  "filedate": null,
  "doctype": "A",
  "doctypeversion": "3.07",
  "mimetype": "ZIP",
  "propertymanagement": "200",
  "metadata": [{
    "reftype": "billingunit",
    "mscnumber": "9999",
    "pmnumber": null,
    "from": null,
    "to": null
  }, {
    "reftype": "residentialunit",
    "mscnumber": "1",
    "pmnumber": "1 M1",
    "from": "2020-07-01",
    "to": "2021-06-30"
  }, {
    "reftype": "residentialunit",
    "mscnumber": "2",
    "pmnumber": "1 M2",
    "from": "2020-07-01",
    "to": "2021-06-30"
  }],
  "hashvalue": null,
  "_links": {
    "self": {
      "href": https://api.kalo.de/arge/dta/v1/documents/out/100"
    }
  },
  "documentid": "100",
  "content": null
}

Bei allen anderen HTTP Antwortcodes

CODE

{
"statustype": OK | ERROR | WARNING ,
"code": '',
"message":''
}

Nicht implementierte Endpunkte

Die Endpunkte nach Version 0.5 und 0.1 des Arge/bved-Standards sind nicht implementiert und werden nicht unterstützt. Sprechen Sie bei Fragen hierzu gerne mit Ihrem KALO-Kundenbetreuer aus dem Bereich digitale Lösungen.

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.
403	Not Allowed	Sie haben keinen Zugriff auf die angeforderte Ressource.
404	Not Found	Der Server kann die angeforderte Ressource nicht finden.
406	Not Acceptable	Derzeit unterstützten wir nicht den Media Type “application/xml”. Bitte wählen Sie den Type “application/json”.
410	Gone	Dokument ist nicht mehr verfügbar oder Dokumenten-Empfang wurde bereits bestätigt.
429	Too Many Requests	Zu viele Anfragen in einem gewissen Zeitraum (“Rate Limiting”).
500	Internal Server Error	Der Server kann die Anfrage nicht beantworten aufgrund interner, weiterführender 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.