Eventim API Workflow - TickAndLive.Connect.TempsReel

Overview

This document presents the complete workflow for using the Eventim API for event catalog management and shopping cart creation.

API Base Path: /api/v1/eventim/

1. General Architecture

Description

The Aparté ticketing solution has one database per site. Each site is autonomous, you will have one entry point (credentials) per site. Data will therefore be partitioned and specific. No object should be managed in a common way between 2 sites.

Multi-database and Multi-connector Architecture Schema

%%{init: {'theme':'base', 'themeVariables': {'primaryColor':'#fff','primaryTextColor':'#000','primaryBorderColor':'#000','lineColor':'#000','secondaryColor':'#fff','tertiaryColor':'#fff','background':'#ffffff','mainBkg':'#ffffff','secondBkg':'#ffffff','clusterBkg':'#ffffff','edgeLabelBackground':'#ffffff'}}}%%
flowchart TB
    subgraph CLIENT["👤 EXTERNAL SELLER"]
        APP[Client Application]
    end

    subgraph API["🔌 CONNECT TEMPS RÉEL API"]
        CTR[TickAndLive.Connect.TempsReel<br/><i>/api/v1/eventim/</i>]
    end

    subgraph SITES["🏛️ AUTONOMOUS SITES"]
        subgraph SITE1["📍 SITE 1"]
            AUTH1[🔑 Site 1 Credentials]
            DB1[(🗄️ Site 1<br/>Database)]
            EVENTIM1[Eventim API<br/>Connector 1]
        end

        subgraph SITE2["📍 SITE 2"]
            AUTH2[🔑 Site 2 Credentials]
            DB2[(🗄️ Site 2<br/>Database)]
            EVENTIM2[Eventim API<br/>Connector 2]
        end

        subgraph SITE3["📍 SITE N"]
            AUTH3[🔑 Site N Credentials]
            DB3[(🗄️ Site N<br/>Database)]
            EVENTIM3[Eventim API<br/>Connector N]
        end
    end

    APP -->|"Request with<br/>Site 1 credentials"| CTR
    APP -->|"Request with<br/>Site 2 credentials"| CTR
    APP -->|"Request with<br/>Site N credentials"| CTR

    CTR -->|Auth + Route| AUTH1
    CTR -->|Auth + Route| AUTH2
    CTR -->|Auth + Route| AUTH3

    AUTH1 --> EVENTIM1
    AUTH2 --> EVENTIM2
    AUTH3 --> EVENTIM3

    EVENTIM1 --> DB1
    EVENTIM2 --> DB2
    EVENTIM3 --> DB3

    DB1 -.->|"❌ NO data<br/>sharing"| DB2
    DB2 -.->|"❌ NO data<br/>sharing"| DB3
    DB1 -.->|"❌ NO data<br/>sharing"| DB3

    style CLIENT fill:#e3f2fd,stroke:#1565c0
    style API fill:#fff3e0,stroke:#ef6c00
    style SITES fill:#f3e5f5,stroke:#7b1fa2
    style SITE1 fill:#e8f5e9,stroke:#2e7d32
    style SITE2 fill:#fff8e1,stroke:#f9a825
    style SITE3 fill:#ffebee,stroke:#c62828

Key Principles

Principle	Description
Complete Isolation	Each site has its own independent database
Dedicated Authentication	Unique credentials per site (distinct credentials)
Routing by Credentials	The Connect Temps Réel API routes requests to the appropriate site based on provided credentials
No Data Sharing	Objects (events, rates, stocks, etc.) are never shared between sites
Horizontal Scalability	Adding new sites without impact on existing sites

2. Catalog Management - Initialization

Cache Strategy Overview

Endpoint	Cache Duration	When to Invalidate
`/schedule/properties`	Long-term	Only when unknown ID detected
`/schedule`	1 hour	Automatic hourly refresh
`/venues/{id}/properties`	Long-term	Only when unknown venue ID detected
`/events/poster/{id}`	Long-term	On demand or when unknown ID detected
`/eventSessions/pricesAndStocks`	15 minutes	Price/stock error, night refresh
`/products/pricesAndStocks`	15 minutes	Price/stock error, night refresh
`/eventSessions/pricesAndStocks/products`	15 minutes	Price/stock error, night refresh

