Foratable - Bookapi

Workflow Reservationprozess

Situation

Mit der Api lässt sich komplett einen Reservationsprozess implementieren d.h damit lässt sich ein eigenes Reservationsfenster programmieren.

1. Initialisieren

Im ersten Schritt initialisiert man den Reservationsprozess mit der Methode initReservation. Die Rückgabe beiinhaltet den request_hash, der für alle weiter API-Calls dieser Reservation benötigt wird.
Des weiteren beinhaltet die Rückgabe Information zum Restaurant(Name, Adresse etc) sowie die Essenszeiten der ganzen Woche.

2. Tisch

Sobald der Gast Datum, Zeit und Anzahl Personen bestimmt hat muss die Methode setTable aufgerufen werden um zu überprüfen ob zu diesem Zeitpunkt überhaupt eine Reservation möglich ist.

Im Erfolgsfall kommt in der Antwort neben status=ok auch choice=[active|inactive]. Ist choice active sollte als nächstes das Auswahlfenster angezeigt werden.

3. Auswahl / Kommentar

In der Antwort der Intialisierung wurde ist bestimmt on des Restaurant ein Kommentar erlaubt und ob es eine Auswahl gibt. Dieser Schriitt muss nur gemacht werden wenn ein Kommentarfenster angeboten wird oder die ausgewählte Zeit/Datum sich in der Auswahl Zeit/Datum befindet. Mmit der Methode setChoice kann die Auswahl und der Kommentar gesetzt werden.

4. Gast

Danach gibt der Gast seine Angaben(Name/Vorname/e-Mail/Mobile)an. Mit der Methode setGuest werden diese Daten der API übermittelt. Ist der Gast schon bei forAtable registriert wird die Reservation automatisch ausgelöst.
Ist der Gast unbekannt oder er ist schon mit einer anderen Mobile Nr oder e-Mail registriert wird dem Gast eine SMS mit einem viersteligen Code gesendt.

5. Code überprüfen

Der per SMS erhaltene Code muss von Gast eingeben werden und dann mit der Method verifyCode der API übermittelt werden. Ist der Code korrekt wird die Reservation ausgelöst.

Workflow Zeit, Datum und Anzahl Personen am Reservationsfenster übermittlen

Situation

Datum, Zeit und Anzahl Personen werden auf der Seite des Gatronnomen erfasst.
Foratable stellt im Moment dafür kein Widget bereit. Dieses muss also vom Gastrom slebst programmiert werden.
Das Reservationsfenster wird dann per POST aufgerufen(mitgegeben wird Datum, Zein und Personenanzahl) und der Gast landet im Reservationsfenster in der entsprechenden Stelle wo er dann den Reservationsprozess fortsetzen kann.

1. Restaurant Information

Mit der Api-Methode getRestaurantInfo. lassen sich die Restaurant relevanten Information beziehen.

2. Ins Reservations springen

Die Daten müssen per POST dem Reservationsfenster übermittelt werden. Das sollte in einem neuen Fenster geschehenn. Der Gast befindet sich danch im Reservationsfenster, also auf foratable.com.
Unter der Pseudo Api-Methode Direct ist das beschrieben und kann dort getestet werden.

Api Methoden

Die Bookapi gibt die Antwort als JSON. Alle Daten werden per POST übermittelt. Ist die Anfrage erfolgreich wird der status = ok zurückgegeben. Bei Misserfolg status = error. Die einzelnen Error Meldungen sind unter der jeweiligen Methode aufgelistet

initReservation

Beschreibung:

Initialisiert den Reservationsprozess und gibt bei Erfolg den Request-Hash zurück, welcher beim weitern Verlauf des Reservationsprozess benötigt wird.
Des weiteren werden Daten zum Restaurant zurückgeben geben und sowie die Zeiten für welche einen Tisch reserviert werden kann am heutigen Tag

Error Messages

