.. include:: globals.txt .. sidebar:: Token |needtokeninfo| .. |dateRangeFormat| replace:: Angabe eines Datumsbereiches (von-bis im Format "*JJJJ-MM-DD, JJJJ-MM-DD*"). Das erste Datum definiert den Beginn des Bereichs, das Zweite das Ende (optional). Parameter ist optional. Beispiele: "*2014-01-01*", "*2014-01-01*, *2014-02-01*" .. |dateRangeFormatError| replace:: Eines der beiden Datumsangaben im lastChanged Parameter hatte ein ungültiges Format. 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. Vermarkterfunktionen -------------------------- .. _sendoffer: sendOffer ````````` Verschickt ein Angebot. |noinvestigateinfo| ============= ================================ Aufruf |connecturl|/sendOffer/ ============= ================================ Methoden **POST** (*multipart/form-data* encoded) Rückgabe Antwortstring "Offer for *USERNAME* received / TransactionID: *ID*" ============= ================================ \ \ ============= ========= **Parameter** ============= ========= **receiver** Empfänger, ID des Teilnehmers im |connectcentername| |useridinfo| **file** Inhalt der Angebots-XML Datei (*multipart/form-data* encoded). |maxuploadfile| **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 dem |connectcentername| nicht bekannt. **401** *...* |autherrors| ========= ============================== ====================================================== Beispiel ''''''''''''' Anfrage ............. .. literalinclude:: tests/outputs_single/sendOffer.in Beispieldatei offer.xml (Ausschnitt): .. literalinclude:: tests/files/offer.xml :language: xml :lines: 1-13 :append: ... :encoding: utf-8 .. _backsendoffer: Rückgabe ............. .. literalinclude:: tests/outputs_single/sendOffer.out .. _sendInventory: sendInventory ````````````` Verschickt ein Inventar an eine bestimmte Agentur. |noinvestigateinfo| ============= ================================ Aufruf |connecturl|/sendInventory/ ============= ================================ Methoden **POST** (*multipart/form-data* encoded) Rückgabe Antwortstring "Inventory for *USERNAME* received / TransactionID: *ID*" ============= ================================ \ \ ============= ========= **Parameter** ============= ========= **receiver** Empfänger, ID der Agentur im |connectcentername| |useridinfo| **file** Inhalt der Inventory-XML Datei (*multipart/form-data* encoded). |maxuploadfile| **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 dem |connectcentername| nicht bekannt. **401** *...* |autherrors| ========= ============================== ====================================================== Beispiel ''''''''''''' Anfrage ............. .. literalinclude:: tests/outputs_single/sendInventory.in Beispieldatei offer.xml (Ausschnitt): .. literalinclude:: tests/files/offer.xml :language: xml :lines: 1-13 :append: ... :encoding: utf-8 Rückgabe ............. .. literalinclude:: tests/outputs_single/sendInventory.out .. _sendPriceLists: sendPriceLists ```````````````` Verschickt eine Preisliste an eine bestimmte Agentur. |noinvestigateinfo| ============= ================================ Aufruf |connecturl|/sendPriceLists/ ============= ================================ Methoden **POST** (*multipart/form-data* encoded) Rückgabe Antwortstring "PriceLists for *USERNAME* received / TransactionID: *ID*" ============= ================================ \ \ ============= ========= **Parameter** ============= ========= **receiver** Empfänger, ID der Agentur im |connectcentername| |useridinfo| **file** Inhalt der Preislisten-XML Datei (*multipart/form-data* encoded). |maxuploadfile| **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 dem |connectcentername| nicht bekannt. **401** *...* |autherrors| ========= ============================== ====================================================== Beispiel ''''''''''''' Anfrage ............. .. literalinclude:: tests/outputs_single/sendPriceLists.in Beispieldatei offer.xml (Ausschnitt): .. literalinclude:: tests/files/offer.xml :language: xml :lines: 1-13 :append: ... :encoding: utf-8 Rückgabe ............. .. literalinclude:: tests/outputs_single/sendPriceLists.out .. _sendAdvertisements: sendAdvertisements ```````````````````` Verschickt die Werbeformen eines Vermarkters an eine bestimmte Agentur. |noinvestigateinfo| ============= ====================================== Aufruf |connecturl|/sendAdvertisements/ ============= ====================================== Methoden **POST** (*multipart/form-data* encoded) Rückgabe Antwortstring "Advertisements for *USERNAME* received / TransactionID: *ID*" ============= ====================================== \ \ ============= ========= **Parameter** ============= ========= **receiver** Empfänger, ID der Agentur im |connectcentername| |useridinfo| **file** Inhalt der Werbeformen-XML Datei (*multipart/form-data* encoded). |maxuploadfile| **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 dem |connectcentername| nicht bekannt. **401** *...* |autherrors| ========= ============================== ====================================================== Beispiel ''''''''''''' Anfrage ............. .. literalinclude:: tests/outputs_single/sendAdvertisements.in Beispieldatei offer.xml (Ausschnitt): .. literalinclude:: tests/files/offer.xml :language: xml :lines: 1-13 :append: ... :encoding: utf-8 Rückgabe ............. .. literalinclude:: tests/outputs_single/sendAdvertisements.out .. _getTransactionsList: getTransactionsList ```````````````````` Gibt eine Liste der eingestellten Dokumente und deren Status aus. Dokumente können drei verschiedene Zustände (Status) haben: .. list-table:: :widths: 7 93 :header-rows: 1 * - 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 :ref:`fetch ` bestätigt. * - **3** - bestätigt => Das Dokument wurde abgerufen und der Empfang per :ref:`fetch ` bestätigt. ============= =========================================== Aufruf |connecturl|/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** |dateRangeFormat| =============== ========= \ \ Mögliche Fehlerrückgaben ''''''''''''''''''''''''' \ \ ========= ==================================== ====================================================== **Code** Infotext Erläuterung ========= ==================================== ====================================================== **400** **wrong param format** |dateRangeFormatError| **401** *...* |autherrors| ========= ==================================== ====================================================== Beispiel ''''''''''''' Anfrage ............. .. literalinclude:: tests/outputs_single/getTransactionsList.in .. _backgetTransactionsList: Rückgabe ............. .. literalinclude:: tests/outputs_single/getTransactionsList.out :language: xml :encoding: utf-8 .. _getTransactionStatus: getTransactionStatus ```````````````````` Gibt den Status eines einzelnen Dokumentes zurück. Erläuterung Status siehe :ref:`getTransactionsList`. ============= =========================================== Aufruf |connecturl|/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 :ref:`sendOffer `). Die ID wird auch bei :ref:`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** *...* |autherrors| ========= ==================================== ====================================================== Beispiel ''''''''''''' Anfrage ............. .. literalinclude:: tests/outputs_single/getTransactionStatus.in Rückgabe ............. .. literalinclude:: tests/outputs_single/getTransactionStatus.out :language: xml :encoding: utf-8 Agenturfunktionen -------------------------- .. |getsuffix| replace:: aller Vermarkter oder des spezifisch abgefragen Vermarkters als XML .. |infone| replace:: Kann auf die Angebote eines Vermarkters eingeschränkt werden. .. _getDocumentsList: getDocumentsList ```````````````` Gibt eine Liste der von Vermarktern für den eingeloggten User eingestellten Angebote und anderer Inhalte aus (siehe :ref:`sendoffer`, :ref:`sendInventory`, :ref:`sendPriceLists`, :ref:`sendAdvertisements`). |infone| Die Angebote werden dabei nicht abgerufen. Jedes Angebot hat ein **id** Tag, das es eindeutig identifiziert. Diese **id** muss beim eigentlichen Abruf (siehe :ref:`fetchoffer`, :ref:`fetchInventory`, :ref:`fetchPriceLists`, :ref:`fetchAdvertisements`) genutzt werden. ============= =================================== Aufruf |connecturl|/getDocumentsList/ ============= =================================== Methoden **GET** Rückgabe XML-Liste der Angebote (encoding: utf-8) ============= =================================== \ \ =============== ========= **Parameter** =============== ========= **type** Typ der Angebote, "**offer**"" für Angebote (siehe :ref:`sendoffer`), "**inventory**"" für Inventare (siehe :ref:`sendInventory`), "**pricelist**"" für Preislisten (siehe :ref:`sendPriceLists`) oder "**advertisment**" für Werbeformen (siehe :ref:`sendAdvertisements`). Parameter ist optional. Keine Angabe gibt alle Typen zurück. **sender** ID des Vermarkters, der das Angebot (bzw. die Angebote) eingestellt hat |useridinfo| =============== ========= \ \ Mögliche Fehlerrückgaben ''''''''''''''''''''''''' \ \ ========= ============================== ====================================================== **Code** Infotext Erläuterung ========= ============================== ====================================================== **401** *...* |autherrors| ========= ============================== ====================================================== Beispiel ''''''''''''' Anfrage ............. .. literalinclude:: tests/outputs_single/getDocumentsList.in Rückgabe ............. .. literalinclude:: tests/outputs_single/getDocumentsList.out :language: xml :lines: 1-25 :emphasize-lines: 4,12, 20 :append: ... :encoding: utf-8 .. _fetchoffer: fetchOffer ````````````` Ruft ein Angebot aus dem connect center ab. |needconfirmfetch| ============= ================================ Aufruf |connecturl|/getOffers/ ============= ================================ Methoden **GET** Rückgabe Eingestelltes Angebot ============= ================================ \ \ =============== ========= **Parameter** =============== ========= **id** Angebots-ID (**id** aus :ref:`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. :ref:`undoFetch` nutzen. **401** *...* |autherrors| ========= ============================== ====================================================== Beispiel ''''''''''''' Anfrage ............. .. literalinclude:: tests/outputs_single/fetchOffer.in Rückgabe ............. .. literalinclude:: tests/outputs_single/fetchOffer.out :language: xml :lines: 1-13 :append: ... :encoding: utf-8 .. _fetchInventory: fetchInventory ```````````````` Ruft ein agenturspezifisches Inventar eines Vermarkters ab (wurde mit :ref:`sendInventory` eingestellt). |needconfirmfetch| ============= ================================ Aufruf |connecturl|/fetchInventory/ ============= ================================ Methoden **GET** Rückgabe Eingestelltes Inventory ============= ================================ \ \ =============== ========= **Parameter** =============== ========= **id** Inventory-ID (**id** aus :ref:`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. :ref:`undoFetch` nutzen. **401** *...* |autherrors| ========= ============================== ====================================================== Beispiel ''''''''''''' Anfrage ............. .. literalinclude:: tests/outputs_single/fetchInventory.in Rückgabe ............. .. literalinclude:: tests/outputs_single/fetchInventory.out :language: xml :lines: 1-13 :append: ... :encoding: utf-8 .. _fetchPriceLists: fetchPriceLists ````````````````` Ruft eine agenturspezifische Preisliste eines Vermarkters ab (wurde mit :ref:`sendPricelists` eingestellt). |needconfirmfetch| ============= ================================== Aufruf |connecturl|/fetchPriceLists/ ============= ================================== Methoden **GET** Rückgabe Eingestellte Preisliste ============= ================================== \ \ =============== ========= **Parameter** =============== ========= **id** PriceLists-ID (**id** aus :ref:`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. :ref:`undoFetch` nutzen. **401** *...* |autherrors| ========= ============================== ====================================================== Beispiel ''''''''''''' Anfrage ............. .. literalinclude:: tests/outputs_single/fetchPriceLists.in Rückgabe ............. .. literalinclude:: tests/outputs_single/fetchPriceLists.out :language: xml :lines: 1-13 :append: ... :encoding: utf-8 .. _fetchAdvertisements: fetchAdvertisements ```````````````````` Ruft die agenturspezifischen Werbeformen eines eines Vermarkters ab (wurde mit :ref:`sendAdvertisements` eingestellt). |needconfirmfetch| ============= ====================================== Aufruf |connecturl|/fetchAdvertisements/ ============= ====================================== Methoden **GET** Rückgabe Eingestelltes Werbeform ============= ====================================== \ \ =============== ========= **Parameter** =============== ========= **id** Advertisements-ID (**id** aus :ref:`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. :ref:`undoFetch` nutzen. **401** *...* |autherrors| ========= ============================== ====================================================== Beispiel ''''''''''''' Anfrage ............. .. literalinclude:: tests/outputs_single/fetchAdvertisements.in Rückgabe ............. .. literalinclude:: tests/outputs_single/fetchAdvertisements.out :language: xml :lines: 1-13 :append: ... :encoding: utf-8 .. _confirmFetch: confirmFetch ````````````````` Wenn Angebote aus dem connect center abgerufen werden (siehe :ref:`fetchoffer`, :ref:`fetchInventory`, :ref:`fetchPriceLists`, :ref:`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 :ref:`connect kit ` durchgeführt wurde, verschickt dieses automatisch eine "confirm" Bestätigung an den Absender, welche dieser in seiner Nachrichtenauflistung angezeigt bekommt (siehe :ref:`getMessagesList` bzw. :ref:`Nachrichten im Portal `). ============= ================================ Aufruf |connecturl|/confirmFetch/ ============= ================================ Methoden **GET** Rückgabe "fetch confirmed" oder "nothing to confirm" ============= ================================ \ \ =============== ========= **Parameter** =============== ========= **id** **id** aus :ref:`getDocumentsList` =============== ========= \ \ Mögliche Fehlerrückgaben ''''''''''''''''''''''''' \ \ ========= ============================== ====================================================== **Code** Infotext Erläuterung ========= ============================== ====================================================== **400** **missing params** Parameter **id** wurde nicht übergeben. **401** *...* |autherrors| ========= ============================== ====================================================== Beispiel ''''''''''''' Anfrage ............. .. literalinclude:: tests/outputs_single/confirmFetch.in Rückgabe ............. .. literalinclude:: tests/outputs_single/confirmFetch.out .. _undoFetch: 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 |connecturl|/undoFetch/ ============= ================================ Methoden **GET** Rückgabe "undo fetch" oder "nothing to undo" ============= ================================ \ \ =============== ========= **Parameter** =============== ========= **id** **id** aus :ref:`getDocumentsList` =============== ========= \ \ Mögliche Fehlerrückgaben ''''''''''''''''''''''''' \ \ ========= ============================== ====================================================== **Code** Infotext Erläuterung ========= ============================== ====================================================== **400** **missing params** Parameter **id** wurde nicht übergeben. **401** *...* |autherrors| ========= ============================== ====================================================== Beispiel ''''''''''''' Anfrage ............. .. literalinclude:: tests/outputs_single/undoFetch.in Rückgabe ............. .. literalinclude:: tests/outputs_single/undoFetch.out :encoding: utf-8 .. _getMessagesList: getMessagesList ````````````````` Gibt eine Liste der für den User anliegenden Nachrichten zurück. ============= ================================ Aufruf |connecturl|/getMessagesList/ ============= ================================ Methoden **GET** Rückgabe XML-Liste der Nachrichten (encoding: utf-8) ============= ================================ \ \ =============== ========= **Parameter** =============== ========= **sender** Filtert die Liste auf einen bestimmten Absender (**id** aus :ref:`getDocumentsList`). Parameter ist optional. **dateRange** |dateRangeFormat| =============== ========= \ \ Mögliche Fehlerrückgaben ''''''''''''''''''''''''' \ \ ========= ====================================== ====================================================== **Code** Infotext Erläuterung ========= ====================================== ====================================================== **400** **wrong param format** |dateRangeFormatError| **409** **internal error: missing user box** Angegebener Absender unbekannt **401** *...* |autherrors| ========= ====================================== ====================================================== Beispiel ''''''''''''' Anfrage ............. .. literalinclude:: tests/outputs_single/getMessagesList.in Rückgabe ............. .. literalinclude:: tests/outputs_single/getMessagesList.out :language: xml :encoding: utf-8 .. _readMessage: readMessage ```````````````` Ruft eine Nachricht ab. ============= ================================ Aufruf |connecturl|/readMessage/ ============= ================================ Methoden **GET** Rückgabe Eingestellte Nachricht ============= ================================ \ \ =============== ========= **Parameter** =============== ========= **id** Nachrichten-ID (**id** aus :ref:`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. **401** *...* |autherrors| ========= ============================== ====================================================== Beispiel ''''''''''''' Anfrage ............. .. literalinclude:: tests/outputs_single/readMessage.in Rückgabe ............. .. literalinclude:: tests/outputs_single/readMessage.out :language: xml :lines: 1-13 :append: ... :encoding: utf-8 .. _deleteMessage: deleteMessage ````````````````` Löscht eine Nachricht. ============= ================================ Aufruf |connecturl|/deleteMessage/ ============= ================================ Methoden **GET** Rückgabe "delete confirmed" oder "nothing to delete" ============= ================================ \ \ =============== ========= **Parameter** =============== ========= **id** **id** aus :ref:`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** *...* |autherrors| ========= ============================== ====================================================== Beispiel ''''''''''''' Anfrage ............. .. literalinclude:: tests/outputs_single/deleteMessage.in Rückgabe ............. .. literalinclude:: tests/outputs_single/deleteMessage.out