WhitePaper

XMLRPC Schnittstelle

GUTSCHEINmarketing

Version 1.0.0

- Stand 18.03.2004 -

Umfang: 30 Seiten

© copyright 4D f/x, 2004
4D f/x Kommunikationsservice
Hauptstr.2
82229 Seefeld
Deutschland

Einleitung

Dieses Papier beschreibt die XMLRPC-Schnittstelle von www.gutscheinmarketing.de, die zur direkten Serverkommunikation dient. Dabei werden die not­wendigen Schritte zu einem Verbindungsaufbau beschrieben. Zusätzlich werden die derzeit verfügbaren Methoden erörtert.

Weitere Informationen zu XMLRPC finden sich unter http://www.xmlrpc.com.

Die Spezifikationen sind zu finden unter http://www.xmlrpc.com/spec.

Um einen schnellen Einstieg zu gewährleisten, steht eine XMLRPC-Client-Klasse unter GPL zur Verfügung. Diese ist momentan in PHP verfügbar und ist nicht Gegenstand dieses Dokumentes. Eine Übertragung nach Java stellt kein Hindernis dar und wird vorgenommen, sobald eine entsprechende Resonanz vorhanden ist.

[zurück]  [Inhalt]

1.Verbindungsaufbau

1.1.Voraussetzungen

Um eine Verbindung zum XMLRPC-Service von www.gutscheinmarketing.de aufbauen zu können, bedarf es einer Zugangskennung und eines Passwortes. Diese können nach Belieben (so weit nicht bereits vergeben) gewählt werden und müssen mit www.gutscheinmarketing.de abgestimmt werden.

Im Gegensatz zu den sonst in anderen Quellen beschriebenen Verfahren, werden Kennung und Passwort nicht für eine http-Authentisierung verwendet.

Aus Sicherheitsgründen findet eine Authentisierung mittels Zufallsschlüssel und beidseitig bekanntem Geheimnis statt.

Bei entsprechechender Resonanz (und Sponsoring) ist eine weitere Möglich­keit mittels gnuPG implementierbar.

Jeder am Service teilnehmende Server erhält eine eindeutige Kennung sowie ein nur dem Service und dem jeweiligen Server bekanntes Passwort. Dieses ist durch geeignete Schutzmassnahmen auf den Servern sicher zu hin­terlegen.

In diesem Papier wird für die Beispiele folgende Serverkennung mit dem Passwort gewählt:

Definition: userid: test-server

Definition: password: supergeheim

Das Passwort sollte auf dem Server als md5-Hash-Wert hinterlegt werden und nur berechtigten Personen und dem entsprechenden Prozeß zugänglich sein. Wir verwenden im Weiteren statt des Passwortes den md5-Hash-Wert:

Definition: secret :=md5(passwort)

[zurück]  [Inhalt]

1.1.1.URL

Um den XMLRPC-Service von www.gutscheinmarketing.de zu erreichen ist die URL

service.gutscheinmarketing.de

anzuwählen.

[zurück]  [Inhalt]

1.1.2.URI

Um die in diesem Papier beschriebenen Methoden aufrufen zu können, muss auf die URI

/valueserver/index.php

zugegriffen werden.

[zurück]  [Inhalt]

1.1.3.Benutzerkennung

Die Benutzerkennung (userid) ist eine eindeutige Adresse für www.gutscheinmarketing.de, die festlegt

1. welche Gutschein-Bereiche abgefragt werden können;

2. welche IP-Adressen für diese Abfrage autorisiert sind. Dabei können neben singulären Adressen, Adressebereiche sowie der gesamte, verfügbare Adressraum berücksichtigt werden.

[zurück]  [Inhalt]

1.1.4.Passwort

Beim Passwort (password) handelt es sich um ein Geheimnis, dass nur beiden Servern, mit den entsprechend dazu berechtigten Personen, bekannt sein sollte. Dieses ist in der Form auf dem Server zu hinterlegen, das nur die berechtigte Person und der entsprechende Service darauf Zugriff haben. Es ist empfehlenswert, statt des Passwortes in Klartext, den md5-Hash-Wert (secret) des selbigen auf dem Server zu hinterlegen und den Klartext an anderer Stelle geeignet zu verwahren.

[zurück]  [Inhalt]

1.1.5.Authentisieren

Zur Authentisierung wird das beiden Seiten bekannte Geheimnis mit einem übermittelten Zufallswert geeignet verrechnet. Entspricht die Antwort nicht dem erwarteten Ergebnis wird eine Verbindung abgelehnt.