Status	Message	Long-Message
error	invalid_restaurant_hash	Ungültiger Restaurant Hash
error	incorrect_login	Ungültiges Api-User Login. Entweder E-Mail oder Passwort falsch
error	blocked	Zur Zeit ist keine Reservation möglich! Für dieses Restaurant wurde das System von Foratable gesperrt.
error	not_enabled	Das Reservationssystem ist momentan nicht aktiviert. Bitte versuchen Sie es telefonisch unter der Nr. %s. Vielen Dank!
error	closed	An diesem Tag ist das Restaurant geschlossen!
error	holiday	Zur Zeit ist leider keine Reservation möglich! Das Restaurant ist heute geschlossen und kann keine Reservationen entgegennehmen. Wir bitten um Verständnis.
error	no_intime	Zur Zeit sind leider keine Online-Reservationen über das Reservationssystem möglich! Bitte versuchen Sie es direkt per Telefon oder später noch einmal.

setRoom

Beschreibung:

Error Messages

Status	ErrorNr.	Message	Long-Message
error	21	invalid_request_hash	Ungültiger Request Hash.
error	22	expired_request_hash	Request Hash ist abgelaufen(Gültigkeit 1Stunde)
error	24	room_not_exists

getTimesOfDate

Beschreibung:

Error Messages

Status	ErrorNr.	Message	Long-Message
error	21	invalid_request_hash	Ungültiger Request Hash.
error	22	expired_request_hash	Request Hash ist abgelaufen(Gültigkeit 1Stunde)

setTable

Beschreibung:

Mit dieser Methode werden die Daten(Datum, Zeit,Anzahl Personen) übergeben. Es wird geprüft ob zu diesem Zeitpunkt für die Anzahl Personen überhaupt reserviert werden kann kann.

Zürückgeben wird die Eigenschaft choice welche den Wert active oder inactive hat. Das darauffolgende Auswahlfenster soll nur bei active angezeigt werden

Ok Messages(status=ok)

Property	Message	Description
choice	active	Auswahl aktiv
choice	inactive	Auswahl inaktiv(Wird nicht angezeigt)
choice_display	dropdown\|radio	Bestimmt die Darstelung der Auswahl. Wird nur zurückgegeben wenn die Auswahl aktiv ist

Error Messages

Status	ErrorNr.	Message	Long-Message
error	21	invalid_request_hash	Ungültiger Request Hash.
error	22	expired_request_hash	Request Hash ist abgelaufen(Gültigkeit 1Stunde)
error	31	day_is_holiday	An diesem Tag hat das Restaurant Betriebsferien
error	32	day_is_closed	An diesem Tag hat das Restaurant geschlossen
error	33	no_person_telefon	Unser Kontingent für Online Reservationen ist zu diesem Zeitpunkt leider aufgebraucht. Heute können keine telefonische Anfragen entgegen genommen werden da wir geschlossen haben.
error	34	no_past	Datum darf nicht in der Vergangenheit liegen!
error	35	no_past_time	Zeit darf nicht in der Vergangenheit liegen!
error	36	not_lunch	Das Restaurant %s kann für diesen Mittag keine Buchungen entgegennehmen. Sie können jedoch gerne ein anderes Datum wählen oder telefonisch direkt eine Anfrage starten: %s
error	37	not_dinner	Das Restaurant %s kann für diesen Abend keine Buchungen entgegennehmen. Sie können jedoch gerne ein anderes Datum wählen oder telefonisch direkt eine Anfrage starten: %s
error	40	nomore_person	Für den gewünschten Zeitpunkt sind leider keine Online-Reservationen über das Reservationssystem möglich Bitte kontaktieren Sie das Restaurant direkt: %s
error	41	only_person	Für den gewünschten Zeitpunkt sind leider keine Online-Reservationen über das Reservationssystem möglich Bitte kontaktieren Sie das Restaurant direkt: %s
error	42	only_persons	Für den gewünschten Zeitpunkt sind leider keine Online-Reservationen über das Reservationssystem möglich Bitte kontaktieren Sie das Restaurant direkt: %s
error	43	too_much_people	Es kann nur für maximal %s Plätze reserviert werden
error	45	no_event_capacity	Für den gewünschten Zeitpunkt sind leider keine Online-Reservationen über das Reservationssystem möglich Bitte kontaktieren Sie das Restaurant direkt: %s
error	49	no_res_time	An diesem Tag stehen keine Tische zur Verfügung. Sie können jedoch gerne ein anderes Datum wählen oder telefonisch direkt eine Anfrage starten: %s
error	61	invalid_promocode	Der Promo-Code ist ungültig.

