API Požadavky

Reálné CoreAPI endpointy

Tento dokument definoval očekávané API kontrakty ještě před analýzou reálného backendu. Nyní máme k dispozici kompletní OpenAPI specifikaci Colosseum CoreAPI (v17.0.0.0, 70 endpointů, 13 domén). Mapování reálných endpointů na obrazovky, datové modely a klíčové poznatky: CoreAPI — Integrace.

Tento dokument definuje, co očekáváme od backend API z pohledu mobilní aplikace. Nejde o přesnou API specifikaci (tu dodá backend tým), ale o funkční požadavky, datové struktury a konvence, které mobilní klient potřebuje.

Formát

Endpointy jsou popsány REST-like konvencí. Implementace může být REST, GraphQL nebo jiná — důležitý je datový kontrakt a chování.

---

Obecné API konvence

Aspekt	Očekávání
Formát	JSON (application/json)
Auth	Bearer token v Authorization header
Pagination	Cursor-based (cursor, limit, hasMore)
Error format	Konzistentní error object: { code, message, details }
Localization	Accept-Language header pro lokalizovaný obsah
Rate limiting	HTTP 429 s Retry-After header
Versioning	URL prefix (/v1/) nebo header-based
Image URLs	Absolutní URL s CDN, podporující width/height query params

Pagination (cursor-based)

Cursor-based pagination zajišťuje stabilní stránkování i při real-time změnách dat (nové akce, sold-out).

// Request
GET /v1/events?limit=20&cursor=eyJpZCI6MTIzfQ

// Response
{
  "data": [...],
  "pagination": {
    "cursor": "eyJpZCI6MTQzfQ",
    "hasMore": true,
    "total": 342
  }
}

Error format

{
  "error": {
    "code": "SEAT_UNAVAILABLE",
    "message": "Vybrané sedadlo již není dostupné.",
    "details": {
      "seatId": "R5-S12",
      "status": "reserved"
    }
  }
}

---

Events API [MVP]

Hlavní skupina endpointů pro práci s akcemi — prohlížení, vyhledávání, filtrování.

Endpoint	Metoda	Popis	Fáze
/v1/events	GET	Seznam akcí (filtrovaný, stránkovaný, sortovatelný)	MVP
/v1/events/{id}	GET	Detail akce s termíny, galerií, metadaty	MVP
/v1/events/{id}/dates	GET	Seznam termínů s dostupností	MVP
/v1/events/{id}/dates/{dateId}/seats	GET	Seat map data (SVG/JSON) pro adresné sezení	MVP
/v1/events/{id}/dates/{dateId}/categories	GET	Cenové kategorie pro neadresné sezení	MVP
/v1/events/featured	GET	Doporučené / promo akce pro feed	MVP
/v1/events/search?q=...&genre=...&city=...	GET	Fulltext hledání s filtry	MVP
/v1/events/{id}/related	GET	Související akce (pro cross-sell)	MVP

Filtering params pro /v1/events

Parametr	Typ	Popis
genre	string	Žánr/kategorie (musical, theatre, music, festival...)
city	string	Město (praha, brno, ostrava)
venueId	string	ID místa konání
organizerId	string	ID pořadatele
dateFrom	ISO 8601	Akce od data
dateTo	ISO 8601	Akce do data
priceMin	number	Minimální cena (CZK)
priceMax	number	Maximální cena (CZK)
availability	enum	available / few / soldout
sort	enum	date / price / popularity

Response příklad: Event detail

{
  "id": "evt_abc123",
  "title": "La Traviata",
  "organizer": {
    "id": "org_xyz",
    "name": "Národní divadlo"
  },
  "description": "Verdiovská opera v nové inscenaci...",
  "category": "opera",
  "tags": ["opera", "verdi", "narodni-divadlo"],
  "hero": {
    "url": "https://cdn.colosseum.cz/events/abc123/hero.webp",
    "blurhash": "LKO2?U%2Tw=w]~RBVZRi};RPxuwH"
  },
  "gallery": [
    { "url": "...", "caption": "Scéna z 1. dějství" }
  ],
  "metadata": {
    "duration": "PT2H30M",
    "language": "cs",
    "subtitles": ["en"],
    "intermission": true,
    "accessibility": true,
    "ageRestriction": null
  },
  "credits": [
    { "role": "Dirigent", "name": "Jakub Hrůša" },
    { "role": "Violetta", "name": "..." }
  ],
  "venue": {
    "id": "ven_nd",
    "name": "Národní divadlo",
    "city": "Praha"
  },
  "priceRange": { "min": 290, "max": 1490, "currency": "CZK" },
  "dates": [
    {
      "id": "date_001",
      "datetime": "2026-04-15T19:00:00+02:00",
      "availability": "available",
      "seatingType": "addressed"
    }
  ]
}

