Přehled

Tento dokument popisuje technický model spolupráce mezi externími poskytovateli událostí a centrální platformou. Slouží jako základní průvodce pro vývojáře, kteří implementují XML datový feed.

1. Model interakce: plánované stahování (pull)

Systém funguje na principu pull synchronizace — naše infrastruktura vystupuje v roli klienta. Místo aby se spoléhala na příchozí webhooky, periodicky odesílá požadavky na vámi poskytnutý endpoint a stahuje aktuální data.

Výchozí synchronizační cyklus probíhá každé čtyři hodiny. Tím zajistíme, že platforma zůstává aktuální, a zároveň zbytečně nezatěžujeme zdroje poskytovatele. Při těchto požadavcích se náš crawler identifikuje User-Agentem KamNaZapade/1.0 (+https://kamnazapade.cz); stejným řetězcem stahujeme i obrázky a přílohy. Filtrujete-li přístup podle User-Agenta (Nginx, Cloudflare, WAF), povolte tento řetězec.

Jak nám feed předat. Pořadatel, který chce akce předávat feedem, uvede jeho adresu už při registraci na kamnazapade.cz/pro-poradatele(otevře se v nové kartě) (část „Vaše akce“ → „Odkaz na váš kalendář akcí nebo feed“), nebo ji pošle redakci. Zdroj pak v panelu zapojí administrátor.

2. Vlastnictví dat a „zdroj pravdy"

Aby si platforma udržela vysokou kvalitu dat, řídí se přísnou hierarchií vlastnictví. XML feed je obecně považován za primární zdroj pravdy pro klíčové atributy — název, popis, média atd. Toto pravidlo se ale mění v okamžiku, kdy do dat manuálně zasáhne administrátor platformy.

Kdy zámek skončí. Zamkne se jen ta část události, kterou redakce skutečně změnila (např. název a popis, termín, místo nebo vstupenky). Pošle-li váš feed při některé synchronizaci v této části přesně to, co událost už obsahuje, zámek se uvolní a další změny z feedu se zase projeví.

Program je výjimka. Položky <nested_event> se řídí vaším feedem i poté, co redakce akci upraví: změna času, konce nebo sálu se projeví při další synchronizaci, i u zveřejněné akce. Redakce může jednotlivý termín od feedu oddělit — takový termín už feed nemění. Položky programu, které redakce doplní sama, feed nepřepíše. Akce, které redakce zamítla nebo předala pořadateli, feed nemění vůbec.

Předání pořadateli. Redakce může importovanou akci předat jejímu pořadateli (odpojit ji od feedu). Od té chvíle platforma změny této akce z feedu nepřebírá a nearchivuje ji, ani když její ID z feedu zmizí. Vazba na ID zůstává — akce se znovu nenaimportuje jako duplicita a redakce ji může kdykoli připojit zpět; změny z mezidobí pak dostane ke schválení.

Výchozí pořadatel zdroje. Administrátor může u vašeho zdroje nastavit výchozího pořadatele — vaši organizaci na platformě. Nové události z feedu i dosavadní události zdroje bez pořadatele jí přiřadíme a členové organizace je uvidí ve Studiu: dostávají oznámení o zveřejnění nebo vrácení a mohou navrhovat změny, které schvaluje redakce. Událost přitom zůstává napojená na feed a dál se jím aktualizuje; části změněné schváleným návrhem feed nepřepíše, stejně jako úpravy redakce.

3. Identifikace záznamů (deduplikace)

Synchronizační engine používá unikátní ID uvedené v XML jako absolutní kotvu pro každý záznam události. Při načtení záznamu engine ověří, zda už dané ID v naší databázi existuje. Pokud ano, provede aktualizaci; pokud ne, vytvoří nový záznam.

Je naprosto klíčové, aby tato ID byla na straně poskytovatele neměnná. Pokud na vaší straně dojde ke změně ID, náš engine bude záznam považovat za zcela novou entitu — a to nevyhnutelně vede k duplicitám na platformě a k roztříštění historie událostí.

Neměnné musí být i id položek <nested_event> — podle něj položku programu aktualizujeme. Posíláte-li každé představení jako samostatnou událost, držte v jeho ID stálé číslo inscenace či série (např. 23443-43701: série 23443, představení 43701). Redakce pak může nastavit, aby se termíny jedné série slučovaly do jedné akce s programem automaticky. Sloučené termíny se dál řídí vaším feedem (čas, konec, místo, vstupenka) a termín, který z feedu zmizí před konáním, se v programu skryje.

4. Životní cyklus a správa stavů

Každá nová událost z feedu čeká na kontrolu redakce a na web jde až po schválení. Změny, které při synchronizaci najdeme, zpracujeme podle stavu události:

• nezveřejněná událost (čeká na kontrolu) se aktualizuje rovnou;
• u zveřejněné události připravíme změny jako návrh (revizi), který redakce schválí nebo zamítne — do té doby web ukazuje dosavadní údaje;
• program (<nested_events>) se mění rovnou, i u zveřejněné události (bod 2);
• části, které upravila redakce, feed nepřepíše (bod 2), a zamítnutou událost už neaktualizuje.

Událost, která z feedu zmizí, při nejbližší synchronizaci archivujeme — z webu zmizí; žádná ochranná lhůta neplatí. Výjimky:

• událost s nadcházejícím termínem v programu zůstane na webu do posledního z nich;
• záznam, který feed poslal, ale v daném běhu neprošel validací nebo se nepodařilo určit místo konání, se za zmizelý nepovažuje;
• když v jednom běhu chybí najednou víc než 10 událostí, které ještě neproběhly, a zároveň víc než čtvrtina aktivních událostí zdroje, nearchivuje se nic — vypadá to na neúplnou odpověď feedu. Pokud jste je opravdu zrušili, dejte nám vědět;
• událost předanou pořadateli (bod 2) nearchivujeme nikdy.

Vrátí-li se událost do feedu, dostane zpět stav, který měla (zveřejněná se znovu objeví na webu), pokud o ní mezitím nerozhodla redakce. Proběhlé události z feedu klidně vynechávejte.

5. Validace a hlášení chyb

Náš synchronizační engine provádí granulární validaci každého jednotlivého záznamu v XML feedu. Pokud konkrétní událost obsahuje nevalidní data — například nesprávně formátované ISO datum nebo název města, který v naší globální databázi neexistuje — bude tento konkrétní záznam přeskočen.

Zbývající validní události ve feedu se zpracují a aktualizují běžným způsobem. Pouze v případě, že je celý feed poškozený nebo selže validace u všech záznamů, neproběhne žádný zápis do databáze, abychom předešli korupci dat.

Záznam, který v daném běhu neprojde validací, jen v tomto běhu přeskočíme — událost, kterou už u nás máte, kvůli tomu z webu nestáhneme; zůstane ve stavu z posledního úspěšného načtení.

Při každém selhání validace generujeme detailní integrační report. Pro rychlé odladění chybných dat doporučujeme využít náš validátor validate-my-feed.kamnazapade.cz(otevře se v nové kartě), kde uvidíte přehled chyb pro konkrétní události v reálném čase.

Co import opraví sám

Drobné nedostatky v datech import od září 2026 neřeší přeskočením události, ale opraví je a událost přijme s upozorněním. Redakce upozornění vidí u každé synchronizace a pošle vám je k opravě:

• Neznámá kategorie — událost se zařadí do kategorie other (Ostatní). Běžná česká označení (např. koncert, vystava, pro-deti) import převede sám; na velikosti písmen a diakritice nezáleží.
• Chybějící nebo neplatný obrázek (preview_url není bezpečný odkaz https://) — událost se přijme bez obrázku a web ukáže fotku místa nebo obce.
• Placená vstupenka bez price_min — událost se přijme bez ceny; na webu se cena nezobrazí.
• Zastaralý stav vstupenky at_door — převede se na sales_channel at_door se stavem on_sale (nebo free, když je cena nulová).
• Hodnoty s velkými písmeny nebo mezerami — převedou se na správný tvar.

Požadavky této specifikace přitom platí dál: povinná pole zůstávají povinná a upozornění znamenají, že je potřeba data ve feedu opravit.

6. Bezpečnost a autentizace

Pro ochranu výměny dat nabízíme několik vrstev zabezpečení. Pokud je váš endpoint za firewallem, můžeme vám poskytnout naše statické NAT IP adresy k whitelistování, abychom našemu crawleru zajistili nepřerušovaný přístup.

Dále podporujeme ověření přístupu k vašemu endpointu: Basic Auth (uživatelské jméno a heslo), Bearer token a API klíč ve vlastní hlavičce (název i hodnotu hlavičky určíte vy). Způsob ověření nastavuje u vašeho zdroje administrátor platformy — přihlašovací údaje mu předejte bezpečnou cestou. Ukládáme je šifrovaně a každý náš požadavek je pak obsahuje.