Foratable - Bookapi

Workflow Reservationsprozess

Situation

Mit der API lässt sich der Reservationsprozess komplett nachbilden, beispielsweise lässt sich damit ein eigenes Reservationsfenster programmieren.

1. Initialisieren

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

2. Raum

Für Restaurants mit nur einem Raum kann dieser Schritt übersprungen werden!
Der Gast wählt den Raum. Dieser wird mit der Methode setRoom der API übermittelt.

3. 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.

4. Auswahl / Kommentar

In der Antwort der Initialisierung ist bestimmt, ob das Restaurant einen Kommentar erlaubt und ob es eine Auswahl gibt. Dieser Schritt muss nur gemacht werden, wenn ein Kommentarfenster angeboten wird oder die ausgewählte Zeit/Datum sich in der Auswahl Zeit/Datum befindet. Mit der Methode setChoice kann die Auswahl und der Kommentar gesetzt werden.

5. Gast

Danach gibt der Gast seine Angaben (Name, Vorname, E-Mail und Mobile-Nr) 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 ist er schon mit einer anderen Mobile-Nr oder E-Mail registriert, wird dem Gast eine SMS mit einem vierstelligen Code gesendet.

6. Code überprüfen

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

Workflow Zeit, Datum und Anzahl Personen am Reservationsfenster übermitteln

Situation

Datum, Zeit und Anzahl Personen werden auf der Seite des Gastronomen erfasst – in der Regel über ein Webformular.
Das Reservationsfenster wird dann per POST Request aufgerufen (mitgegeben wird Datum, Zeit und Personenanzahl) und der Gast landet im Reservationsfenster an der entsprechenden Stelle, von wo er den Reservationsprozess fortsetzen kann.

1. Restaurant Information

Mit der API-Methode getRestaurantInfo lassen sich die Restaurant relevanten Informationen beziehen.

2. Ins Reservationsfenster springen

Die Daten müssen per POST Request dem Reservationsfenster übermittelt werden. Das sollte in einem neuen Fenster geschehen. Der Gast befindet sich danach im Reservationsfenster, also auf der Domain foratable.com.
Dies ist unter der Pseudo API-Methode Direct beschrieben und kann dort getestet werden.

Api Methoden

Die Bookapi liefert die Antwort im JSON-Format. 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 weiteren Verlauf des Reservationsprozesses benötigt wird.
Es werden sowohl Daten zum Restaurant zurückgegeben sowie raumspezifisch die Essenszeiten für jeden Wochentag. Ausnahmezeiten(event_times) überschreiben die Ferienzeiten(holiday_times) welche die Standardzeiten(times) überschreiben.

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:

Mit dieser Methode wird der Raum des Restaurants gesetzt. Ist nur für Restaurants mit mehreren Räumen nötig!

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 1 Stunde)!
error	24	room_not_exists

getTimesOfDate

Beschreibung:

Mit dieser Methode lassen sich Essenszeiten zu einem bestimmten Datum abholen.

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 1 Stunde)!

setTable

Beschreibung:

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

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 1 Stunde)!
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 sowie den Gast-Kommenntar übermitteln.

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 1 Stunde)!
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. Falls der Gast im System schon registriert ist, wird die Reservation ausgelöst. Ist der Gast unbekannt oder die E-Mail und die Mobile Nummer stimmen nicht überein, wird dem Gast eine SMS mit einem Verifizierungscode 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 bekannt ist wurde die Reservation direkt ausgelöst antstatt einen Verfizierungscode zu senden.

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 1 Stunde)!
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 Verifizierungscode, 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.

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 1 Stunde)!
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 eine weitere SMS mit dem Verfizierungscode 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 1 Stunde)!
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 - ebenso 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 1 Stunde)!
error	29	incorrect_language	Ungültige Sprache!

setFeedback

Beschreibung:

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

Error Messages

Status	ErrorNr.	Message	Long-Message
error	23	invalid_reservation_hash	Ungültiger Reservation Hash!
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!

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 Property times sind die Essenseiten der entsprechenden Tage aufgelistet. Der Index 0 ist der Sonntag und index 6 der Samstag.
Das Object restaurant hat eine Property namens closed_days, welches ein 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 an jedem Wochentag offen ist.
Für genauere 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 entsprechende Stelle geleitet, von wo er die Reservation fortsetzen kann.
Das ist keine API-Methode, sondern ein Browser-Request.

getContingents

Beschreibung:

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

getFeedbacks

Beschreibung:

Mit dieser Funktion können die Feedbacks eines Restaurants abgerufen werden. Optional kann mitgegeben werden wieviele Monate zurück die Feedbacks ausgegeben werden sollen. Der Default Wert ist 3 Monate.

Error Messages

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

setFeedbackAnswer

Beschreibung:

Eine Antwort auf ein Feedback posten.

Error Messages

Status	Message	Long-Message
error	incorrect_login	Ungültiges Api-User Login. Entweder E-Mail oder Passwort falsch!
error	invalid_reservation_hash	Ungültiger Reservation Hash!
error	feedback_answer_already_exists	Es existiert schon eine Feedback Antwort

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
comment

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

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

URL	https://foratable.com/bookapi2/setFeedbackAnswer
METHOD	post
Post Fields:
reservation_hash *
answer *
username *	API Benutzername
pswd *	API Passwort
public *

Book-API version:1.2

Workflow Reservationsprozess

Situation

1. Initialisieren

2. Raum

3. Tisch

4. Auswahl / Kommentar

5. Gast

6. Code überprüfen

Workflow Zeit, Datum und Anzahl Personen am Reservationsfenster übermitteln

Situation

1. Restaurant Information

2. Ins Reservationsfenster springen

Api Methoden

initReservation

Beschreibung:

Error Messages

setRoom

Beschreibung:

Error Messages

getTimesOfDate

Beschreibung:

Error Messages

setTable

Beschreibung:

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:

getFeedbacks

Beschreibung:

Error Messages

setFeedbackAnswer

Beschreibung:

Error Messages