Veřejná integrační platforma

Vlakové zážitky pro vaše systémy

Jedno rozhraní pro zveřejněné jízdy, kalendáře, mapy a bezpečné propojení správy spolku.

Partner API je zatím uzavřeno Klíče lze bezpečně připravit, provoz ale není povolen.

Základ v1

Oddělené Partner API

Kanonický základ rozhraní je /api/partner/v1/. Mobilní API v1/v2 ani veřejný web se jeho zavedením nemění.

Stav služby: GET /api/partner/v1/status/
Ověření klienta: GET /api/partner/v1/identity/
Datový formát: JSON, UTF-8, časy RFC 3339
Chyby: application/problem+json

Autentizace

Dva druhy klíčů

vz_pk_live_...

Publikovatelný klíč pro prohlížeč a budoucí widgety. Funguje jen z přesně povolených HTTPS originů a pouze pro zveřejněná data.

vz_sk_live_...

Tajný klíč pro server spolku. Posílá se výhradně v hlavičce Authorization: Bearer, nikdy v URL.

curl https://vlakovezazitky.cz/api/partner/v1/identity/ \
  -H "Authorization: Bearer $VZ_SECRET_KEY" \
  -H "X-Request-ID: 6e6d2bf4-3c73-4e90-847b-a6f8357c96e0"

Nejmenší oprávnění

Scopes podle účelu

public:readzveřejněný katalog
organization:readdata vlastního spolku bez osobních údajů
events:writekoncepty akcí
events:publishpublikace a archivace akcí
rides:writejízdy a ruční výjimky
timetables:writejízdní řády
notices:writemimořádnosti
reservations:createjen po schválení superadminem

RFC 9457

Stabilní chybové odpovědi

Každá chyba obsahuje stabilní code, request_id a referenční kód centrální evidence. Tělo požadavku, query s osobními údaji, hlavička Authorization ani celý klíč se do provozního logu neukládají.

{
  "type": "https://vlakovezazitky.cz/vyvojari/chyby/invalid_api_key/",
  "title": "Chybí platné přihlášení",
  "status": 401,
  "code": "invalid_api_key",
  "request_id": "...",
  "error_reference": "ERR-..."
}

Ochrana provozu

Limity a rotace

Klíče platí nejvýše 365 dní, výchozí platnost je 180 dní. Při rotaci lze starý a nový klíč překrýt nejvýše na 24 hodin. Odpovědi vracejí hlavičky RateLimit-Limit, RateLimit-Remaining a RateLimit-Reset.