Öffentliche Vermarkterdaten

Hier sind die Funktionen zur Ablage und Abruf der Vermarkterdaten mit connect beschrieben. Auf die Vermarkterdaten haben alle Teilnehmer des connect centers uneingeschränkten Zugriff.

Auflistung

getPublicDocumentsList

Gibt eine Auflistung der im connect eingestellten öffentlichen Vermarkterdaten zurück.

Aufruf http://127.0.0.1:8888/api/getPublicDocumentsList
Methoden GET
Rückgabe XML-Liste der Stammdatendokumente (encoding: utf-8)
Parameter  
type Stammdatentyp: “placements” für Inventare (siehe getPlacements), “pricelist” für Preislisten (siehe getPriceLists) oder “advertisement” für Werbeformen (siehe getAdvertisements).. Parameter ist optional. Keine Angabe gibt alle Dokumente zurück.
lastChanged Angabe eines Datumsbereiches (von-bis im Format “JJJJ-MM-DD, JJJJ-MM-DD”). Das erste Datum definiert den Beginn des Bereichs, das Zweite (optionale) das Ende. Der Parameter ist optional. Beispiele: “2014-01-01”, “2014-01-01, 2014-02-01”. Neben dem axakten Datumsformat ist auch “TODAY” als Datumsangabe möglich. Bei diesem Format können beim Bereichsende zur Zahlen angegeben werden. Beispiele: “TODAY” => alles von heute, “TODAY,-1” => alles seid gestern, “TODAY,-2” => alles seid vorgestern

Mögliche Fehlerrückgaben

Code Infotext Erläuterung
401 ... Bei einem Authentifizierungsproblem sind grundsätzlich die unter Authentifizierung aufgeführten Antworten möglich.

Beispiel

<?xml version="1.0" encoding="UTF-8"?><Documents>
  <Document id="2" date="2013-01-21 16:46:09.0">
    <User>
      <ovkparticipantid>2_NOOVK</ovkparticipantid>
      <name>Vermarkter 1</name>
      <type>publisher</type>
    </User>
    <Attributes>
      <Attribute key="type" value="pricelist"/>
    </Attributes>
  </Document>
  <Document id="3" date="2013-01-21 16:46:09.0">
    <User>
      <ovkparticipantid>2_NOOVK</ovkparticipantid>
      <name>Vermarkter 1</name>
      <type>publisher</type>
    </User>
    <Attributes>
      <Attribute key="type" value="advertisement"/>
    </Attributes>
  </Document>
  <Document id="5" date="2013-02-12 11:35:57.0">
    <User>
      <ovkparticipantid>100001</ovkparticipantid>
      <name>AGOF_Vermarkter</name>
...

Zugehöriges XSD-Schema: publicDocumentsList.xsd.

Elemente von “Document”
Element Attribut Bedeutung
  id Eindeutige ID im connect System.
  date Zeitpunkt zu dem das Dokument eingestellt wurde im YYY-MM-DD HH:MM:SS Format
User ovkparticipantid ID des Users in connect. Diese ID entspricht der OVKParticipantsID.
  name Name des connect users
  type Der Typ des Users. Es gibt die Typen “publisher” (= Vermarkter) und “user” ( = Alle anderen User wie z.B. Agenturen)
Attributes type Stammdatentyp: “placements” für Inventare (siehe getPlacements), “pricelist” für Preislisten (siehe getPriceLists) oder “advertisement” für Werbeformen (siehe getAdvertisements).

Sender

setPlacements

Dient zur Ablage des Inventars eines Vermarkters für den allgemeinen Zugriff. Ein evtl. bereits vorhandenes Inventar des Vermarkters wird überschrieben.

Aufruf http://127.0.0.1:8888/api/setPlacements
Methoden POST (multipart/form-data encoded)
Rückgabe ConnectResponse mit InfoText “received” wenn Empfang abgeschlossen werden konnte.
Parameter  
file Die Placements-XML Datei (multipart/form-data encoded). Die Dateigröße darf 256 Megabyte nicht überschreiten.

Mögliche Fehlerrückgaben

Code Infotext Erläuterung
400 missing params Parameter file wurde nicht übergeben.
401 ... Bei einem Authentifizierungsproblem sind grundsätzlich die unter Authentifizierung aufgeführten Antworten möglich.
432 siehe Validierung der Inhalte Probleme bei der Validierung der Inhalte

Beispiel

Beispieldatei placements.xml (Ausschnitt):

