.. include:: globals.txt Allgemeines ============= Rückgabeformat ----------------- |connectcentername| liefert grundsätzlich XML zurück. Der Aufbau ist in den einzelnen API-Aufrufen erläutert. Darüber hinaus existieren folgende allgemeinen XML-Antworten. .. _genericresponse: ConnectResponse ```````````````` .. literalinclude:: files/response.xml :language: xml :encoding: utf-8 Zugehöriges XSD-Schema: :download:`response.xsd `. .. list-table:: :widths: 30 70 * - Attribut "status" - 0 = OK, 1 = ERROR * - Element "InfoText" - Optionaler Infotext für z.B. Erläuterungen bei Fehlerrückgaben * - Attribut "transactionID" - In einigen Kommunikationen wird eine TransactionsID erzeugt, welche über dieses Attribut ausgelesen werden kann. Die Auswertung der Fehlerursache kann über den **HTTP Status Code** ermittelt werden. Die möglichen Fehlercodes sind in den jeweiligen Aufrufen dokumentiert. Verschlüsselung ----------------- Die Kommunikation mit |connectcentername| erfolgt verschlüsselt über das **https** Protokoll (Server-Side-Certificat). .. _auth: Authentifizierung ------------------- Die Authentifizierung zwischen dem connect kit und |connectcentername| erfolgt über Username/Passwort. Diese werden in den Einstellungen im connect kit (:ref:`siehe`) angegeben. Name und Passwort erhalten Sie als Teilnehmer von der AGOF Services GmbH. Sollte es zu Problemen mit der Authentifizierung geben (siehe Fehlerrückgabe unten), prüfen Sie bitte die Eintragung in den Einstellungen im connect kit. Sollte das Problem dann immer noch auftreten, wenden Sie sich bitte an den Support zur Überprüfung der eingetragenen Daten im connect center. Die Kommunikation zwischen Ihrem System und dem connect kit (bei Ihnen lokal) funktioniert derzeit ohne Authentifizierung. Mögliche Fehlerrückgaben ````````````````````````` ========= ==================================================================== **Code** Infotext ========= ==================================================================== **401** **Kombination Username/Passwort stimmt nicht mit connect überein** ========= ==================================================================== Nutzerkennung -------------------------- .. _getusers: getOVKParticipants ```````````````````` Jedes teilnehmende Unternehmen, bzw. jeder Standort eines Unternehmens erhält bei der Anmeldung über die AGOF die OVKParticipant ID. Diese ID ist für die Kommunikation in |connectcentername| notwendig. Sie identifiziert den jeweiligen Teilnehmer, sowie die Prüfungs- und Validierungsroutinen sind darauf ausgerichtet. Eine Liste der vorhandenen OVKParticipants kann man über den Befehl **getOVKParticipants** erhalten werden. Die OVKParticipantID ist im ID Tag der Rückantwort zu finden. Diese ID ist fix und ändert sich für einen Teilnehmer nicht. ============================= ================================ Aufruf :api_url:`getOVKParticipants/` ============================= ================================ Methoden **GET** Rückgabe XML-Liste der User (encoding: utf-8) ============================= ================================ Mögliche Fehlerrückgaben ''''''''''''''''''''''''' ========= ============================== ====================================================== **Code** Infotext Erläuterung ========= ============================== ====================================================== **401** *...* |autherrors| ========= ============================== ====================================================== Beispiel '''''''''''' .. literalinclude:: files/api_response/getOVKParticipants.xml :language: xml :lines: 1-17 :append: ... :encoding: utf-8 :download:`download ` Schema ''''''''' Das zugehöriges XSD-Schema: :download:`OVKParticipants.xsd `. Erläuterungen: Elemente von "User" .................... .. list-table:: :widths: 10 10 80 :header-rows: 1 * - Element - Attribut - Bedeutung * - - **created** - Zeitpunkt und Datum an dem diese Auflistung generiert wurde. * - **ovkparticipantid** - - |ovkID-explained| * - **name** - - Name des Users im connect center. * - **type** - - |usertype| * - **Schemes** - - Dokument Schemas, die der User unterstützt. Die Schemas der in connect genutzten Dokumente sind unter :ref:`connectschemes` abrufbar. Der connect User setzt seine unterstützen Schemas über die Einstellungen in seinem connect kit (siehe :ref:`Settings `) * - **Schemes.xxx** - - Mögliche Schemas sind *BusinessTransactions*, *Placements*, *Pricelists*, *Advertisements* und *Defines* * - **Schemes.xxx.Version** - - Versionen des jeweiligen Dokumenttypes, die der User verabeiten kann. Aktivität ---------- getProtocols ```````````````` Ruft ab, welche Aktionen im Konto des Users in einem gegebenen Zeitraum ausgeführt wurden ============================= ================================ Aufruf :api_url:`getProtocols/` ============================= ================================ Methoden **GET** Rückgabe XML-Liste der Aktionen (encoding: utf-8) ============================= ================================ ============= ========= **Parameter** ============= ========= **fromDate** Datum, ab dem das Protokoll beginnen soll, optional, Format: "DD.MM.JJJJ" bzw. "DD.MM.JJJ HH:MM" (z.B. 01.01.2013 13:00). Uhrzeit ist im 24h Format und optional. **toDate** Datum, bei dem das Protokoll enden soll, optional, Format wie fromDate ============= ========= Mögliche Fehlerrückgaben ''''''''''''''''''''''''' ========= ============================== ====================================================== **Code** Infotext Erläuterung ========= ============================== ====================================================== **401** *...* |autherrors| ========= ============================== ====================================================== Beispiel ''''''''''' .. literalinclude:: files/api_response/getProtocols.xml :language: xml :lines: 1-20 :append: ... :encoding: utf-8 :download:`download ` Schema ''''''''''' Das zugehöriges XSD-Schema: :download:`protocols.xsd `. Erläuterungen: Elemente von "Entry" in "History" .................................... .. list-table:: :widths: 10 10 80 :header-rows: 1 * - Element - Attribut - Bedeutung * - **User** - - User, der die Aktion ausgelöst hat. Eindeutig über seine ID gekennzeichnet. Der name wird zu Kontrollzwecken ebenfalls mit ausgegeben. Dies ist immer der User selbst. * - **Action** - - Beschreibt die Aktion des Users in connect. Englischer Freitext für die einzelnen Aktionen. * - **Date** - - Datum und Uhrzeit im englischen YYYY-MM-DD HH:MM:SS. Format .. _connectschemes: Schemas ---------- Die XSD Schemas zur Validierung der in |connectcentername| eingestellten Dokumente werden ebenfalls über |connectcentername| ausgeliefert. getDocumentSchemes ```````````````````` Liefert eine Liste aller verfügbaren XSDs aus. ============================= ================================ Aufruf :api_url:`getDocumentSchemes/` ============================= ================================ Methoden **GET** Rückgabe XML-Liste der verfügbaren Schemes (encoding: utf-8) ============================= ================================ Diese Funktion ist auch ohne das connect kit direkt in |connectcentername| aufrufbar: :center_url:`getDocumentSchemes/`. Beispiel ''''''''''''' Rückgabe ............... .. literalinclude:: files/schemelist.xml :language: xml :encoding: utf-8 :download:`download ` Schema ''''''''''' Das zugehöriges XSD-Schema: :download:`schemelist.xsd `. Die möglichen Schema-Container sind *BusinessTransactions, Placements, Pricelist, Advertisement, DiscountScale, Targetings* und *Defines* (siehe :download:`schemelist.xsd `). Diese enthalten alle aktiven Versionen des jeweiligen Dokumenttypes. Im "**path**" Attribut steht die URL unter der das Schema abgerufen bzw. referenziert werden kann. Unterelemente der Schema-Container .................................... .. list-table:: :widths: 10 10 80 :header-rows: 1 * - Element - Attribut - Bedeutung * - **Version** - - Infos zur Version des Schemas * - Version - **number** - Offizielle Versionbezeichnung des Schemas. * - Version - **path** - Pfad unter dem das Schema abgerufen werden kann * - Version - **releaseDate** - Datum, an dem das Schema in connect eingestellt und freigegeben wurde. Im englischen YYYY-MM-DD Format.