Angebotsdaten¶

Hier sind die Funktionen zum Versand und Empfang von Angeboten zwischen Vermarktern und Agenturen beschrieben. Auf die Angebotsdaten haben nur bestimmte Teilnehmer des connect centers Zugriff.

Sender¶

sendBusinessTransaction¶

Verschickt ein Angebot.

Es findet von connect aus keinerlei weitere Verarbeitung der verschickten Datei statt. Das connect speichert lediglich den Inhalt der Datei. Somit ist es z.B. auch möglich die Datei komprimiert oder verschlüsselt zu übergeben.

Aufruf	http://127.0.0.1:8888/api/sendBusinessTransaction
Methoden	POST (multipart/form-data encoded)
Rückgabe	ConnectResponse mit InfoText und der TransactionsID im Attribut

Parameter
receiver	Empfänger, ID des Teilnehmers in connect (ID kann über getOVKParticipants bestimmt werden)
file	Inhalt der Angebots-XML Datei (multipart/form-data encoded). Die Dateigröße darf 256 Megabyte nicht überschreiten.
attr_XXX	Eine beliebige Anzahl von Attributen (key/value pairs) um das Angebot mit Metainformationen anzureichern. Diese haben das Prefix attr_ gefolgt vom Attributname (z.B. attr_codeinternal)

Mögliche Fehlerrückgaben¶

Code	Infotext	Erläuterung
400	missing params	Parameter file wurde nicht übergeben
409	unknown receiver	Der angegebene Empfänger ist connect nicht bekannt.
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¶

<ConnectResponse status="0" transactionID="2-479">
	<InfoText>BusinessTransaction for Vermarkter 2 received</InfoText>
</ConnectResponse>

sendPlacements¶

Verschickt ein Inventar an eine bestimmte Agentur.

Aufruf	http://127.0.0.1:8888/api/sendPlacements/
Methoden	POST (multipart/form-data encoded)
Rückgabe	ConnectResponse mit InfoText und der TransactionsID im Attribut

Parameter
receiver	Empfänger, ID der Agentur in connect (ID kann über getOVKParticipants bestimmt werden)
file	Inhalt der Inventory-XML Datei (multipart/form-data encoded). Die Dateigröße darf 256 Megabyte nicht überschreiten.
attr_XXX	Eine beliebige Anzahl von Attributen (key/value pairs) um das Inventory mit Metainformationen anzureichern. Diese haben das Prefix attr_ gefolgt vom Attributname (z.B. attr_codeinternal)

Mögliche Fehlerrückgaben¶

Code	Infotext	Erläuterung
400	missing params	Parameter file wurde nicht übergeben
409	unknown receiver	Der angegebene Empfänger ist connect nicht bekannt.
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¶

<ConnectResponse status="0" transactionID="317">
	<InfoText>Inventory for Agentur 1 received</InfoText>
</ConnectResponse>

sendPriceLists¶

Verschickt eine Preisliste an eine bestimmte Agentur.

Aufruf	http://127.0.0.1:8888/api/sendPriceLists
Methoden	POST (multipart/form-data encoded)
Rückgabe	ConnectResponse mit InfoText und der TransactionsID im Attribut

Parameter
receiver	Empfänger, ID der Agentur in connect (ID kann über getOVKParticipants bestimmt werden)
file	Inhalt der Preislisten-XML Datei (multipart/form-data encoded). Die Dateigröße darf 256 Megabyte nicht überschreiten.
attr_XXX	Eine beliebige Anzahl von Attributen (key/value pairs) um die Preisliste mit Metainformationen anzureichern. Diese haben das Prefix attr_ gefolgt vom Attributname (z.B. attr_codeinternal)

Mögliche Fehlerrückgaben¶

Code	Infotext	Erläuterung
400	missing params	Parameter file wurde nicht übergeben
409	unknown receiver	Der angegebene Empfänger ist connect nicht bekannt.
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¶

<ConnectResponse status="0" transactionID="318">
	<InfoText>PriceLists for Agentur 1 received</InfoText>
</ConnectResponse>

sendAdvertisements¶

