.. include:: globals.txt .. |transactionReceive| replace:: :ref:`genericresponse` mit InfoText und der TransactionsID im Attribut 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 -------- .. _sendoffer: sendBusinessTransaction ```````````````````````` Verschickt ein Angebot. |noinvestigateinfo| ============= ================================ Aufruf :api_url:`sendBusinessTransaction` ============= ================================ Methoden **POST** (*multipart/form-data* encoded) Rückgabe |transactionReceive| ============= ================================ ============= ========= **Parameter** ============= ========= **receiver** Empfänger, ID des Teilnehmers in |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 |connectcentername| nicht bekannt. **401** *...* |autherrors| **432** siehe :ref:`validateBehavior` Probleme bei der Validierung der Inhalte ========= ============================== ====================================================== Beispiel ''''''''''''' .. _backsendoffer: .. literalinclude:: files/api_response/sendBusinessTransaction.out :language: xml :encoding: utf-8 .. _sendInventory: sendPlacements ```````````````` Verschickt ein Inventar an eine bestimmte Agentur. |noinvestigateinfo| ============= ================================ Aufruf |connecturl|/sendPlacements/ ============= ================================ Methoden **POST** (*multipart/form-data* encoded) Rückgabe |transactionReceive| ============= ================================ ============= ========= **Parameter** ============= ========= **receiver** Empfänger, ID der Agentur in |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 |connectcentername| nicht bekannt. **401** *...* |autherrors| **432** siehe :ref:`validateBehavior` Probleme bei der Validierung der Inhalte ========= ============================== ====================================================== Beispiel ''''''''''''' .. literalinclude:: files/api_response/sendPlacements.out :language: xml :encoding: utf-8 .. _sendPriceLists: sendPriceLists ```````````````` Verschickt eine Preisliste an eine bestimmte Agentur. |noinvestigateinfo| ============= ================================ Aufruf :api_url:`sendPriceLists` ============= ================================ Methoden **POST** (*multipart/form-data* encoded) Rückgabe |transactionReceive| ============= ================================ ============= ========= **Parameter** ============= ========= **receiver** Empfänger, ID der Agentur in |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 |connectcentername| nicht bekannt. **401** *...* |autherrors| **432** siehe :ref:`validateBehavior` Probleme bei der Validierung der Inhalte ========= ============================== ====================================================== Beispiel ''''''''''''' .. literalinclude:: files/api_response/sendPriceLists.out :language: xml :encoding: utf-8 .. _sendAdvertisements: sendAdvertisements ```````````````````` Verschickt die Werbeformen eines Vermarkters an eine bestimmte Agentur. |noinvestigateinfo| ============= ====================================== Aufruf :api_url:`sendAdvertisements` ============= ====================================== Methoden **POST** (*multipart/form-data* encoded) Rückgabe |transactionReceive| ============= ====================================== ============= ========= **Parameter** ============= ========= **receiver** Empfänger, ID der Agentur in |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 |connectcentername| nicht bekannt. **401** *...* |autherrors| **432** siehe :ref:`validateBehavior` Probleme bei der Validierung der Inhalte ========= ============================== ====================================================== Beispiel ''''''''''''' .. literalinclude:: files/api_response/sendAdvertisements.out :language: xml :encoding: utf-8 .. _getTransactionsList: getTransactionsList ```````````````````` Gibt eine Liste der für andere eingestellten Dokumente und deren Status aus. Dokumente können drei verschiedene Zustände (Status) haben: .. _transactions_status: .. 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 :api_url:`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 ''''''''''''' .. literalinclude:: tests/outputs_single/getTransactionsList.out :language: xml :encoding: utf-8 Zugehöriges XSD-Schema: :download:`documentinfoList.xsd `. .. _transactionslist_explained: Elemente von "Document" ........................ .. list-table:: :widths: 10 10 80 :header-rows: 1 * - Element - Attribut - Bedeutung * - - **id** - Die TransactionsID des Dokumentes. Eindeutige ID im |connectcentername| System. * - **Receiver** - - Der Empfänger des Dokumentes * - Receiver - **id** - |ovkID-explained| * - Receiver - **name** - Name des |connectcentername| users * - **State** - - Der Status des Dokumentes. * - State - **id** - Status ID. Erläuterung siehe :ref:`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: getTransactionStatus ```````````````````` Gibt den Status eines einzelnen Dokumentes zurück. Erläuterung Status siehe :ref:`getTransactionsList`. ============= =========================================== Aufruf :api_url:`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:`sendBusinessTransaction `). 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 ''''''''''''' .. literalinclude:: tests/outputs_single/getTransactionStatus.out :language: xml :encoding: utf-8 Zugehöriges XSD-Schema: :download:`documentinfo.xsd `, Erläuterung hierzu siehe: :ref:`Erläuterung getTransactionsList `. .. _validateBehavior: Validierung der Inhalte beim Versand ````````````````````````````````````` Bei den oben aufgeführten **send...** Befehlen wird eine automatische Validierung durchgeführt: 1. Validierung des XML gegen die in der XML angegebene(n) XSD(s) 2. Prüfung, ob der Sender in der XML die eigene ID ist (OVK ParticipantID identisch mit den Attribute *ovkparticipantsenderid*) 3. 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 4. Prüfung, ob der Empfänger in der XML auch der Receiver ist (OVK ParticipantID identisch mit Attribute *ovkparticipantreceiverid*) 5. Prüfen, ob Empfänger die im Dokument angegeben Version der XSD unterstützt Hierbei sind folgende Fehlerszenarien denkbar: .. list-table:: :widths: 70 30 :header-rows: 1 * - 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** .. _validateErrors: Fehlermeldungen ''''''''''''''''' Im Rahmen der Validerungen werden unterschiedliche Fehlermeldungen entweder in die Logdatei des connect kits oder im Response ausgegeben. .. list-table:: :widths: 70 20 10 :header-rows: 1 * - 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 ---------- .. |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 für den eingeloggten User eingestellten Angebote und anderer Inhalte aus (siehe :ref:`sendoffer`, :ref:`sendInventory`, :ref:`sendPriceLists`, :ref:`sendAdvertisements`), deren Abruf noch nicht mit :ref:`confirmFetch` bestätigt wurde. |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 :api_url:`getDocumentsList` ============= =================================== Methoden **GET** Rückgabe XML-Liste der Angebote (encoding: utf-8) ============= =================================== =============== ========= **Parameter** =============== ========= **type** Typ der Angebote, "**businesstransaction**" für Angebote (siehe :ref:`sendoffer`), "**placements**" für Inventare (siehe :ref:`sendInventory`), "**pricelist**" für Preislisten (siehe :ref:`sendPriceLists`) oder "**advertisement**" 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| **lastChanged** |dateRangeFormat| =============== ========= Mögliche Fehlerrückgaben ''''''''''''''''''''''''' ========= ============================== ====================================================== **Code** Infotext Erläuterung ========= ============================== ====================================================== **401** *...* |autherrors| ========= ============================== ====================================================== Beispiel ''''''''''''' .. literalinclude:: files/api_response/getDocumentsList.xml :language: xml :lines: 1-25 :append: ... :encoding: utf-8 Zugehöriges XSD-Schema: :download:`documentsList.xsd `. .. _explain_document: Elemente von "Document" ........................ .. list-table:: :widths: 10 10 80 :header-rows: 1 * - Element - Attribut - Bedeutung * - - **id** - Die TransactionsID des Dokumentes. Eindeutige ID im |connectcentername| System. * - - **date** - Zeitpunkt zu dem das Dokument eingestellt wurde im YYY-MM-DD HH:MM:SS Format * - **Sender** - - Der Sender des Dokumentes * - Sender - **id** - |ovkID-explained| * - Sender - **name** - Name des |connectcentername| 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. .. _fetchoffer: fetchBusinessTransaction ```````````````````````````` Ruft ein Angebot aus dem connect center ab. |needconfirmfetch| ============= ================================ Aufruf :api_url:`fetchBusinessTransaction` ============= ================================ 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| **432** siehe :ref:`validateBehaviorReceive` Probleme bei der Validierung der Inhalte ========= ===================================== ====================================================== Beispiel ''''''''''''' .. literalinclude:: files/businesstransaction.xml :language: xml :lines: 1-13 :append: ... :encoding: utf-8 .. _fetchInventory: fetchPlacements ```````````````` Ruft ein agenturspezifisches Inventar eines Vermarkters ab (wurde mit :ref:`sendInventory` eingestellt). |needconfirmfetch| ============= ================================ Aufruf :api_url:`fetchPlacements` ============= ================================ 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| **432** siehe :ref:`validateBehaviorReceive` Probleme bei der Validierung der Inhalte ========= ===================================== ====================================================== .. literalinclude:: files/Placements.xml :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 :api_url:`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| **432** siehe :ref:`validateBehaviorReceive` Probleme bei der Validierung der Inhalte ========= ===================================== ====================================================== Beispiel ''''''''''''' .. literalinclude:: files/Pricelist.xml :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 :api_url:`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| **432** siehe :ref:`validateBehaviorReceive` Probleme bei der Validierung der Inhalte ========= ===================================== ====================================================== Beispiel ''''''''''''' .. literalinclude:: files/advertisements.xml :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 :api_url:`confirmFetch` ============= ================================ Methoden **GET** Rückgabe :ref:`genericresponse` mit InfoText "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 ''''''''''''' .. literalinclude:: files/api_response/confirmFetch.out :language: xml :encoding: utf-8 .. _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 :api_url:`undoFetch` ============= ================================ Methoden **GET** Rückgabe :ref:`genericresponse` mit InfoText "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 ''''''''''''' .. literalinclude:: files/api_response/undoFetch.out :language: xml :encoding: utf-8 .. _validateBehaviorReceive: 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: .. list-table:: :widths: 70 20 10 :header-rows: 1 * - 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: getMessagesList ````````````````` Gibt eine Liste der für den User anliegenden Nachrichten zurück. ============= ================================ Aufruf :api_url:`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 ''''''''''''' .. literalinclude:: files/api_response/getMessagesList.xml :language: xml :encoding: utf-8 Zugehöriges XSD-Schema: :download:`messageList.xsd `. .. _explain_messages: Elemente von "Message" ........................ .. list-table:: :widths: 10 10 80 :header-rows: 1 * - Element - Attribut - Bedeutung * - - **id** - Die ID der Nachricht. Eindeutige ID im |connectcentername| System. * - - **type** - Nachrichtentyp. Typ **0** ist eine automatisch vom |connectcentername| verschickte Mitteilung beim :ref:`confirmFetch`. Typ **1** ist eine persönliche Nachricht eines anderen |connectcentername| 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** - |ovkID-explained| * - Sender - **name** - Name des |connectcentername| users * - **Date** - - Zeitpunkt zu dem die Nachticht verschickt wurde im YYY-MM-DD HH:MM:SS Format .. _readMessage: readMessage ```````````````` Ruft eine Nachricht ab. ============= ================================ Aufruf :api_url:`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. **409** **...** Allgemeiner Fehler beim Lesen der Message(z.B. ubekannte MessageID) **401** **...** |autherrors| ========= ============================== ====================================================== Beispiel ''''''''''''' .. literalinclude:: files/api_response/readMessage.xml :language: xml :encoding: utf-8 Zugehöriges XSD-Schema: :download:`message.xsd `. Erläuterung siehe :ref:`explain_messages`. Hier noch zusätzliches **Body** Element: .. list-table:: :widths: 10 10 80 :header-rows: 1 * - Element - Attribut - Bedeutung * - **Body** - - Inhalt der Nachricht .. _sendMessage: sendMessage ```````````` Sendet eine Nachricht an einen |connectcentername| Nutzer. ============= ================================ Aufruf :api_url:`sendMessage` ============= ================================ Methoden **POST** (*multipart/form-data* encoded) Rückgabe |transactionReceive| ============= ================================ =================== ========= **Parameter** =================== ========= **receiver** Empfänger, ID des Teilnehmers in |connectcentername| |useridinfo| **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 |connectcentername| nicht bekannt. **401** *...* |autherrors| ========= ============================== ====================================================== Beispiel ''''''''''''' .. literalinclude:: files/api_response/sendMessage.out :language: xml :encoding: utf-8 .. _deleteMessage: deleteMessage ````````````````` Löscht eine Nachricht. ============= ================================ Aufruf :api_url:`deleteMessage` ============= ================================ Methoden **GET** Rückgabe :ref:`genericresponse` mit InfoText "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 ''''''''''''' .. literalinclude:: files/api_response/deleteMessage.out :language: xml :encoding: utf-8