Verbrauchsdaten direkt in Ihre Software. Nach bved-Standard.

Überblick

Der Bundesverband für Energie- und Wasserdatenmanagement (bved) legt einheitliche Webservices für den Datenaustausch zwischen Messdienstleistern und Verwaltungssoftware fest. Heidi richtet seine Schnittstelle an diesen Spezifikationen aus. Wer bereits einen bved-Webservice angebunden hat, kann Heidi mit wenig Aufwand ergänzen.

Schnellstart

1. 1
   Zugang anfragen

   Ihr persönlicher Ansprechpartner bei Heidi richtet den Zugang für Ihre Verwaltung oder Ihr Softwareunternehmen ein.

2. 2
   Zugangsdaten erhalten

   Sie erhalten Benutzername und Passwort sowie die Zuordnung Ihrer Liegenschaften zu Heidi-Abrechnungsnummern.

3. 3
   Ersten Abruf senden

   Fragen Sie die verfügbaren Abrechnungszeiträume einer Liegenschaft ab.

curl https://api.heidisystems.example/bved/consumptions/v1/billingunits/123456789/consumptions/periods \
  -u "BENUTZER:PASSWORT" \
  -H "accept: application/json"

Authentifizierung

Alle Anfragen laufen ausschließlich verschlüsselt über HTTPS. Die bved-Webservices sehen Basic Auth und OAuth 2.0 vor. Jede Anfrage enthält einen Authorization-Header und accept: application/json.

Basis-URL und Versionen

Die Hauptversion steht im Pfad. Kleinere, abwärtskompatible Erweiterungen der Spezifikation ändern den Pfad nicht.

https://api.heidisystems.example/bved/consumptions/v1

• Format: JSON, Zeichensatz UTF-8
• Zeitstempel: ISO 8601 in UTC, z. B. 2022-05-09T09:04:55.772Z
• Abrechnungszeitraum: YYYY-MM, z. B. 2021-06

Liefert monatliche Verbrauchsdaten auf Ebene der Nutzeinheit. Damit stellen Sie Bewohnern die unterjährige Verbrauchsinformation nach EED und HKVO in Ihrem eigenen Portal bereit. Der Webservice ging aus der ARGE HeiWaKo hervor und wird heute vom bved gepflegt.

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

Übermittelt Nutzer- und Bewohnerwechsel tagesaktuell aus Ihrer Software an Heidi. Das ist nötig, damit die unterjährige Verbrauchsinformation den richtigen Bewohnern zugeordnet wird und Zwischenablesungen korrekt in die Abrechnung einfließen.

Für neue Anbindungen empfiehlt der bved Version 2.0. Version 1.2 bleibt für bestehende Integrationen gültig. Endpunkte und Feldschema folgen in der finalen Fassung.

Automatisiert das Hoch- und Herunterladen von Dokumenten zwischen Ihrer Software und Heidi, zum Beispiel Heizkostenabrechnungen. Mit Version 1.3 arbeitet der Webservice nur noch mit JSON.

• Endpunkt setStatus, um den Empfang vieler Dokumente auf einmal zu bestätigen
• Neuer Dokumenttyp P und optionaler Info-Block
• Referenztyp order für Bestellnummern

Endpunkte und Feldschema folgen in der finalen Fassung.

Für Software, die noch keine Webservices nutzt, unterstützt Heidi den dateibasierten bved-Standard-Datenaustausch für die Heizkostenabrechnung. Angaben zum CO2-Kostenaufteilungsgesetz sind ab Version 3.10 enthalten.

Der E-Satz für den Volldatenaustausch wird vom bved nicht weiterentwickelt. Für neue Anbindungen empfehlen wir die Webservices.

Statuscodes

Antworten sind entweder leer oder ein JSON-Objekt.

Versionen

Grundlage: bved-Spezifikationen (öffnet in neuem Tab)