Verschickt die Werbeformen eines Vermarkters an eine bestimmte Agentur.

Aufruf	http://127.0.0.1:8888/api/sendAdvertisements
Methoden	POST (multipart/form-data encoded)
Rückgabe	ConnectResponse mit InfoText und der TransactionsID im Attribut

Parameter
receiver	Empfänger, ID der Agentur in connect (ID kann über getOVKParticipants bestimmt werden)
file	Inhalt der Werbeformen-XML Datei (multipart/form-data encoded). Die Dateigröße darf 256 Megabyte nicht überschreiten.
attr_XXX	Eine beliebige Anzahl von Attributen (key/value pairs) um die Werbeform mit Metainformationen anzureichern. Diese haben das Prefix attr_ gefolgt vom Attributname (z.B. attr_codeinternal)

Mögliche Fehlerrückgaben¶

Code	Infotext	Erläuterung
400	missing params	Parameter file wurde nicht übergeben
409	unknown receiver	Der angegebene Empfänger ist connect nicht bekannt.
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¶

<ConnectResponse status="0" transactionID="319">
	<InfoText>Advertisements for Agentur 1 received</InfoText>
</ConnectResponse>

getTransactionsList¶

Gibt eine Liste der für andere eingestellten Dokumente und deren Status aus. Dokumente können drei verschiedene Zustände (Status) haben:

Status	Erläuterung
1	eingestellt => Das Dokument wurde eingestellt, aber noch nicht abgerufen.
2	abgerufen => Das Dokument wurde abgerufen, aber der Abruf wurde noch nicht mit fetch bestätigt.
3	bestätigt => Das Dokument wurde abgerufen und der Empfang per fetch bestätigt.

Aufruf	http://127.0.0.1:8888/api/getTransactionsList
Methoden	GET
Rückgabe	XML-Liste der Angebote (encoding: utf-8)

Parameter
states	Einschränkung auf den Status der Dokumente. Mögliche StatusIDs siehe oben. Es können mehrere States angegeben werden (kommasepariert). Parameter ist optional. Beispiel: “1,3“
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

Parameter

states

Einschränkung auf den Status der Dokumente. Mögliche StatusIDs siehe oben. Es können mehrere States angegeben werden (kommasepariert). Parameter ist optional. Beispiel: “1,3“

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
400	wrong param format	Eines der beiden Datumsangaben im lastChanged Parameter hatte ein ungültiges Format.
401	...	Bei einem Authentifizierungsproblem sind grundsätzlich die unter Authentifizierung aufgeführten Antworten möglich.

Beispiel¶

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<Documents>
  <Document id="4">
    <Receiver id="3" name="Agentur 1" />
    <State id="3" info="bestätigt" changed="2013-01-21 16:46:10.0" />
    <Attributes>
      <Attribute key="campain" value="WSV2013" />
      <Attribute key="internalid" value="1234" />
      <Attribute key="type" value="useroffer" />
    </Attributes>
  </Document>
  <Document id="63">
    <Receiver id="3" name="Agentur 1" />
    <State id="3" info="bestätigt" changed="2013-03-06 19:26:15.0" />
    <Attributes>
      <Attribute key="type" value="useroffer" />
    </Attributes>
  </Document>
</Documents>

Zugehöriges XSD-Schema: documentinfoList.xsd.

Elemente von “Document”¶

Element	Attribut	Bedeutung
	id	Die TransactionsID des Dokumentes. Eindeutige ID im connect System.
Receiver		Der Empfänger des Dokumentes
Receiver	id	ID des Users in connect. Diese ID entspricht der OVKParticipantsID.
Receiver	name	Name des connect users
State		Der Status des Dokumentes.
State	id	Status ID. Erläuterung siehe oben.
State	name	Name für den Status.
State	changed	Zeitpunkt zu dem der aktuelle Status des Dokumentes sich geändert hat im YYY-MM-DD HH:MM:SS Format
Attributes		Sammlung von META-Informationen zum Dokument. Hier stehen technisch vom System vergebene Informationen wie z.B. der Typ des Dokumentes als auch vom Sender beim Versand angegebene Attribute.
Attribute	key, value	Ein Attribut ist durch ein Key/Value Paar gekennzeichnet.

