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í

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

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

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

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

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

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

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

  8. 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í. 

 

V případě dotazů nás prosím kontaktujte na ticketovacím emailu podpory