connect liefert grundsätzlich XML zurück. Der Aufbau ist in den einzelnen API-Aufrufen erläutert. Darüber hinaus existieren folgende allgemeinen XML-Antworten.
<ConnectResponse status="0" transactionID="2">
<InfoText>received</InfoText>
</ConnectResponse>
Zugehöriges XSD-Schema: response.xsd.
| 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.
Die Kommunikation mit connect erfolgt verschlüsselt über das https Protokoll (Server-Side-Certificat).
Die Authentifizierung zwischen dem connect kit und connect erfolgt über Username/Passwort. Diese werden in den Einstellungen im connect kit (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.
| Code | Infotext |
|---|---|
| 401 | Kombination Username/Passwort stimmt nicht mit connect überein |
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 connect 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 | http://127.0.0.1:8888/api/getOVKParticipants/ |
|---|---|
| Methoden | GET |
| Rückgabe | XML-Liste der User (encoding: utf-8) |
| Code | Infotext | Erläuterung |
|---|---|---|
| 401 | ... | Bei einem Authentifizierungsproblem sind grundsätzlich die unter Authentifizierung aufgeführten Antworten möglich. |
<?xml version="1.0" encoding="UTF-8"?><Users created="2015-10-23 12:1:13">
<User>
<ovkparticipantid>2_NOOVK</ovkparticipantid>
<name>Vermarkter 1</name>
<type>publisher</type>
<publicKeyId>0010_38fdf73b1d580ce5b749b5117fe0d05f</publicKeyId>
<publicKey>
<RSAKeyValue>
<Modulus>zPiAsHBTH5A1O4AZjefBpcXVPUiZHmelZSyM5BD3IOkrD2GlPmB6ETVskQ+FdbWowG7zMdMqGGQxuCZgKpREM1xtJiR/4TzDJ3O8SDZ6JKcLB2vVhpvBl3WnasbdmwpLF+5K9cYZbeprR9thWks1YTbXJJFibxODeh8beEhLizs=</Modulus>
<Exponent>AQAB</Exponent>
</RSAKeyValue>
</publicKey>
<localcenter/>
<Schemes>
<Pricelists>
<Version>1.2</Version>
</Pricelists>
...
Das zugehöriges XSD-Schema: OVKParticipants.xsd. Erläuterungen:
| Element | Attribut | Bedeutung |
|---|---|---|
| created | Zeitpunkt und Datum an dem diese Auflistung generiert wurde. | |
| ovkparticipantid | ID des Users in connect. Diese ID entspricht der OVKParticipantsID. | |
| name | Name des Users im connect center. | |
| type | Der Typ des Users. Es gibt die Typen “publisher” (= Vermarkter) und “user” ( = Alle anderen User wie z.B. Agenturen) | |
| Schemes | Dokument Schemas, die der User unterstützt. Die Schemas der in connect genutzten Dokumente sind unter Schemas abrufbar. Der connect User setzt seine unterstützen Schemas über die Einstellungen in seinem connect kit (siehe 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. |
Ruft ab, welche Aktionen im Konto des Users in einem gegebenen Zeitraum ausgeführt wurden
| Aufruf | http://127.0.0.1:8888/api/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 |
| Code | Infotext | Erläuterung |
|---|---|---|
| 401 | ... | Bei einem Authentifizierungsproblem sind grundsätzlich die unter Authentifizierung aufgeführten Antworten möglich. |
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<History>
<Entry>
<User>
<id>955555</id>
<name>COM_Vermarkter</name>
</User>
<Action>Offer for User</Action>
<Date>2013-10-10 09:25:52.0</Date>
</Entry>
<Entry>
<User>
<id>955555</id>
<name>COM_Vermarkter</name>
</User>
<Action>Read XML from userbox (Inventory)</Action>
<Date>2013-11-28 11:22:26.0</Date>
</Entry>
...
Das zugehöriges XSD-Schema: protocols.xsd. Erläuterungen:
| 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 |
Die XSD Schemas zur Validierung der in connect eingestellten Dokumente werden ebenfalls über connect ausgeliefert.
Liefert eine Liste aller verfügbaren XSDs aus.
| Aufruf | http://127.0.0.1:8888/api/getDocumentSchemes/ |
|---|---|
| Methoden | GET |
| Rückgabe | XML-Liste der verfügbaren Schemes (encoding: utf-8) |
Diese Funktion ist auch ohne das connect kit direkt in connect aufrufbar: https://connectcentertest.agof.de/getDocumentSchemes/.
<Schemes>
<BusinessTransaction>
<Version number="1.4.1" path="https://connectcenterqs01.agof.de/xsd/businesstransaction/v1.4.1/BusinessTransaction.xsd" releaseDate="2014-07-04"/>
</BusinessTransaction>
<Placements>
<Version number="1.4.1" path="https://connectcenterqs01.agof.de/xsd/placements/v1.4.1/Placements.xsd" releaseDate="2014-07-04"/>
</Placements>
<Pricelist>
<Version number="1.4.1" path="https://connectcenterqs01.agof.de/xsd/pricelist/v1.4.1/Pricelist.xsd" releaseDate="2014-07-04"/>
</Pricelist>
<Advertisement>
<Version number="1.4.1" path="https://connectcenterqs01.agof.de/xsd/advertisement/v1.4.1/Advertisement.xsd" releaseDate="2014-07-04"/>
</Advertisement>
<Defines>
<Version number="1.4.1" path="https://connectcenterqs01.agof.de/xsd/defines/v1.4.1/Defines.xsd" releaseDate="2014-07-04"/>
</Defines>
</Schemes>
Das zugehöriges XSD-Schema: schemelist.xsd.
Die möglichen Schema-Container sind BusinessTransactions, Placements, Pricelist, Advertisement, DiscountScale, Targetings und Defines (siehe 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.
| 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. |