getTransactionStatus¶

Gibt den Status eines einzelnen Dokumentes zurück. Erläuterung Status siehe getTransactionsList.

Aufruf	http://127.0.0.1:8888/api/getTransactionStatus
Methoden	GET
Rückgabe	XML-Liste der Angebote (encoding: utf-8)

Parameter
id	ID des Dokuments. Die ID entspricht der TransactionID, die beim Einstellen von Dokumenten zurückgegeben wird (siehe z.B. Rückgabe bei sendBusinessTransaction). Die ID wird auch bei getTransactionsList ausgegeben.

Mögliche Fehlerrückgaben¶

Code	Infotext	Erläuterung
400	missing params id	Der Parameter id wurde nicht übergeben.
400	document not found	Unter der angegebenen ID wurde kein Dokument gefunden.
401	...	Bei einem Authentifizierungsproblem sind grundsätzlich die unter Authentifizierung aufgeführten Antworten möglich.

Beispiel¶

<Document id="200">
  <Receiver id="3" name="Agentur 1" />
  <State id="3" info="bestätigt" changed="2013-08-09 11:12:24.0" />
  <Attributes>
    <Attribute key="pw" value="test" />
    <Attribute key="encrypted" value="1" />
    <Attribute key="type" value="offer" />
  </Attributes>
</Document>

Zugehöriges XSD-Schema: documentinfo.xsd, Erläuterung hierzu siehe: Erläuterung getTransactionsList.

Validierung der Inhalte beim Versand¶

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

Validierung des XML gegen die in der XML angegebene(n) XSD(s)
Prüfung, ob der Sender in der XML die eigene ID ist (OVK ParticipantID identisch mit den Attribute ovkparticipantsenderid)
Prüfung ob der Sender (ovkparticipantsenderid) identisch ist mit dem Participant in “participants”. Wenn der Sender ein Vermarkter ist, wird die ovkparticipantid von participants/advertiser verglichen. In allen anderen Fällen wird participants/agency genutzt. Eine Nicht-Übereinstimmung verhindert im Moment den Versand nicht, sondern führt nur zu einer Warnung im Log
Prüfung, ob der Empfänger in der XML auch der Receiver ist (OVK ParticipantID identisch mit Attribute ovkparticipantreceiverid)
Prüfen, ob Empfänger die im Dokument angegeben Version der XSD unterstützt

Hierbei sind folgende Fehlerszenarien denkbar:

Bedingung	Verhalten
Inhalt ist kein valides XML	keine Validierung möglich, Versand erfolgt
Inhalt ist XML aber die XSD wird nicht gefunden bzw. ist nicht angegeben	keine Validierung möglich, Versand erfolgt
Inhalt ist XML, XSD wird gefunden => Validierung schlägt fehl	kein Versand
Inhalt ist XML, XSD wird gefunden, Validierung klappt => Participant.VID ist nicht Empfänger ID	kein Versand
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
“Angebots XML Inhalt konnte nicht geparsed werden”	Logdatei	200
“Im Root Element des Angebotes wurde kein Schema (Attribut: “xsi:schemaLocation”) gefunden”	Logdatei	200
“XML-Encoding Angabe fehlt”	Response	432
“ovkparticipantid of participants/{publisher\|agency} stimmt nicht mit ovkparticipantsenderid überein”	Logdatei	432
“Die angegebene XSD (...) konnte gefunden werden! “	Response	432
“Fehlermeldung vom Parser beim validieren gegen XSD”	Response	432
“Empfänger ID im XML stimmt nicht mit connect Empfänger überein”	Response	432
“Absender ID im XML stimmt nicht mit connect Absender überein”	Response	432
“Angebots XML enthält keine OVK Absender Id (ovkparticipantsenderid)”	Logdatei	200
“Angebots XML enthält keine OVK Empfaenger Id (ovkparticipantreceiverid)”	Logdatei	200
“Empfänger unterstützt die Version des Angebotes nicht!”	Response	432

