iCalendar - správna implementácia pre hotely a ubytovacie zariadenia

Ak prevádzkujete katalóg ubytovania alebo akýkoľvek systém s exportom rezervácií ubytovania do formátu iCalendar (iCal), nájdete v tomto článku užitočné informácie ako správne implementovať podporu formátu iCalendar a najčastejšie chyby .

Samozrejmosťou je validita iCal feedu. Ak používate nejakú aktualizovanú knižnicu funkcií pre export iCalendar, tak s validitou pravdepodobne nebudete mať problém. Zameriame sa preto na obsahové chyby, ktoré zabránia správnemu importu rezerácií.

1. Unikátny UID udalosti a jeho tvar
   Účelom UID je, aby bolo "persistent, globally unique identifier", pozri špecifikácia. UID teda musí byť za všetkých okolností trvalým, globálne unikátnym identifikátorom udalosti. To je najdôležitejšie pravidlo zo všetkých a nedodržanie tejto špecifikácie spôsobí najkritickejšie chyby pri spracovaní iCal feedu.
   Ideálnym tvarom UID je: VAS-INTERNI-IDENTIFIKATOR-REZERVACE@nazev-katalogu.tld
   Tento tvar umožní zistiť prvotný zdroj rezervácie. Ako UID je ale prípustný akýkoľvek jedinečný reťazec, napríklad štandardne generovaný UUID reťazec.
   
   
2. Chyba: UID nie je trvalé
   Táto chyba je spôsobená tým, že sa UID jednej udalosti v čase zmení. Najkritickejšia existujúca chyba je, že ako UID je zasielaný náhodný reťazec, ktorý sa generuje zakaždým znovu pri generovaní aktualizácie feedu. Takáto chyba spôsobí pri importe nemožnosť rozoznania už importovanej rezervácie a rezervácia bude importovaná zakaždým znovu ako nová rezerácia pri každom cykle spracovania feedu. Veľmi ľahko sa tak vytvoria desiatky tisíc falošných rezervácií. Táto najkritickejšia existujúca chyba bude mať vždy za následok vylúčenie feedu zo spracovania a blokáciu zdroja feedu pre ďalšie importy.
   
   
3. Chyba: Katalóg zmení UID importovanej rezervácie
   Táto chyba nastane, ak katalóg importuje rezerváciu z iného iCal feedu (napríklad z iného katalógu) a už existujúce UID udalosti prepíše vlastným UID udalosti. Už pridelené UID udalosti nemôže byť zmenené, pretože musí byť podľa špecifikácie trvalo globálne unikátnym identifikátorom. Táto chyba spôsobí v ďalších zdrojoch duplicitné stiahnutie rezervácie z pôvodného zdroja a z katalógu, ktorý zmenil UID rezervácie.
   
   
4. Chyba: Katalóg zašle v UID neunikátny reťazec, napríklad ID skupinovej rezervácie
   Ak váš katalóg podporuje skupinové rezervácie, tak je potrebné si uvedomiť, že v iCal feedu je zasielaná vždy rezervácia jednej ubytovacej jednotky (napr. izby). Ako UID teda nemožno zaslať ID skupinovej rezervácie, pretože ID skupinovej rezervácie by sa opakovalo vo všetkých feedoch každej z rezervovaných izieb a nebolo by preto unikátne. Okrem toho musí byť zachovaná možnosť editácie a zmien termínov, údajov alebo stavov v každej jednotlivej rezervácii zo skupiny rezervácií a každá zo skupiny rezervácií musí byť identifikovateľná vlastným jedinečným identifikátorom. Na strane importu spôsobí táto chyba, že rezervácia sa importuje iba do jednej z izieb - pri importe duplicitných UID bude nahlásená chyba unikátnosti a rezervácia sa duplicitne neimportuje.
   
   
5. Ukážka vhodného obsahu udalosti rezervácie vrátane osobných údajov
   
   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\, Telefón: 777123456\, Cena: 2500 CZK\,  Hostov celkom: 3 (Katalóg ABC)
   END:VEVENT
   
   
