Spezifikation

Hier möchten wir kurz und präzise alle Funktionen der Schnittstelle vorstellen.

Allgemeines:
Die Schnittstelle ist skriptbasiert, d.h. für jede wichtige Funktion wird eine eigenständige Datei bereitgestellt. Zugriff auf die Schnittstelle erfolgt durch Aufrufen von entsprechenden Dateien. Natürlich wird dafür ein Schnittstellenaccount benötigt, den Sie hier anmelden können. Unsere Software prüft beim Aufruf der jeweiligen Datei die angegebenen Parameter und gibt dann einen Rückgabecode sowie verschiedene zusätzliche Informationen im Textformat, getrennt durch das Zeichen "|".

Rückgabecodes:
1001 = Alles OK

1011 = Falsche Punkteart
1012 = Falsche Punkteanzahl (z.B. keine ganze Zahl oder negativ)
1013 = Betreff zu lang oder nicht angegeben

1021 = Falsche Schnittstellen-ID
1022 = Falsches Schnittstellen-Passwort
1023 = Zu wenig Punkte auf diesem Schnittstellenaccount
1024 = Falsche KennungsID
1025 = Keine Abfragen mehr auf dem Schnittstellenaccount
1026 = Zu viele fehlgeschlagene Login-Versuche über diesen Schnittstellenaccount oder IP-Adresse

1031 = Keine oder falsche UserID bzw. Usernamen angegeben
1032 = UserID UND Username angegeben, benötigt wird nur eins!
1033 = Kein oder falsches User-Passwort angegeben
1034 = Dieser User ist gesperrt
1035 = Das Guthaben des Users reicht nicht aus
1036 = Der User hat keine Berechtigung für die Nutzung der Transfer-Funktionen

1098 = Schnittstelle z.Z. nicht verfügbar (DB-Arbeiten o.ä.)
1099 = Unbekannter Fehler


Benötigte Parameter:
Parameter werden nacheinander nach dem Namen der entsprechenden Datei einfach aufgelistet ( ein ? davor), Trennung erfolgt mit dem Zeichen "&".
stid - ID des Schnittstellenaccounts
stpw - Passwort des Schnittstellenaccounts
a - Punkteart (1 für Besuchertausch, 2 für Mailtausch)
uun - Username des Users ...oder...
uid - ID des Users

Der Parameter a gibt die Art der verwendeten Punkte an. Das System verfügt über zwei unterschiedliche Punktearten, mit denen gearbeitet werden kann:
- die 1 steht für Besuchertauschpunkte
- die 2 steht für Mailtauschpunkte
Dieser Parameter beeinflusst die Art der transferierten Punkte sowie auch die Art der Punkteguthaben in der Rückgabe (User und Schnittstelle).

Die Parameter uun und uid ergänzen einander, d.h. es muss nur eins davon angegeben werden. Aus Optimierungsgründen wird die Fehlermeldung 1032 angezeigt, wenn beides angegeben wird (die Transaktion wird nicht ausgeführt, auch wenn alle anderen Daten korrekt sind!).

get.php
URL: http://st.ebesucher.de/get.php?

Funktion:
Zieht Punkte vom dem Account eines Users ab und schreibt sie dem Schnittstellenaccount gut (Transaktion: User->ST). Es müssen mind. 50 Punkte transferiert werden!!!

Zusätzliche Parameter:
upw - Schnittstellenpasswort des Users
k - KennungsID
p - Punkteanzahl (muss eine positive ganze Zahl sein)
b - Betreff der Abhebung (max. 40 Zeichen)

Rückgabeformat:
Rückgabecode|STPunkte|UserID|UserPunkte|kostenloseSTAnfragen|bezahlteSTAnfragen
// bei Fehler verschiedene Werte, ggf. -1

Beispielaufruf:
http://st.ebesucher.de/get.php?stid=123&stpw=test&uid=1234&upw=xxyy&k=1122&a=1&p=1000&b=Testing

send.php
URL: http://st.ebesucher.de/send.php?

Funktion:
Zieht Punkte vom dem Schnittstellenaccount und schreibt sie dem Account des angegebenen Users wieder gut (Transaktion: ST->User). Es müssen mind. 50 Punkte transferiert werden!!! Beim Aufruf ohne User-Passwort wird aus Sicherheitsgründen immer eine -1 für Userguthaben zurückgegeben.

Zusätzliche Parameter:
upw - Schnittstellenpasswort des Users (optional!!!)
k - KennungsID
p - Punkteanzahl (muss eine positive ganze Zahl sein)
b - Betreff der Gutschrift (max. 40 Zeichen)

Rückgabeformat:
Rückgabecode|STPunkte|UserID|UserPunkte|kostenloseSTAnfragen|bezahlteSTAnfragen
// bei Fehler verschiedene Werte, ggf. -1

Beispielaufruf:
http://st.ebesucher.de/send.php?stid=123&stpw=test&uid=1234&upw=xxyy&k=1122&a=1&p=1000&b=Testing

info.php
URL: http://st.ebesucher.de/info.php?

Funktion:
Gibt Informationen über den angegebenen User zurück (dies kann z.B. zur Überprüfung der Echtheit einer ID oder auch um die einem Usernamen zugehörige ID zu erfahren genutzt werden).

Zusätzliche Parameter:
upw - Schnittstellenpasswort des Users


Rückgabeformat:
Rückgabecode|STPunkte|UserID|UserPunkte|Signed|kostenloseSTAnfragen|bezahlteSTAnfragen
// bei Fehler verschiedene Werte, ggf. -1
// Signed = Anmeldungsdatum des Users

Beispielaufruf:
http://st.ebesucher.de/info.php?stid=123&stpw=test&uid=1234&upw=xxyy