Empfänger¶

getDocumentsList¶

Gibt eine Liste der für den eingeloggten User eingestellten Angebote und anderer Inhalte aus (siehe sendBusinessTransaction, sendPlacements, sendPriceLists, sendAdvertisements), deren Abruf noch nicht mit confirmFetch bestätigt wurde. Kann auf die Angebote eines Vermarkters eingeschränkt werden.

Die Angebote werden dabei nicht abgerufen. Jedes Angebot hat ein id Tag, das es eindeutig identifiziert. Diese id muss beim eigentlichen Abruf (siehe fetchBusinessTransaction, fetchPlacements, fetchPriceLists, fetchAdvertisements) genutzt werden.

Aufruf	http://127.0.0.1:8888/api/getDocumentsList
Methoden	GET
Rückgabe	XML-Liste der Angebote (encoding: utf-8)

Parameter
type	Typ der Angebote, “businesstransaction” für Angebote (siehe sendBusinessTransaction), “placements” für Inventare (siehe sendPlacements), “pricelist” für Preislisten (siehe sendPriceLists) oder “advertisement” für Werbeformen (siehe sendAdvertisements). Parameter ist optional. Keine Angabe gibt alle Typen zurück.
sender	ID des Vermarkters, der das Angebot (bzw. die Angebote) eingestellt hat (ID kann über getOVKParticipants bestimmt werden)
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" standalone="yes"?>

<Documents>

  <Document id="289" date="2013-08-09 11:12:24.0" >
    <Sender id="2" name="Vermarkter 1" />
    <Attributes>
      <Attribute key="pw" value="test" />
      <Attribute key="encrypted" value="1" />
      <Attribute key="type" value="offer" />
      <Attribute key="waitForConfirm" value="0" />
    </Attributes>
  </Document>

  <Document id="290" date="2014-02-22 14:29:24.0" >
    <Sender id="3" name="Agentur 1" />
    <Attributes>
      <Attribute key="type" value="offer" />
      <Attribute key="waitForConfirm" value="0" />
    </Attributes>
  </Document>

  <Document id="291" date="2014-04-17 15:27:22.0">
    <Sender id="3" name="Agentur 1" />
    <Attributes>
...

Zugehöriges XSD-Schema: documentsList.xsd.

Elemente von “Document”¶

Element	Attribut	Bedeutung
	id	Die TransactionsID des Dokumentes. Eindeutige ID im connect System.
	date	Zeitpunkt zu dem das Dokument eingestellt wurde im YYY-MM-DD HH:MM:SS Format
Sender		Der Sender des Dokumentes
Sender	id	ID des Users in connect. Diese ID entspricht der OVKParticipantsID.
Sender	name	Name des connect users
Attributes		Sammlung von META-Informationen zum Dokument. Hier stehen technisch vom System vergebene Informationen wie z.B. der Typ des Dokumentes als auch vom Sender beim Versand angegebene Attribute.
Attribute	key, value	Ein Attribut ist durch ein Key/Value Paar gekennzeichnet.

fetchBusinessTransaction¶

Ruft ein Angebot aus dem connect center ab.

Der Fetch erfolgt in zwei Stufen. Wenn der Fetch erfolgreich war, muss er im Anschluss mit confirmFetch abgeschlossen werden, um den Inhalt im connect center dauerhaft zu entfernen. Wenn ein Fetch nicht funktioniert hat, kann man nach Aufruf von undoFetch den Inhalt erneut abrufen.

Aufruf	http://127.0.0.1:8888/api/fetchBusinessTransaction
Methoden	GET
Rückgabe	Eingestelltes Angebot

Parameter
id	Angebots-ID (id aus getDocumentsList)

Mögliche Fehlerrückgaben¶

Code	Infotext	Erläuterung
400	missing params	Angebots-ID wurde nicht übergeben.
404	not found	Das Angebot unter der ID konnte nicht gefunden werden.
409	allready fetched	Das Angebot wurde bereits abgerufen, ggf. undoFetch nutzen.
401	...	Bei einem Authentifizierungsproblem sind grundsätzlich die unter Authentifizierung aufgeführten Antworten möglich.
432	siehe Validierung der Inhalte beim Empfangen	Probleme bei der Validierung der Inhalte