[zurück]  [Inhalt]

1.1.6.Client

Sämtliche Methoden-Aufrufe basieren auf einem vorhandenen Client-Objekt. Das Vorgehen dazu ist abhängig von der verwendeten Programmiersprache. Mögliche Lösungen finden sich unter
http://www.xmlrpc.com/directory/1568/implementations.

[zurück]  [Inhalt]

1.2.Schematischer Aufbau

Um eine gültige Verbindung zum XMLRPC-Service von www.gutscheinmarketing.de aufzubauen, müssen folgenden Schritte eingehalten werden:

1. Verbindungskanal öffnen oder initialisieren mit Nennung des Benutzers.

2. Den Benutzer ausweisen oder authentisieren.

3. Schließen des Verbindungskanal.

[zurück]  [Inhalt]

1.2.1.Verbindungskanal öffnen/initialisieren

Zum Öffnen des Verbindungskanals wird die Benutzerkennung (userid) an die Methode openChannel unter der URI /valueserver/index.php auf dem Server mit der URL service.gutscheinmarketing.deals string geschickt.

Ist die Benutzerkennung bekannt, wird eine sessionid als string zurückgeliefert.
Diese sessionid ist Voraussetzung für jede weitere Kommunikation!
No sessionid no communication!

Ist die Benutzerkennung nicht bekannt oder kann nicht von der vorhandenen IP-Adresse zugegriffen werden, erfolgt eine Fehlermeldung entsprechend XMLRPC-Standard.

Parameter	Value	Type
Methode	openChannel
Werte	userid	string
Response success	sessionid	string
error	errorcode	int
	errormsg	string
URI	/valueserver/index.php
URL	service.gutscheinmarketing.de

Tabelle 1: openChannel(string)

Call:

<?xml version="1.0"?>
<methodCall>
   <methodName>openChannel</methodName>
   <params>
      <param>
         <value><string>userid</string></value>
      </param>
   </params>
</methodCall>

Response success:

<?xml version="1.0"?>
<methodResponse>
   <params>
      <param>
         <value><string>sessionid</string></value>
      </param>
   </params>
</methodResponse>

Response error:

<?xml version="1.0"?>
<methodResponse>
   <fault>
      <value>
         <struct>
            <member>
               <name>faultCode</name>
               <value><int>errorcode</int></value>
            </member>
            <member>
               <name>faultString</name>
               <value><string>errorstring</string></value>
            </member>
         </struct>
      </value>
   </fault>
</methodResponse>

Mögliche Fehlercodes und -meldungen finden sich unter 3. Fehlercodes. Um eine lokalisierte Fehlermeldung zu erhalten wird die Methode getLocalMessage aufgerufen.

[zurück]  [Inhalt]

1.2.1.1.Gültigkeit sessionid

Für das weitere Vorgehen ist eine gültige sessionid notwendig und Voraussetzung!

Eine sessionid ist für eine Zeitdauer von 1 Stunde gültig.

Daher wird dringend empfohlen, jede nicht mehr benötigte Verbindung zum Abschluss zu beenden! (s. 1.2.3 Schließen des Verbindungskanals)

[zurück]  [Inhalt]

1.2.2.Benutzer ausweisen/authentisieren

Als nächstes muss der Benutzer ausgewiesen werden. Dazu wird der md5-verrechnete Wert der String-Konkatenation aus sessionid und secret (d.h. md5(password)) zusammen mit der sessionid an die Methode authenticate unter der URI /valueserver/index.php auf dem Server mit der URL service.gutscheinmarketing.de als string geschickt.

Entspricht der übertragene Wert dem vom Server vorausberechneten, d.h. wird der Benutzer richtig ausgewiesen wird der Integerwert 1 zurückgegeben.

Kann eine gültige Authentiserung nicht durchgeführt werden, weil entweder die sessionid oder der berechnete Wert fehlen oder falsch sind, erfolgt eine entsprechende Fehlermeldung.

Definition: expected := md5(concat(sessionid,secret))

Parameter	Value	Type
Methode	authenticate
Werte	sessionid	string
	expected	string
Response success	'1'	int
error	errorcode	int
	errormsg	string
URI	/valueserver/index.php
URL	service.gutscheinmarketing.de

Tabelle 2: authenticate(string,string)

Call:

<?xml version="1.0"?>
<methodCall>
   <methodName>authenticate</methodName>
   <params>
      <param>
         <value>
		<array>
		   <data>
			<value><string>sessionid</string></value>
			<value><string>expected</string></value>
		   </data>
		</array>
	   </value>
      </param>
   </params>
