Neue Spezifikationen
Neue Spezifikationen
Hier finden Sie die neuen Spezifikationen für den Datenaustausch. Diese sorgen künftig für mehr Einheitlichkeit, Kontrolle und effizientere Prozesse. Bei Fragen können Sie jederzeit Kontakt mit uns aufnehmen.
Hier können Sie den aktuellen Stand der Servicespezifikation als OpenAPI yaml-Dateien herunterladen.
Zu jeder Schnittstelle steht zusätzlich ein ERP-Implementierungsleitfaden als PDF bereit. Die Leitfäden erläutern die Schnittstellen aus Sicht der ERP-Anbieter (Abläufe, Statusmodelle, Feldbelegung, Fehlerbehandlung). Grundlage ist jeweils die zugehörige OpenAPI-Spezifikation. Die Leitfäden wurden mit Hilfe von KI erstellt.
Stand: Oktober 2026 – aktuelle Versionen: Billing Unit Data 1.0.3, On-Site-Roles 2.0.3, Billing Input 1.1.0, Billing Result 1.0.3
Änderungen zur Vorversion für alle Schnittstellen:
- Einheitliche URLs
- billingunitdata/v1/…
- billinginput/v1/…
- billingresult/v1/…
- onsiteroles/v2/…
- Header X-API-VERSION in allen Antworten ergänzt
- Einheitliche Antwort-Strukturen, um den Header zu ergänzen
- Behebung von Inkonsistenzen und Fehlern bei Dokumentation und Pflichtfeldern
- Einheitliche Bezeichnungen für Warmwasser / Hot Water
- OAuth Flow wurde in Version x.0.2 auf Client Credentials Flow angepasst
Billing Unit Data
Ablösung des Ordnungsbegriff-Tauschs für Abrechnungs- und Nutzeinheiten über PDF-/Excel-Dateien
- ERP sendet Liste der Nutzeinheiten mit eigenen Ordnungsbegriffen, Namen, Flächen etc.
- Messdienstleister ordnet die Daten zu und stellt eigene Ordnungsbegriffe bereit
- Asynchron, da ggf. manueller Prozess notwendig
- Ersetzt den A-Satz Austausch
Änderungen zur Vorversion:
v1.0.3
- POST Setup: Antwort 409 ergänzt (ein weiteres Setup wird beim Messdienstleister gerade verarbeitet)
- Status OPEN: gilt auch, wenn der Messdienstleister eine bereits zugeordnete Abrechnungseinheit für einen erneuten Abgleich wieder geöffnet hat
v1.0.2
- Service-Pfad-Präfix ergänzt: /billingunitdata/v1/
- X-API-VERSION Response-Header an allen Endpunkten
- Vereinheitlichte Fehler-Antworten via gemeinsame Definitionen
- Positionsfeld (position): maximale Länge von 10 auf 20 Zeichen erhöht
v1.0.1
- Korrektur: Werttyp des Beispiels für das Positionsfeld
v1.0
- Erstveröffentlichung
On-Site-Roles 2
Neue Version mit vereinfachtem Datenmodell
- ERP sendet aktuelle Daten, Messdienstleister erkennt und verarbeitet Änderungen im Hintergrund
- Plausibilisierung beim Messdienstleister immer sofort mit direkter Rückmeldung
- Keine Insert/Update/Delete-Aktionen und keine Status-Abfrage mehr notwendig
- Abruf der zuletzt erfolgreich gesendeten Daten möglich
Änderungen zur Vorversion:
v2.0.3
- Rollen für verschiedene Dienstleistungen müssen getrennt gesendet werden (bisher: Empfehlung)
- POST On-Site-Roles: Antwort 403 liefert einen Validierungs-Body
v2.0.2
- Service-Pfad-Präfix ergänzt: /onsiteroles/v2/
- X-API-VERSION Response-Header an allen Endpunkten
- Vereinheitlichte Fehler-Antworten via gemeinsame Definitionen
- 404-Response für PUT-Endpunkt ergänzt
- Verarbeitung nicht mehr gesendeter Rollen: Klarstellung, dass das Verhalten vom MSC abhängt (Fehler, Beenden oder Löschen möglich)
- Abrechnungsempfänger: Übermittlung muss lückenlos und überschneidungsfrei sein; für nicht vermietete Zeiträume wird ein Partner mit Leerstandskennzeichen erwartet
- Empfehlung: Rollen für verschiedene Dienstleistungen sollen getrennt gesendet werden
- Beendigungsdatum ist Pflichtfeld, wenn terminateallbillingcontracts bzw. terminateallconsumptioninformationcontracts auf true gesetzt wird
v2.0
- Erstveröffentlichung der v2-API (ersetzt arge-spec-on-site-roles 1.x)
- Separate optionale Rollen für Abrechnungsempfänger (billingcontracts) und Verbrauchsinformationsempfänger (consumptioninformationcontracts)
- Beende-alle-Flags für Abrechnungs- und Verbrauchsinformationsverträge
- Eigentümer-Kennzeichen
- OAuth 2 Sicherheit
Billing Input
- API zur Beauftragung der Abrechnung (Ablösung B/K-Sätze und L/M-Sätze, sofern nicht in On-Site-Roles enthalten).
Messdienstleister stellt für jeden AZ „Schablone“ mit voreingestellten Daten bereit.
ERP füllt die Schablone mit Rechnungen, Verteilwerten etc. aus und sendet sie an den Messdienstleister.
Plausibilisierung beim Messdienstleister immer sofort mit direkter Rückmeldung. Test-Plausibilisierung beliebig oft möglich. Nach Senden mit erfolgreicher Plausibilisierung gilt der Abrechnungszeitraum für die Abrechnung als beauftragt.
Achtung: v1.1.0 enthält inkompatible Änderungen (Umbenennung energyefficiencyratio, Pflichtfeld Art des Lagerbestands). Bestehende Implementierungen müssen angepasst werden. Der Service-Pfad /billinginput/v1/ bleibt unverändert.
Änderungen zur Vorversion:
v1.1.0
- energyefficiencyratio ersetzt durch performancefactor (Jahresarbeitszahl / Nutzungsfaktor); neues Feld totalheatoutput (Wärmemenge Wärmepumpe)
- Art des Lagerbestands (type) ist nun Pflichtfeld
- Schablone: Abrechnungsempfänger um riskallocation, vatdisplay, allocatebillingrecipientchangefee und exceptedcosts ergänzt
- CO2-Emissionsmenge: negative Werte möglich (Korrekturbuchungen)
- CO2-Energiemix: leere Liste erlaubt
- Filter OPEN für Abrechnungszeiträume umfasst auch den Status READY
- Beschreibungen und Beispiele zu validfrom / validto korrigiert
- Einheit TNE (Tonne) ergänzt
- Kostenschlüssel-Dokument: Mapping alt → neu korrigiert
v1.0.3
- allocationkey ist nun Pflichtfeld bei Kostenzuordnungen
- amounts ist nun Pflichtfeld bei Rechnungen (Energieträger, Heiznebenkosten, Nebenkosten)
- Kostenschlüssel-Gruppe V05 eingeführt
- Gesamtemissionsfaktor CO2 (factor) auf Abrechnungseinheitsebene ist kein Pflichtfeld mehr
v1.0.2
- Service-Pfad-Präfix ergänzt: /billinginput/v1/
- X-API-VERSION Response-Header an allen Endpunkten
- Vereinheitlichte Fehler-Antworten via gemeinsame Definitionen
- Doku: Verarbeitungslogik für beendete Partner ergänzt
v1.0.1
- Einheitliche Benennung des Feldes "text" (statt "customtext")
- Einheitliche Benennung der Liste "allocations" (statt "allocation")
- Einheitliche Benennung des Feldes "cost" (statt "costkey")
- Einheitliche Benennung des Feldes "invoicedate" (statt "date" oder "invoiceDate")
- Einheitliche Benennung des Feldes "vatdisplay" (statt "vatDisplay")
- Änderung der Feldlänge für Kostenbezeichnungen von 19 auf 25 Zeichen
- Gültigkeitszeitraum für Nutzer-Verteilschlüssel ergänzt
- Gemeinsame Vorauszahlung Heizung und Warmwasser ergänzt
- Lagerbestände im Template ergänzt
- Neue Struktur für Fehlermeldungen, die jetzt den gesendeten Objekten zugeordnet werden
- Enum-Konstante ergänzt für kein MwSt.-Ausweis
- Negative Rechnungsbeträge für Lagerbestände und Gutschriften möglich
- Lagerbestände haben eine Einheit und sind CO2-bewertet
- Neue Fehler-Struktur für detaillierte Rückgabe von Fehlermeldungen
Billing Result
Messdienstleister stellt Liste der Abrechnungszeiträume pro Liegenschaft bereit, für die Abrechnungsergebnisse vorliegen.
Pro Abrechnungseinheit und Abrechnungszeitraum werden nutzerbezogen Abrechnungsergebnisse bereitgestellt.
Änderungen zur Vorversion:
v1.0.3
- Aufnahme von updated in Liste der verfügbaren Abrechnungseinheiten, um die Aktualität der Abrechnung zu kennzeichnen
v1.0.2
- Service-Pfad-Präfix ergänzt: /billingresult/v1/
- X-API-VERSION Response-Header an allen Endpunkten
- Vereinheitlichte Fehler-Antworten via gemeinsame Definitionen
v1.0.1
- Struktur des Results für getBillingPeriods an die äquivalente Funktion des billing-input angepasst
- Strukturen von Elementen in billingbalances (totalcosts, balances, budgetpayments) an amounts-Struktur entsprechend billing-input angepasst
- costpositionspar35a umbenannt zu wagecosts
- amounts in CO2-Kosten entsprechend billing-input angepasst
- vatMode in billingbalance entfällt