Beispiel¶

<businesstransaction xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="https://connectcenterqs01.agof.de/xsd/businesstransaction/v1.4.2/BusinessTransaction.xsd" VID="23103278" version="2014-06-26" ovkparticipantsenderid="1111" ovkparticipantreceiverid="1234">
  <type>offer</type>
  <offerid>42239</offerid>
  <version>1</version>
  <status>offered</status>
  <validto>2014-11-23</validto>
  <campaign>Finanzplanung privat Test </campaign>
  <participants>
    <advertiser VID="71190">
      <name>Beispiel Giroverband e.V.</name>
      <type>advertiser</type>
      <address>
...

fetchPlacements¶

Ruft ein agenturspezifisches Inventar eines Vermarkters ab (wurde mit sendPlacements eingestellt).

Aufruf	http://127.0.0.1:8888/api/fetchPlacements
Methoden	GET
Rückgabe	Eingestelltes Inventory

Parameter
id	Inventory-ID (id aus getDocumentsList parameter typ = ‘inventory’)

Mögliche Fehlerrückgaben¶

Code	Infotext	Erläuterung
400	missing params	Inventory-ID wurde nicht übergeben.
404	not found	Das Inventory unter der ID konnte nicht gefunden werden.
409	allready fetched	Das Inventory wurde bereits abgerufen, ggf. undoFetch nutzen.
401	...	Bei einem Authentifizierungsproblem sind grundsätzlich die unter Authentifizierung aufgeführten Antworten möglich.
432	siehe Validierung der Inhalte beim Empfangen	Probleme bei der Validierung der Inhalte

<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>   
...

fetchPriceLists¶

Ruft eine agenturspezifische Preisliste eines Vermarkters ab (wurde mit sendPriceLists eingestellt).

Aufruf	http://127.0.0.1:8888/api/fetchPriceLists
Methoden	GET
Rückgabe	Eingestellte Preisliste

Parameter
id	PriceLists-ID (id aus getDocumentsList parameter typ = ‘pricelist’)

Mögliche Fehlerrückgaben¶

Code	Infotext	Erläuterung
400	missing params	PriceLists-ID wurde nicht übergeben.
404	not found	Die Preisliste unter der ID konnte nicht gefunden werden.
409	allready fetched	Die Preisliste wurde bereits abgerufen, ggf. undoFetch nutzen.
401	...	Bei einem Authentifizierungsproblem sind grundsätzlich die unter Authentifizierung aufgeführten Antworten möglich.
432	siehe Validierung der Inhalte beim Empfangen	Probleme bei der Validierung der Inhalte

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">
...

fetchAdvertisements¶

Ruft die agenturspezifischen Werbeformen eines eines Vermarkters ab (wurde mit sendAdvertisements eingestellt).

Aufruf	http://127.0.0.1:8888/api/fetchAdvertisements
Methoden	GET
Rückgabe	Eingestelltes Werbeform

Parameter
id	Advertisements-ID (id aus getDocumentsList parameter typ = ‘advertisment’)

Mögliche Fehlerrückgaben¶

Code	Infotext	Erläuterung
400	missing params	Advertisements-ID wurde nicht übergeben.
404	not found	Die Werbeformen unter der ID konnte nicht gefunden werden.
409	allready fetched	Die Werbeformen wurde bereits abgerufen, ggf. undoFetch nutzen.
401	...	Bei einem Authentifizierungsproblem sind grundsätzlich die unter Authentifizierung aufgeführten Antworten möglich.
432	siehe Validierung der Inhalte beim Empfangen	Probleme bei der Validierung der Inhalte

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>
...

confirmFetch¶

Wenn Angebote aus dem connect center abgerufen werden (siehe fetchBusinessTransaction, fetchPlacements, fetchPriceLists, fetchAdvertisements) dann werden diese nicht gelöscht. Um diese Angebote zu löschen muss man die Abholung des Angebote mit den Aufruf dieser Funktion bestätigen. Erst dann wird das abgerufende Angebot gelöscht.

