Rezervace nemusejí přicházet jen z vaší stránky rezervací nebo po telefonu. Rezervační platforma, web na míru nebo aplikace, kterou používá obsluha, se mohou k rezervacím ProfiRESTu připojit přes veřejné API v2. Rezervace se pak zapíšou do stejné Knihy rezervací a kapacitu dál hlídá jeden server. Článek je pro majitele, kteří o napojení uvažují, i pro vývojáře, kteří ho budou dělat.
Pro koho je API rezervací
- Rezervační platformy, které chtějí nabízet volné časy vaší provozovny a zakládat rezervace přímo do vaší knihy.
- Weby provozoven na míru, které chtějí vlastní rezervační formulář místo vloženého formuláře ProfiRESTu.
- Aplikace obsluhy, třeba obrazovka u vstupu, která ukazuje volné stoly, čekací listinu a historii volajícího hosta.
Pokud vám stačí stránka rezervací a formulář na váš web, který ProfiREST nabízí v Nastavení rezervací, API nepotřebujete. Má smysl tam, kde rezervace přicházejí z cizí aplikace.
Co API umí
| Oblast | Co aplikace dostane nebo udělá |
|---|---|
| Pravidla provozovny | Jestli přijímá online rezervace, jak dlouho se sedí, jak daleko dopředu a jaká je největší skupina. |
| Služby | Délka, cena a pracovníci každé služby (salon, wellness). U restaurace bez služeb prázdné. |
| Volné časy dne | Časy, které jde nabídnout pro daný počet osob nebo službu. |
| Založení a úpravy | Nová rezervace, změna času, počtu osob nebo délky, seznam a detail rezervací. |
| Změny stavu | Potvrzení, odmítnutí, zrušení s důvodem, usazení, odchod a stav Nepřišli. |
| Obsazenost stolů teď | Které stoly jsou obsazené účtem nebo rezervací a jaká je další rezervace dne. Pro hosty bez rezervace a obrazovky u vstupu. |
| Host a čekací listina | Podle telefonního čísla historie hosta (kolikrát přišel, nepřišel nebo zrušil) a jeho štítky; zápis na čekací listinu, SMS o volném stole, usazení z listiny. |
| Zálohy a hodnocení | Odeslání odkazu k zaplacení zálohy u rezervace z telefonu, odpuštění zálohy, hodnocení hostů po návštěvě. |
Kapacitu hlídá server i pro API
Pro rezervace z API platí stejná pravidla jako pro online stránku: kapacita stolů, spojování, doba u stolu, tempo příchodů, otevírací doba a dny bez rezervací. Stůl, pracovník ani místnost nejsou nikdy rezervované dvakrát. Web a API kapacitu nepřekročí; přepsat ji může jen obsluha v Knize rezervací.
Pro vývojáře z toho plynou dvě praktické věci. Volný čas se aplikaci nedrží: rezervaci je potřeba založit hned po výběru. A když mezitím čas obsadí někdo jiný, API vrátí chybu 409 reservation_unavailable; aplikace má načíst volné časy znovu a nabídnout jiný. Založení se posílá s klíčem Idempotency-Key, takže opakované odeslání při výpadku spojení nezaloží rezervaci dvakrát.
Typický průběh z pohledu aplikace
- Aplikace načte pravidla provozovny a zjistí, jestli přijímá online rezervace, jak daleko dopředu a jakou největší skupinu.
- Host v aplikaci zvolí den a počet osob, případně službu a pracovníka. Aplikace načte volné časy dne a nabídne jen ty dostupné.
- Host vybere čas a vyplní kontakt. Aplikace hned založí rezervaci, ideálně s vlastním identifikátorem, aby ji při opakovaném odeslání nezaložila dvakrát.
- Když server odpoví, že čas už je obsazený, aplikace načte volné časy znovu a nabídne jiný.
- Další změny, třeba potvrzení obsluhou, zrušení nebo usazení hosta, aplikace sleduje v událostech.
Rezervace z API nemusí být hned potvrzená. Když provozovna potvrzuje online rezervace ručně nebo chce zálohu, čeká rezervace na potvrzení. Odkaz k zaplacení zálohy pošle hostovi obsluha z Knihy rezervací, nebo aplikace obsluhy přes API.
Události: změny bez neustálého dotazování
Když obsluha v administraci rezervaci potvrdí, zruší nebo hosta usadí, aplikace se to dozví z událostí reservation.created, reservation.updated a reservation.status_changed. Události jde číst po stránkách, odebírat živě přes Server-Sent Events, nebo je nechat doručovat webhooky, které jsou podepsané, takže aplikace pozná, že zpráva opravdu přišla od ProfiRESTu. Kontakty hosta v události nejsou; aplikace si je načte z detailu rezervace, pokud na to má oprávnění.
Jak se aplikace připojí k vašemu účtu
- Vývojář požádá na vývojářském portálu o přístup. Testovací přístup dostane hned po potvrzení e-mailu, ale připojí se s ním jen k veřejnému ukázkovému účtu. Ostrý přístup schvaluje ProfiREST.
- V aplikaci kliknete na Připojit přes Profirest. Heslo aplikaci nedáváte.
- V administraci zkontrolujete, co bude aplikace smět. U rezervací jde o oprávnění číst rezervace (
reservations:read) a zakládat a měnit je (reservations:write). - Zaškrtnete provozovny, které má aplikace vidět, a povolíte přístup. Povolit ho smí jen majitel.
Stránka s žádostí o připojení platí 15 minut; když ji necháte otevřenou déle, spusťte připojení v aplikaci znovu. Zaměstnanec místo formuláře uvidí vysvětlení, že aplikaci připojit nemůže. Každá připojená aplikace má v administraci vlastní kartu, kde vidíte, kdy jste ji připojili a kdy byla naposledy aktivní, a můžete jí přidat nebo odebrat provozovny. Vrátit odebrané oprávnění jde jen novým připojením z aplikace, proto se stránka před uložením zeptá.
Připojení kdykoli zrušíte na stránce Připojené aplikace; aplikace tím hned ztratí přístup. Odškrtnutím oprávnění jí můžete vzít jen část práv. Provozovna musí mít Rezervační systém v licenci; bez něj operace rezervací odpovědí, že modul není v licenci.
Co předat vývojáři
Odkaz na dokumentaci api.mujprofirest.cz/v2/docs. Je česky i anglicky, má návod Rezervace stolů a služeb s celým scénářem, referenční popis všech operací, changelog, specifikaci OpenAPI a playground, ve kterém jde každou operaci spustit v prohlížeči. Oficiální knihovny jsou pro JavaScript, TypeScript, PHP, Javu, Kotlin, C#, Python, Swift, Dart a Go.
Na co myslet před napojením portálu
Obecná rada: když rezervace přicházejí z víc míst, ptejte se partnera, jestli bere volné časy z vaší knihy, nebo vede vlastní. Jen první varianta zaručí, že telefon, vaše stránka a portál nikdy neprodají stejný stůl dvakrát. V Knize rezervací je u každé rezervace vidět, odkud přišla, a Přehled ukazuje rezervace podle zdroje. Po pár týdnech tak víte, kolik hostů vám partner skutečně přivádí.
Co udělat teď
- Ujasněte si, co má aplikace dělat: jen nabízet volné časy, nebo i měnit stavy a pracovat s čekací listinou.
- Pošlete vývojáři odkaz na dokumentaci a nechte ho vyzkoušet napojení na ukázkovém účtu.
- Po schválení ostrého přístupu aplikaci připojte a povolte jen potřebná oprávnění a provozovny.
Jak rezervace fungují v administraci, popisuje kapitola Rezervace stolů a služeb, celou řadu stránka Rezervace.