</methodCall>

Response success:

<?xml version="1.0"?>
<methodResponse>
   <params>
      <param>
         <value><int>1</int></value>
      </param>
   </params>
</methodResponse>

Response error:

<?xml version="1.0"?>
<methodResponse>
   <fault>
      <value>
         <struct>
            <member>
               <name>faultCode</name>
               <value><int>errorcode</int></value>
            </member>
            <member>
               <name>faultString</name>
               <value><string>errorstring</string></value>
            </member>
         </struct>
      </value>
   </fault>
</methodResponse>

Mögliche Fehlercodes und -meldungen finden sich unter 3. Fehlercodes. Um eine lokalisierte Fehlermeldung zu erhalten wird die Methode getLocalMessage  aufgerufen.

[zurück]  [Inhalt]

1.2.3.Schließen des Verbindungskanals

Bedingt durch die Gültigkeit der sessionid von einer Stunde ist es notwendig, jede nicht mehr benötigte Verbindung zu schließen. Dies entspricht auch gutem Programmierstil.

Dazu wird die Methode close unter der URI /valueserver/index.php auf dem Server mit der URL service.gutscheinmarketing.de mit der sessionid als string aufgerufen.

Kann die Verbindung beendet werden wird der Integerwert 0 zurückgegeben.

Parameter	Value	Type
Methode	close
Werte	sessionid	string
Response success	'0'	int
error
URI	/valueserver/index.php
URL	service.gutscheinmarketing.de

Tabelle 3: close(string)

Call:

<?xml version="1.0"?>
<methodCall>
   <methodName>close</methodName>
   <params>
      <param>
	   <value><string>sessionid</string></value>
      </param>
   </params>
</methodCall>

Response success:

<?xml version="1.0"?>
<methodResponse>
   <params>
      <param>
         <value><int>0</int></value>
      </param>
   </params>
</methodResponse>

[zurück]  [Inhalt]

2.Methoden

Die XMLRPC-Schnittstelle von www.gutscheinmarketing.de stellt grundsätzlich Methoden zur Verfügung, für die eine Benutzer-Authentizierung (entsprechend 1. Verbindungsaufbau) notwendig ist.

Die Ausnahmen werden in 2.3 beschrieben.

[zurück]  [Inhalt]

2.1.Allgemeines Vorgehen

Zunächst wird eine geeignetes XMLRPC-Client-Objekt erzeugt. Das Vorgehen dazu ist abhängig von der verwendeten Programmiersprache. Mögliche Lösungen finden sich unter http://www.xmlrpc.com/directory/1568/implementations.

Eine speziell optimierte PHP-Klasse für den Zugriff stellt www.gutscheinmarketing.de unter GPL zur kostenlosen und freien Verfügung. Weitere Angaben dazu und eine Beschreibung finden sich unter ####.

[zurück]  [Inhalt]

2.1.1.Schemata

Das Schaubild verdeutlicht die Vorgehensweise.

[zurück]  [Inhalt]

2.1.2.Verbindungsaufbau

Mit dem erzeugtem XMLRPC-Client wird eine Verbindung zum XMLRPC-Service von www.gutscheinmarketing.de mit der URL service.gutscheinmarketing.de und der URI /valueserver/index.php aufgebaut. Die Beschreibung dazu findet sich unter 1.2.1 Verbindungskanal öffnen.

Als Ergebnis eines erfolgreichen Verbindungsaufbaues wird eine Sessionkennung (sessionid) zurückgegeben. Diese Sessionkennung ist Voraussetzung für jede weitere Kommunikation.

No sessionid no communication!

[zurück]  [Inhalt]

2.1.3.Authentisieren

Nach erfolgreichem Verbindungsaufbau muss der Benutzer authentisiert werden. Dazu wird ein beidseitiges Geheimnis mit einem Zufallswert verechnet und zusammen mit der Sessionkennung an den XMLRPC-Service gesendet. Die Beschreibung dazu findet sich unter 1.2.2 Benutzer ausweisen.

Eine erfolgreiche Anmeldung ist Voraussetzung um die weiteren Methoden aufrufen zu können.

[zurück]  [Inhalt]

2.1.4.Methodenaufrufe

Ist die Anmeldung erfolgreich durchgeführt, können Methoden in beliebiger Anzahl und Reihenfolge aufgerufen werden. Diese Methoden liefern entweder ein gültiges Ergebnis oder eine Fehlermeldung.