Wenn das confirmFetch durch ein connect kit durchgeführt wurde, verschickt dieses automatisch eine “confirm” Bestätigung an den Absender, welche dieser in seiner Nachrichtenauflistung angezeigt bekommt (siehe getMessagesList bzw. Nachrichten im Portal).

Aufruf	http://127.0.0.1:8888/api/confirmFetch
Methoden	GET
Rückgabe	ConnectResponse mit InfoText “fetch confirmed” oder “nothing to confirm”

Parameter
id	id aus getDocumentsList

Mögliche Fehlerrückgaben¶

Code	Infotext	Erläuterung
400	missing params	Parameter id wurde nicht übergeben.
401	...	Bei einem Authentifizierungsproblem sind grundsätzlich die unter Authentifizierung aufgeführten Antworten möglich.

Beispiel¶

<ConnectResponse status="0" transactionID="316">
  <InfoText>fetch confirmed</InfoText>
</ConnectResponse>

undoFetch¶

Wenn beim Abruf von Angebote aus den connect center Fehler auftreten, dann kann man mit diesen Befehl die Abrufung des Angebotes rückgängig machen. Erst dann kann man das Angebot erneut abrufen.

Aufruf	http://127.0.0.1:8888/api/undoFetch
Methoden	GET
Rückgabe	ConnectResponse mit InfoText “undo fetch” oder “nothing to undo”

Parameter
id	id aus getDocumentsList

Mögliche Fehlerrückgaben¶

Code	Infotext	Erläuterung
400	missing params	Parameter id wurde nicht übergeben.
401	...	Bei einem Authentifizierungsproblem sind grundsätzlich die unter Authentifizierung aufgeführten Antworten möglich.

Beispiel¶

<ConnectResponse status="0" transactionID="316">
  <InfoText>undo fetch</InfoText>
</ConnectResponse>

Validierung der Inhalte beim Empfangen¶

Bei den oben aufgeführten fetch... Befehlen wird eine automatische Validierung durchgeführt und unterschiedliche Fehlermeldungen entweder in die Logdatei des connect kits oder im Response ausgegeben:

Meldung	Ausgabe	Response Code
“Eingehendes Angebots XML konnte nicht geparsed werden. Fehlermeldung vom XML Parser: _FEHLERMELDUNG_ “	Logdatei, Warnfenster im Portal	200
“Eingehendes Angebots XML enthaelt keine OVK Id”	Logdatei, Warnfenster im Portal	200
“WARNUNG! Eingehendes Angebots XML enthaelt nicht die eigene OVK Id! “	Logdatei, Warnfenster im Portal	200

Nachrichten¶

getMessagesList¶

Gibt eine Liste der für den User anliegenden Nachrichten zurück.

Aufruf	http://127.0.0.1:8888/api/getMessagesList
Methoden	GET
Rückgabe	XML-Liste der Nachrichten (encoding: utf-8)

Parameter
sender	Filtert die Liste auf einen bestimmten Absender (id aus getDocumentsList). Parameter ist optional.
dateRange	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

Parameter

sender

Filtert die Liste auf einen bestimmten Absender (id aus getDocumentsList). Parameter ist optional.

dateRange

Mögliche Fehlerrückgaben¶

Code	Infotext	Erläuterung
400	wrong param format	Eines der beiden Datumsangaben im lastChanged Parameter hatte ein ungültiges Format.
409	internal error: missing user box	Angegebener Absender unbekannt
401	...	Bei einem Authentifizierungsproblem sind grundsätzlich die unter Authentifizierung aufgeführten Antworten möglich.

Beispiel¶

<?xml version="1.0" encoding="utf-8"?>
<Messages>
	<Message id="484" type="1" subject="Angebot abgerufen" transactionID="231">
	  <Sender id="3" name="Agentur 1" />
	  <Date>2014-01-23 14:17:30.774</Date>
	</Message>
	<Message id="524" type="3" subject="Allgemeine Anfrage">
	  <Sender id="2" name="Vermarkter 1" />
	  <Date>2014-02-25 11:13:22.387</Date>
	</Message>
