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