PDF-Datei - TicketPRINTER

TicketPRINTER-API
PLANinterNET GmbH
15. Januar 2004
Zusammenfassung
Diese Dokument berschreibt die Programmierschnittstelle für Anwendungen (API)
des TicketPRINTER-Systems. Die meisten Funktionen werden per HTTP über ihre
URL aufgerufen. Diese Anleitung richtet sich also an Leser, die mit dem TicketPRINTERSystem und dem Protokoll HTTP vertraut sind.
Inhaltsverzeichnis
1 Systembestandteile
3
2 Schnittstellen zur Veranstaltungsdatenbank
3
2.1
mySQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3
2.2
API-Funktion (HTTP / HTTPS) . . . . . . . . . . . . . . . . . . . . . . .
4
3 Aufruf der API-Funktionen
4
4 Funktionen zum individuellen Ticketkauf, Warenkorbverwaltung
4
4.1
getbasket(ip) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5
4.2
addtobasket(handle,rid,gid,zid,fid) . . . . . . . . . . . . . . . . . . . . . .
5
4.3
delfrombasket(handle,rid,gid,zid) . . . . . . . . . . . . . . . . . . . . . . .
5
4.4
putpaydata(handle,...) . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5
4.5
sendseccode(handle,via) . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5
4.6
buy(handle) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6
5 Ticketkauf durch Vorverkaufsstellen
1
6
6 Sonstige Funktionen
6
6.1
getstate(rid,gid,zids) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6
6.2
setstate(rid,gid,zids,status)
. . . . . . . . . . . . . . . . . . . . . . . . . .
7
6.3
getbarcode(ticketcode,format) . . . . . . . . . . . . . . . . . . . . . . . . .
7
6.4
getticket(ticketcode,format) . . . . . . . . . . . . . . . . . . . . . . . . . .
7
6.5
query extern(table,rid, ...) . . . . . . . . . . . . . . . . . . . . . . . . . . .
7
6.6
query handles(rid,gid,bezahl parameter,wert) . . . . . . . . . . . . . . . .
7
6.7
resend basket(rid,gid,handle) . . . . . . . . . . . . . . . . . . . . . . . . .
7
6.8
query ticket(rid,gid,ticketcode) . . . . . . . . . . . . . . . . . . . . . . . .
8
6.9
refund ticket(rid,gid,ticketcode) . . . . . . . . . . . . . . . . . . . . . . . .
8
7 Tabellen-Definitionen
8
7.1
Tabelle veranstalter
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9
7.2
Tabelle platzstatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9
7.3
Tabelle veranstaltungen . . . . . . . . . . . . . . . . . . . . . . . . . . . .
10
7.4
Tabelle belegungsplaene . . . . . . . . . . . . . . . . . . . . . . . . . . . .
10
7.5
Tabelle tarifgruppen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
10
7.6
Tabelle preisgruppen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
11
7.7
Tabelle tarife . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
11
7.8
Tabelle preise . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
11
7.9
Tabelle plaetze . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
12
2
1
Systembestandteile
Das TicketPRINTER-System besteht aus drei Bestandteilen:
Veranstaltungsdatenbank: Sie beinhaltet sämtliche Daten der Veranstaltungen eines
oder mehrerer Veranstalter, außer den Belegungszustand der Plätze. Die Datenbank
muß mindestens eine der unter 2 aufgeführten Schnittstellen aufweisen, damit die
anderen Systembestandteile auf sie zugreifen können. 7 beschreibt die Tabellen, die
in dieser Datenbank enthalten sein müssen.
TicketPRINTER-Kern: Er verwaltet die Veranstalter mit den Zugangsdaten auf die
Veranstaltungsdatenbanken und den Belegungszustand der Plätze. Außerdem koordiniert er sämtliche Verkaufs-, Bezahl- und Ticketversandvorgänge. Tickets werden
in der Regel per Email versandt. Nur falls der Verkauf durch eine registrierte Vorverkaufsstelle erfolgt, wird das Ticket unmittelbar durch die API übermittelt.
Anwendung (z.B. auf Webserver): Sie verwenden die API und Datenbankschnittstellen, um das TicketPRINTER-System den Endnutzern, den Ticketkäufern, zugänglich zu machen.
Der TicketPRINTER-Kern ist unveränderbarer Bestandteil des Systems und wird auf den
Webservern von PLANinterNET betrieben. Einblick und Zugriff ist nur mittels der API
oder durch Anwendungen von PLANinterNET möglich.
Die anderen Bestandteile können auf Wunsch eines Veranstalters für dessen Veranstaltungen von ihm selbst oder von Dritten realisiert werden. Die nötigen Schnittstellen definiert
dieses Dokument.
2
Schnittstellen zur Veranstaltungsdatenbank
Es sind derzeit zwei Protokolle zum Zugriff auf die Datenbanken definiert. Die Veranstalterdatenbank muß mindestens eine von beiden aufweisen. Die kleine Datenbank im
TicketPRINTER-Kern (Veranstalter-Grunddaten und Belegungszustand der Plätze) weist
beide auf.
Beide Schnittstellen sollten nur lesenden Zugriff erlauben.
2.1
mySQL
Falls die Daten in einer mySQL-Datenbank verwaltet werden, kann über das mySQLeigene Netzprotokoll auf die Datenbank zugegriffen werden. Es ist allerdings dringend zu
empfehlen, daß der Datentransport über das Internet per SSL gesichert wird.
Zwecks SSL-Transport können entweder die modernen SSL-Optionen von mySQL 4 verwendet werden oder die Portredirektfunktion von SSH, wofür bei Bedarf ein Useraccount
auf dem betreffenden Linuxsystem zur Verfügung gestellt wird.
3
2.2
API-Funktion (HTTP / HTTPS)
Hier werden die Daten in einer sehr einfachen QueryLanguage angefordert und als quasiCSV-Datei zurückgegeben. Hierbei handelt es sich um 8-bit-ASCII-Daten mit \n (newline)
oder \r\n (carriage retrun + newline) als Zeilentrenner und \t (Tab) als Spaltentrenner.
Also stehen als Nutzdaten alle 8-bit-ASCII-Zeichen bis auf Tab, Newline und CarriageReturn zur Verfügung. Die Zeichen werden gemäß ISO 8859-1 (Latin1) interpretiert.
Die Daten werden angefordert über eine URL der Art:
http(s)://dbuser:passwd@dbhost/dbname?table=<Tabelle>&primary key1=<Key1>&...
dbname ist virtuell zu verstehen und darf auch die Zeichen ‘/’ und ‘.’ enthalten, um einen
cgi-Aufruf oder ein PHP-Skript oder dergleichen samt Pfad zu bezeichnen.
Im Falle der Minidatenbank im TicketPRINTER-Kern ist dies:
http(s)://ticket-printer.de/interface/query.php?table=veranstalter&rid=<rid>
oder ...?table=platzstatus&rid=<rid>&gid=<gid>&zid=<zid>
Dies entspricht einer URL der nachfolgend beschriebenen API und wäre in deren Syntax
zu schreiben als: query(table,key1,...).
Als Argumente sind jeweils der Tabellenname und alle Primärschlüsselbestandteile dieser
Tabelle anzugeben. Die Primärschlüssel der meisten Tabellen enthalten die Felder rid
(Veranstalter-ID) und gid (Veranstaltungs-ID).
3
Aufruf der API-Funktionen
Die API-Funktionen des TicketPRINTER-Kerns lassen sich per HTTP(S) aufrufen unter
URLs der Art:
http(s)://ticket-printer.de/interface/<funktion>.php?<par1>=<wert1>&...
Um diesen Aufruf nachfolgend vereinfacht darzustellen, wird er als geschrieben als:
<function>(par oder wert1, par· oder wert2, ...) wie im vorigen Kapitel die Funktion query(table, key1, ...).
Die Funktionsantwort hat dasselbe Format wie unter 2.2 beschrieben. Antworten von
variabler Zeilenanzahl werden bei fehlerfreier Ausführung mit einem ‘.’ in einer Zeile für
sich abgeschlossen. Evtl. Fehler werde durch entsprechende Fehlermeldungen beschrieben
und meist mit einem ‘!’ eingeleitet.
4
Funktionen zum individuellen Ticketkauf, Warenkorbverwaltung
Inidvidueller Ticketkauf meint hier: nicht über Vorverkaufsstellen.
4
4.1
getbasket(ip)
Als ip sollte die IP-Adresse des Ticketkäufers übergeben werden, um bei Betrug im Zusammenhang mit dem Bezahlvorgang ermitteln zu können.
Rückgabe: Handle, eine ganze Zahl, die ein 10-ziffriges Einmalpaßwort enthält. Dieses
Handle kann die Anwendung auch an anderen Stellen verwenden, um auf unschöne Techniken wie Cookies oder eine IP-basierte Identifikation verzichen zu können.
Beispiel: https://ticket-printer.de/interface/getbasket.php?ip=1.2.3.4
4.2
addtobasket(handle,rid,gid,zid,fid)
Die Parameter sind das Warenkorbhandle und Primärschlüsselbestandteile der Tabellen
tarife und platzstatus.
Rückgabe: Inhalt des Warenkorbs mit den Spalten rid, gid, zid, fid, preis, vvgebuehr,
verfall. preis und vvgebuehr stammen aus der Tabelle preise. Die Tickets im Warenkorb werden nur 10 Minuten reserviert, um das mißbräuchliche blockieren zu verhindern.
Um nur den Inhalt des Warenkorbs zu erhalten, können die hinteren Parameter der Funktion auch auf 0 gesetzt werden.
4.3
delfrombasket(handle,rid,gid,zid)
S.o.! Entfernt ein Ticket aus dem Warenkorb.
4.4
putpaydata(handle,...)
Diese Funktion speichert Daten für den Zahlungsverkehr und kann dazu auch mehrere
Male aufgerufen werden. Als Parameter stehen zur Verfügung und sollten sich weitgehend
selbst erklären: vorname, nachname, strasse, land, plz, ort, tel, fax, mobil,
email, kdnr, bezahlart, ktinhaber, ktnummer, blz, gueltig bis jahr, gueltig bis monat.
Welche Parameter nötig oder sinnvoll sind, hängt vom verwendeten Bezahlsystem ab. Als
Bezahlart sind die Kürzel ec (Lastschrift, Einzug vom Girokonto), kk (Kreditkarte), eg
(e-gold), ue (Vorauskasse per Giroüberweisung), vs (Vorauskasse per Verrechnungsscheck)
und rg (auf Rechnung) vorgesehen.
4.5
sendseccode(handle,via)
Sendet einen 5-ziffrigen Sicherheitscode via email, fax oder sms an den Ticketkäufer.
Dieser Code muß dann per buy(...) (s.u.) übergeben werden, damit die Tickets gekauft
5
werden können. Die Email- oder SMS-Nummer wird im TicketPRINTER-Kern gespeichert
und kann im Betrugsfall bei der Ermittlung helfen.
Optional können die Parameter from und shop übergeben werden, um die Email, die SMS
oder das Fax zu gestalten.
4.6
buy(handle)
Führt den Kartenkauf durch, falls alle Daten vollständig und korrekt vorliegen.
Optional können die Parameter seccode (s.o.) und min übergeben werden. min gibt an,
wieviele Karten des Warenkorbes mindestens noch verfügbar sein müssen, um den Kartenkauf durchzuführen. Wird min nicht angegeben, müssen alle Karten verfügbar sein,
sonst schlägt der Kauf fehl.
Rückgabe: Gekaufte Tickets, Beschreibung je eines pro Zeile, Spalten: rid,gid,zid,handle,seccode.
5
Ticketkauf durch Vorverkaufsstellen
Um den Verkauf durch Vorverkaufsstellen abzuwickeln, werden diesselben Funktionen wie
für Individuen außer seccode() verwendet.
Außerdem hat putpaydata() andere Agrgumente, nämlich: handle, reseller id, reseller passwd.
buy() gibt als letzte Spalte statt des seccode den 24-stelligen, chiffrierten ticketcode
zurück.
6
6.1
Sonstige Funktionen
getstate(rid,gid,zids)
rid, gid, zid sind Primärschlüsselbestandteile der Tabelle platzstatus. zids ist eine
durch ‘,’ (oder andere Trenner) getrennte Liste von zid. Diese Funktion ermittelt den
Status einer Liste von Plätzen.
Rückgabe: Liste mit Spalten zid, status. Bedeutung von Status:
0: Platz frei
1: Platz nicht verfügbar (VIP-Reservierung, ...)
2: Platz kurzzeitig reserviert
3: Platz verkauft
6
6.2
setstate(rid,gid,zids,status)
Wie geststate (s.o.), nur daß mit state ein gewünschter Status gesetzt wird. Plätze mit
Status 2 oder 3 können mit dieser Funktion den Status nicht ändern.
6.3
getbarcode(ticketcode,format)
Wandelt einen ticketcode in einen Barcode. format ist png, pdf, eps. R ückgabe:
Grafik in dem gewünschten Format.
6.4
getticket(ticketcode,format)
Wie getbarcode, nur daß das fertige Ticket zurückgegeben wird.
6.5
query extern(table,rid, ...)
Liest aus der Veranstalterdatenbank, auch wenn diese auf externen Rechnern liegt, also
nicht bei der Datenbank des TicketPRINTER-Kerns. Als Parameter sind der Tabellennamen und der komplette Primärschlüssel zu übergeben. rid ist der Primärschlüssel der
Tabelle veranstalter.
Diese Funktion dient nur zu Testzwecken, um externe Implementationen der Veranstaltungsdatenbank und deren Schnittstelle zu testen.
Achtung, mit dieser Funktion lassen sich ohne Mühe gefährliche Endlosschleifen zwischen
zwei Webservern programmieren!
6.6
query handles(rid,gid,bezahl parameter,wert)
Sucht anhand eines Wertes, die bei früheren Einkäufen mit putpaydata() eingegeben
wurde (z.B. die Emailadresse) nach passenden Handles. Diese Funktion wird z.B. benötigt,
wenn eine Email verloren ging und ein Warenkorb neu per Email zugesandt werden soll
(s.u.).
rid, gid sind Primärschlüsselbestandteile der Tabelle veranstaltung.
Achtung, das Handle enthält kein Einmalpaßwort mehr und ist deshalb entsprechend
kürzer als während des Kaufvorganges!
6.7
resend basket(rid,gid,handle)
Sendet eine Email mit Tickets aus einem Warenkorb nochmals. Aus Sicherheitsgr ünden
kann die Emailadresse nicht geändert werden. Das handle läßt sich mit query handles()
7
(s.o.) ermitteln.
rid, gid sind Primärschlüsselbestandteile der Tabelle veranstaltung.
6.8
query ticket(rid,gid,ticketcode)
Erfragt sämtliche Informationen über ein Ticket.
rid, gid sind Primärschlüsselbestandteile der Tabelle veranstaltung.
Rückgabe: Liste mit Spalten rid,gid,zid,sid,fid,pid,preis,vvgebuehr,ibid,gueltig,
die den Spallten der Tabellen der Veranstaltungsdatenbank entsprechen.
gueltig gibt an, ob daß Ticket noch gültig ist. Ungültig ist ein Ticket, nach dem zurückgegeben wurde (s.u.).
sid ist eine Seriennummer. Jeder Platz, der zum ersten mal verkauft wird, erhält die
Seriennummer 0. Wird das Ticket zurückgegeben, erhält der Platz die Seriennummer 1
und kann erneut verkauft werden usw..
ibid ist eine Referenz auf den betreffenden Datensatz im Bezahlsystem.
6.9
refund ticket(rid,gid,ticketcode)
Entwertet ein Ticket und veranlaßt die Erstattung des Ticketpreises, nicht jedoch der
Vorverkaufsgebühr. Parameter wie bei query ticket() (s.o.).
Rückgabe: Erstattungsbetrag in Cent.
7
Tabellen-Definitionen
Veranstalter oder deren Dienstleister, die die Veranstaltungsdatenbank für den TicketPRINTER für ihre Veranstaltungen selbst implementieren wollen, müssen dabei die nachfolgend aufgeführten Tabellen, außer veranstalter und platzstatus vorsehen. Die Tabellen können beliebig viele weitere, hier nicht erwähnte Spalten aufweisen. Die hier spezifierten Spalten müssen jedoch vorhanden sein.
2 beschreibt den Zugriff auf diese Tabellen von jeweils anderen Systembestandteilen innerhalb des TicketPRINTER-Systems.
8
7.1
Tabelle veranstalter
Diese Tabelle ist im TicketPRINTER-Kern implementiert und würde in der Veranstaltungsdatenbank nicht berücksichtigt.
Spalten:
Ps Name
∗ rid
veranstalter
zahlmodi
dgib
dbtyp
dbhost
dbname
dbuser
dbpasswd
7.2
Definition
int not null
varchar(255) not null
varchar(255) not null
varchar(20) not null
varchar(5) not null
varchar(255) not null
varchar(255) not null
varchar(255) not null
varchar(255) not null
Beschreibung
Veranstalter-ID
Name des Veranstalters
erlaubte Bezahlmethoden
DGiB-Nummer des Veranstalters
z.B. mysql, https, ...
nur intern lesbar
Tabelle platzstatus
Diese Tabelle ist im TicketPRINTER-Kern implementiert und würde in der Veranstaltungsdatenbank nicht berücksichtigt.
Spalten:
Ps Name
∗ rid
∗ gid
∗ zid
status
release
handle
Definition
int not null
int not null
int not null
tinyint not null
int not null
int not null
Beschreibung
Veranstalter-ID
Veranstaltungs-ID
Platz-ID
s. API-Funktion getstate()
(interne Verwendung)
(interne Verwendung)
9
7.3
Tabelle veranstaltungen
Spalten:
Ps Name
∗ rid
∗ gid
veranstaltung
unti1
unti2
ort
beginn
ende
vvbeginn
vvende
bid
tid
lid
7.4
Definition
int not null
int not null
varchar(255) not null
varchar(255) not null
varchar(255) not null
varchar(255) not null
datetime not null
datetime
datetime not null
datetime not null
int not null
int not null
int not null
Beschreibung
Veranstalter-ID
Veranstaltungs-ID
Name der Veranstaltung
Untertitel 1
Untertitel 2
Vorverkaufsbeginn
Belegungsplan-ID (Saalplan o.ä.)
Tarifgruppen-ID
Ticketlayout-ID
Tabelle belegungsplaene
Saalpläne, Sitzpläne, o.ä. die den einzelnen Veranstaltungen zugeordnet werden können.
Spalten:
Ps Name
∗ rid
∗ bid
belegungsplan
7.5
Definition
int not null
int not null
varchar(255) not null
Beschreibung
Veranstalter-ID
Belegungsplan-ID
Name des Belegungsplanes
Tabelle tarifgruppen
Eine Tarifgruppe hier ist die Gruppe aller Preise, die einer Veranstaltung zugeordnet
sind. Viele Veranstalter haben teure und preiswerte Veranstaltungen. Dies wird durch
verschiedene Tarifgruppen abgebildet.
Innerhalb einer Tarifgruppe kann es verschiedene Preise geben, etwa für teure und preiswerte Plätze oder verschiedene Tarife für Senioren, Schüler usw.. S.a. Tabelle preise!
Spalten:
Ps Name
∗ rid
∗ tid
tarifgruppe
Definition
int not null
int not null
varchar(255) not null
Beschreibung
Veranstalter-ID
Tarifgruppen-ID
Name der Tarifgruppe
10
7.6
Tabelle preisgruppen
Eine Preisgruppe hier ist die Gruppe der verschiedenen Preise der Plätze des Belegungsplanes. Viele Veranstaltungen haben teure Plätze und preiswerte Plätze. Dies wird durch
verschiedene Preisgruppen abgebildet.
Innerhalb einer Preisgruppe kann es verschiedene Preise geben, etwa für teure und preiswerte Veranstaltungen oder verschiedene Tarife für Senioren, Schüler usw.. S.a. Tabelle
preise!
Spalten:
Ps Name
∗ rid
∗ pid
preisgruppe
7.7
Definition
int not null
int not null
varchar(255) not null
Beschreibung
Veranstalter-ID
Preisgruppen-ID
Name der Preisgruppe
Tabelle tarife
Ein Tarif entspricht einer Veranstaltungsbesuchergruppe. Z.B. ein Tarif für Senioren, einer
für Schüler und ein Normaltarif.
Innerhalb eines Tarifes kann es verschiedene Preise geben, etwa für teure und preiswerte
Veranstaltungen oder für teure und preiswerte Plätze. S.a. Tabelle preise!
Spalten:
Ps Name
∗ rid
∗ fid
tarif
7.8
Definition
int not null
int not null
varchar(255) not null
Beschreibung
Veranstalter-ID
Tarif-ID
Name des Tarifs
Tabelle preise
Diese Tabelle definiert die Preise und Vorverkaufsgebühren
bei einer bestimmten tarifgruppe (Veranstaltungskategorie)
auf einer bestimmten preisgruppe (Platzkategorie)
für einen bestimmten tarif (Besuchergruppe).
Spalten:
Ps Name
∗ rid
∗ tid
∗ pid
∗ fid
preis
vvgebuehr
Definition
int not null
int not null
int not null
int not null
int not null
int not null
Beschreibung
Veranstalter-ID
Tarifgruppen-ID
Preisgruppen-ID
Tarif-ID
Preis in Eurocent
Vorverkaufsgebühr in Eurocent
11
7.9
Tabelle plaetze
Diese Tabelle definiert, welche Plätze bei welchem belegungsplan tatsächlich existieren
und legt neben weiteren Details fest, zu welcher preisgruppe sie gehören.
Spalten:
Ps Name
∗ rid
∗ bid
∗ zid
pid
platz
reihe
platznummer
Definition
int not null
int not null
int not null
int not null
varchar(255)
int not null
int not null
Beschreibung
Veranstalter-ID
Belegungsplan-ID
Platz-ID
Preisgruppen-ID
Name des Platzes, falls sinnvoll
Reihennummer, falls zutreffend
ggf. Platznummer innerhalb der Reihe
platz, reihe, platznummer darf frei interpretiert werden und dient lediglich zur Beschriftung des Tickets.
12