</Messages>

Zugehöriges XSD-Schema: messageList.xsd.

Elemente von “Message”¶

Element	Attribut	Bedeutung
	id	Die ID der Nachricht. Eindeutige ID im connect System.
	type	Nachrichtentyp. Typ 0 ist eine automatisch vom connect verschickte Mitteilung beim confirmFetch. Typ 1 ist eine persönliche Nachricht eines anderen connect Nutzers.
	subject	Betreff der Nachricht
	transactionID	TransactionID auf die sich diese Nachricht bezieht (zum Beispiel ein vorher verschicktes Angebot). Optional.
Sender		Der Absender der Nachricht
Sender	id	ID des Users in connect. Diese ID entspricht der OVKParticipantsID.
Sender	name	Name des connect users
Date		Zeitpunkt zu dem die Nachticht verschickt wurde im YYY-MM-DD HH:MM:SS Format

readMessage¶

Ruft eine Nachricht ab.

Aufruf	http://127.0.0.1:8888/api/readMessage
Methoden	GET
Rückgabe	Eingestellte Nachricht

Parameter
id	Nachrichten-ID (id aus getMessagesList)

Mögliche Fehlerrückgaben¶

Code	Infotext	Erläuterung
400	missing params	Nachrichten-ID wurde nicht übergeben.
404	not found	Die Nachricht unter der ID konnte nicht gefunden werden.
409	...	Allgemeiner Fehler beim Lesen der Message(z.B. ubekannte MessageID)
401	...	Bei einem Authentifizierungsproblem sind grundsätzlich die unter Authentifizierung aufgeführten Antworten möglich.

Beispiel¶

<?xml version="1.0" encoding="utf-8"?>
<Message id="484" type="1" subject="Angebot abgerufen" transactionID="231">
  <Sender id="3" name="Agentur 1" />
  <Date>2014-01-23 14:17:30.774</Date>
  <Body>Das Angebot wurde abgerufen, wir prüfen es und melden uns dazu in der 32 KW.</Body>
</Message>

Zugehöriges XSD-Schema: message.xsd.

Erläuterung siehe Elemente von “Message”. Hier noch zusätzliches Body Element:

Element	Attribut	Bedeutung
Body		Inhalt der Nachricht

sendMessage¶

Sendet eine Nachricht an einen connect Nutzer.

Aufruf	http://127.0.0.1:8888/api/sendMessage
Methoden	POST (multipart/form-data encoded)
Rückgabe	ConnectResponse mit InfoText und der TransactionsID im Attribut

Parameter
receiver	Empfänger, ID des Teilnehmers in connect (ID kann über getOVKParticipants bestimmt werden)
subject	Betreff der Nachricht
content	Inhalt der Nachricht
transactionID	TransactionsID auf die sich diese Message bezieht (optional).

Mögliche Fehlerrückgaben¶

Code	Infotext	Erläuterung
409	unknown receiver	Der angegebene Empfänger ist connect nicht bekannt.
401	...	Bei einem Authentifizierungsproblem sind grundsätzlich die unter Authentifizierung aufgeführten Antworten möglich.

Beispiel¶

<ConnectResponse status="0" transactionID="451">
	<InfoText>received</InfoText>
</ConnectResponse>

deleteMessage¶

Löscht eine Nachricht.

Aufruf	http://127.0.0.1:8888/api/deleteMessage
Methoden	GET
Rückgabe	ConnectResponse mit InfoText “delete confirmed” oder “nothing to delete”

Parameter
id	id aus getMessagesList

Mögliche Fehlerrückgaben¶

Code	Infotext	Erläuterung
400	missing params	Parameter id wurde nicht übergeben.
400	nothing to delete	Nachricht wurde nicht gefunden oder schon gelöscht.
401	...	Bei einem Authentifizierungsproblem sind grundsätzlich die unter Authentifizierung aufgeführten Antworten möglich.

Beispiel¶

<ConnectResponse status="0" transactionID="484">
  <InfoText>delete confirmed</InfoText>
</ConnectResponse>