Mögliche Fehlercodes und -meldungen finden sich unter 3. Fehlercodes. Um eine lokalisierte Fehlermeldung zu erhalten wird die Methode getLocalMessage aufgerufen.

[zurück]  [Inhalt]

2.1.5.Verbindung schließen

Wird eine Verbindung nicht mehr benötigt, sollte diese immer geschlossen werden. Die Beschreibung dazu findet sich unter 1.2.3 Schließen des Verbindungskanals.

[zurück]  [Inhalt]

2.2.Methoden nur mit Authentisierung

Im folgenden werden Methoden beschrieben, die nur nach einer erfolgreichen Authentisierung aufgerufen werden können.

[zurück]  [Inhalt]

2.2.1.isValidCoupon

Die Methode liefert den Booleschen Wert von true, wenn der zusammen jeweils als string mit der Sessionkennung (sessionid) übermittelte Gutscheincode couponid gültig ist. Ein Gutscheincode wird als gültig ausgewiesen, wenn

1. der Gutschein aktiviert wurde, d.h. persönliche Angaben wurden ergänzt oder bestätigt und der Gutschein wurde an den Empfänger per Email versendet;

2. der aktivierte Gutschein noch nicht anderweitig eingelöst wurde.

3. das für den Gutschein definierte Verfallsdatum noch nicht überschritten ist.

Ansonsten erfolgt eine Fehlermeldung.

Parameter	Value	Type
Methode	isValidCoupon
Werte	sessionid	string
	couponid	string
Response success	True	boolean
error	errorcode	int
	errormsg	string
URI	/valueserver/index.php
URL	service.gutscheinmarketing.de

Tabelle 4: isValidCoupon(string,string)

Call:

<?xml version="1.0"?>
<methodCall>
   <methodName>isValidCoupon</methodName>
   <params>
      <param>
         <value>
		<array>
		   <data>
			<value><string>sessionid</string></value>
			<value><string>couponid</string></value>
		   </data>
		</array>
	   </value>
      </param>
   </params>
</methodCall>

Response success:

<?xml version="1.0"?>
<methodResponse>
   <params>
      <param>
         <value><boolean>1</boolean></value>
      </param>
   </params>
</methodResponse>

Response error:

<?xml version="1.0"?>
<methodResponse>
   <fault>
      <value>
         <struct>
            <member>
               <name>faultCode</name>
               <value><int>errorcode</int></value>
            </member>
            <member>
               <name>faultString</name>
               <value><string>errorstring</string></value>
            </member>
         </struct>
      </value>
   </fault>
</methodResponse>

Mögliche Fehlercodes und -meldungen finden sich unter 3. Fehlercodes. Um eine lokalisierte Fehlermeldung zu erhalten wird die Methode getLocalMessage aufgerufen.

[zurück]  [Inhalt]

2.2.2.getCouponValues

Die Methode liefert als XMLRPC-Struktur die Werte für einen gültigen Gutschein mit der Gutscheinnummer couponid zurück. Dazu muss jeweils die Sessionkennung sessionid und die Gutscheinnummer couponid als string an die Methode gesendet werden.

Die Struktur der Antwort ist bei vorhandenem und gültigen Gutscheincode abhängig vom Gutschein.

Ist ein Gutscheincode nicht gültig wird eine Fehlermeldung zurückgegeben.

Parameter	Value	Type
Methode	isValidCoupon
Werte	sessionid	string
	couponid	string
Response success	Siehe nächste Kapitel
error	errorcode	int
	errormsg	string
URI	/valueserver/index.php
URL	service.gutscheinmarketing.de

Tabelle 5: getCouponValues(string,string)

Call:

<?xml version="1.0"?>
<methodCall>
   <methodName>isValidCoupon</methodName>
   <params>
      <param>
         <value>
		<array>
		   <data>
			<value><string>sessionid</string></value>
			<value><string>couponid</string></value>
		   </data>
		</array>
	   </value>
      </param>
   </params>
</methodCall>

Response error:

<?xml version="1.0"?>
<methodResponse>
   <fault>
      <value>
         <struct>
            <member>
               <name>faultCode</name>
               <value><int>errorcode</int></value>
            </member>
            <member>
               <name>faultString</name>
               <value><string>errorstring</string></value>
            </member>
         </struct>
      </value>
   </fault>
</methodResponse>

Mögliche Fehlercodes und -meldungen finden sich unter 3. Fehlercodes. Um eine lokalisierte Fehlermeldung zu erhalten wird die Methode getLocalMessage aufgerufen.

