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 pomocí specifického User-Agent řetězce KNZCrawler/1.0.

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.

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

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

Všechny události zpracované přes XML feed procházejí povinným moderačním workflow, aby byla zajištěna shoda se standardy platformy. Kdykoliv detekujeme novou událost nebo změnu u stávajícího záznamu, automaticky ji převedeme do stavu čekajícího na schválení.

Tyto záznamy musí naši administrátoři před zveřejněním zkontrolovat a schválit. Systém navíc implementuje ochrannou lhůtu pro mazání: pokud ID události zmizí z XML feedu, platforma uchovává záznam ještě 48 hodin, než ho přesune do archivu. Předejdeme tak nechtěné ztrátě dat při dočasných výpadcích feedu.

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.

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 <https://validate-my-feed.365karlovarsko.com>, kde uvidíte přehled chyb pro konkrétní události v reálném čase.

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 standardní autentizační metody pro zabezpečení vašeho endpointu. Poskytovatelé si v nastavení svého profilu na platformě mohou nakonfigurovat buď Basic Auth, nebo Bearer Token. Všechny naše požadavky pak budou tyto hlavičky obsahovat — ověříme tím naši identitu a udržíme zabezpečený komunikační kanál.