Generell sind Schreibzugriffe nur explizit authorisierten Clients bzw. Usern möglich. Je nach Anforderung werden pro Client Berechtigungen zum Aktualisieren bzw. Hinzufügen von Daten beim msw hinterlegt. Diese Berechtigungen können für einen kompletten Sender oder nur bestimmte Teilbereiche vergeben werden.

Um alle Sender abzurufen, für die erweiterte Berechtigungen hinterlegt wurden, kann der Endpunkt /v5/Sender/Zugeordnet verwendet werden.

Sind für die über diesen Endpunkt zurückgelieferten Sender klientenspezifische ( aus Sicht der Audio-PPD also "externe" ) Ids von Interesse, können diese iterativ über den Endpunkt /v5/Sender/{senderId} ermittelt werden. Die dabei referenzierten Typen ( Ids zwischen 7000 und 7099 ) lassen sich über die allgemeinen Typen auflösen.

WICHTIG: Hieraus ergibt sich, dass Daten grundsätzlich nur für bereits eingerichtete Sender(-jahrespakete) hochgeladen werden können.
Die Vergabe von Sender- und Vermarkter-Ids erfolgt ausschließlich durch den msw. Das gilt auch auch für das Einrichten der Tarifgenerationen, also der Jahrespakte pro Sender bzw. Vermarkter.

Derzeit können pro Client eine oder auch mehrere Vermarkter Ids hinterlegt werden. Daneben werden den entsprechenden Clients alle erforderlichen Sender Ids zugeordnet, für die Schreibberechtigungen bestehen sollen. Hierbei kann noch differenziert werden, ob die Berechtigungen zum Aktualisieren / Hinzufügen oder Löschen für alle oder nur vermarkterspezifische Daten gelten sollen.

Wurde also bspw. einem bestimmten Client die Vermarkter Id = 600111 und die Sender Id = 802730 zugeordnet und als Berechtigungssatz "vermarkterspezifisch" festgelegt, kann der Client über die API lediglich diejenigen Daten bearbeiten, die in der folgenden Abbildung innerhalb des grün markierten Blocks zu sehen sind:

Für Third-Party Clients sind die Endpunkte der Versionen 5.* vorgesehen.

Es werden hier nur einige wenige Endpunkte bereitgestellt, die im Wesentlichen das Aktualisieren der kompletten Daten für ein gegebenes Kalenderjahr eines Senders ermöglichen. Je nach erteilter Berechtigung gegebenenfalls auf bestimmte Vermarkter Ids beschränkt.
Um beim oben erwähnten Beispiel zu bleiben, könnte der Client per PUT /v5/Sender/802730/2021 die kompletten Datenblöcke wie in der Abbildung gezeigt an die API senden, jedoch würden nur diejenigen Zeitraum-Datensätze berücksichtigt, die mit der VermarkterId = 600111 gekennzeichnet sind.

Als Alternative zu strukturierten Daten für die Anlieferung werden zusätzlich "flache Listen" für einzelne Kategorien wie Preise, Rabattstaffeln, Zuschläge angeboten, die per Json oder Exceldatei hochgeladen werden können.
Eine weitergehende Beschreibung der jeweiligen Listen mit Beispielen kann hier heruntergeladen werden.

Eine Aufstellung aller verwendeten Typen-Ids, Werbeformen usw. kann über die API bezogen werden. Zur Vereinfachung kann aber auch eine Exceldatei heruntergeladen werden..

Der generelle Ablauf beim Hochladen struktierter Daten für ein externes Tool wäre demnach:

• Die zum gewünschten Sender und dem jeweils zu bearbeitenden Jahrespaket gehörenden Daten über die Endpunkt
  /v5/Sender/{id}/{jahr}/Aktuell ( struktierierte, hierarchisch aufgebaute Daten ) herunterladen
• Die erforderlichen Änderungen durchführen
  ( also Hinzufügen / Aktualisieren / Löschen von Datensätzen innerhalb des erhaltenen Objektbaums )
• ( optional ) Den geänderten Objektbaum per HTTP-POST an den Endpunkt /v5/Sender/Validieren hochladen
• Den erfolgreich validierten Objektbaum per HTTP-PUT an den Endpunkt /v5/Sender/{id}/{jahr} senden
• Und schließlich bei Bedarf die neuen bzw. geänderten Daten über den Endpunkt /v5/Sender/{id}/JahresPaketVeroeffentlichen für den allgemeinen (Lese-)Zugriff freischalten.

Bei dem Weg über die flachen Listen wäre der Ablauf in etwa so:

• Die gewünschten Daten aus dem eigenen System in die vereinfachten Listen überführen.
• Diese Listen als Json-Objekt an den Endpunkt /v5/Sender/{id}/{jahr}/DenormalisierteDaten oder alternativ
• diese Listen in eine Exceldatei übernehmen und an den Endpunkt /v5/Sender/{id}/{jahr}/ExcelDateiUpload senden.
• Optional die Rückgabe der übernommenen Daten aus der Anwort von der API mit den gewünschten Daten vergleichen.
• Und schließlich auch hier bei Bedarf die neuen bzw. geänderten Daten über den Endpunkt /v5/Sender/{id}/JahresPaketVeroeffentlichen für den allgemeinen (Lese-)Zugriff freischalten.

Während des expliziten Freischaltens wird von der API im Hintergrund ein Snapshot der zu diesem Zeitpunkt aktuellen Daten angelegt.
Nachfolgende Änderungen für den dann öffentlich zugänglichen Datensatz durch erfolgreichen Upload eines geänderten Jahrespaketes führen ebenfalls zur automatischen Anlage eines Snapshots.

Allerdings kann es pro Kalendertag nur genau einen Snapshot geben. Das bedeutet, auch mehrfache Änderungen pro Tag erzeugen nur beim ersten Hochladen einen solchen Snapshot, der dann die Daten des Vortages enthält.