[zurück]  [Inhalt]

2.2.2.1.getCouponValues bei geldwertem Vorteil

Diese Antwort wird gegeben, wenn der übertragene Gutscheincode einem Geldwertgutschein zugeordnet ist.

Key	Value	Type
type	money	string
price	[cdata]	double
currency	[cdata]	string
invoicetext	[cdata]	string
minimumorder	[cdata]	double
validuntil	[cdata]	dateTime.iso8601

Response success:

<?xml version="1.0"?>
<methodResponse>
   <params>
	<param>
	   <value><struct>
		<member>
		   <name>type</name>
		   <value><string>money</string></value>
		</member>
		<member>
		   <name>price</name>
		   <value><double>[cdata]</double></value>
		</member>
		<member>
		   <name>currency</name>
		   <value><string>[cdata]</string></value>
		</member>
		<member>
		   <name>invoicetext</name>
		   <value><string>[cdata]</string></value>
		</member>
		<member>
		   <name>minimumorder</name>
		   <value><double>[cdata]</double></value>
		</member>
		<member>
		   <name>validuntil</name>
		   <value><dateTime.iso8601>[cdata]</dateTime.iso8601></value>
		</member>
	   </struct></value>
	</param>
   </params>
</methodResponse>

[zurück]  [Inhalt]

2.2.2.2.getCouponValues bei Warenwert

Diese Antwort wird gegeben, wenn der übertragene Gutscheincode einem Warenwertgutschein zugeordnet ist.

Key	Value	Type
type	goods	string
quantity	[cdata]	double
article	[cdata]	string
invoicetext	[cdata]	string
minimumorder	[cdata]	double
validuntil	[cdata]	dateTime.iso8601

Response success:

<?xml version="1.0"?>
<methodResponse>
   <params>
	<param>
	   <value><struct>
		<member>
		   <name>type</name>
		   <value><string>goods</string></value>
		</member>
		<member>
		   <name>quantity</name>
		   <value><double>[cdata]</double></value>
		</member>
		<member>
		   <name>article</name>
		   <value><string>[cdata]</string></value>
		</member>
		<member>
		   <name>invoicetext</name>
		   <value><string>[cdata]</string></value>
		</member>
		<member>
		   <name>minimumorder</name>
		   <value><double>[cdata]</double></value>
		</member>
		<member>
		   <name>validuntil</name>
		   <value><dateTime.iso8601>[cdata]</dateTime.iso8601></value>
		</member>
	   </struct></value>
	</param>
   </params>
</methodResponse>

[zurück]  [Inhalt]

2.2.2.3.getCouponValues bei Rabattgutschein

Diese Antwort wird gegeben, wenn der übertragene Gutscheincode einem Rabattgutschein zugeordnet ist.

Key	Value	Type
type	percent	string
percent	[cdata]	double
invoicetext	[cdata]	string
minimumorder	[cdata]	double
validuntil	[cdata]	dateTime.iso8601

Response success:

<?xml version="1.0"?>
<methodResponse>
   <params>
	<param>
	   <value><struct>
		<member>
		   <name>type</name>
		   <value><string>percent</string></value>
		</member>
		<member>
		   <name>percent</name>
		   <value><double>[cdata]</double></value>
		</member>
		<member>
		   <name>invoicetext</name>
		   <value><string>[cdata]</string></value>
		</member>
		<member>
		   <name>minimumorder</name>
		   <value><double>[cdata]</double></value>
		</member>
		<member>
		   <name>validuntil</name>
		   <value><dateTime.iso8601>[cdata]</dateTime.iso8601></value>
		</member>
	   </struct></value>
	</param>
   </params>
</methodResponse>

[zurück]  [Inhalt]

2.2.3.lockCoupon

Diese Methode sperrt einen Gutschein, wenn die Einlösung erfolgreich war, z.B. wenn ein Bestellvorgang durch Zahlung abgeschlossen werden soll. Dazu wird an die Methode die Sessionkennung sessionid und der gültige Gutscheincode couponid jeweils als string gesendet.

Kann der Gutschein erfolgreich gesperrt werden wird eine Kennung zurückgegeben. Diese Kennung kann dazu verwendet werden, um den Gutschein gegebenenfalls wieder zu entsperren, falls der Kunde z.B. die Bestellung storniert oder den Zahlvorgang abbricht (!).