<placements xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="https://connectcenterqs01.agof.de/xsd/placements/v1.4.2/Placements.xsd" version="2014-06-26" ovkparticipantsenderid="1111">
  <placement VID="22914221" validfrom="2014-01-01">
    <media VID="1007">
      <name>IP-Netzwerk</name>
    </media>
    <name>IP Kochen-Kombi 2014</name>
    <description>Kochen-Kombi</description>
   <availableadvertisement>
      <advertisement VID="57683" compoundadvertisement="false">
        <name>Post-Roll 20 Sek.</name>
      </advertisement>
    </availableadvertisement>   
...
Rückgabe
<ConnectResponse status="0">
	<InfoText>received</InfoText>
</ConnectResponse>

setPriceLists

Dient zur Ablage der Preislisten eines Vermarkters für den allgemeinen Zugriff. Eine evtl. bereits vorhandene Preisliste des Vermarkters wird überschrieben.

Aufruf http://127.0.0.1:8888/api/setPriceLists/
Methoden POST
Rückgabe ConnectResponse mit InfoText “received” wenn Empfang abgeschlossen werden konnte.
Parameter  
file Inhalt der Preislisten-XML Datei (multipart/form-data encoded). Die Dateigröße darf 256 Megabyte nicht überschreiten.

Mögliche Fehlerrückgaben

Code Infotext Erläuterung
400 missing params Parameter file wurde nicht übergeben.
401 ... Bei einem Authentifizierungsproblem sind grundsätzlich die unter Authentifizierung aufgeführten Antworten möglich.
432 siehe Validierung der Inhalte Probleme bei der Validierung der Inhalte

Beispiel

Beispieldatei pricelist.xml (Ausschnitt):

<pricelists xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="https://connectcenterqs01.agof.de/xsd/pricelist/v1.4.2/Pricelist.xsd" ovkparticipantsenderid="1111" >
  <pricelist issued="2014-06-26" VID="2070" currency="EUR" version="1" validfrom="2013-01-01" validto="2014-12-31">
    <name>Frauenzimmer Newsletter</name>
    <priceentry VID="53309">
      <placement VID="22914221" validfrom="2014-01-01">
        <media VID="1007">
          <name>IP-Netzwerk</name>
        </media>
        <name>IP Kochen-Kombi 2014</name>
        <description>Kochen-Kombi</description>
      </placement>
      <advertisement VID="57683" compoundadvertisement="false">
...
Rückgabe
<ConnectResponse status="0">
	<InfoText>received</InfoText>
</ConnectResponse>

setAdvertisements

Dient zur Ablage der Werbeformen eines Vermarkters für den allgemeinen Zugriff. Evtl. bereits vorhandene Werbeformen des Vermarkters werden überschrieben.

Aufruf http://127.0.0.1:8888/api/setAdvertisements
Methoden POST
Rückgabe ConnectResponse mit InfoText “received” wenn Empfang abgeschlossen werden konnte.
Parameter  
file Inhalt der Werbeformen-XML Datei (multipart/form-data encoded). Die Dateigröße darf 256 Megabyte nicht überschreiten.

Mögliche Fehlerrückgaben

Code Infotext Erläuterung
400 missing params Parameter file wurde nicht übergeben.
401 ... Bei einem Authentifizierungsproblem sind grundsätzlich die unter Authentifizierung aufgeführten Antworten möglich.
432 siehe Validierung der Inhalte Probleme bei der Validierung der Inhalte

Beispiel

Beispieldatei advertisements.xml (Ausschnitt):

<advertisements xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="https://connectcenterqs01.agof.de/xsd/advertisement/v1.4.2/Advertisement.xsd" ovkparticipantsenderid="1111">
  <advertisement VID="57653" compoundadvertisement="false">
    <name>Pre-Roll 20 Sek.</name>
    <advertisementtype VID="1011">
      <name>In-Stream</name>
    </advertisementtype>
     <delivery>
      <destination>banner@ip-deutschland.de</destination>
      <timeframe>5</timeframe>
      <timeframeunit>businessday</timeframeunit>
    </delivery>
  </advertisement>
...
Rückgabe
<ConnectResponse status="0">
	<InfoText>received</InfoText>
</ConnectResponse>

Validierung der Inhalte

Bei den oben aufgeführten set... Befehlen wird eine automatische Validierung durchgeführt:

  1. Prüfung, ob der Sender in der XML die eigene ID ist (OVK ParticipantID identisch mit den Attribute ovkparticipantsenderid)