Beschreibung:

Mit dieser Methode lässt sich die Auswahl setzen. Diese Methode muss nach der Methode setTable aufgerufen werden

setChoice

Error Messages

Status	ErrorNr.	Message	Long-Message
error	21	invalid_request_hash	Ungültiger Request Hash.
error	22	expired_request_hash	Request Hash ist abgelaufen(Gültigkeit 1Stunde)
error	62	choice_disabled	The choice Feature is disabled
error	63	choice_not_set	The choice Feature is not set

setGuest

Beschreibung:

Die Daten des Gastes werden geprüft. Ist der Gast schon registriert im System wird die Reservation aus gelöst. Ist der Gast unbekannt oder die E-Mail und die Moobile Nummer stimmen nicht überein wird dem Gast ein SMS mit einem Verifizierungs Code geschickt.

Ok Messages(status=ok)

StatusNr.	Message	Description
1	verify_code	Gast bekommt ein SMS mit dem Verifizierungs Code
2	reservation_done	Reservation wurde erfolgreich ausgelöst. Da der Gast bekommt ist wurde die Reservation direkt ausgelöst antstatt ihme ein Verfizierungscode zuschicken

Error Messages

Status	ErrorNr.	Message	Long-Message
error	21	invalid_request_hash	Ungültiger Request Hash.
error	22	expired_request_hash	Request Hash ist abgelaufen(Gültigkeit 1Stunde)
error	6	not_valid_email	Ungültige E-Mail Adresse
error	5	wrong_euromobile	Die Telefonnummer ist im falschen Format. Zur Zeit nur mit europäischen und amerikanischen Mobilnummern möglich.
error	91	not_status_1	Die Angaben des Zeitpunkt der Tischbuchung wurden noch nicht übermittelt. Bitte zuerst setTable ausführen
error	95	res_allready_done	Die Reservationsanfrage wurde schon ausgelöst. Haben Sie Geduld.

verifyCode

Beschreibung:

Der Code welcher der Gast per SMS bekommen hat wird auf Übereinstimmung geprüft. Ist der Code richtig wird die Reservation ausgelöst.

URL	https://foratable.com//bookapi2/verifyCode
METHOD	post
RESPONSE	json
Post Fields:
request_hash *
code *

Ok Messages(status=ok)

StatusNr.	Message	Description
2	reservation_done	Reservation wurde erfolgreich ausgelöst. Da der Gast bekommt ist wurde die Reservation direkt ausgelöst antstatt ihme ein Verfizierungscode zuschicken

Error Messages

Status	ErrorNr.	Message	Long-Message
error	21	invalid_request_hash	Ungültiger Request Hash.
error	22	expired_request_hash	Request Hash ist abgelaufen(Gültigkeit 1Stunde)
error	7	wrong_code	Der SMS Code ist falsch
error	8	no_code	Für diesen Request wurde im System noch keinen Code hinterlegt. Bitte zuerst die Methode setGuest aufrufen.
error	92	not_status_2	Die Angaben des Gastes wurden noch nicht übermittelt. Bite zuerst setGuest ausführen
error	95	res_allready_done	Die Reservationsanfrage wurde schon ausgelöst. Haben Sie Geduld.

newCode

Beschreibung:

Mit dieser Methode kann ein weiteres SMS mit dem Verfizierungs-Code an den Gast versendet werden. Da es vorkommen kann, dass eine SMS nicht ankommt, kann man dem Gast optional anbieten einen neuen Code anzufordern.

Error Messages

Status	ErrorNr.	Message	Long-Message
error	21	invalid_request_hash	Ungültiger Request Hash.
error	22	expired_request_hash	Request Hash ist abgelaufen(Gültigkeit 1Stunde)
error	92	not_status_2	Die Angaben des Gastes wurden noch nicht übermittelt. Bite zuerst setGuest ausführen

Beschreibung:

Mit dieser Methode kann man die Sprache der Reservation setzen. Die Meldungen der Api sind dann in der gesetzten Sprache und die Bestätigung(SMS und/oder E-Mail)

setLanguage

Error Messages

Status	ErrorNr.	Message	Long-Message
error	21	invalid_request_hash	Ungültiger Request Hash.
error	22	expired_request_hash	Request Hash ist abgelaufen(Gültigkeit 1Stunde)
error	29	incorrect_language	Ungültige Sprache

setFeedback

Beschreibung:

Nachdem der Gast in einem Restaurant gegessen hat bekommt er ein E-Mail mit einem Link um das Feedback abzugeben. Mit dieser Methode kann ein Feedback abgegeben werden zu einer bestimmten Reservation.

Error Messages

Status	ErrorNr.	Message	Long-Message
error	23	invalid_reservation_hash	Ungültiger Reservation Hash. Es kann kein Feedback abgegeben werden
error	51	feedback_not_updated	Feedback wurde nicht geändert
error	52	feedback_not_allowed	Feedback kann nicht mehr geändert werden!

getReservation

Beschreibung:

Damit kann man die Daten zu einer Reservation holen.Jede Reservation hat einen Status:
1: Ok(Telefonanruf angenommen)
2: Error(telefon abgelehnt)
3: Error(Telefonanruf technisch fehlgeschlagen)
4: Error:(Unbekannter Fehler)
5: open(Antwort noch ausstehend)
6: Error(Keine Verbindung zum IVR Server)
8: Ok(Kontingent Buchung)
9: Ok(Selbstersate Reservation)
10: Ok(Email Reservation)
20: storniert(Durch Gastronom Reservation Status 8,10)
21: mutiert(reaktiviert nach Stornierung )
22: mutiert(abgelehnte,nicht beantworte Reservation)
23: storniert(Durch Gastronom Reservation Status 1)
24: storniert(Durch Gastronom Reservation Status 9)
25: mutiert(Reservation Status 8)
26: mutiert,(Reservation Status 9,10)
27: mutiert(Reservation Status 1)
28: storniert (Durch Gast Reservation Status 8,9,10)
29: storniert (Durch Gast Reservation Status1)
32: Error(Anruf nicht beantwortet)

Error Messages

Status	ErrorNr.	Message	Long-Message
error	23	invalid_reservation_hash	Ungültiger Reservation Hash. Es kann kein Feedback abgegeben werden

getRestaurantHash

Beschreibung:

Mit dieser Methode kann man den forAtable Restaurant-Hash abholen. Es wird eine komma-separierte Liste von Luchgate Ids mitgepostet. Die Lunchgate Ids erhält man von der Lunchgate API

Error Messages

Status	Message	Long-Message
error	incorrect_login	Ungültiges Api-User Login. Entweder E-Mail oder Passwort falsch

getRestaurantInfo

Beschreibung:

Es werden Informationen zum Restaurant zurückgegeben welche unter Umständen benötigt werden um ein Kalender-Widget zu programmieren.
In der Properts times sind die Servicezeiten der entsprechenden Tage aufgelistet. Der Index 0 ist der Sonntag und index & der Samstag
Im Object restaurant hat eine Property namens closed_days welches in array mit den geschlossen Wochentagen enthält. Der Wert 1 ist der Montag, der Wert 7 ist der Sonntag, der Wert 0 bedeutet, dass das Restaurant in jedem Wochentag offen ist.
Für genaure Angaben zum Datensatz beim Support nachfragen

Error Messages

Status	Message	Long-Message
error	invalid_restaurant_hash	Ungültiger Restaurant Hash
error	incorrect_login	Ungültiges Api-User Login. Entweder E-Mail oder Passwort falsch

Direct

Beschreibung:

Das Reservationsfenster wird per POST aufgerufen(mitgegeben wird Datum, Uhrzeit und Personenanzahl).
Der Gast wird dann automatisch im Reservationsfenster an die Stelle geleitet wo er die Reservation fortsetzen kann.
Das ist kein Api-Methode sondern einen Browser-Request.

getContingents

Beschreibung:

Mit dieser Funktion können die verfügbaren Kontingente der verschiedenen Restaurant zu einem bestimmten Zeitpunkt(Datum/Uhrzeit) abgerufen werden.

URL	https://foratable.com//bookapi2/initReservation
METHOD	post
RESPONSE	json
Post Fields:
restaurant_hash *
username *	API Benutzername
pswd *	API Passwort
mediapartner_hash
language
agent

URL	https://foratable.com//bookapi2/setFeedback
METHOD	post
RESPONSE	json
Post Fields:
username *	API Benutzername
pswd *	API Passwort
reservation_hash *
service *	Service
food *	Küche
ambience *	Ambiente
performance *	Preis / Leistung
comment

URL	https://foratable.com//bookapi2/getRestaurantHash
METHOD	post
RESPONSE	json
Post Fields:
lunchgate_ids *	comma-separeted list of lunchgate restaurant ids
username *	API Benutzername
pswd *	API Passwort

URL	https://foratable.com/bookapi2/getRestaurantInfo
METHOD	post
Post Fields:
restaurant_hash *
username *	API Benutzername
pswd *	API Passwort

Restaurant-Hash	um hier testen zu können
URL	https://foratable.com/reserve/restaurant/#/direct
METHOD	post
Post Fields:
date *	YYYY-MM-DD zb. 2012-09-13
time *	HH:ii z.b 12:30
places *

URL	https://foratable.com//bookapi2/setRoom
METHOD	post
RESPONSE	json
Post Fields:
request_hash *
room_id *

URL	https://foratable.com//bookapi2/getTimesOfDate
METHOD	post
RESPONSE	json
Post Fields:
request_hash *
date *	YYYY-MM-DD zb. 2012-09-13
person

URL	https://foratable.com//bookapi2/setTable
METHOD	post
RESPONSE	json
Post Fields:
request_hash *
date *	YYYY-MM-DD zb. 2012-09-13
time *	HH:ii z.b 12:30
person *
comment
promocode

URL	https://foratable.com//bookapi2/setChoice
METHOD	post
RESPONSE	json
Post Fields:
request_hash *
choice *

URL	https://foratable.com//bookapi2/setGuest
METHOD	post
RESPONSE	json
Post Fields:
request_hash *
firstname *
lastname *
mobile *
email *
countryCode *

URL	https://foratable.com//bookapi2/newCode
METHOD	post
RESPONSE	json
Post Fields:
request_hash *

URL	https://foratable.com//bookapi2/setLanguage
METHOD	post
RESPONSE	json
Post Fields:
request_hash *
language *

URL	https://foratable.com//bookapi2/getReservation
METHOD	post
RESPONSE	json
Post Fields:
reservation_hash *
username *	API Benutzername
pswd *	API Passwort

URL	https://foratable.com/bookapi2/getContingents
METHOD	post
Post Fields:
date	YYYY-MM-DD zb. 2012-09-13
username *	API Benutzername
pswd *	API Passwort

Book-API version:1.2

Workflow Reservationprozess

Situation

1. Initialisieren

2. Tisch

3. Auswahl / Kommentar

4. Gast

5. Code überprüfen

Workflow Zeit, Datum und Anzahl Personen am Reservationsfenster übermittlen

Situation

1. Restaurant Information

2. Ins Reservations springen

Api Methoden

initReservation

Beschreibung:

Error Messages

setRoom

Beschreibung:

Error Messages

getTimesOfDate

Beschreibung:

Error Messages

setTable

Beschreibung:

Ok Messages(status=ok)

Error Messages

Beschreibung:

setChoice

Error Messages

setGuest

Beschreibung:

Ok Messages(status=ok)

Error Messages

verifyCode

Beschreibung:

Ok Messages(status=ok)

Error Messages

newCode

Beschreibung:

Error Messages

Beschreibung:

setLanguage

Error Messages

setFeedback

Beschreibung:

Error Messages

getReservation

Beschreibung:

Error Messages

getRestaurantHash

Beschreibung:

Error Messages

getRestaurantInfo

Beschreibung:

Error Messages

Direct

Beschreibung:

getContingents

Beschreibung: