Integrácie — SportUp.sk

Obsah kapitoly

REST API
MCP servery
Webhooks a event stream
Napojenie na štátne registre
Otvorené dáta
Certifikácia aplikácií

01 · REST

REST API

REST API je hlavným rozhraním systému pre klasické aplikácie — zväzové portály, klubové systémy, obecné aplikácie, komerčné platformy. Špecifikácia je publikovaná ako OpenAPI 3.1 a všetky zmeny prechádzajú verzionovaním.

Princípy

Versioning v URL — /v1/, /v2/. Paralelný beh verzií, deprecation policy oznamuje prevádzkovateľ 18 mesiacov vopred.
OAuth 2.0 + OIDC autentifikácia, klientské certifikáty na úrovni mTLS pre citlivé operácie.
Scope-based autorizácia — každý token nesie scopes, ktoré sa vyhodnocujú v policy engine spolu s consent záznamami.
Idempotency keys na zápisových endpointoch — klient môže bezpečne opakovať požiadavku.
Cursor-based pagination pre zoznamy, nie offset. Stabilné pri zmenách dát počas prechodu.
RFC 7807 Problem Details pre chyby — strojovo spracovateľné error kódy.

Hlavné resource paths

Path	Účel	Typické scopes
`/v1/persons`	Správa osôb	`persons:read`, `persons:write:own_org`
`/v1/affiliations`	Afiliácie a prestupy	`affiliations:read`, `affiliations:write:own_org`
`/v1/qualifications`	Kvalifikácie a licencie	`qualifications:read`, `qualifications:write`
`/v1/consents`	Consent manažment	`consents:read:own`, `consents:grant`, `consents:withdraw:own`
`/v1/organizations`	Organizácie	`organizations:read`, `organizations:write:own`
`/v1/facilities`	Športoviská	`facilities:read:public`, `facilities:write:own`
`/v1/events`	Podujatia	`events:read`, `events:write:own`
`/v1/verify`	Verifikačné volania (komerčné)	`verify:athlete_status`, `verify:license`
`/v1/statistics`	Agregované štatistiky	`statistics:read:aggregate`
`/v1/my`	Dotknutá osoba — vlastné dáta	`self:read`, `self:manage_consents`

02 · MCP

MCP servery

Pre agentické systémy a AI asistentov (výskumné tímy, ministerské analytiky, novinári spracúvajúci športové dáta) poskytuje SportUp súbor MCP serverov. MCP (Model Context Protocol) je otvorený štandard pre komunikáciu AI agentov s externými systémami.

MCP nie je zadný vchod

Každý MCP server je tenkou vrstvou nad rovnakým REST API. Prechádza identickým policy engine a rešpektuje rovnaké scopes a consent záznamy. MCP len dáva AI agentom ergonomický spôsob, ako opísať svoje dotazy pomocou tools.

Servery

mcp-sport-persons

Vyhľadávanie osôb, základné atribúty, deduplikačné operácie. Scope-limited — agent vidí len to, na čo má oprávnenie.

mcp-sport-affiliations

Afiliácie, prestupy, časové rady. Užitočné pre analytikov a športových novinárov.

mcp-sport-qualifications

Licencie, platnosti, expirácie. Pre administratívne pracovníky zväzov.

mcp-sport-events

Súťažný kalendár, účasti, výsledky. Napojenie na publicistiku a fanúšikovské aplikácie.

mcp-sport-facilities

Katalóg športovísk vrátane turistických atribútov. Hlavné rozhranie pre cestovný ruch.

mcp-sport-statistics

Anonymizované agregáty pre výskum. Differential privacy, k-anonymita.

03 · Webhooks

Webhooks a event stream

Pre systémy, ktoré potrebujú reagovať na zmeny v reálnom čase — ligové systémy, turistické platformy, mediálne spracovanie — ponúka SportUp dva spôsoby odoberania eventov.

Webhooks (push)

Certifikovaná aplikácia sa prihlási na odber konkrétnych typov eventov. Server pri každej udalosti vysiela HTTP POST na registrovanú URL s podpísaným payloadom. Retries, dead-letter queue, audit doručovania.

POST https://partner.example.com/hooks/sportup

Headers:
  X-SportUp-Event: AffiliationActivated
  X-SportUp-Signature: sha256=...
  X-SportUp-Delivery-Id: del_a83f...

{
  "event_type": "AffiliationActivated",
  "aggregate_id": "aff_...",
  "occurred_at": "2026-04-20T12:00:00Z",
  "data": { /* scope-filtered payload */ }
}

Event stream (pull, bulk)

Pre backendové systémy a dátové sklady — čitateľný AsyncAPI stream cez Server-Sent Events alebo batch API. Podporuje obnovenie od posledného event_id bez straty dát.

04 · Štátne registre

Napojenie na RFO, RPO a ÚPVS

Všetka komunikácia so štátnymi registrami ide cez dedikovanú službu Identity Broker (viď architektúra). Zvyšok systému štátne registre priamo nevidí.

Obrázok · Identity Broker ako jediná komunikačná hranica medzi SportUp a štátnymi registrami. Plné šípky = synchrónne dotazy, prerušované = notifikácie cez CSRÚ.

Typy interakcie

Operácia	Smer	Trigger
Match-or-create osoby	SportUp → RFO	Registrácia novej osoby
Verifikácia existujúcej osoby	SportUp → RFO	Profesionálny prestup, vyplácanie dotácie, akreditácia na reprezentáciu
Match-or-create organizácie	SportUp → RPO	Registrácia novej organizácie
Notifikácia o zmene	CSRÚ → SportUp	Zmena v RFO/RPO (adresa, úmrtie, zánik PO)
Výmazová požiadavka	Obojsmerne	GDPR čl. 17 — právo na výmaz

05 · Otvorené dáta

Otvorené dáta — bez certifikácie

Určité vrstvy dát sú verejné a dostupné bez certifikácie, bez OAuth, bez rate limitov presahujúcich štandardný misuse prevention. Cieľom je otvoriť športovú infraštruktúru celej spoločnosti.

Katalóg športovísk

Všetky športoviská v stave operational s verejnými atribútmi. Turistické atribúty, dostupnosť, mapa. JSON, CSV, GeoJSON, RDF.

Kalendár podujatí

Verejné športové podujatia s miestom, časom, disciplínou. iCal, JSON, RSS.

Všetky číselníky

Športy, odvetvia, kategórie, druhy činnosti, druhy organizácií, typy športovísk. JSON, CSV, verzionované.

Agregované štatistiky

Počty osôb po športoch a krajoch, dostupnosť športovísk na obyvateľa, trendy v rokoch. Bez PII, k-anonymita ≥ 5.

Register organizácií

Verejné atribúty organizácií: názov, typ, sídlo, štatutár, kontakt. Právne predpoklady sú už v RPO.

Výsledky súťaží

Výsledky podľa organizačného výboru. Prepojené na identitu športovca cez person_id (s consent), alebo len ako anonymizované dáta.

Licencia a formáty

Všetky otvorené dáta sa publikujú pod licenciou CC-BY 4.0 — voľné použitie vrátane komerčného s uvedením zdroja. Pre čísleníky a geodata zvažujeme CC0. Formáty podľa štandardu európskej dátovej interoperability: DCAT-AP, popis metadát v data.gov.sk.

06 · Certifikácia aplikácií

Ako sa stať certifikovanou aplikáciou

Aplikácie, ktoré chcú zapisovať alebo čítať neverejné dáta, musia prejsť certifikáciou prevádzkovateľom. Certifikácia má štyri kroky.

Žiadosť a právna dokumentácia

Vyplnená žiadosť, predstavenie subjektu, aký problém rieši, aké dáta potrebuje, právne posúdenie účelu spracovania.

II.

Technický audit

Overenie bezpečnostných opatrení, šifrovania, logovania, prístupu k produkčným dátam. Penetračný test. Kód review pri open-source aplikáciách.

III.

Prideľovanie scopes

Na základe účelu sa aplikácii priradia konkrétne scopes. Napríklad klubový portál dostane affiliations:write:own_org, komerčný hotel len verify:athlete_discount.

IV.

Vydanie certifikátu a sandbox

Aplikácia dostane klientský certifikát + OAuth credentials. Najprv sandbox prostredie s testovacími dátami, až potom prechod do produkcie.

Kategórie aplikácií

Rozlišujeme štyri kategórie s rôznou prísnosťou auditu: tier A (zväzy, štátne subjekty) — najprísnejší; tier B (kluby, obce) — štandardný; tier C (komerční, verifikačné) — odľahčený scope; tier D (výskum) — pseudonymizovaný prístup pod zmluvou.

Nasledujúca kapitola — Technológie — popisuje navrhovaný technologický stack pre implementáciu SportUp.