Seat map data (/v1/events/{id}/dates/{dateId}/seats)

Vyřešeno — OQ-T-01

Formát seat map dat je JSON s koordináty — HallSeatOnline s x1, y1, x2, y2 (obdélníkové koordináty sedadla), color (#AARRGGBB), rotation (stupně). Endpointy: GET /cashdesk/event/{eventId} + GET /cashdesk/event/matrix/{eventId}. Viz CoreAPI integrace.

Očekávaná struktura:

{
  "hall": {
    "name": "Hlavní sál",
    "layout": "svg_or_json_data_here",
    "stagePosition": "top",
    "sections": [
      { "id": "sec_1", "name": "Přízemí", "rows": [...] }
    ]
  },
  "seats": [
    {
      "id": "R5-S12",
      "section": "sec_1",
      "row": "5",
      "number": "12",
      "x": 245.5,
      "y": 180.0,
      "categoryId": "cat_premium",
      "status": "available",
      "price": 890
    }
  ],
  "categories": [
    {
      "id": "cat_premium",
      "name": "Premium",
      "color": "#D4AF37",
      "price": 890
    }
  ],
  "meta": {
    "totalSeats": 856,
    "availableSeats": 342,
    "updatedAt": "2026-04-15T18:30:00Z"
  }
}

---

Auth API [MVP]

Endpoint	Metoda	Popis	Fáze
/v1/auth/register	POST	Email+heslo registrace	MVP
/v1/auth/login	POST	Email+heslo login	MVP
/v1/auth/oauth/{provider}	POST	OAuth login/registrace (apple/google/facebook)	MVP
/v1/auth/refresh	POST	Token refresh	MVP
/v1/auth/forgot-password	POST	Password reset email	MVP
/v1/auth/verify-email	POST	Ověření emailu po registraci	MVP
DELETE /v1/auth/account	DELETE	GDPR smazání účtu (soft → hard po 30 dnech)	MVP

Request/Response příklady

Login:

// POST /v1/auth/login
{
  "email": "jan@example.cz",
  "password": "..."
}

// Response 200
{
  "accessToken": "eyJ...",
  "refreshToken": "eyJ...",
  "expiresIn": 900,
  "user": {
    "id": "usr_abc",
    "email": "jan@example.cz",
    "name": "Jan Novák",
    "verified": true
  }
}

OAuth:

// POST /v1/auth/oauth/apple
{
  "idToken": "apple_id_token_here",
  "nonce": "random_nonce"
}

// Response 200 (same format as login)

Token refresh:

// POST /v1/auth/refresh
{ "refreshToken": "eyJ..." }

// Response 200
{
  "accessToken": "eyJ_new...",
  "refreshToken": "eyJ_new_rotated...",
  "expiresIn": 900
}

---

Cart & Payment API [MVP]

Endpoint	Metoda	Popis	Fáze
/v1/cart	POST	Vytvořit košík (session-based, timer start)	MVP
/v1/cart/items	PUT	Přidat/odebrat položky	MVP
/v1/cart/voucher	POST	Uplatnit kupón/voucher	MVP
/v1/cart/checkout	POST	Zahájit platbu	MVP
/v1/cart/payment-status/{id}	GET	Stav platby (polling)	MVP
/v1/cart/timer	GET	Zbývající čas seat lock	MVP

Timer management

Server řídí seat lock timer. Klient zobrazuje countdown na základě expiresAt timestamp z API. Při expiraci server automaticky uvolní sedadla.

// GET /v1/cart/timer
{
  "cartId": "cart_xyz",
  "expiresAt": "2026-04-15T19:15:00Z",
  "remainingSeconds": 720,
  "warningThreshold": 120
}

Platební flow

1. Klient → POST /v1/cart/checkout (vybraná metoda)
2. Server → redirect URL / payment intent (dle brány)
3. Klient → native payment sheet (Apple/Google Pay) nebo WebView (kartová brána)
4. Klient → polling GET /v1/cart/payment-status/{id} → success/failure

// POST /v1/cart/checkout
{
  "paymentMethod": "apple_pay",
  "cartId": "cart_xyz",
  "contactInfo": {
    "email": "jan@example.cz",
    "firstName": "Jan",
    "lastName": "Novák"
  }
}

// Response 200
{
  "paymentId": "pay_abc",
  "status": "pending",
  "method": "apple_pay",
  "paymentIntent": "pi_...",
  "clientSecret": "pi_..._secret_..."
}

Payment status polling

// GET /v1/cart/payment-status/pay_abc
{
  "paymentId": "pay_abc",
  "status": "completed",
  "orderId": "ord_xyz",
  "tickets": [
    { "id": "tkt_001", "eventTitle": "La Traviata", "seat": "R5-S12" }
  ]
}

Možné stavy: pending → processing → completed | failed | expired

---

Tickets API [MVP]

Endpoint	Metoda	Popis	Fáze
/v1/tickets	GET	Moje vstupenky (včetně QR dat pro offline)	MVP
/v1/tickets/{id}	GET	Detail vstupenky	MVP
/v1/tickets/{id}/share	POST	Vygenerovat share token (deep link)	MVP
/v1/tickets/shared/{token}	GET	Načíst sdílenou vstupenku	MVP
/v1/tickets/{id}/wallet-pass	GET	Generovat Apple/Google Wallet pass	MVP

QR data format

Response musí obsahovat qrPayload (podepsaný string pro offline validaci) a qrMetadata (event name, date, seat info pro offline zobrazení).

{
  "id": "tkt_001",
  "orderId": "ord_xyz",
  "event": {
    "title": "La Traviata",
    "venue": "Národní divadlo",
    "datetime": "2026-04-15T19:00:00+02:00"
  },
  "seat": {
    "section": "Přízemí",
    "row": "5",
    "number": "12",
    "category": "Premium"
  },
  "qr": {
    "payload": "signed_jwt_string_for_offline_validation",
    "expiresAt": "2026-04-15T23:59:59Z"
  },
  "status": "valid",
  "walletPassUrl": "https://api.colosseum.cz/v1/tickets/tkt_001/wallet-pass"
}

---

Orders API [MVP]

Endpoint	Metoda	Popis	Fáze
/v1/orders	GET	Historie objednávek (stránkovaná)	MVP
/v1/orders/{id}	GET	Detail objednávky	MVP

{
  "id": "ord_xyz",
  "createdAt": "2026-04-10T14:30:00Z",
  "status": "completed",
  "paymentMethod": "apple_pay",
  "total": {
    "amount": 1780,
    "currency": "CZK"
  },
  "items": [
    {
      "ticketId": "tkt_001",
      "eventTitle": "La Traviata",
      "datetime": "2026-04-15T19:00:00+02:00",
      "seat": "Přízemí, Řada 5, Sedadlo 12",
      "category": "Premium",
      "price": 890
    }
  ],
  "voucher": null
}

---

User Profile API [MVP / F1]

Endpoint	Metoda	Popis	Fáze
/v1/profile	GET	Profil uživatele	MVP
/v1/profile	PUT	Aktualizace profilu	MVP
/v1/profile/preferences	PUT	Onboarding preference (žánry, města)	F1
/v1/profile/preferences	GET	Aktuální preference	F1

---

Notifications API [MVP / F1]

Endpoint	Metoda	Popis	Fáze
/v1/notifications	GET	Seznam notifikací (stránkovaný, cursor-based)	F1
/v1/notifications/{id}/read	PUT	Označit přečtenou	F1
/v1/notifications/read-all	PUT	Označit vše přečtené	F1
/v1/notifications/preferences	GET	Nastavení per typ notifikace	F1
/v1/notifications/preferences	PUT	Uložit nastavení	F1
/v1/devices	POST	Registrace push tokenu (FCM/APNs)	MVP
/v1/devices/{id}	DELETE	Odregistrace push tokenu (logout)	MVP

Registrace push tokenu

// POST /v1/devices
{
  "token": "fcm_or_apns_token_here",
  "platform": "ios",
  "appVersion": "1.0.0",
  "osVersion": "iOS 17.2"
}

---

Watchdog API [F1]

Endpoint	Metoda	Popis	Fáze
/v1/watchdogs	POST	Vytvořit hlídač (event + date)	F1
/v1/watchdogs	GET	Seznam aktivních hlídačů	F1
/v1/watchdogs/{id}	DELETE	Zrušit hlídač	F1

// POST /v1/watchdogs
{
  "eventId": "evt_abc123",
  "dateId": "date_001",
  "notifyVia": ["push", "email"]
}

---

Loyalty API [F1]

Endpoint	Metoda	Popis	Fáze
/v1/loyalty/account	GET	Bodový stav, tier, historie	F1
/v1/loyalty/transactions	GET	Historie bodových transakcí	F1
/v1/loyalty/rewards	GET	Katalog odměn (stránkovaný)	F1
/v1/loyalty/redeem/{rewardId}	POST	Vyměnit body za odměnu	F1

// GET /v1/loyalty/account
{
  "userId": "usr_abc",
  "points": {
    "balance": 450,
    "lifetime": 1250,
    "pendingExpiry": {
      "amount": 100,
      "expiresAt": "2026-10-15T00:00:00Z"
    }
  },
  "tier": "Silver",
  "nextTier": {
    "name": "Gold",
    "requiredPoints": 2000,
    "remaining": 750
  }
}

---

Content API [MVP / F1 / F2+]

Endpoint	Metoda	Popis	Fáze
/v1/venues/{id}	GET	Detail místa konání	MVP
/v1/organizers/{id}	GET	Detail pořadatele	MVP
/v1/subscriptions	GET	Seznam předplatných / abonmá	MVP
/v1/subscriptions/{id}	GET	Detail předplatného	MVP
/v1/faq	GET	FAQ seznam (kategorizovaný)	F1
/v1/articles	GET	Blog feed (stránkovaný)	F2+
/v1/articles/{slug}	GET	Detail článku	F2+

---

Souhrnná tabulka všech endpointů

#	Endpoint	Metoda	Fáze
1	/v1/events	GET	MVP
2	/v1/events/{id}	GET	MVP
3	/v1/events/{id}/dates	GET	MVP
4	/v1/events/{id}/dates/{dateId}/seats	GET	MVP
5	/v1/events/{id}/dates/{dateId}/categories	GET	MVP
6	/v1/events/featured	GET	MVP
7	/v1/events/search	GET	MVP
8	/v1/events/{id}/related	GET	MVP
9	/v1/auth/register	POST	MVP
10	/v1/auth/login	POST	MVP
11	/v1/auth/oauth/{provider}	POST	MVP
12	/v1/auth/refresh	POST	MVP
13	/v1/auth/forgot-password	POST	MVP
14	/v1/auth/verify-email	POST	MVP
15	/v1/auth/account	DELETE	MVP
16	/v1/cart	POST	MVP
17	/v1/cart/items	PUT	MVP
18	/v1/cart/voucher	POST	MVP
19	/v1/cart/checkout	POST	MVP
20	/v1/cart/payment-status/{id}	GET	MVP
21	/v1/cart/timer	GET	MVP
22	/v1/tickets	GET	MVP
23	/v1/tickets/{id}	GET	MVP
24	/v1/tickets/{id}/share	POST	MVP
25	/v1/tickets/shared/{token}	GET	MVP
26	/v1/tickets/{id}/wallet-pass	GET	MVP
27	/v1/orders	GET	MVP
28	/v1/orders/{id}	GET	MVP
29	/v1/profile	GET/PUT	MVP
30	/v1/profile/preferences	GET/PUT	F1
31	/v1/devices	POST	MVP
32	/v1/devices/{id}	DELETE	MVP
33	/v1/notifications	GET	F1
34	/v1/notifications/{id}/read	PUT	F1
35	/v1/notifications/read-all	PUT	F1
36	/v1/notifications/preferences	GET/PUT	F1
37	/v1/watchdogs	GET/POST	F1
38	/v1/watchdogs/{id}	DELETE	F1
39	/v1/loyalty/account	GET	F1
40	/v1/loyalty/transactions	GET	F1
41	/v1/loyalty/rewards	GET	F1
42	/v1/loyalty/redeem/{rewardId}	POST	F1
43	/v1/venues/{id}	GET	MVP
44	/v1/organizers/{id}	GET	MVP
45	/v1/subscriptions	GET	MVP
46	/v1/subscriptions/{id}	GET	MVP
47	/v1/faq	GET	F1
48	/v1/articles	GET	F2+
49	/v1/articles/{slug}	GET	F2+

Celkem: 49 endpointů (32 MVP, 12 F1, 2 F2+, zbytek sdílený)