CoreAPI — Integrace
Analýza vychází z OpenAPI specifikace coreapi_online.json (CoreApi /online/ v17.0.0.0). Kompletní raw data: context/analysis/coreapi-analysis.md.
Colosseum CoreAPI je transakční backend pro zákaznickou zónu. APP s ním komunikuje přímo pro operace s košíkem, platbami, objednávkami, účtem a seat map daty.
| Endpointy | 70 ve 13 doménách |
| Autentizace | JWT token per session (POST /token/create) |
| Formát | REST, JSON (application/json) |
| Verze | v17.0.0.0 |
Přehled domén
| Doména | Počet | Fáze | Účel |
|---|---|---|---|
| Account | 9 | MVP | Registrace, login, OAuth, profil, heslo |
| Cart | 20+ | MVP | Správa košíku — vstupenky, vouchery, balíčky, služby, fees |
| Cashdesk | 12 | MVP | Seat map data, cenové kategorie, dostupné doplňky |
| Catalog | 6 | MVP | Detaily akcí, tours, okruhů, předplatného, balíčků |
| Order | 5 | MVP | Vytvoření, detail, storno, seznam, obnovení do košíku |
| Payment | 2 | MVP | Vytvoření platby, ověření stavu |
| Sale | 3 | MVP | Prodané položky, seznam prodejů, detail (wallet) |
| Document | 4 | MVP | E-vstupenka, e-voucher, e-služba, e-účtenka |
| Program | 1 | TBD | Seznam tours |
| Codebook | 2 | MVP | Číselníky (země, jazyky) |
| GroupBook | 2 | F2+ | Skupinové rezervace |
| Registry | 1 | MVP | Registrace firmy |
| Token | 1 | MVP | JWT session token |
Mapování endpointů na obrazovky
Account
| Endpoint | Metoda | Obrazovky | Fáze |
|---|---|---|---|
/account | GET | P9 Účet, S14 Editace | MVP |
/account/login | POST | S4 Přihlášení | MVP |
/account/login-by-provider | POST | S4 (OAuth) | MVP |
/account/registration | POST | S5 Registrace | MVP |
/account/change-password | POST | S14 Editace profilu | MVP |
/account/forgotten-password-prepare | POST | S4 (zapomenuté heslo) | MVP |
/account/forgotten-password-finish | POST | S4 (zapomenuté heslo) | MVP |
/account/logout | GET | P9 Účet | MVP |
/account/set-language | POST | S14 Nastavení | MVP |
Cashdesk (seat map)
| Endpoint | Metoda | Obrazovky | Fáze |
|---|---|---|---|
/cashdesk/event/{eventId} | GET | P4 Seat Map — sedadla s koordináty | MVP |
/cashdesk/event/matrix/{eventId} | GET | P4 (maticové rozložení) | MVP |
/cashdesk/event/state/{eventId} | GET | P4 (refresh stavů, polling) | MVP |
/cashdesk/tour/{tourId} | GET | P4 varianta pro tours | TBD |
/cashdesk/non-timed-circuit | GET | S1 varianta pro circuits | TBD |
/cashdesk/subscription/{subscriptionId} | GET | S11 Předplatné (sál) | MVP |
/cashdesk/services | GET | P5 Košík (doplňky) | F1 |
/cashdesk/vouchers | GET | P5 Košík (dostupné vouchery) | MVP |
/cashdesk/credit-packages | GET | F1 Věrnostní hub | F1 |
/cashdesk/goods | GET | F2+ Doplňkový prodej | F2+ |
Cart
| Endpoint | Metoda | Obrazovky | Fáze |
|---|---|---|---|
/cart | GET | P5 Košík — kompletní stav | MVP |
/cart/delete | DELETE | P5 (zrušení košíku) | MVP |
/cart/set-person | POST | S2 Osobní údaje, P6 guest checkout | MVP |
/cart/ticket/add/event | POST | P4 → P5 (přidání adresných) | MVP |
/cart/ticket/add/event-non-numbered | POST | S1 → P5 (neadresné) | MVP |
/cart/ticket/add/tour | POST | P4/S1 (tour vstupenky) | TBD |
/cart/ticket/remove | POST | P5 (odebrání) | MVP |
/cart/ticket/set-customer-category | PUT | P5 (student, senior...) | MVP |
/cart/ticket/set-voucher | POST | P5 (per-ticket voucher) | MVP |
/cart/voucher/add | POST | P5 (cart-level voucher) | MVP |
/cart/voucher-payment/add | POST | P6 (voucher jako platba) | MVP |
/cart/service/set | POST | P5 (přidání služby) | F1 |
/cart/goods/add | POST | F2+ (doplňkový prodej) | F2+ |
Order + Payment + Sale
| Endpoint | Metoda | Obrazovky | Fáze |
|---|---|---|---|
/order/create | POST | P6 Checkout | MVP |
/order/list | POST | S7 Historie objednávek | MVP |
/order/{orderNumber} | GET | S7, X1/X2 Thank you | MVP |
/order/cancel/{orderNumber} | GET | S7 (storno) | MVP |
/order/restore-to-cart/{orderNumber} | GET | S7 (obnova) | MVP |
/payment/create | POST | P6 Checkout | MVP |
/payment/verify | POST | X1/X3 (ověření platby) | MVP |
/sale/items | POST | P7 Wallet, S7 Historie | MVP |
/sale/list | POST | S7 Historie | MVP |
/sale/{saleNumber} | GET | S8 Detail vstupenky | MVP |
/document/eticket | POST | P7 Wallet, S8 Detail | MVP |
/document/evoucher | POST | P7 (e-voucher) | MVP |
/document/ebill | POST | S8 (e-účtenka) | MVP |
Data model alignment — PRD vs CoreAPI
| PRD entita | CoreAPI schema | Klíčové rozdíly |
|---|---|---|
| Event | EventProgramItem | API rozlišuje title_id a event_id. Má event_tag_name/color. Galerie, video, credits — v DatoCMS. |
| Hall / Seat map | HallSeatOnline + HallSection | JSON koordináty (x1,y1,x2,y2), ne SVG. Sedadla mají rotaci a barvu. |
| Ticket type (dospělý/student) | CustomerCategory | PRD říká "typ vstupného", API říká "customer category" s discount_type/value. |
| Cenová kategorie | PriceCategory | Lokační kategorie s barvou a abbreviation. |
| Voucher / kupón | Voucher | Trojí typologie: per-ticket, cart-level, platební. DiscountType: Percent, ByAmount, ToAmount. |
| — (PRD nemá) | Package | Balíčky vstupenek (rodinný, combo). Numbered i non-numbered. |
| — (jen OQ) | Tour / Circuit | Prohlídkové vstupenky — API plně podporuje. |
| Order | Order | Pre-payment objednávka. Může být cancelled, restored to cart. |
| — (PRD nerozlišuje) | Sale | Post-payment prodej. Vstupenky s barcodes, dokumenty. |
| E-vstupenka | TicketOnline | Dva identifikátory: number (tištěné) a barcode (QR pro skenování). |
| Věrnostní program | LoyaltyProgram | 4 typy: Points, TicketCount, Revenue, EventCount. LoyaltyProgramPoints = platební metoda. |
Nové poznatky z API
1. Seat map = JSON koordináty
API vrací sedadla jako HallSeatOnline s x1, y1, x2, y2 (obdélníkové koordináty), color (#AARRGGBB), rotation (stupně). Sály mají sekce s tvary (Rectangle, Triangle, Quadrilateral, Ellipse). Na klientu se renderuje Canvas/SVG z těchto JSON dat.
2. Trojí voucher typologie
- Per-ticket (
/cart/ticket/set-voucher) — voucher přiřazený ke konkrétní vstupence - Cart-level (
/cart/voucher/add) — voucher na celou objednávku - Platební (
/cart/voucher-payment/add) — voucher jako platební metoda (dárkový poukaz)
Kupóny JSOU kumulativní — per-ticket + cart-level + payment voucher na jedné objednávce.
3. Order vs Sale lifecycle
API rozlišuje:
- Order — pre-payment (může být cancelled, restored to cart)
- Sale — post-payment (vstupenky s barcodes, dokumenty)
Flow: order/create → payment/create → payment/verify → Sale.
4. Packages — nový koncept
Balíčky vstupenek (rodinný, combo): cart/package/add, catalog/package/{id}, cashdesk/package. Numbered i non-numbered varianty.
5. Multi-seats (dvojsedadla)
HallSeatOnline.seat_group_id: kladná hodnota = skupina (dvojsedadlo), záporná = single seat. Edge case pro P4 Seat Map.
6. 23+ platebních metod
Kromě karty a Apple/Google Pay: LoyaltyProgramPoints (věrnostní body), BenefitPlus, Pluxee, Edenred, Benefity, Twisto, GoPay, Comgate, eAPI, PayPal, bankovní převod, hotovost (rezervace).
7. Fees jako separátní řádky
Cart a Order mají fees[] — servisní poplatky jako samostatné řádky v objednávce.
8. Tours / Circuits — plná podpora
API má kompletní infrastrukturu pro prohlídky: timed tours + non-timed circuits. ProductType zahrnuje Tour.
9. Barcode vs Ticket Number
TicketOnline má number (tištěné číslo) i barcode (QR pro skenování). Pro wallet je klíčový barcode.
10. Server-managed countdown
Cart má validity timestamp — server řídí seat lock timer. Klient zobrazuje countdown z API.
Platební metody (PaymentType enum)
| Metoda | Relevance pro MA |
|---|---|
| Card | MVP — kartová platba |
| ApplePay | MVP — nativní Apple Pay |
| GooglePay | MVP — nativní Google Pay |
| Cash | MVP — rezervace na pokladnu |
| BankTransfer | MVP — bankovní převod |
| GPWebPay, Gopay, eAPI, Comgate | MVP — platební brány (dle konfigurace) |
| Voucher | MVP — voucherová platba |
| LoyaltyProgramPoints | F1 — věrnostní body jako platba |
| BenefitPlus, Pluxee, Edenred, Benefity | Volitelné — zaměstnanecké benefity |
| PayPal | Volitelné |
| Twisto | Volitelné — odložená platba |
Vyřešené otevřené otázky
| OQ | Otázka | Odpověď z CoreAPI |
|---|---|---|
| OQ-01-01 | Prohlídkové vstupenky v MVP? | API plně podporuje tours + circuits. Rozhodnutí je business scope, ne tech bariéra. |
| OQ-01-03 | Kupóny — kumulativnost? | Ano. Per-ticket + cart-level + payment voucher = N voucherů na objednávku. |
| OQ-01-04 | Seat map formát? | JSON s koordináty (x1,y1,x2,y2), barva #AARRGGBB, rotace. Ne SVG. |
| OQ-01-05 | Servisní poplatek? | Ano, jako fees[] v cart/order. Separátní řádky s FeeType. |
| OQ-T-01 | Formát seat map dat? | Viz OQ-01-04 — JSON koordináty, rendering na klientu. |