%%{init: {'theme':'base', 'themeVariables': {'primaryColor':'#fff','primaryTextColor':'#000','primaryBorderColor':'#000','lineColor':'#000','secondaryColor':'#fff','tertiaryColor':'#fff','background':'#ffffff','mainBkg':'#ffffff','secondBkg':'#ffffff','clusterBkg':'#ffffff','edgeLabelBackground':'#ffffff'}}}%%
flowchart TB
    subgraph INIT["🚀 INITIALIZATION PHASE"]
        START([Application Startup]) --> PROPS
        PROPS["<b>GET /eventim/catalog/schedule/properties</b><br/>📋 Retrieve reference properties<br/><i>rates, ratesRules, taxes, contingents,<br/>categories, amountColumns</i>"]
        PROPS --> SCHEDULE
        SCHEDULE["<b>POST /eventim/catalog/schedule</b><br/>📅 Retrieve complete catalog<br/><i>eventGroups, events, sessions, products</i>"]
    end

    subgraph VENUES["🏛️ VENUE ENRICHMENT"]
        SCHEDULE --> LOOP_VENUES{{"∀ venueId<br/>from schedule"}}
        LOOP_VENUES --> VENUE_PROPS["<b>GET /eventim/catalog/venues/{venueId}/properties</b><br/>🏟️ Venue properties<br/><i>blocks, floors, categories,<br/>doors, tribunes, accesses</i>"]
        VENUE_PROPS --> LOOP_VENUES
        LOOP_VENUES --> CHECK_POSTER
    end

    subgraph POSTERS["🖼️ POSTER ENRICHMENT"]
        CHECK_POSTER{{"∀ event<br/>with hasPoster=true"}}
        CHECK_POSTER --> GET_POSTER["<b>GET /eventim/catalog/events/poster/{eventId}</b><br/>🎨 Download poster<br/><i>base64 encoded image</i>"]
        GET_POSTER --> CHECK_POSTER
        CHECK_POSTER --> PRICES_SECTION
    end

    subgraph PRICES["💰 PRICES & STOCKS"]
        PRICES_SECTION[Start Prices Loading] --> PRICES_STOCKS
        PRICES_STOCKS["<b>POST /eventim/catalog/eventSessions/pricesAndStocks</b><br/>💵 Session prices & stocks<br/><i>prices by rate/category, stocks by block/floor</i>"]
        
        PRICES_STOCKS --> CHECK_PRODUCTS{{"Global products<br/>in schedule?"}}
        CHECK_PRODUCTS -->|Yes| GLOBAL_PRODUCTS["<b>POST /eventim/catalog/products/pricesAndStocks</b><br/>📦 Global product prices & stocks<br/><i>Products NOT linked to sessions</i>"]
        CHECK_PRODUCTS -->|No| CHECK_SESSION_PRODUCTS
        GLOBAL_PRODUCTS --> CHECK_SESSION_PRODUCTS
        
        CHECK_SESSION_PRODUCTS{{"Sessions with<br/>hasProducts=true?"}}
        CHECK_SESSION_PRODUCTS -->|Yes| SESSION_PRODUCTS["<b>POST /eventim/catalog/eventSessions/pricesAndStocks/products</b><br/>🎫 Session-linked product prices & stocks<br/><i>Products linked to specific sessions</i>"]
        CHECK_SESSION_PRODUCTS -->|No| READY
        SESSION_PRODUCTS --> READY
    end

    READY([✅ Catalog Ready])

    style INIT fill:#e8f5e9,stroke:#2e7d32
    style VENUES fill:#e3f2fd,stroke:#1565c0
    style POSTERS fill:#fff3e0,stroke:#ef6c00
    style PRICES fill:#f3e5f5,stroke:#7b1fa2

3. Catalog Management - Periodic Refresh & Unknown ID Handling

Automatic Refresh Cycle

The catalog must be refreshed every hour to ensure data consistency. This periodic refresh:

Updates the complete schedule via POST /eventim/catalog/schedule
Detects and fetches new venues and posters
Maintains the 1-hour cache validity for catalog data