6. Príklad vhodného minimálneho obsahu udalosti rezervácie bez osobných údajov
   Rezervácia je v tomto prípade ťažšie dohľadateľná prevádzkovateľom ubytovacieho zariadenia. Prevádzkovateľ musí vždy pre zistenie údajov rezervácie otvoriť extranet pôvodného zdroja ubytovania, čo znamená významné nepohodlie. Je preto užitočné generovať oba formáty feedov, vrátane osobných dát aj bez osobných dát s odlišnými heslami odovzdávanými URL parametrom a ponechať voľbu exportu/importu osobných údajov na prevádzkovateľovi.
   
   BEGIN:VEVENT
   UID:cid -123456789-bid-8@trevlix.com
   DTSTAMP:20220629T123921Z
   SUMMARY:Rezervácia #8 (Trevlix)
   DTSTART;TZID=Europe/Prague:20220714T14 Europe/Prague:20220717T110000
   STATUS:CONFIRMED
   END:VEVENT
   
   
7. Chyba Neidentifikovateľná udalosť
   Pri tejto chybe dátumu udalosť neobsahuje žiadne údaje, ktoré by prevádzkovateľ mohol použiť na identifikáciu rezervácie. Po importe zistí prevádzkovateľ ubytovacieho zariadenia iba to, že je v termíne obsadené. Nemá žiadny údaj (ani číslo rezervácie), podľa ktorého by mohol aspoň v extranete katalógu dohľadať, o akú rezerváciu sa jedná. Takýto import je preto pre prevádzkovateľov ubytovacieho zariadenia veľmi mätúci a prakticky bezcenný.
   
   BEGIN:VEVENT
   UID:8d9ffae1-a98a-433e-83df-4a1b30012020
   DTSTAMP:20220629T123921Z
   SUMMARY: Obsadené
   DTSTART;TZID=Europe/Prague:20220714T140000
   DTEND;TZID=Europe/Prague:20220717T110000
   END:VEVENT
   
   
8. Stavy rezervácií (vlastnosť STATUS)
   Pre potreby rezervácií môžeme v rámci štandardu formátu iCal použiť stavy:
   
   CONFIRMED = potvrdené, blokujúci stav
   TENTATIVE = predbežná, neblokujúca stav
   CANCELLED = stornovaná, neblokujúci stav
   
   Všeobecne platí, že každá rezervácia, ktorá už blokuje termín rezervácie, by mala mať STATUS:CONFIRMED.
   Rezervácia dodatočne stornovaná hosťom by mala vždy vo feede trvalo zostať a mala by mať STATUS:CANCELLED. 
   Ak bude v importovanom feede vymazaná skôr existujúca budúca rezervácia, bude v Trevlixe prevedená do neblokujúceho stavu "čaká na schválenie".
   Nezáväzné predbežné rezervácie, ktoré ešte neblokujú termín, môžu byť exportované so stavom STATUS:TENTATIVE alebo nemusia byť vo feede uvedené vôbec až do okamihu potvrdenia rezervácie - hlavným zmyslom exportu/importu iCal je predísť overbookingu a rezervácia v neblokujúcom stave TENTATIVE je iba informatívnym stavom, v ktorom môže termín rezervovať iný hosť.
   
   Ak vlastnosť STATUS nie je exportovaná vôbec (čo je chyba), sú všetky rezeravce považované za platné a blokujúce. 
   
   
9. Pre každý feed poskytujeme tiež hodnotu LAST-MODIFIED, napr.:
   LAST-MODIFIED;TZID=Europe/Prague:20220912T143628
   , ktorá vás informuje o čase poslednej vykonanej zmeny. Ak sa hodnota od poslednej kontroly feedu nezmenila, nemusíte feed znova spracovávať.

V prípade otázok nás prosím kontaktujte na ticketovacom emaile podpory info@trevlix.com