

 BVED on-site-roles API 2.0 
 ==========================
  
    Allgemeine Informationen
    ------------------------

    Diese Schnittstelle dient dem fortlaufenden Austausch von Partnern und ihren Rollen zwischen Hausverwaltungen
    (Property Manager, PM) und Messdienstleistern (Measuring Service Company, MSC).
	
	Weitere Details können der openapi Spezifikation bved-on-site-roles-*.openapi.yaml entnommen werden.
	

    Datenmodell
    -----------

    Jede Anfrage wird pro Nutzeinheit gesendet und kann enthalten:

    * Liste der Partner (verpflichtend): natürliche oder juristische Personen, die "On-Site"-Rollen in Bezug auf eine
      Nutzeinheit einnehmen. Partner haben einen eindeutigen Schlüssel `pmnumber`, der vom ERP-System des Kunden vergeben wird.
    * Abrechnungsempfänger (optional): Verträge für die Heiz- und Nebenkostenabrechnung
    * Empfänger von Verbrauchsinformationen (optional): Verträge für Verbrauchsinformationen z.B. im Kontext EED

     Rollen für verschiedene Dienstleistungen sollen unabhängig voneinander gesendet werden,
     um gezielte Fehlerbehandlung zu ermöglichen.
     Im Fall Von Abrechnungsempfängern (billingcontracts): Die Übermittelung der Abrechnungsempfänger muss lückenlos
     und überschneidungsfrei erfolgen, d.h. Für nicht vermietete Zeiträume wird ein Partner mit Leerstandskennzeichen erwartet.

     Datenverarbeitung
        -----------------

     Die Daten in einer Datenlieferung sind jeweils die vollständigen Daten für eine Nutzeinheit. Das bedeutet:

     * Bislang beim MSC nicht bekannte Rollen werden ergänzt
     * Vorhandene Rollen werden aktualisiert
     * Nicht mehr gesendete Rollen werden abhängig vom Messdienstleister verarbeitet:
          * Der Messdienstleister kann in dem Fall eine Fehlermeldung zurückgeben
          * Der Messdienstleister kann sie zum aktuellen Datum beenden bzw. -- wenn das Beginn-Datum in der Zukunft
            liegt -- komplett löschen
        * Historische Daten (d.h., bereits in der Vergangenheit beendet und nicht mehr mitgesendet) bleiben unverändert

     Werden in einer Anfrage keine Daten für eine der Dienstleistungen gesendet, geschieht Folgendes:

     * Im Standardfall bleiben die beim Messdienstleister gespeicherten Daten unverändert
     * Es werden alle Rollen beendet, wenn ein entsprechendes Kennzeichen gesetzt ist
       (`terminateallbillingcontracts` bzw. `terminateallconsumptioninformationcontracts` auf `true`)

    Datenmodell und Prüfungen
    -------------------------

    Die empfangenen Daten werden beim Messdienstleister sofort validiert und Fehlermeldungen werden zurückgegeben.
    Die Meldungen sind individuell für jeden MSC. Insbesondere sind aber folgende Prüfungen relevant:

    * Die Nummer der Abrechnungseinheit hat ein ungültiges Format, die Abrechnungseinheit existiert nicht
      oder der Datenaustausch ist nicht eingerichtet
    * Die Nutzeinheit existiert nicht oder ist nicht für Datenaustausch geeignet
    * Ein Partner, der in einer Rolle referenziert wird, fehlt in der Datenlieferung
    * Abrechnungs- oder uVI-Empfänger werden in dieser API für die Abrechnungseinheit nicht erwartet
    * Im Fall von uVI-Empfängern: Die Abrechnungseinheit ist nicht für uVI eingerichtet oder die Rollen werden
      nicht auf diesem Eingangskanal erwartet
    * Zeiträume in einem Vertrag sind nicht gültig, z.B. Einzugsdatum vor Auszugsdatum
    * Der Name eines Partners ist nicht gültig, z.B. nur Leerzeichen
    * Der Länderschlüssel ist ungültig, d.h. entspricht nicht ISO 3166-1 alpha-3


    Sicherheit
    ----------

    Die Schnittstelle ist mit OAuth 2 -Verfahren gesichert. 
	Die Endpunkte sind bein jeweiligen MSC zu erfragen.
    Die Datenübertragung muss über einen sicheren Kanal erfolgen (HTTPS/SSL).