Unknown ID Resolution

When an API response contains an unknown ID (missing label), immediately refresh the corresponding properties endpoint to retrieve the associated label.

%%{init: {'theme':'base', 'themeVariables': {'primaryColor':'#fff','primaryTextColor':'#000','primaryBorderColor':'#000','lineColor':'#000','secondaryColor':'#fff','tertiaryColor':'#fff','background':'#ffffff','mainBkg':'#ffffff','secondBkg':'#ffffff','clusterBkg':'#ffffff','edgeLabelBackground':'#ffffff'}}}%%
flowchart TB
    subgraph REFRESH["🔄 PERIODIC REFRESH (Every Hour)"]
        TIMER([⏰ Hourly Timer]) --> REFRESH_SCHEDULE
        REFRESH_SCHEDULE["<b>POST /eventim/catalog/schedule</b><br/>🔃 Refresh full catalog"]
        
        REFRESH_SCHEDULE --> NEW_VENUES{{"New venueIds<br/>detected?"}}
        NEW_VENUES -->|Yes| FETCH_NEW_VENUES["<b>GET /eventim/catalog/venues/{venueId}/properties</b><br/>📥 Fetch new venue properties"]
        NEW_VENUES -->|No| NEW_POSTERS
        FETCH_NEW_VENUES --> NEW_POSTERS
        
        NEW_POSTERS{{"New events<br/>with hasPoster?"}}
        NEW_POSTERS -->|Yes| FETCH_NEW_POSTERS["<b>GET /eventim/catalog/events/poster/{eventId}</b><br/>🖼️ Fetch new posters"]
        NEW_POSTERS -->|No| END_REFRESH
        FETCH_NEW_POSTERS --> END_REFRESH
        
        END_REFRESH([🔄 Refresh cycle complete])
    end

    subgraph UNKNOWN["❓ UNKNOWN ID HANDLING"]
        API_RESPONSE([API Response with<br/>unknown ID]) --> CHECK_ID_TYPE
        
        CHECK_ID_TYPE{{"ID type?"}}
        
        CHECK_ID_TYPE -->|"rateId, taxId,<br/>categoryId, contingentId,<br/>amountColumnId, ruleId"| REFRESH_PROPS
        CHECK_ID_TYPE -->|"blockId, floorId,<br/>doorId, tribuneId,<br/>accessId, designationId"| REFRESH_VENUE
        
        REFRESH_PROPS["<b>GET /eventim/catalog/schedule/properties</b><br/>🔃 Refresh reference properties"]
        REFRESH_VENUE["<b>GET /eventim/catalog/venues/{venueId}/properties</b><br/>🔃 Refresh venue properties"]
        
        REFRESH_PROPS --> RETRY([🔁 Retry processing with updated labels])
        REFRESH_VENUE --> RETRY
    end

    style REFRESH fill:#fff8e1,stroke:#f9a825
    style UNKNOWN fill:#ffebee,stroke:#c62828

4. Cart Creation - Reserved Seating with Manual Selection

%%{init: {'theme':'base', 'themeVariables': {'primaryColor':'#fff','primaryTextColor':'#000','primaryBorderColor':'#000','lineColor':'#000','secondaryColor':'#fff','tertiaryColor':'#fff','background':'#ffffff','mainBkg':'#ffffff','secondBkg':'#ffffff','clusterBkg':'#ffffff','edgeLabelBackground':'#ffffff'}}}%%
flowchart TB
    subgraph MANUAL["🎯 RESERVED SEATING - MANUAL SEAT SELECTION"]
        START_MANUAL([👤 User wants to<br/>choose specific seats]) --> CHECK_CACHE
        
        CHECK_CACHE{{"First call for<br/>this session?"}}
        
        CHECK_CACHE -->|Yes - No cache| SEATMAP_FULL["<b>POST /eventim/catalog/eventSessions/seatMap</b><br/>🗺️ Full seat map download<br/><i>onlyAvailableSeats: false</i><br/><i>includeDecorations: true</i><br/>📥 Cache map + decorations locally"]
        
        CHECK_CACHE -->|No - Cache exists| SEATMAP_AVAIL["<b>POST /eventim/catalog/eventSessions/seatMap</b><br/>🗺️ Available seats only<br/><i>onlyAvailableSeats: true</i><br/><i>includeDecorations: false</i><br/>🔄 Merge with cached decorations"]
        
        SEATMAP_FULL --> DISPLAY_MAP[🖥️ Display interactive seat map<br/><i>Show all seats with decorations</i>]
        SEATMAP_AVAIL --> DISPLAY_MAP
        
        DISPLAY_MAP --> USER_CLICK{{"👆 User clicks<br/>on a seat"}}
        
        USER_CLICK -->|Select seat| ALLOCATE_SELECT["<b>POST /eventim/cart/allocateManualSeats</b><br/>✅ actionSelect: true<br/><i>Add seat to cart</i>"]
        USER_CLICK -->|Deselect seat| ALLOCATE_DESELECT["<b>POST /eventim/cart/allocateManualSeats</b><br/>❌ actionSelect: false<br/><i>Remove seat from cart</i>"]
        
        ALLOCATE_SELECT --> CHECK_ERROR{{"Price/Stock<br/>error?"}}
        ALLOCATE_DESELECT --> UPDATE_UI
        
        CHECK_ERROR -->|Yes| REFRESH_PRICES["🔃 Invalidate 15min cache<br/><b>POST /eventim/catalog/eventSessions/pricesAndStocks</b><br/>+ conditionally:<br/><b>POST /eventim/catalog/products/pricesAndStocks</b><br/><b>POST /eventim/catalog/eventSessions/pricesAndStocks/products</b>"]
        CHECK_ERROR -->|No| UPDATE_UI
        
        REFRESH_PRICES --> DISPLAY_MAP
        
        UPDATE_UI[🔄 Update UI with cart state<br/><i>cartId, cartItemId, allocated seats</i>]
        
        UPDATE_UI --> CONTINUE{{"Continue<br/>selection?"}}
        CONTINUE -->|Yes| USER_CLICK
        CONTINUE -->|No| CART_READY
        
        CART_READY([🛒 Cart ready for checkout])
    end

    style MANUAL fill:#e0f2f1,stroke:#00897b

5. Cart Creation - Automatic Placement (Best Seats)

%%{init: {'theme':'base', 'themeVariables': {'primaryColor':'#fff','primaryTextColor':'#000','primaryBorderColor':'#000','lineColor':'#000','secondaryColor':'#fff','tertiaryColor':'#fff','background':'#ffffff','mainBkg':'#ffffff','secondBkg':'#ffffff','clusterBkg':'#ffffff','edgeLabelBackground':'#ffffff'}}}%%
flowchart TB
    subgraph AUTO["⚡ AUTOMATIC PLACEMENT"]
        START_AUTO([👤 User chooses<br/>automatic placement<br/><i>OR General Admission session</i>]) --> SELECT_CRITERIA
        
        SELECT_CRITERIA[📝 Selection criteria<br/><i>• categoryId</i><br/><i>• quantities per rateId</i><br/><i>• Optional: blockId, floorId, contingentId</i>]
        
        SELECT_CRITERIA --> ALLOCATE_BEST
        
        ALLOCATE_BEST["<b>POST /eventim/cart/allocateBestSeats</b><br/>🎲 System allocates best available seats<br/><i>Returns seats grouped by contiguity</i><br/><i>isContiguous flag indicates adjacent seats</i>"]
        
        ALLOCATE_BEST --> CHECK_ERROR{{"Price/Stock<br/>error?"}}
        
        CHECK_ERROR -->|Yes| REFRESH_DATA
        CHECK_ERROR -->|No| SHOW_RESULT
        
        REFRESH_DATA["🔃 Invalidate 15min cache"]
        REFRESH_DATA --> REFRESH_SESSION["<b>POST /eventim/catalog/eventSessions/pricesAndStocks</b><br/>💵 Refresh session prices"]
        REFRESH_SESSION --> CHECK_GLOBAL_PROD{{"Global products?"}}
        CHECK_GLOBAL_PROD -->|Yes| REFRESH_GLOBAL_PROD["<b>POST /eventim/catalog/products/pricesAndStocks</b>"]
        CHECK_GLOBAL_PROD -->|No| CHECK_SESSION_PROD
        REFRESH_GLOBAL_PROD --> CHECK_SESSION_PROD
        CHECK_SESSION_PROD{{"Session products<br/>(hasProducts)?"}}
        CHECK_SESSION_PROD -->|Yes| REFRESH_SESSION_PROD["<b>POST /eventim/catalog/eventSessions/pricesAndStocks/products</b>"]
        CHECK_SESSION_PROD -->|No| SELECT_CRITERIA
        REFRESH_SESSION_PROD --> SELECT_CRITERIA
        
        SHOW_RESULT[🖥️ Display allocated seats<br/><i>• isContiguous status</i><br/><i>• seatProperties </i><br/><i>• finalAmount, amountDetails</i>]
        
        SHOW_RESULT --> ACCEPT{{"Accept<br/>proposal?"}}
        
        ACCEPT -->|Yes| CART_READY([🛒 Cart ready for checkout])
        ACCEPT -->|No| REMOVE_SEATS["<b>POST /eventim/cart/removeSeats</b><br/>🗑️ Release allocated seats"]
        
        REMOVE_SEATS --> SELECT_CRITERIA
    end

    style AUTO fill:#fce4ec,stroke:#c2185b

6. Cart Consultation (Optional)

%%{init: {'theme':'base', 'themeVariables': {'primaryColor':'#fff','primaryTextColor':'#000','primaryBorderColor':'#000','lineColor':'#000','secondaryColor':'#fff','tertiaryColor':'#fff','background':'#ffffff','mainBkg':'#ffffff','secondBkg':'#ffffff','clusterBkg':'#ffffff','edgeLabelBackground':'#ffffff'}}}%%
flowchart TB
    subgraph CART_MGMT["🛒 CART CONSULTATION (Optional)"]
        CART_EXISTS([Cart in progress<br/><i>cartId + cartItemId available</i>]) --> GET_DETAIL
        
        GET_DETAIL["<b>GET /eventim/cart/{cartId}/{cartItemId}</b><br/>📋 Retrieve cart details<br/><i>Optional verification step</i>"]
        
        GET_DETAIL --> DISPLAY_CART[🖥️ Display cart summary<br/><i>• Event & session info</i><br/><i>• Allocated seats with prices</i><br/><i>• Total amounts</i><br/><i>• Contiguity status</i>]
        
        DISPLAY_CART --> ACTIONS{{"User action?"}}
        
        ACTIONS -->|Remove specific seats| REMOVE["<b>POST /eventim/cart/removeSeats</b><br/>🗑️ Release selected seats"]
        ACTIONS -->|Add more seats| ADD_MORE([↩️ Return to seat selection flow])
        ACTIONS -->|Confirm purchase| CONFIRM["<b>POST /eventim/order/confirm</b><br/>✅ Finalize order"]
        
        REMOVE --> GET_DETAIL
        CONFIRM --> ORDER_CONFIRMED([📝 Order confirmed<br/><i>orderId returned</i>])
    end

    style CART_MGMT fill:#e1f5fe,stroke:#0288d1

7. Complete Workflow - Decision Tree

%%{init: {'theme':'base', 'themeVariables': {'primaryColor':'#fff','primaryTextColor':'#000','primaryBorderColor':'#000','lineColor':'#000','secondaryColor':'#fff','tertiaryColor':'#fff','background':'#ffffff','mainBkg':'#ffffff','secondBkg':'#ffffff','clusterBkg':'#ffffff','edgeLabelBackground':'#ffffff'}}}%%
flowchart TB
    subgraph PHASE1["📚 PHASE 1: INITIALIZATION"]
        direction TB
        A1["<b>GET</b> /schedule/properties"] --> A2["<b>POST</b> /schedule"]
        A2 --> A3["∀ venue: <b>GET</b> /venues/{id}/properties"]
        A3 --> A4["∀ hasPoster: <b>GET</b> /events/poster/{id}"]
        A4 --> A5["<b>POST</b> /eventSessions/pricesAndStocks"]
        A5 --> A6{{"Global products<br/>in schedule?"}}
        A6 -->|Yes| A7["<b>POST</b> /products/pricesAndStocks"]
        A6 -->|No| A8
        A7 --> A8{{"Sessions with<br/>hasProducts?"}}
        A8 -->|Yes| A9["<b>POST</b> /eventSessions/pricesAndStocks/products"]
        A8 -->|No| A10([Init Complete])
        A9 --> A10
    end

    subgraph PHASE2["🔄 PHASE 2: HOURLY REFRESH"]
        direction TB
        B1["⏰ Every hour"] --> B2["<b>POST</b> /schedule"]
        B2 --> B3["Fetch new venues/posters if detected"]
    end

    subgraph PHASE3["❓ PHASE 3: UNKNOWN ID"]
        direction TB
        C1["Unknown ID detected"] --> C2{{"ID type?"}}
        C2 -->|Reference ID| C3["<b>GET</b> /schedule/properties"]
        C2 -->|Venue ID| C4["<b>GET</b> /venues/{id}/properties"]
    end

    subgraph PHASE4["🛒 PHASE 4: CART CREATION"]
        direction TB
        D0{{"Session type?"}}
        
        D0 -->|"Reserved Seating"| D1{{"Selection mode?"}}
        D0 -->|"General Admission"| D5
        
        D1 -->|Manual| D2{{"First call?"}}
        D1 -->|Auto| D5
        
        D2 -->|Yes| D3["<b>POST</b> /seatMap<br/><i>full + decorations</i>"]
        D2 -->|No| D4["<b>POST</b> /seatMap<br/><i>available only</i>"]
        
        D3 --> D6["<b>POST</b> /allocateManualSeats"]
        D4 --> D6
        
        D5["<b>POST</b> /allocateBestSeats"]
        
        D6 --> D7{{"Price/Stock<br/>error?"}}
        D5 --> D7
        
        D7 -->|Yes| D8["Invalidate 15min cache<br/><b>POST</b> /eventSessions/pricesAndStocks<br/>+ conditional:<br/><b>POST</b> /products/pricesAndStocks<br/><b>POST</b> /eventSessions/pricesAndStocks/products"]
        D7 -->|No| D9([Cart ready])
        D8 --> D0
    end

    subgraph PHASE5["📋 PHASE 5: CART INFO (Optional)"]
        direction TB
        E1["<b>GET</b> /cart/{cartId}/{cartItemId}"]
    end

    subgraph PHASE6["✅ PHASE 6: ORDER CONFIRMATION"]
        direction TB
        F1["<b>POST</b> /order/confirm"] --> F2([Order confirmed])
    end

    PHASE1 --> PHASE2
    PHASE2 --> PHASE4
    PHASE3 -.-> PHASE4
    PHASE4 --> PHASE5
    PHASE5 --> PHASE6

    style PHASE1 fill:#c8e6c9,stroke:#388e3c
    style PHASE2 fill:#fff9c4,stroke:#f9a825
    style PHASE3 fill:#ffcdd2,stroke:#c62828
    style PHASE4 fill:#f8bbd0,stroke:#c2185b
    style PHASE5 fill:#e1f5fe,stroke:#0288d1
    style PHASE6 fill:#d1c4e9,stroke:#7b1fa2

8. Endpoint Summary Table

Phase	Endpoint	Method	Trigger	Cache Strategy
Catalog Init	`/eventim/catalog/schedule/properties`	GET	1. Initialization 2. Unknown reference ID	Long-term
Catalog Init	`/eventim/catalog/schedule`	POST	1. Initialization 2. Every hour	1 hour
Catalog Init	`/eventim/catalog/venues/{venueId}/properties`	GET	1. Per venueId from schedule 2. Unknown venue-related ID	Long-term
Catalog Init	`/eventim/catalog/events/poster/{eventId}`	GET	Only if event.hasPoster=true	Long-term
Pricing	`/eventim/catalog/eventSessions/pricesAndStocks`	POST	1. Initialization 2. Cart creation phase (if 15min cache expired or price/stock error) 3. Night refresh	15 min
Pricing	`/eventim/catalog/products/pricesAndStocks`	POST	1. Init if global products exist in schedule 2. Cart creation phase (if 15min cache expired or price/stock error) 3. Night refresh	15 min
Pricing	`/eventim/catalog/eventSessions/pricesAndStocks/products`	POST	1. Init if sessions have hasProducts=true 2. Cart creation phase (if 15min cache expired or price/stock error) 3. Night refresh	15 min
Cart	`/eventim/catalog/eventSessions/seatMap`	POST	Reserved seating - Manual selection	See SeatMap Strategy
Cart	`/eventim/cart/allocateBestSeats`	POST	Auto placement / General admission	Real-time
Cart	`/eventim/cart/allocateManualSeats`	POST	Manual seat selection/deselection	Real-time
Cart	`/eventim/cart/removeSeats`	POST	Seat removal from cart	Real-time
Cart	`/eventim/cart/{cartId}/{cartItemId}`	GET	Optional - Cart verification	Real-time
Order	`/eventim/order/confirm`	POST	Order finalization	N/A

9. SeatMap Caching Strategy

Optimization Strategy for Seat Maps

To minimize API calls and bandwidth, seat maps use a two-stage caching approach:

Call Type	onlyAvailableSeats	includeDecorations	Action	Purpose
First call for event session	`false`	`true`	Download full map + decorations → Store in local cache	Complete venue layout with static elements
Subsequent calls	`true`	`false`	Get available seats only → Merge with cached decorations	Real-time availability with cached layout

10. Error Handling - Price/Stock Changes

15-Minute Cache Management

Price and stock data endpoints use a 15-minute cache to balance performance and data freshness:

/eventim/catalog/eventSessions/pricesAndStocks
/eventim/catalog/products/pricesAndStocks
/eventim/catalog/eventSessions/pricesAndStocks/products

Cache Invalidation Triggers

The 15-minute cache must be immediately invalidated when:

⚠️ Price/Stock Error: Cart API returns an error indicating price or stock has changed
🕐 Cache Expiration: 15 minutes have elapsed since last refresh

Error Recovery Flow

When a price/stock error occurs during cart creation:

%%{init: {'theme':'base', 'themeVariables': {'primaryColor':'#fff','primaryTextColor':'#000','primaryBorderColor':'#000','lineColor':'#000','secondaryColor':'#fff','tertiaryColor':'#fff','background':'#ffffff','mainBkg':'#ffffff','secondBkg':'#ffffff','clusterBkg':'#ffffff','edgeLabelBackground':'#ffffff'}}}%%
flowchart TB
    subgraph ERROR["⚠️ PRICE/STOCK ERROR HANDLING - GRANULAR REFRESH"]
        ERR([Cart API returns<br/>price/stock error]) --> IDENTIFY
        
        IDENTIFY{{"Identify<br/>error source<br/>endpoint"}}
        
        IDENTIFY -->|eventSessions<br/>price/stock error| INVALIDATE_SESSION
        IDENTIFY -->|products<br/>price/stock error| INVALIDATE_PRODUCTS
        IDENTIFY -->|session products<br/>price/stock error| INVALIDATE_SESSION_PROD
        
        INVALIDATE_SESSION[🗑️ Invalidate cache:<br/>eventSessions/pricesAndStocks]
        INVALIDATE_PRODUCTS[🗑️ Invalidate cache:<br/>products/pricesAndStocks]
        INVALIDATE_SESSION_PROD[🗑️ Invalidate cache:<br/>eventSessions/pricesAndStocks/products]
        
        INVALIDATE_SESSION --> REFRESH_SESSION["<b>POST</b> /eventSessions/pricesAndStocks<br/>🔄 Refresh ONLY this endpoint"]
        INVALIDATE_PRODUCTS --> REFRESH_PRODUCTS["<b>POST</b> /products/pricesAndStocks<br/>🔄 Refresh ONLY this endpoint"]
        INVALIDATE_SESSION_PROD --> REFRESH_SESSION_PRODUCTS["<b>POST</b> /eventSessions/pricesAndStocks/products<br/>🔄 Refresh ONLY this endpoint"]
        
        REFRESH_SESSION --> RETRY_SESSION([🔁 Retry cart operation<br/>with updated session prices])
        REFRESH_PRODUCTS --> RETRY_PRODUCTS([🔁 Retry cart operation<br/>with updated product prices])
        REFRESH_SESSION_PRODUCTS --> RETRY_SESSION_PRODUCTS([🔁 Retry cart operation<br/>with updated session product prices])
    end

    style ERROR fill:#fff3e0,stroke:#e65100
    style INVALIDATE_SESSION fill:#ffebee,stroke:#c62828
    style INVALIDATE_PRODUCTS fill:#e8f5e9,stroke:#2e7d32
    style INVALIDATE_SESSION_PROD fill:#e3f2fd,stroke:#1565c0

11. Key Business Rules

Session Types & Cart Creation Methods

Session Type	Seating	Cart Creation Method
Reserved Seating	Manual selection	`seatMap` → `allocateManualSeats`
Reserved Seating	Auto placement	`allocateBestSeats`
General Admission	N/A	`allocateBestSeats`

Product Types

Product Type	Endpoint	Trigger
Global products (not session-linked)	`/products/pricesAndStocks`	If present in schedule
Session-linked products	`/eventSessions/pricesAndStocks/products`	If session.hasProducts=true

Seat Contiguity

The isContiguous flag in allocateBestSeats response indicates whether allocated seats are physically adjacent - important for group bookings and customer experience.

12. Data Flow Summary

%%{init: {'theme':'base', 'themeVariables': {'primaryColor':'#fff','primaryTextColor':'#000','primaryBorderColor':'#000','lineColor':'#000','secondaryColor':'#fff','tertiaryColor':'#fff','background':'#ffffff','mainBkg':'#ffffff','secondBkg':'#ffffff','clusterBkg':'#ffffff','edgeLabelBackground':'#ffffff'}}}%%
flowchart LR
    subgraph CATALOG["📚 CATALOG DATA"]
        SP[schedule/properties]
        SC[schedule]
        VP[venues/properties]
        PS[poster]
    end
    
    subgraph PRICING["💰 PRICING DATA"]
        ESP[eventSessions/<br/>pricesAndStocks]
        PP[products/<br/>pricesAndStocks]
        ESPP[eventSessions/<br/>pricesAndStocks/products]
    end
    
    subgraph CART["🛒 CART OPERATIONS"]
        SM[seatMap]
        ABS[allocateBestSeats]
        AMS[allocateManualSeats]
        RS[removeSeats]
        CD[cart detail]
    end
    
    subgraph ORDER["📝 ORDER"]
        OC[order/confirm]
    end
    
    SP --> SC
    SC --> VP
    SC --> PS
    SC --> ESP
    SC --> PP
    SC --> ESPP
    
    ESP --> SM
    ESP --> ABS
    PP --> ABS
    ESPP --> ABS
    
    SM --> AMS
    ABS --> CD
    AMS --> CD
    RS --> CD
    
    CD --> OC

    style CATALOG fill:#c8e6c9,stroke:#388e3c
    style PRICING fill:#fff9c4,stroke:#f9a825
    style CART fill:#f8bbd0,stroke:#c2185b
    style ORDER fill:#d1c4e9,stroke:#7b1fa2

Overview​

1. General Architecture​

Description​

Multi-database and Multi-connector Architecture Schema​

Key Principles​

2. Catalog Management - Initialization​

Cache Strategy Overview​

3. Catalog Management - Periodic Refresh & Unknown ID Handling​

Automatic Refresh Cycle​

Unknown ID Resolution​

4. Cart Creation - Reserved Seating with Manual Selection​

5. Cart Creation - Automatic Placement (Best Seats)​

6. Cart Consultation (Optional)​

7. Complete Workflow - Decision Tree​

8. Endpoint Summary Table​

9. SeatMap Caching Strategy​

Optimization Strategy for Seat Maps​

10. Error Handling - Price/Stock Changes​

15-Minute Cache Management​

Cache Invalidation Triggers​

Error Recovery Flow​

11. Key Business Rules​

Session Types & Cart Creation Methods​

Product Types​

Seat Contiguity​

12. Data Flow Summary​

TODO : Complete cart/order endpoints​