iCalendar - správná implementace pro hotely a ubytovací zařízení

Pokud provozujete katalog ubytování nebo jakýkoli systém s exportem rezervací ubytování do formátu iCalendar (iCal), najdete v tomto článku užitečné informace jak správně implementovat podporu formátu iCalendar a nejčastější chyby.

Samozřejmostí je validita formát. Pokud používáte nějakou aktualizovanou knihovnu funkcí pro export iCalendar, tak s validitou pravděpodobně nebudete mít problém. Zaměříme se proto na obsahové chyby, které zabrání správnému importu rezerací.

Pravidla správné implementace iCalendar pro rezervace ubytování

Unikátní UID události a jeho tvar
Účelem UID je, aby bylo "persistent, globally unique identifier", viz specifikace. UID tedy musí být za všech okolností trvalým, globálně unikátním identifikátorem události. To je nejdůležitější pravidlo ze všech a nedodržení této specifikace způsobí nejkritičtější chyby při zpracování iCal feedu.
Ideálním tvarem UID je: VAS-INTERNI-IDENTIFIKATOR-REZERVACE@nazev-katalogu.tld
Tento tvar umožní zjistit prvotní zdroj rezervace. Jako UID je ale přípustný jakýkoli jedinečný řetězec, například standardně generovaný UUID řetězec.
Chyba: UID není trvalé
Tato chyba je způsobena tím, že se UID jedné události v čase změní. Nejkritičtější existující chyba je, že jako UID je zasílán náhodný řetězec, který se generuje pokaždé znovu při generování aktualizace feedu. Taková chyba způsobí při importu nemožnost rozeznání již importované rezervace a rezervace bude importována pokaždé znovu jako nová rezerace při každém cyklu zpracování feedu. Velmi snadno se tak vytvoří desítky tisíc falešných rezervací. Tato nejkritičtější existující chyba bude mít vždy za následek vyloučení feedu ze zpracování a blokaci zdroje feedu pro další importy.
Chyba: Katalog změní UID importované rezervace
Tato chyba nastane, pokud katalog importuje rezervaci z jiného iCal feedu (například z jiného katalogu) a již existující UID události přepíše vlastním UID události. Již přidělené UID události nemůže být změněno, protože musí být dle specifikace trvale globlálně unikátním identifikátorem. Tato chyba způsobí v dalších zdrojích duplicitní stažení rezervace z původního zdroje a z katalogu, který změnil UID rezervace.
Chyba: Katalog zašle v UID neunikátní řetězec, například ID skupinové rezervace
Pokud váš katalog podporuje skupinové rezervace, tak je potřeba si uvědomit, že v iCal feedu je zasílána vždy rezervace jedné ubytovací jednotky (např. pokoje). Jako UID tedy nelze zaslat ID skupinové rezervace, protože ID skupinové rezervace by se opakovalo ve všech feedech každého z rezervovaných pokojů a nebylo by proto unikátní. Kromě toho musí být zachována možnost editace a změn termínů, údajů nebo stavů v každé jednotlivé rezervaci ze skupiny rezervací a každá ze skupiny rezervací musí být identifikovatelná vlastním jedinečným identifikátorem. Na straně importu způsobí tato chyba, že rezervace se importuje pouze do jednoho z pokojů - při importu duplicitních UID bude nahlášena chyba unikátnosti a rezervace se duplicitně neimportuje.
Ukázka vhodného obsahu události rezervace včetně osobních údajů

BEGIN:VEVENT
UID:cid-123456789-bid-8@trevlix.com
DTSTAMP:20220629T123921Z
SUMMARY:Jan Novák
DTSTART;TZID=Europe/Prague:20220714T140000
DTEND;TZID=Europe/Prague:20220717T110000
STATUS:CONFIRMED
DESCRIPTION:Email: jan@novak.cz\, Telefon: 777123456\, Cena: 2500 CZK\, Hostů celkem: 3 (Katalog ABC)
END:VEVENT
Příklad vhodného minimálního obsahu události rezervace bez osobních údajů
Rezervace je v tomto případě obtížněji dohledatelná provozovatelem ubytovacího zařízení. Provozovatel musí vždy pro zjištění údajů rezervace otevřít extranet původního zdroje ubytování, což znamená významné nepohodlí. Je proto užitečné generovat oba formáty feedů, včetně osobních dat i bez osobních dat s odlišnými hesly předávanými URL parametrem a ponechat volbu exportu/importu osobních údajů na provozovateli.

BEGIN:VEVENT
UID:cid-123456789-bid-8@trevlix.com
DTSTAMP:20220629T123921Z
SUMMARY:Rezervace #8 (Trevlix)
DTSTART;TZID=Europe/Prague:20220714T140000
DTEND;TZID=Europe/Prague:20220717T110000
STATUS:CONFIRMED
END:VEVENT
Chyba Neidentifikovatelná událost
Při této chybě data událost neobsahuje žádné údaje, které by provozovatel mohl použít k identifikaci rezervace. Po importu zjistí provozovatel ubytovacího zařízení pouze to, že je v termínu obsazeno. Nemá žádný údaj (ani číslo rezervace), podle kterého by mohl alespoň v extranetu katalogu dohledat, o jakou rezervaci se jedná. Takový import je proto pro provozovatele ubytovacího zařízení velmi matoucí a prakticky bezcenný.

BEGIN:VEVENT
UID:8d9ffae1-a98a-433e-83df-4a1b30012020
DTSTAMP:20220629T123921Z
SUMMARY: Obsazeno
DTSTART;TZID=Europe/Prague:20220714T140000
DTEND;TZID=Europe/Prague:20220717T110000
END:VEVENT
Stavy rezervací (vlastnost STATUS)
Pro potřeby rezervací můžeme v rámci standardu formátu iCal použít stavy:

CONFIRMED = potvrzeno, blokující stav
TENTATIVE = předběžná, neblokujicí stav
CANCELLED = stornovaná, neblokující stav

Obecně platí, že každá rezervace, která již blokuje termín rezervace, by měla mít STATUS:CONFIRMED.
Rezervace dodatečně stornovaná hostem by měla vždy ve feedu trvale zůstat a měla by mít STATUS:CANCELLED.
Pokud bude v importovaném feedu vymazána dříve existující budoucí rezervace, bude v Trevlixu převedena do neblokujícího stavu "čeká na schválení".
Nezávazné předběžné rezervace, které ještě neblokují termín, mohou být exportovány se stavem STATUS:TENTATIVE nebo nemusí být ve feedu uvedeny vůbec až do okamžiku potvrzení rezervace - hlavním smyslem exportu/importu iCal je předejít overbookingu a rezervace v neblokujícím stavu TENTATIVE je pouze informativním stavem, ve kterém může termín rezervovat jiný host.

Pokud vlastnost STATUS není exportována vůbec (což je chyba), jsou všechny rezeravce považovány za platné a blokující.
Pro každý feed poskytujeme také hodnotu LAST-MODIFIED, např.:
LAST-MODIFIED;TZID=Europe/Prague:20220912T143628
, která vás informuje o čase poslední provedené změny. Pokud se hodnota od poslední kontroly feedu nezměnila, nemusíte feed znovu zpracovávat.