Optional kann ein eigener Kommentar (z.B. eine OrderId oder eine Kundennummer) als string der Methode mit übermittelt werden. Dieser Wert ist momentan ohne besondere Bedeutung, könnte aber in Zukunft z.B. für eine Suchfunktionalität herangezogen werden.

Kann ein Gutschein nicht gesperrt werden, so liegt dies daran, dass parallel der Gutschein durch einen anderen Vorgang gesperrt wurde. In diesem Fall wird eine Fehlermeldung zurückgegeben. Etwaige Rechnungskorrekturen sind geeignet vorzunehmen.

Parameter	Value	Type
Methode	lockCoupon
Werte	sessionid	string
	couponid	string
	comment (optional)	string
Response success	trackid	string
error	errorcode	int
	errormsg	string
URI	/valueserver/index.php
URL	service.gutscheinmarketing.de

Tabelle 6: lockCoupon(string,string) oder lockCoupon(string,string,string)

Call ohne Kommentar:

<?xml version="1.0"?>
<methodCall>
   <methodName>isValidCoupon</methodName>
   <params>
      <param>
         <value>
		<array>
		   <data>
			<value><string>sessionid</string></value>
			<value><string>couponid</string></value>
		   </data>
		</array>
	   </value>
      </param>
   </params>
</methodCall>

Call mit Kommentar:

<?xml version="1.0"?>
<methodCall>
   <methodName>isValidCoupon</methodName>
   <params>
      <param>
         <value>
		<array>
		   <data>
			<value><string>sessionid</string></value>
			<value><string>couponid</string></value>
			<value><string>comment</string></value>
		   </data>
		</array>
	   </value>
      </param>
   </params>
</methodCall>

Response success:

<?xml version="1.0"?>
<methodResponse>
   <params>
      <param>
         <value><string>[cdata]</string></value>
      </param>
   </params>
</methodResponse>

Response error:

<?xml version="1.0"?>
<methodResponse>
   <fault>
      <value>
         <struct>
            <member>
               <name>faultCode</name>
               <value><int>errorcode</int></value>
            </member>
            <member>
               <name>faultString</name>
               <value><string>errorstring</string></value>
            </member>
         </struct>
      </value>
   </fault>
</methodResponse>

Mögliche Fehlercodes und -meldungen finden sich unter 3. Fehlercodes. Um eine lokalisierte Fehlermeldung zu erhalten wird die Methode getLocalMessage aufgerufen.

[zurück]  [Inhalt]

2.2.4.unlockCoupon

Diese Methode gibt einen gesperrten Gutschein wieder frei. Dazu muss der Methode jeweils als string die Sessionkennung sessionid, der Gutscheincode couponid und der Transaktionscode der Sperrung trackid übergeben werden.

Kann der Gutschein entsperrt werden und damit für eine erneute Einlösung freigegeben werden, wird ein Transaktionscode für diesen Vorgang als string zurückgegeben.

Optional kann ein eigener Kommentar (z.B. eine OrderId oder eine Kundennummer) als string der Methode mit übermittelt werden. Dieser Wert ist momentan ohne besondere Bedeutung, könnte aber in Zukunft z.B. für eine Suchfunktionalität herangezogen werden.

Kann ein Gutschein nicht freigegeben werden, wird eine Fehlermeldung zurückgegeben. Dafür kann es unterschiedliche Ursachen geben:

1. die Transaktionskennung fehlt oder ist falsch;

2. der Gutscheincode entspricht nicht dem bei der Sperrung oder fehlt. Aus Sicherheitsgründen wird auf eine gesonderte Meldung dafür verzichtet.

Parameter	Value	Type
Methode	unlockCoupon
Werte	sessionid	string
	couponid	string
	trackid	string
	comment (optional)	string
Response success	trackid	string
error	errorcode	int
	errormsg	string
URI	/valueserver/index.php
URL	service.gutscheinmarketing.de

Tabelle 7: unlockCoupon(string,string,string) oder lockCoupon(string,string,string,string)

Call ohne Kommentar:

<?xml version="1.0"?>
<methodCall>
   <methodName>isValidCoupon</methodName>
   <params>
      <param>
         <value>
		<array>
		   <data>
			<value><string>sessionid</string></value>
			<value><string>couponid</string></value>
			<value><string>trackid</string></value>
		   </data>
		</array>
	   </value>
      </param>
   </params>
</methodCall>

Call mit Kommentar:

<?xml version="1.0"?>
<methodCall>
   <methodName>isValidCoupon</methodName>
   <params>
      <param>
         <value>
		<array>
		   <data>
			<value><string>sessionid</string></value>
			<value><string>couponid</string></value>
			<value><string>trackid</string></value>
			<value><string>comment</string></value>
		   </data>
		</array>
	   </value>
      </param>
   </params>
</methodCall>

Response success:

<?xml version="1.0"?>
<methodResponse>
   <params>
      <param>
         <value><string>[cdata]</string></value>
      </param>
   </params>
</methodResponse>

Response error:

<?xml version="1.0"?>
<methodResponse>
   <fault>
      <value>
         <struct>
            <member>
               <name>faultCode</name>
               <value><int>errorcode</int></value>
            </member>
            <member>
               <name>faultString</name>
               <value><string>errorstring</string></value>
            </member>
         </struct>
      </value>
   </fault>
</methodResponse>

Mögliche Fehlercodes und -meldungen finden sich unter 3. Fehlercodes. Um eine lokalisierte Fehlermeldung zu erhalten wird die Methode getLocalMessage aufgerufen.

[zurück]  [Inhalt]

2.3.Methoden ohne Authentisierung

Diese Methodenaufrufe sind Gutscheinunabhängig und liefern Informationen zu den Methoden oder lokalisierte Fehlermeldungen.

[zurück]  [Inhalt]

2.3.1.system.listMethods

Diese Methode ohne weitere Parameter aufgerufen liefert eine Liste aller vom XMLRPC-Service angebotenen Methoden.

Parameter	Value	Type
Methode	system.listMethods
Werte
Response success	alle verfügbaren Methoden	string[]
URI	/valueserver/index.php
URL	service.gutscheinmarketing.de

Tabelle 8: system.listMethods()

Call:

<?xml version="1.0"?>
<methodCall>
   <methodName>system.listMethods</methodName>
   <params>
   </params>
</methodCall>

Response:

<?xml version="1.0"?>
<methodResponse>
   <params>
	<param>
	   <value>
		<array><data>
		   <value><string>openChannel</string></value>
		   <value><string>authenticate</string></value>
		   <value><string>close</string></value>
			.
			.
			.
		   <value><string>system.listMethods</string></value>
		   <value><string>system.methodHelp</string></value>
		 <value><string>system.methodSignature</string></value>
		</data></array>
	   </value>
	</param>
   </params>
</methodResponse>

[zurück]  [Inhalt]

2.3.2.system.methodHelp

Diese Methode liefert den zu einer mittels string übermittelten Methode methode vorhandenen Erklärungstext helptext in englisch.

Wird die Methode nicht gefunden, wird eine Fehlermeldung zurückgegeben.

Parameter	Value	Type
Methode	system.methodHelp
Werte	methode	string
Response success	helptext	string
error	errorcode	int
	errormsg	string
URI	/valueserver/index.php
URL	service.gutscheinmarketing.de

Tabelle 9: system.methodHelp(string)

Call:

<?xml version="1.0"?>
<methodCall>
   <methodName>system.methodHelp</methodName>
   <params>
      <param>
	   <value><string>methode</string></value>
      </param>
   </params>
</methodCall>

Response success:

<?xml version="1.0"?>
<methodResponse>
   <params>
      <param>
         <value><string>[cdata]</string></value>
      </param>
   </params>
</methodResponse>

Response error:

<?xml version="1.0"?>
<methodResponse>
   <fault>
      <value>
         <struct>
            <member>
               <name>faultCode</name>
               <value><int>errorcode</int></value>
            </member>
            <member>
               <name>faultString</name>
               <value><string>errorstring</string></value>
            </member>
         </struct>
      </value>
   </fault>
</methodResponse>

Mögliche Fehlercodes und -meldungen finden sich unter 3. Fehlercodes. Um eine lokalisierte Fehlermeldung zu erhalten wird die Methode getLocalMessage aufgerufen.

[zurück]  [Inhalt]

2.3.3.system.methodSignature

Diese Methode liefert die zu einer mittels string übermittelten Methode methode vorhandenen Signaturen als Array.

Wird die Methode nicht gefunden, wird eine Fehlermeldung zurückgegeben.

Parameter	Value	Type
Methode	system.methodSignature
Werte	methode	string
Response success	signatures	string[]
error	errorcode	int
	errormsg	string
URI	/valueserver/index.php
URL	service.gutscheinmarketing.de

Tabelle 10: system.methodSignature(string)

Call:

<?xml version="1.0"?>
<methodCall>
   <methodName>system.methodSignature</methodName>
   <params>
      <param>
	   <value><string>methode</string></value>
      </param>
   </params>