Hierbei sind folgende Fehlerszenarien denkbar:

Bedingung Verhalten
Inhalt ist kein valides XML keine Validierung möglich, Versand erfolgt
Inhalt ist XML, XSD wird gefunden, Validierung klappt => Absender.VID ist nicht die eigene ID kein Versand

Fehlermeldungen

Im Rahmen der Validerungen werden unterschiedliche Fehlermeldungen entweder in die Logdatei des connect kits oder im Response ausgegeben.

Meldung Ausgabe Response Code
“Ausgehendes XML konnte nicht geparsed werden” Logdatei 200
“Ausgehendes XML enthält keine OVK Absender Id (ovkparticipantsenderid)” Logdatei 200
“Absender ID im XML stimmt nicht mit Ihrer ID überein” Response 432

Empfänger

getPlacements

Dient zum Abruf der Inventories der Vermarkter.

Aufruf http://127.0.0.1:8888/api/getPlacements/
Methoden GET
Rückgabe Inventory des abgefragen Vermarkters als XML.
Parameter  
publisher ID des Vermarkters in connect (ID kann über getOVKParticipants bestimmt werden)

Mögliche Fehlerrückgaben

Code Infotext Erläuterung
401 ... Bei einem Authentifizierungsproblem sind grundsätzlich die unter Authentifizierung aufgeführten Antworten möglich.

Beispiel

<placements xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="https://connectcenterqs01.agof.de/xsd/placements/v1.4.2/Placements.xsd" version="2014-06-26" ovkparticipantsenderid="1111">
  <placement VID="22914221" validfrom="2014-01-01">
    <media VID="1007">
      <name>IP-Netzwerk</name>
    </media>
    <name>IP Kochen-Kombi 2014</name>
    <description>Kochen-Kombi</description>
   <availableadvertisement>
      <advertisement VID="57683" compoundadvertisement="false">
        <name>Post-Roll 20 Sek.</name>
      </advertisement>
    </availableadvertisement>   
...

getPriceLists

Dient zum Abruf der Preislisten der Vermarkter.

Aufruf http://127.0.0.1:8888/api/getPriceLists
Methoden GET
Rückgabe Preislisten des abgefragen Vermarkters als XML.
Parameter  
publisher ID des Vermarkters in connect (ID kann über getOVKParticipants bestimmt werden)

Mögliche Fehlerrückgaben

Code Infotext Erläuterung
401 ... Bei einem Authentifizierungsproblem sind grundsätzlich die unter Authentifizierung aufgeführten Antworten möglich.

Beispiel

<pricelists xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="https://connectcenterqs01.agof.de/xsd/pricelist/v1.4.2/Pricelist.xsd" ovkparticipantsenderid="1111" >
  <pricelist issued="2014-06-26" VID="2070" currency="EUR" version="1" validfrom="2013-01-01" validto="2014-12-31">
    <name>Frauenzimmer Newsletter</name>
    <priceentry VID="53309">
      <placement VID="22914221" validfrom="2014-01-01">
        <media VID="1007">
          <name>IP-Netzwerk</name>
        </media>
        <name>IP Kochen-Kombi 2014</name>
        <description>Kochen-Kombi</description>
      </placement>
      <advertisement VID="57683" compoundadvertisement="false">
...

getAdvertisements

Dient zum Abruf der Werbeformen der Vermarkter.

Aufruf http://127.0.0.1:8888/api/getAdvertisements
Methoden GET
Rückgabe Werbformen des abgefragen Vermarkters als XML.
Parameter  
publisher ID des Vermarkters in connect (ID kann über getOVKParticipants bestimmt werden)

Mögliche Fehlerrückgaben

Code Infotext Erläuterung
401 ... Bei einem Authentifizierungsproblem sind grundsätzlich die unter Authentifizierung aufgeführten Antworten möglich.

Beispiel

<advertisements xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="https://connectcenterqs01.agof.de/xsd/advertisement/v1.4.2/Advertisement.xsd" ovkparticipantsenderid="1111">
  <advertisement VID="57653" compoundadvertisement="false">
    <name>Pre-Roll 20 Sek.</name>
    <advertisementtype VID="1011">
      <name>In-Stream</name>
    </advertisementtype>
     <delivery>
      <destination>banner@ip-deutschland.de</destination>
      <timeframe>5</timeframe>
      <timeframeunit>businessday</timeframeunit>
    </delivery>
  </advertisement>
...