</methodCall>

Response success:

<?xml version="1.0"?>
<methodResponse>
   <params>
	<param>
	   <value><array>
		<data>
		   <value><array>
			<data>
				<value><string>[cdata]</string></value>
				   .
				   .
				   .
			</data>
		   </array></value>
		   [<value><array> ... </array></value>]
		       .
		       .
		       .
		   [<value><array> ... </array></value>]
		</data>
	   </array></value>
	</param>
   </params>
</methodResponse>

Response error:

<?xml version="1.0"?>
<methodResponse>
   <fault>
      <value>
         <struct>
            <member>
               <name>faultCode</name>
               <value><int>errorcode</int></value>
            </member>
            <member>
               <name>faultString</name>
               <value><string>errorstring</string></value>
            </member>
         </struct>
      </value>
   </fault>
</methodResponse>

Mögliche Fehlercodes und -meldungen finden sich unter 3. Fehlercodes Um eine lokalisierte Fehlermeldung zu erhalten wird die Methode getLocalMessage aufgerufen.

[zurück]  [Inhalt]

2.3.4.getLocalMessage

Diese Methode liefert den zu einer Meldung mit der Kennung id vom Typ type entsprechend der Landeskennung locale vorhandenen Text oder eine Fehlermeldung, wenn eine entsprechende Übersetzung nicht vorhanden ist.

Derzeit werden deutsch (de_DE) und englisch (en_US) unterstützt. Eine Übersetzung in andere Sprachen, kann bei Anforderung jederzeit erfolgen.

Parameter	Value	Type
Methode	getLocalMessage
Werte	type	string
	id	int
	locale	string
Response success	signatures	string[]
error	errorcode	int
	errormsg	string
URI	/valueserver/index.php
URL	service.gutscheinmarketing.de

Tabelle 11: getLocalMessage(string,int,string)

Call:

<?xml version="1.0"?>
<methodCall>
   <methodName>getLocalMessage</methodName>
   <params>
      <param>
	   <value><string>type</string></value>
	   <value><int>id</int></value>
	   <value><string>locale</string></value>
      </param>
   </params>
</methodCall>

Response success:

<?xml version="1.0"?>
<methodResponse>
   <params>
      <param>
         <value><string>[cdata]</string></value>
      </param>
   </params>
</methodResponse>

[zurück]  [Inhalt]

2.3.4.1.Übersetzung einer Fehlermeldung

Um eine Fehlermeldung in einer entsprechend anderen Landessprache zu erhalten (soweit Übersetzung vorliegt) wird die Methode getLocalMessage mit dem Typ

type := error

und dem entsprechenden Fehllercode errorcode und der Landeskennung entsprechend ISO aufgerufen.

[zurück]  [Inhalt]

3.Fehlercodes

Bereich	Fehlerursache
<199	allgemeine XMLRPC-Fehler
201-799	allgemeine XML-Fehler
801-999	XMLRPC-Service-Fehlermeldung von www.gutscheinmarketing.de
>1001	Fehlermeldung des XMLRPC-Client

[zurück]  [Inhalt]

3.1.Allgemeine XMLRPC-Fehler

Fehlerwert	Beschreibung
1	Unbekannte Methode
2	Ungültiger Rückgabewert: schalten Sie in den Debug-Modus ("?debug=1") um die Rückgabewerte zu kontollieren
3	Ungültige Parameter an Methode übergeben
4	Kann nicht prüfen: Methode unbekannt
5	Kein 200 OK vom Server empfangen

[zurück]  [Inhalt]

3.2.Allgemeine XML-Fehler

t.b.d

[zurück]  [Inhalt]

3.3.XMLRPC-Service-Fehlermeldung

Fehlerwert	Beschreibung
801	Benutzer unbekannt
802	Keine gültige Anmeldung
803	Keine gültige Verbindung
804	Kein gültiger Gutschein
805	Gutschein bereits eingelöst durch anderen Server
806	Keinen Gutschein zum Freigeben gefunden oder Gutschein bereits freigegeben

[zurück]  [Inhalt]

3.4.Fehlermeldung des XMLRPC-Client

Fehlerwert	Beschreibung
1001	Kein Benutzer angegeben
1002	Kein Geheimnis angeben
1003	Keine Gutscheinnummer oder Gutscheinnummer ist leer oder NULL
1004	Kein gültiger Gutschein
1005	Keine gültige Session oder Session nicht initialisiert

[zurück]  [Inhalt]

4.Tabellenverzeichnis