Skip to content

GoGlobal Hotel Integration - Use Case Specification

1. Introduction

1.1 Purpose

This document describes all use cases for the GoGlobal hotel integration plugin (tqgglbl), detailing the interactions between actors and the system for searching, booking, and managing hotel accommodations through the Yanolja GoGlobal API (v3.16.8).

1.2 Scope

This document covers: - Hotel availability search use cases (city, filters, multi-room) - Extended shopping use cases (hotel info, price breakdown) - Offer validation and booking lifecycle use cases - Booking management use cases (status, details, cancellation, amendment) - Voucher generation use cases - Static data management use cases - Dual-mode search (online vs contracted) use cases - End-to-end flow use cases

1.3 Actors

Primary Actors: - Customer - End user searching and booking hotels via B2C website - Agent - Travel agent managing hotel bookings via B2B portal or admin portal - Administrator - System administrator managing configuration and static data

Secondary Actors: - GoGlobal API - External Yanolja GoGlobal hotel supplier system (SOAP/REST) - NTS Plugin - Internal PostgreSQL-based contracted hotel system - System Scheduler - Automated background processes for static data refresh - TripMaker Engine - Internal trip itinerary planner requesting accommodation search

2. Use Case Overview

2.1 Use Case Diagram

+-------------------------------------------------------------------------+
|                  GoGlobal Hotel Integration System                       |
+-------------------------------------------------------------------------+
|                                                                         |
|  Customer/Agent              Administrator              System          |
|       |                           |                        |            |
|       +---> UC-1: Hotel Availability Search                |            |
|       |                           |                        |            |
|       +---> UC-2: Extended Shopping (Info, Breakdown)      |            |
|       |                           |                        |            |
|       +---> UC-3: Offer Validation                         |            |
|       |                           |                        |            |
|       +---> UC-4: Booking Creation                         |            |
|       |                           |                        |            |
|       +---> UC-5: Booking Status Check                     |            |
|       |                           |                        |            |
|       +---> UC-6: Booking Details                          |            |
|       |                           |                        |            |
|       +---> UC-7: Advanced Booking Search                  |            |
|       |                           |                        |            |
|       +---> UC-8: Booking Cancellation                     |            |
|       |                           |                        |            |
|       +---> UC-9: Voucher Generation                       |            |
|       |                           |                        |            |
|       +---> UC-10: Booking Amendment                       |            |
|       |                           |                        |            |
|       +---> UC-11: End-to-End Flows                        |            |
|       |                           |                        |            |
|       +---> UC-13: Dual-Mode Search                        |            |
|       |                           |                        |            |
|                           +---> UC-12: Static Data Management           |
|                           |                        |                    |
|                                                    +---> Scheduled      |
|                                                    |     Refresh        |
+-------------------------------------------------------------------------+

2.2 Use Case List

UC ID Use Case Name Primary Actor GoGlobal Op Priority Status
UC-1.1 Basic city search Customer 11 High Planned
UC-1.2 Multi-room search Customer 11 High Planned
UC-1.3 Search with children (extra beds) Customer 11 High Planned
UC-1.4 Search with infants (cots) Customer 11 Medium Planned
UC-1.5 Search with filters Customer 11 High Planned
UC-1.6 Search by hotel ID Customer 11 Medium Planned
UC-1.7 Nationality and currency Customer 11 High Planned
UC-1.8 Sort order options Customer 11 Medium Planned
UC-1.9 Async results (MaximumWaitTime) Customer 11 Low Planned
UC-1.10 No results / invalid input Customer 11 High Planned
UC-1.11 Limit exceeded Customer 11 High Planned
UC-2.1 Hotel info without geo Customer 6 Medium Planned
UC-2.2 Hotel info with geo Customer 61 Medium Planned
UC-2.3 Hotel info by HotelSearchCode Customer 6 Medium Planned
UC-2.4 Hotel info by InfoHotelId Customer 6 Medium Planned
UC-2.5 Price breakdown per night Customer 14 High Planned
UC-2.6 Hotel info in non-English language Customer 6 Low Planned
UC-3.1 Validate offer - price unchanged Agent 9 High Planned
UC-3.2 Validate offer - price changed Agent 9 High Planned
UC-3.3 Validate offer - CXL updated Agent 9 High Planned
UC-3.4 Validate with late remarks Agent 9 Medium Planned
UC-3.5 Validate non-refundable offer Agent 9 High Planned
UC-3.6 Validate with CXL policies Agent 9 High Planned
UC-3.7 Validate expired offer Agent 9 High Planned
UC-4.1 Book - immediate confirmation Agent 2 High Planned
UC-4.2 Book - pending (RQ) Agent 2 High Planned
UC-4.3 Book - rejection (RJ) Agent 2 High Planned
UC-4.4 Book - multi-room Agent 2 High Planned
UC-4.5 Book with children Agent 2 High Planned
UC-4.6 Book with infant (cot) Agent 2 Medium Planned
UC-4.7 Book with preferences Agent 2 Medium Planned
UC-4.8 Book with client reference Agent 2 Medium Planned
UC-4.9 Book with credit card Agent 2 Low Planned
UC-4.10 Book failure - pax validation Agent 2 High Planned
UC-4.11 Book failure - room mismatch Agent 2 High Planned
UC-4.12 Book failure - expired offer Agent 2 High Planned
UC-5.1 Check single booking Agent 5 High Planned
UC-5.2 Check multiple bookings Agent 5 Medium Planned
UC-5.3 Poll RQ until resolution Agent 5 High Planned
UC-5.4 Check after cancellation Agent 5 Medium Planned
UC-6.1 Full booking details Agent 4 High Planned
UC-6.2 Details with payments Agent 4 Medium Planned
UC-6.3 Details with commission Agent 4 Medium Planned
UC-6.4 Details with converted currency Agent 4 Low Planned
UC-6.5 Details with hotel confirmation Agent 4 Medium Planned
UC-7.1 Search by date range Agent 10 High Planned
UC-7.2 Search by pax name Agent 10 Medium Planned
UC-7.3 Search by city code Agent 10 Medium Planned
UC-7.4 Search by status Agent 10 Medium Planned
UC-7.5 Search across sub-agencies Agent 10 Low Planned
UC-7.6 Search with booking user name Agent 10 Low Planned
UC-8.1 Free cancellation Agent 3 High Planned
UC-8.2 Penalty cancellation Agent 3 High Planned
UC-8.3 Non-refundable cancellation Agent 3 High Planned
UC-8.4 Pending cancellation Agent 3 Medium Planned
UC-8.5 Retry on no response Agent 3 High Planned
UC-8.6 Booking not found Agent 3 Medium Planned
UC-9.1 Generate voucher Agent 8 High Planned
UC-9.2 Download PDF Agent 8 High Planned
UC-9.3 Voucher with emergency phone Agent 8 Low Planned
UC-9.4 Voucher - not confirmed Agent 8 Medium Planned
UC-9.5 Voucher - agency not allowed Agent 8 Low Planned
UC-10.1 Get amendment options Agent 15 Medium Planned
UC-10.2 Amend room basis Agent 16 Medium Planned
UC-10.3 Amend pax details Agent 16 Medium Planned
UC-10.4 Add room Agent 16 Medium Planned
UC-10.5 Remove room Agent 16 Medium Planned
UC-10.6 Add pax Agent 16 Medium Planned
UC-10.7 Remove pax Agent 16 Medium Planned
UC-10.8 Not amendable Agent 15 Medium Planned
UC-10.9 Type vs Adults consistency Agent 16 Medium Planned
UC-11.1 Happy path E2E Agent Multiple High Planned
UC-11.2 Book and cancel (free) Agent Multiple High Planned
UC-11.3 Book and cancel (penalty) Agent Multiple High Planned
UC-11.4 Book and amend Agent Multiple Medium Planned
UC-11.5 Contracted vs online Agent Multiple High Planned
UC-11.6 TripMaker integration Agent Multiple High Planned
UC-11.7 Stale offer recovery Agent Multiple High Planned
UC-11.8 Multi-room lifecycle Agent Multiple Medium Planned
UC-12.1 Initial static data load System N/A High Planned
UC-12.2 Scheduled refresh System N/A High Planned
UC-12.3 Search hotels by name (cache) Customer N/A High Planned
UC-12.4 Get hotels by city (cache) Customer N/A High Planned
UC-12.5 Enrich availability results System N/A High Planned
UC-13.1 searchMode=online Customer 11 High Planned
UC-13.2 searchMode=contracted Customer N/A High Planned
UC-13.3 Default searchMode Customer 11 High Planned
UC-13.4 searchByName dual-mode Customer N/A High Planned
UC-13.5 Supplier registry resolution System N/A High Planned

3. UC-1: Hotel Availability Search (GoGlobal Op 11)

Primary Actor: Customer/Agent

Description: Search for available hotel offers in a city for a given date range and room configuration.

Preconditions: - GoGlobal plugin is initialized and registered as the active online hotel supplier - GoGlobal API credentials are configured in config/goglobal-client.xml - Static data cache is populated (city codes available)

Steps: 1. User provides search criteria: cityCode, arrivalDate, nights=3, rooms=[{adults:2}], nationality="GB" 2. System resolves cityCode to GoGlobal city ID using static data cache (goglobal.city table) 3. System builds GoGlobal Operation 11 request XML via GoGlobalRequestBuilder.buildAvailabilityRequest() 4. System wraps request in SOAP 1.2 envelope and sends via GoGlobalSoapClient 5. GoGlobal returns JSON response with hotel availability 6. System parses response via GoGlobalResponseParser into GGAvailabilityResponse DTO 7. System maps GGHotelOffer native entities to CHotelOffer canonical entities via EntityTransformer 8. System enriches results with cached hotel details (thumbnail, description, star rating) from goglobal.hotel table 9. System returns list of CHotelOffer objects

Expected Result: - List of hotel offers, each containing: - HotelSearchCode (unique offer identifier for subsequent operations) - Hotel name, hotel code, city, country - Total price, currency, tax - Room basis (meal plan: BB, HB, FB, AI, RO, etc.) - Cancellation deadline and NonRef flag - Room configuration details - Commission percentage and value - Category (star rating code)

Data Flow: 

CHotelSearch (TQPro)
    --> GoGlobalRequestBuilder.buildAvailabilityRequest()
        --> SOAP envelope with Op 11 XML
            --> GoGlobal API
                --> JSON response
                    --> GGAvailabilityResponse DTO
                        --> GGHotelOffer (native)
                            --> CHotelOffer (canonical)

Key field: HotelSearchCode -- this code is required for all subsequent operations (valuation, booking, info, breakdown). It is valid for approximately 20 minutes from the time of the search.

Error Scenarios: - GoGlobal API unreachable: System returns connection error - Invalid city code: GoGlobal returns error 209 ("City doesn't exist") - Invalid date format: GoGlobal returns error 208 ("Invalid date format") - No availability: Empty results array returned (not an error)

Business Rules: - Arrival date must be in the future (format: yyyy-MM-dd) - Nights must be between 1 and 99 - At least 1 room required, at least 1 adult per room - Nationality is a 2-letter ISO country code (required by GoGlobal for pricing) - GoGlobal JSON response format is used for availability (Op 11 only; all other operations return XML)

Primary Actor: Customer/Agent

Description: Search for hotel availability with multiple rooms, each having independent occupancy configuration.

Preconditions: - Same as UC-1.1

Steps: 1. User provides search with multiple room configurations, e.g.: 

{
  "rooms": [
    { "adults": 2 },
    { "adults": 2, "children": [8, 12] },
    { "adults": 1 }
  ]
}
2. System builds Op 11 request with multiple <Room> elements 3. Each room element specifies Adults, RoomCount, and optionally ExtraBed/Cots sub-elements 4. GoGlobal returns offers that can accommodate all rooms 5. System maps results to CHotelOffer with per-room details

Expected Result: - Each offer includes pricing for all requested rooms combined - TotalPrice reflects the total across all rooms - Individual room details available in the Rooms array of each offer

Error Scenarios: - More than 8 rooms requested: GoGlobal returns error 214 ("Room limit exceeded")

Business Rules: - Maximum 8 rooms per search request - Each room has independent adult/child/cot configuration - All rooms share the same arrival date and number of nights - Room configuration at booking time must exactly match the search configuration

UC-1.3: Search with Children and Extra Beds

Primary Actor: Customer/Agent

Description: Search including children who require extra beds in the room.

Preconditions: - Same as UC-1.1

Steps: 1. User specifies children with ages in room configuration: 

{
  "rooms": [
    { "adults": 2, "children": [8, 12], "extraBeds": true }
  ]
}
2. System builds <ExtraBed> elements within the <Room>, each with <ChildAge> attribute 3. GoGlobal factors extra bed pricing into the offer 4. Response includes extra bed charges in total price

Expected Result: - Offers include extra bed pricing - Children ages reflected in room configuration

Error Scenarios: - Too many extra beds/cots: GoGlobal returns error 211 - Too many pax per room (>8): GoGlobal returns error 143

Business Rules: - Children ages: 1 to 18 - Maximum 4 children per room - Maximum 8 total pax (adults + children) per room - Cannot mix extra beds and cots in the same room

UC-1.4: Search with Children and Cots (Infants)

Primary Actor: Customer/Agent

Description: Search including infants (ages 1-2) who require a cot instead of an extra bed.

Preconditions: - Same as UC-1.1

Steps: 1. User specifies infant requiring a cot: 

{
  "rooms": [
    { "adults": 2, "cots": 1 }
  ]
}
2. System sets Cots="1" attribute on the <Room> element 3. GoGlobal returns offers that include cot availability

Expected Result: - Offers include cot availability information - Cots are typically provided free of charge (hotel-dependent)

Error Scenarios: - More than 1 cot per room: GoGlobal returns error 211 - Mixing cots and extra beds in same room: validation error

Business Rules: - Only 1 cot allowed per room - Cots are for infants aged 1-2 - Cannot mix extra beds and cots in the same room -- use one or the other - Cot availability depends on the hotel; not all hotels provide cots

UC-1.5: Search with Filters

Primary Actor: Customer/Agent

Description: Search with additional filtering criteria to narrow results.

Preconditions: - Same as UC-1.1

Steps: 1. User provides filter parameters along with basic search criteria: - starRating: GoGlobal star rating code (1-11, where 1=1 star, 5=5 stars, 6=unrated, etc.) - minPrice / maxPrice: Price range filter - boardType: Room basis filter (BB, HB, FB, AI, RO, SC, etc.) 2. System includes filter elements in Op 11 request XML: - <StarRating> with code value - <MinPrice> / <MaxPrice> elements - <RoomBasis> element 3. GoGlobal applies filters server-side and returns matching offers

Expected Result: - Reduced result set matching all specified filter criteria - Offers sorted by default (price ascending) unless sort order specified

Error Scenarios: - Invalid star rating code: results may be empty (no error from API)

Business Rules: - Star rating codes: 1 (1-star) through 5 (5-star), 6 (unrated), 7 (apart-hotel), 8 (2-star sup), 9 (3-star sup), 10 (4-star sup), 11 (5-star sup) - Board type codes: RO (Room Only), BB (Bed & Breakfast), HB (Half Board), FB (Full Board), AI (All Inclusive), SC (Self Catering), and others - Price filter applies to total price per stay

UC-1.6: Search by Specific Hotel ID

Primary Actor: Customer/Agent

Description: Search availability for a specific hotel, identified by GoGlobal hotel ID.

Preconditions: - Hotel ID is known (from previous search, static data cache, or hotel info lookup)

Steps: 1. User provides hotelId along with date and room configuration 2. System includes <HotelId> element in Op 11 request instead of <CityCode> 3. GoGlobal returns availability for the specific hotel only

Expected Result: - Offers for the specified hotel only - Multiple offers possible (different room types, meal plans)

Error Scenarios: - Invalid hotel ID: empty results returned

Business Rules: - Hotel ID is the GoGlobal internal identifier (integer) - Can be combined with other filters (star rating, price range, board type) - Results typically faster than city-wide search

UC-1.7: Search with Nationality and Currency Preferences

Primary Actor: Customer/Agent

Description: Search with specific nationality for pricing eligibility and optional currency preference.

Preconditions: - Same as UC-1.1

Steps: 1. User provides nationality (2-letter ISO code) and optionally currency 2. System includes <Nationality> element in request (always required) 3. If currency preference is set in agency GoGlobal profile, prices returned in that currency 4. GoGlobal applies nationality-based pricing rules

Expected Result: - Prices adjusted based on traveler nationality (some rates are nationality-restricted) - Currency in response matches agency profile setting

Error Scenarios: - Invalid nationality code: GoGlobal may return error or default pricing

Business Rules: - Nationality is a 2-letter ISO 3166-1 alpha-2 country code (e.g., "GB", "US", "AE") - Nationality affects pricing: some hotels have restricted rates for specific nationalities - Currency can only be changed if the agency profile in GoGlobal is configured to allow it - Default currency is typically USD unless configured otherwise in goglobal-client.xml

UC-1.8: Search with Sort Order

Primary Actor: Customer/Agent

Description: Search with a specific sort order for the results.

Preconditions: - Same as UC-1.1

Steps: 1. User specifies sort preference: - Price ascending (default) - Price descending - Cancellation deadline ascending - Cancellation deadline descending 2. System includes <SortOrder> element in Op 11 request 3. GoGlobal returns results in the requested order

Expected Result: - Results sorted by the specified criteria - Sorting is applied server-side by GoGlobal

Business Rules: - Default sort is price ascending - Sort applies across all hotels in the result set - Cancellation deadline sort is useful for finding most flexible offers first

UC-1.9: Search with MaximumWaitTime (Async Results)

Primary Actor: Customer/Agent

Description: Set a maximum wait time for search results, enabling partial/async response patterns.

Preconditions: - Same as UC-1.1

Steps: 1. User specifies MaximumWaitTime (in seconds, up to 20) 2. System includes <MaximumWaitTime> element in Op 11 request 3. GoGlobal returns results available within the specified time window 4. Partial results may be returned if the full search takes longer

Expected Result: - Results available within the wait time window - HotelQty and ResultsQty in response header indicate completeness

Business Rules: - Maximum value: 20 seconds - Default behavior (no element): GoGlobal waits for complete results - Useful for UX responsiveness in frontend search interfaces - Partial results can still be used for booking

UC-1.10: Search Yielding No Results

Primary Actor: Customer/Agent

Description: Search that returns no results due to invalid input or no availability.

Preconditions: - Same as UC-1.1

Steps: 1. User provides search criteria that cannot yield results: - Invalid city code - Dates in the past - Future date with no hotel availability 2. System sends request to GoGlobal 3. GoGlobal returns error response or empty result set

Expected Result: - Empty result set with appropriate error message - No HotelSearchCode values generated

Error Scenarios:

Error Code Description Cause
209 City doesn't exist Invalid CityCode value
208 Invalid date format Date not in yyyy-MM-dd format or dates in past
207 No availability Valid search but no hotels available

Business Rules: - System should distinguish between "no results" (valid search, no availability) and "error" (invalid parameters) - Frontend should display appropriate messages for each case

UC-1.11: Search Exceeding Limits

Primary Actor: Customer/Agent

Description: Search that violates GoGlobal API limits.

Preconditions: - Same as UC-1.1

Steps: 1. User provides search that exceeds API constraints 2. System sends request to GoGlobal 3. GoGlobal returns validation error

Expected Result: - Error response with specific error code

Error Scenarios:

Error Code Description Limit
210 Nights exceed maximum More than 99 nights
214 Room limit exceeded More than 8 rooms
143 Pax per room exceeded More than 8 pax (adults + children) per room
211 Extra beds/cots exceeded Too many extra beds or cots for room

Business Rules: - All limits are enforced server-side by GoGlobal - Client-side validation should prevent these errors from reaching the API - Error messages should be user-friendly and guide correction

4. UC-2: Extended Shopping (GoGlobal Ops 6/61, 14)

UC-2.1: Get Hotel Info Without Geo (Op 6)

Primary Actor: Customer/Agent

Description: Retrieve detailed hotel information without geographic coordinates.

Preconditions: - A valid HotelSearchCode from a previous availability search (UC-1), or a known InfoHotelId

Steps: 1. User requests hotel details for a specific offer or hotel 2. System builds Op 6 request with either HotelSearchCode or InfoHotelId 3. System sends SOAP request via GoGlobalSoapClient 4. GoGlobal returns XML response with hotel details 5. System parses response into GGHotelInfoResponse DTO 6. System maps to GGHotelInfo native entity

Expected Result: - Hotel information including: - Hotel name, address, city, country - Star rating - Description (short and long) - Thumbnail and full-size images - Facilities list (hotel-level and room-level) - Contact information

Data Flow: 

HotelSearchCode or InfoHotelId
    --> GoGlobalRequestBuilder.buildHotelInfoRequest(withGeo=false)
        --> SOAP Op 6
            --> XML response
                --> GGHotelInfoResponse
                    --> GGHotelInfo

Error Scenarios: - Invalid HotelSearchCode: error response from GoGlobal - Invalid InfoHotelId: error response or empty data

UC-2.2: Get Hotel Info With Geo Coordinates (Op 61)

Primary Actor: Customer/Agent

Description: Retrieve hotel information including latitude and longitude for map display.

Preconditions: - Same as UC-2.1

Steps: 1. User requests hotel details with geo coordinates 2. System builds Op 61 request (same as Op 6 but includes <GeoCoordinates>true</GeoCoordinates>) 3. GoGlobal returns hotel info with latitude/longitude fields 4. System parses and returns GGHotelInfo with populated latitude and longitude

Expected Result: - All fields from UC-2.1 plus: - Latitude (decimal degrees) - Longitude (decimal degrees)

Business Rules: - Op 61 is a variant of Op 6 with the geo flag enabled - Not all hotels have geo coordinates; fields may be null - Coordinates are useful for map rendering in frontend

UC-2.3: Get Hotel Info by HotelSearchCode

Primary Actor: Customer/Agent

Description: Retrieve hotel information using the HotelSearchCode obtained from an availability search.

Preconditions: - HotelSearchCode obtained from a recent availability search (UC-1) - The search code is still valid (within ~20-minute window)

Steps: 1. User clicks on a hotel offer from search results 2. System extracts HotelSearchCode from the selected offer 3. System sends Op 6 (or Op 61) request with <HotelSearchCode> element 4. GoGlobal returns hotel details associated with that specific offer

Expected Result: - Hotel details specific to the offer context (may include offer-specific information)

Business Rules: - HotelSearchCode links back to the original search context - Provides hotel info relevant to the specific offer (room type, basis)

UC-2.4: Get Hotel Info by InfoHotelId

Primary Actor: Customer/Agent

Description: Retrieve hotel information using the GoGlobal hotel ID (independent of any search).

Preconditions: - InfoHotelId is known (from static data cache or previous interaction)

Steps: 1. User requests hotel details by ID (e.g., from hotel list or cached data) 2. System sends Op 6 request with <InfoHotelId> element 3. GoGlobal returns hotel details for that hotel ID

Expected Result: - Complete hotel information for the specified hotel - Not tied to any specific search or offer

Business Rules: - InfoHotelId is the GoGlobal internal hotel identifier (integer) - Can be used independently of availability search - Useful for displaying hotel profile pages

UC-2.5: Get Price Breakdown Per Night Per Room (Op 14)

Primary Actor: Customer/Agent

Description: Retrieve nightly price breakdown for each room in an offer.

Preconditions: - A valid HotelSearchCode from a recent availability search

Steps: 1. User requests price breakdown for a selected offer 2. System builds Op 14 request with HotelSearchCode 3. System sends SOAP request to GoGlobal 4. GoGlobal returns XML with per-night, per-room pricing 5. System parses into GGPriceBreakdownResponse DTO

Expected Result: - Breakdown structure: 

Room 1:
  Night 1 (2026-03-01): $120.00
  Night 2 (2026-03-02): $120.00
  Night 3 (2026-03-03): $150.00 (weekend rate)
Room 2:
  Night 1 (2026-03-01): $95.00
  Night 2 (2026-03-02): $95.00
  Night 3 (2026-03-03): $110.00

Data Flow: 

HotelSearchCode
    --> GoGlobalRequestBuilder.buildPriceBreakdownRequest()
        --> SOAP Op 14
            --> XML response with per-night pricing
                --> GGPriceBreakdownResponse

Business Rules: - Price breakdown is only available for offers with a valid HotelSearchCode - Nightly rates may vary (weekday vs weekend, seasonal pricing) - Total of nightly rates should match the TotalPrice from the availability search - Useful for displaying transparent pricing to customers

UC-2.6: Hotel Info in Non-English Language

Primary Actor: Customer/Agent

Description: Retrieve hotel information in a specified language.

Preconditions: - Same as UC-2.1

Steps: 1. User requests hotel info with a language code (e.g., fr, de, ar) 2. System includes <Language> element in Op 6/61 request 3. GoGlobal returns hotel description and details in the requested language

Expected Result: - Hotel name, description, and facility names in the requested language - Fallback to English if translation not available

Business Rules: - GoGlobal supports 28 languages - Language is specified as a 2-letter code (ISO 639-1) - Not all hotels have translations for all languages - Default language is English if not specified

5. UC-3: Offer Validation (GoGlobal Op 9)

UC-3.1: Validate Offer - Price Unchanged

Primary Actor: Agent

Description: Validate a hotel offer to confirm current pricing and availability before booking.

Preconditions: - HotelSearchCode obtained from a recent availability search (within 20 minutes) - Offer was returned in the availability search results

Steps: 1. Agent selects an offer to book 2. System builds Op 9 (Valuation) request with HotelSearchCode and ArrivalDate 3. System sends SOAP request to GoGlobal 4. GoGlobal validates the offer and returns current pricing 5. System parses GGValuationResponse DTO 6. System compares NewRate with original price -- price is unchanged 7. System returns validated offer with confirmed pricing

Expected Result: - Valuation response with: - Confirmed HotelSearchCode - ArrivalDate confirmation - CancellationDeadline (date/time) - Rates (confirmed pricing) - Currency - TotalTax - Remarks (supplier remarks about the booking) - NewRate field absent or matching original (price unchanged)

Data Flow: 

HotelSearchCode + ArrivalDate
    --> GoGlobalRequestBuilder.buildValuationRequest()
        --> SOAP Op 9
            --> XML response
                --> GGValuationResponse
                    --> Confirmed pricing for booking

Business Rules: - Valuation is mandatory before booking -- it confirms the price is still valid - The HotelSearchCode from valuation is used for the booking request - Valuation response may include updated cancellation terms

UC-3.2: Validate Offer - Price Changed

Primary Actor: Agent

Description: Validate an offer where the price has changed since the original search.

Preconditions: - Same as UC-3.1

Steps: 1. Agent validates an offer 2. GoGlobal returns valuation with a NewRate field that differs from the original search price 3. System detects price change by comparing NewRate with the original TotalPrice 4. System flags the offer as "price changed" to the agent

Expected Result: - Valuation response with NewRate element containing the updated price - Agent is informed of the price difference before proceeding to book - Agent can accept the new price or abandon the booking

Business Rules: - Price changes are common, especially for dynamic pricing hotels - The NewRate value is the binding price for booking - Agent must explicitly accept the new price before booking proceeds - Original search price becomes invalid once NewRate is returned

UC-3.3: Validate Offer - Cancellation Deadline Updated

Primary Actor: Agent

Description: Validate an offer where the cancellation deadline has been updated.

Preconditions: - Same as UC-3.1

Steps: 1. Agent validates an offer 2. GoGlobal returns valuation with an updated CancellationDeadline 3. System compares with the deadline from the original search 4. System presents updated cancellation terms to the agent

Expected Result: - Updated CancellationDeadline in the valuation response - Agent is informed of the new cancellation terms

Business Rules: - Cancellation deadline may change between search and valuation - The valuation deadline is the binding deadline for the booking - Agent should review cancellation terms before confirming booking

UC-3.4: Validate Offer - Late Remarks Added

Primary Actor: Agent

Description: Validate an offer that includes supplier remarks not available during search.

Preconditions: - Same as UC-3.1

Steps: 1. Agent validates an offer 2. GoGlobal returns valuation with Remarks element containing supplier notes 3. System presents remarks to the agent

Expected Result: - Remarks text in the valuation response - May include: check-in instructions, special conditions, resort fee notices, etc.

Business Rules: - Remarks are informational and should be displayed to the agent - Some remarks may contain important booking conditions - Remarks should be stored with the booking record

UC-3.5: Validate Non-Refundable Offer

Primary Actor: Agent

Description: Validate an offer marked as non-refundable.

Preconditions: - Offer has NonRef=true in the availability search results

Steps: 1. Agent validates a non-refundable offer 2. GoGlobal confirms NonRef=true in valuation 3. Valuation includes remark indicating immediate full charges upon booking 4. System presents non-refundable warning to agent

Expected Result: - Valuation confirms non-refundable status - Remarks include: "Full charges apply from the time of booking" - No cancellation deadline (or deadline set to booking date)

Business Rules: - Non-refundable offers typically have lower prices - Full cancellation penalty applies immediately after booking - Agent must acknowledge the non-refundable terms before booking - NonRef=true is a boolean flag in both search and valuation responses

UC-3.6: Validate with Cancellation Policies (Structured)

Primary Actor: Agent

Description: Validate an offer that includes structured cancellation policy details.

Preconditions: - Same as UC-3.1

Steps: 1. Agent validates an offer 2. GoGlobal returns CancellationPolicies array with structured policy entries 3. System parses each policy entry

Expected Result: - Cancellation policies array, each entry containing:

Field Description Example
Id Policy identifier 1
Starting When the policy takes effect "2026-02-15T00:00:00"
BasedOn What the penalty is based on "BOOKINGPRICE"
Mode Penalty calculation mode "PCT" (percentage) or "FLAT" (fixed amount)
Value Penalty value 50 (meaning 50% or $50)

Business Rules: - Multiple policies can apply to the same booking (tiered penalties) - Policies are ordered by Starting date - BasedOn=BOOKINGPRICE means the penalty is calculated on the total booking price - Mode=PCT with Value=100 means full cancellation charges (equivalent to non-refundable) - Mode=FLAT means a fixed monetary penalty amount

UC-3.7: Validate Expired Offer

Primary Actor: Agent

Description: Attempt to validate an offer that has expired (more than 20 minutes since search).

Preconditions: - HotelSearchCode was obtained more than 20 minutes ago

Steps: 1. Agent attempts to validate a stale offer 2. System sends Op 9 request 3. GoGlobal returns error 312 ("Offer expired" / "Search to Book time exceeded")

Expected Result: - Error response with code 312 - Agent must perform a new availability search

Error Scenarios:

Error Code Description
312 Offer expired - search to book time should be within 20 minutes

Business Rules: - Search-to-book window is approximately 20 minutes - After expiration, a new search (Op 11) is required to obtain fresh HotelSearchCode values - System should track search timestamps to proactively warn agents of approaching expiration

6. UC-4: Booking Creation (GoGlobal Op 2)

UC-4.1: Single Room, Immediate Confirmation (Status C)

Primary Actor: Agent

Description: Create a booking for a single room that is immediately confirmed by the hotel.

Preconditions: - Offer validated via Op 9 (UC-3) - Guest details collected (names, titles) - HotelSearchCode is still valid

Steps: 1. Agent provides booking details: - HotelSearchCode from valuation - ArrivalDate, Nights - Room with guest names (Title: MR./MRS./MISS/MS., FirstName, LastName) - Adults count matching search 2. System builds Op 2 (Insert Booking) request via GoGlobalRequestBuilder.buildBookingRequest() 3. System sends SOAP request to GoGlobal 4. GoGlobal processes booking and returns immediate confirmation 5. System parses GGBookingResponse DTO

Expected Result: - Booking response with: - GoBookingCode (unique booking identifier) - GoReference (supplier reference) - BookingStatus = "C" (Confirmed) - TotalPrice, Currency - HotelId, HotelName - HotelConfirmation (hotel's own confirmation number, if available) - Room and pax details as confirmed

Data Flow: 

HotelSearchCode + Guest Details
    --> GoGlobalRequestBuilder.buildBookingRequest()
        --> SOAP Op 2
            --> XML response
                --> GGBookingResponse
                    --> GGBooking (native)
                        --> Booking record in TQPro

Business Rules: - Room configuration (adults, children, nights, arrival) must exactly match the original search - Guest names must have minimum 2-letter last name - Title must be MR., MRS., MISS, or MS. (with period) - Names must be in non-Unicode (Latin) characters only - The GoBookingCode is the primary identifier for all subsequent operations

UC-4.2: Single Room, Pending (Status RQ)

Primary Actor: Agent

Description: Create a booking that requires hotel confirmation (on-request).

Preconditions: - Same as UC-4.1

Steps: 1. Agent creates booking (same as UC-4.1) 2. GoGlobal returns BookingStatus = "RQ" (Requested) 3. System stores booking with pending status 4. Agent is informed that booking is pending hotel confirmation 5. Agent must poll Op 5 (UC-5) to check for confirmation

Expected Result: - BookingStatus = "RQ" - GoBookingCode assigned (booking is registered but not yet confirmed) - Agent informed to check back later

Business Rules: - RQ bookings are common for contracted hotels that require manual confirmation - Hotel may confirm (C) or reject (RJ) the request - No voucher can be generated until status changes to C - Polling interval recommendation: every 15-30 minutes

UC-4.3: Single Room, Rejection (Status RJ)

Primary Actor: Agent

Description: Create a booking that is rejected by the hotel.

Preconditions: - Same as UC-4.1

Steps: 1. Agent creates booking 2. GoGlobal returns BookingStatus = "RJ" (Rejected) 3. System stores booking with rejected status

Expected Result: - BookingStatus = "RJ" - No charges applied - Agent informed that the hotel rejected the booking

Business Rules: - Rejection may occur immediately or after initial RQ status - No financial obligation for rejected bookings - Agent should search for alternative offers

UC-4.4: Multi-Room with Multiple Guests

Primary Actor: Agent

Description: Create a booking with multiple rooms, each having different guest configurations.

Preconditions: - Multi-room availability search completed (UC-1.2) - Offer validated (UC-3)

Steps: 1. Agent provides booking with multiple rooms: 

<Rooms>
  <Room Id="1" Adults="2" RoomCount="1">
    <Pax Title="MR." FirstName="John" LastName="Smith"/>
    <Pax Title="MRS." FirstName="Jane" LastName="Smith"/>
  </Room>
  <Room Id="2" Adults="2" RoomCount="1">
    <Pax Title="MR." FirstName="Robert" LastName="Johnson"/>
    <Pax Title="MRS." FirstName="Lisa" LastName="Johnson"/>
  </Room>
</Rooms>
2. System validates each room matches the original search configuration 3. System builds Op 2 request with multiple <Room> elements 4. GoGlobal processes booking for all rooms

Expected Result: - Single GoBookingCode for the entire multi-room booking - All rooms confirmed (or all pending) together - Total price covers all rooms

Business Rules: - Room configuration (arrival, nights, adults, children ages) must match the original search exactly - Each room must have at least one guest (the "leader" is the first pax in the first room) - All rooms are booked together as a single transaction - Cannot partially book (some rooms confirmed, others not)

UC-4.5: Booking with Children (Extra Beds)

Primary Actor: Agent

Description: Create a booking with rooms that include children requiring extra beds.

Preconditions: - Search with children completed (UC-1.3) - Offer validated (UC-3)

Steps: 1. Agent provides room with extra bed details: 

<Room Id="1" Adults="2" RoomCount="1">
  <Pax Title="MR." FirstName="John" LastName="Smith"/>
  <Pax Title="MRS." FirstName="Jane" LastName="Smith"/>
  <ExtraBed ChildAge="8"/>
  <ExtraBed ChildAge="12"/>
</Room>
2. System validates child count and ages match the search 3. GoGlobal processes booking with extra bed configuration

Expected Result: - Booking confirmed with extra bed charges included in total price - Children recorded in booking details

Business Rules: - ExtraBed elements must match the children specified in the original search - ChildAge must be between 1 and 18 - Extra bed pricing was already factored into the offer during search

UC-4.6: Booking with Infant (Cot)

Primary Actor: Agent

Description: Create a booking with a room that includes a cot for an infant.

Preconditions: - Search with cot completed (UC-1.4) - Offer validated (UC-3)

Steps: 1. Agent provides room with cot: 

<Room Id="1" Adults="2" Cots="1" RoomCount="1">
  <Pax Title="MR." FirstName="John" LastName="Smith"/>
  <Pax Title="MRS." FirstName="Jane" LastName="Smith"/>
</Room>
2. System validates cot configuration matches search 3. GoGlobal processes booking with cot

Expected Result: - Booking confirmed with cot provision noted - Cot typically at no additional charge (hotel-dependent)

Business Rules: - Cots attribute must match the cot count from the search - Only 1 cot per room - Cot availability is hotel-dependent

UC-4.7: Booking with Preferences

Primary Actor: Agent

Description: Create a booking with special room/stay preferences.

Preconditions: - Offer validated (UC-3)

Steps: 1. Agent specifies preferences: - EarlyCheckIn - request early check-in - LateCheckout - request late check-out - NonSmoking - non-smoking room - Honeymoon - honeymoon arrangement - Other text-based special requests 2. System includes <Preferences> element in Op 2 request 3. GoGlobal records preferences with the booking

Expected Result: - Booking created with preferences noted - Preferences are requests, not guarantees (subject to hotel availability)

Business Rules: - Preferences are best-effort; the hotel is not obligated to fulfill them - Preferences do not affect pricing - Special text requests should be kept concise

UC-4.8: Booking with Client Booking Code

Primary Actor: Agent

Description: Create a booking with an agency reference number for internal tracking.

Preconditions: - Offer validated (UC-3)

Steps: 1. Agent provides ClientBookingCode (agency's own reference number) 2. System includes <ClientBookingCode> element in Op 2 request 3. GoGlobal stores the client reference with the booking

Expected Result: - Booking created with ClientBookingCode stored - Client booking code appears in booking details (Op 4) and search (Op 10)

Business Rules: - ClientBookingCode is optional - It is the agency's own reference for cross-system tracking - Useful for matching GoGlobal bookings to TQPro internal booking records

UC-4.9: Booking with Credit Card Payment

Primary Actor: Agent

Description: Create a booking with credit card payment details (RSA-encrypted).

Preconditions: - Offer validated (UC-3) - RSA public key obtained from GoGlobal for card encryption

Steps: 1. Agent provides credit card details 2. System RSA-encrypts the card data using GoGlobal's public key 3. System includes <PaymentInfo> element with encrypted card data in Op 2 request 4. GoGlobal processes the booking with card payment

Expected Result: - Booking created with card payment processed - Payment transaction details available in booking details (UC-6.2)

Business Rules: - Credit card data must be RSA-encrypted before transmission - Card types supported depend on GoGlobal agency agreement - Payment failures result in booking rejection - PCI-DSS compliance requirements apply

UC-4.10: Booking Failure - Pax Name Validation

Primary Actor: Agent

Description: Booking fails due to invalid passenger name format.

Preconditions: - Offer validated (UC-3)

Steps: 1. Agent provides guest details with invalid format: - Non-Latin characters in name - Title not one of MR./MRS./MISS/MS. - Last name shorter than 2 characters 2. GoGlobal returns error 314 (invalid pax data)

Expected Result: - Error response with code 314 - Booking not created

Error Scenarios:

Error Code Description Cause
314 Invalid pax data Non-Unicode names, invalid title, last name < 2 chars

Business Rules: - Titles must be exactly: MR., MRS., MISS, or MS. (with period) - Names must use Latin characters only (no Arabic, Chinese, Cyrillic, etc.) - Last name must be at least 2 characters - First name must be at least 1 character

UC-4.11: Booking Failure - Room Parameters Mismatch

Primary Actor: Agent

Description: Booking fails because room configuration does not match the original search.

Preconditions: - Offer validated (UC-3)

Steps: 1. Agent provides room configuration that differs from the original search: - Different number of adults - Different number of children or different ages - Different number of nights or arrival date 2. GoGlobal returns error (room parameters mismatch)

Expected Result: - Error response indicating room configuration mismatch - Booking not created

Business Rules: - The booking room configuration must exactly match the search room configuration - This is a hard constraint -- GoGlobal validates against the original search parameters - System should validate locally before sending to GoGlobal to avoid unnecessary API calls

UC-4.12: Booking Failure - Offer Expired

Primary Actor: Agent

Description: Booking fails because the offer has expired (>20 minutes since search).

Preconditions: - HotelSearchCode was obtained more than 20 minutes ago

Steps: 1. Agent attempts to book with an expired HotelSearchCode 2. GoGlobal returns error 312

Expected Result: - Error response with code 312: "Search to Book time should be within 20 minutes" - Booking not created

Error Scenarios:

Error Code Description
312 Offer expired - search to book time exceeded 20 minutes

Business Rules: - Search-to-book window is approximately 20 minutes - This applies from the original search time, not from valuation time - Agent must perform a new search to get fresh offer codes - System should implement proactive expiration warnings

7. UC-5: Booking Status Check (GoGlobal Op 5)

UC-5.1: Check Single Booking Status

Primary Actor: Agent

Description: Check the current status of a single GoGlobal booking.

Preconditions: - GoBookingCode obtained from a previous booking (UC-4)

Steps: 1. Agent requests status for a specific booking 2. System builds Op 5 request with <GoBookingCode> element 3. GoGlobal returns current booking status

Expected Result: - Current booking status code:

Status Code Description
Requested RQ Booking awaiting hotel confirmation
Confirmed C Booking confirmed by hotel
Cancellation Requested RX Cancellation submitted, pending
Cancelled (No Penalty) X Booking cancelled, no charges
Cancelled (With Penalty) XP Booking cancelled, penalty charged
Rejected RJ Booking rejected by hotel
Voucher Issued VCH Voucher has been generated
Voucher Requested VRQ Voucher generation requested

UC-5.2: Check Multiple Bookings in Batch

Primary Actor: Agent

Description: Check status of multiple bookings in a single request.

Preconditions: - Multiple GoBookingCode values available

Steps: 1. Agent requests status for multiple bookings 2. System builds Op 5 request with multiple <GoBookingCode> elements 3. GoGlobal returns status for each booking

Expected Result: - Array of booking statuses, one per GoBookingCode

Business Rules: - Batch status check is more efficient than individual calls - Useful for dashboard views showing multiple booking statuses

UC-5.3: Poll RQ Booking Until Confirmation or Rejection

Primary Actor: Agent/System

Description: Repeatedly check a pending (RQ) booking until it is confirmed (C) or rejected (RJ).

Preconditions: - Booking created with status RQ (UC-4.2)

Steps: 1. System or agent initiates periodic status checks 2. System sends Op 5 request at regular intervals (e.g., every 15-30 minutes) 3. If status = RQ, continue polling 4. If status = C, booking is confirmed -- notify agent 5. If status = RJ, booking is rejected -- notify agent

Expected Result: - Eventually receives either C (confirmed) or RJ (rejected)

Business Rules: - RQ bookings may take hours or days to resolve - System should implement automated polling with configurable intervals - Agent should be notified upon status change - There is no defined timeout -- some RQ bookings remain pending indefinitely

UC-5.4: Check Status After Cancellation

Primary Actor: Agent

Description: Check booking status after a cancellation request has been submitted.

Preconditions: - Cancellation request submitted (UC-8), status may be RX

Steps: 1. Agent checks status of a booking after cancellation request 2. System sends Op 5 request 3. GoGlobal returns current status

Expected Result: - Status progression: RX (Cancellation Requested) -> X (Cancelled) or XP (Cancelled with Penalty) - If still RX, cancellation is being processed

Business Rules: - RX is a transitional state - Final cancellation status will be X (free) or XP (with penalty) - In rare cases, cancellation may revert to C (cancellation denied)

8. UC-6: Booking Details (GoGlobal Op 4)

UC-6.1: Full Booking Details

Primary Actor: Agent

Description: Retrieve complete booking details including rooms, guests, pricing, and dates.

Preconditions: - GoBookingCode obtained from a previous booking

Steps: 1. Agent requests full booking details 2. System builds Op 4 request with GoBookingCode 3. GoGlobal returns comprehensive booking information 4. System parses into GGBookingDetailsResponse DTO

Expected Result: - Complete booking details: - GoBookingCode, GoReference - BookingStatus - HotelId, HotelName, hotel address - ArrivalDate, Nights - Room details (type, basis, occupancy) - Guest details (names, titles) per room - TotalPrice, Currency, TotalTax - CancellationDeadline - ClientBookingCode (if provided at booking) - Booking creation date and user

UC-6.2: Booking Details with Payment Transactions

Primary Actor: Agent

Description: Retrieve booking details including payment transaction history.

Preconditions: - Booking with credit card payment (UC-4.9)

Steps: 1. Agent requests booking details 2. Response includes <PaymentTransactions> element 3. System parses payment details

Expected Result: - Payment transactions including: - Transaction date - Amount and currency - Transaction status - Card type (masked)

UC-6.3: Booking Details with Commission Info

Primary Actor: Agent

Description: Retrieve booking details including commission information.

Preconditions: - Booking exists with commission arrangement

Steps: 1. Agent requests booking details 2. Response includes commission fields

Expected Result: - Commission details: - CommValue - Commission amount - CommPercent - Commission percentage - IncludeCommission - Whether commission is included in the price

Business Rules: - Commission is configured at the agency level in GoGlobal - IncludeCommission=true means the displayed price already includes commission - Commission percentage and value are for agent reference and invoicing

UC-6.4: Booking Details with Converted Currency

Primary Actor: Agent

Description: Retrieve booking details with pricing converted to the agency's preferred currency.

Preconditions: - Agency has a currency conversion configured in GoGlobal

Steps: 1. Agent requests booking details 2. Response includes converted currency fields

Expected Result: - Additional fields: - ConvertedGross - Total price in converted currency - ConvertedCommission - Commission in converted currency - Converted currency code

UC-6.5: Booking Details with Hotel Confirmation Number

Primary Actor: Agent

Description: Retrieve booking details including the hotel's own confirmation number.

Preconditions: - Booking is confirmed (status C) - Hotel has issued a confirmation number - GoGlobal API v3.16.7+

Steps: 1. Agent requests booking details with <IncludeHotelConfirmation>true</IncludeHotelConfirmation> 2. GoGlobal returns HotelConfirmation field

Expected Result: - HotelConfirmation - The hotel's own booking reference number - Useful for direct communication with the hotel

Business Rules: - Available from GoGlobal API v3.16.7 onwards - Not all hotels provide a separate confirmation number - Field may be empty even for confirmed bookings

9. UC-7: Advanced Booking Search (GoGlobal Op 10)

UC-7.1: Search by Date Range

Primary Actor: Agent

Description: Search for bookings within a specified date range.

Preconditions: - Agent has booking management access

Steps: 1. Agent specifies date range criteria: - ArrivalDateFrom / ArrivalDateTo (by arrival date) - CreatedFrom / CreatedTo (by booking creation date) 2. System builds Op 10 request with date range elements 3. GoGlobal returns matching bookings

Expected Result: - List of bookings within the specified date range - Each booking includes: GoBookingCode, hotel name, dates, status, price

UC-7.2: Search by Pax Name

Primary Actor: Agent

Description: Search for bookings by passenger name.

Preconditions: - Agent has booking management access

Steps: 1. Agent provides PaxName (guest name or partial name) 2. System builds Op 10 request with <PaxName> element 3. GoGlobal returns bookings matching the name

Expected Result: - Bookings where any guest name matches the search term

UC-7.3: Search by City Code

Primary Actor: Agent

Description: Search for bookings in a specific city.

Preconditions: - Agent has booking management access

Steps: 1. Agent provides CityCode 2. System builds Op 10 request with city filter 3. GoGlobal returns bookings in that city

Expected Result: - All bookings for hotels in the specified city

UC-7.4: Search by Status Filter

Primary Actor: Agent

Description: Search for bookings with a specific status.

Preconditions: - Agent has booking management access

Steps: 1. Agent selects status filter (C, RQ, X, XP, RJ, etc.) 2. System builds Op 10 request with status filter 3. GoGlobal returns bookings matching the status

Expected Result: - Bookings filtered by the specified status

UC-7.5: Search Across Sub-Agencies

Primary Actor: Agent (master agency)

Description: Search for bookings across all sub-agencies.

Preconditions: - Agent belongs to a master agency with sub-agencies in GoGlobal

Steps: 1. Agent optionally specifies AgencyId filter 2. System builds Op 10 request with <AgencyId> element 3. GoGlobal returns bookings for the specified sub-agency (or all if not specified)

Expected Result: - Bookings across the agency hierarchy

Business Rules: - Only master agencies can search across sub-agencies - If AgencyId is not specified, bookings from all sub-agencies are returned

UC-7.6: Search with Booking User Name

Primary Actor: Agent

Description: Search for bookings created by a specific user.

Preconditions: - Agent has booking management access

Steps: 1. Agent enables <ShowBookingUserName>true</ShowBookingUserName> in request 2. GoGlobal includes the booking user name in each result

Expected Result: - Each booking result includes the name of the user who created it

10. UC-8: Booking Cancellation (GoGlobal Op 3)

UC-8.1: Free Cancellation (Before Deadline)

Primary Actor: Agent

Description: Cancel a booking before the cancellation deadline with no penalty.

Preconditions: - Booking is confirmed (status C) - Current date/time is before the cancellation deadline

Steps: 1. Agent requests cancellation for a confirmed booking 2. System builds Op 3 request with GoBookingCode 3. GoGlobal processes cancellation 4. Booking status changes to X (Cancelled, no penalty)

Expected Result: - BookingStatus = "X" - No cancellation charges - Full refund processed

Business Rules: - Cancellation must be requested before the CancellationDeadline from valuation/booking - Free cancellation window varies by hotel and rate

UC-8.2: Penalty Cancellation (After Deadline)

Primary Actor: Agent

Description: Cancel a booking after the cancellation deadline, incurring a penalty.

Preconditions: - Booking is confirmed (status C) - Current date/time is after the cancellation deadline

Steps: 1. Agent requests cancellation for a booking past the deadline 2. System builds Op 3 request with GoBookingCode 3. GoGlobal processes cancellation with penalty 4. Booking status changes to XP (Cancelled with Penalty)

Expected Result: - BookingStatus = "XP" - Penalty amount based on cancellation policy: - Mode=PCT, BasedOn=BOOKINGPRICE: Penalty = Value% of total booking price - Mode=FLAT, BasedOn=BOOKINGPRICE: Penalty = fixed Value amount

Business Rules: - Penalty is calculated according to the cancellation policies returned during valuation (UC-3.6) - Agent should be warned about penalties before confirming cancellation - Penalty amount is deducted from any refund

UC-8.3: Non-Refundable Cancellation

Primary Actor: Agent

Description: Cancel a non-refundable booking (full charges apply).

Preconditions: - Booking was made on a non-refundable rate (NonRef=true)

Steps: 1. Agent requests cancellation of non-refundable booking 2. GoGlobal processes with full penalty (100% of booking price) 3. Booking status changes to XP

Expected Result: - BookingStatus = "XP" - Penalty = 100% of booking price (full charges)

Business Rules: - Non-refundable bookings always incur full cancellation charges - Agent should be clearly warned before proceeding

UC-8.4: Pending Cancellation (RX Status)

Primary Actor: Agent

Description: Cancellation request is submitted but requires processing time.

Preconditions: - Booking has an active status (C or RQ)

Steps: 1. Agent requests cancellation 2. GoGlobal returns status RX (Cancellation Requested) 3. System records pending cancellation 4. Agent polls Op 5 (UC-5.4) for final status

Expected Result: - BookingStatus = "RX" (transitional) - Final status: X (free cancellation) or XP (with penalty)

Business Rules: - RX is a transitional state -- it will resolve to X or XP - Agent must poll for the final status

UC-8.5: Retry on No Valid Response

Primary Actor: Agent

Description: Cancellation request fails to return a valid response -- must retry.

Preconditions: - Cancellation request sent but no valid response received (timeout, network error)

Steps: 1. Agent submits cancellation request 2. System does not receive a valid response (timeout, connection error) 3. System MUST retry the cancellation request 4. Continue retrying until a valid response is received

Expected Result: - Eventually receives a valid cancellation response

Business Rules: - CRITICAL: If no valid response is received, the cancellation was NOT queued by GoGlobal - Unlike bookings (which may be queued server-side), failed cancellations must be retried - System should implement automatic retry logic with exponential backoff - Agent should be informed that cancellation status is uncertain until confirmed

UC-8.6: Booking Not Found

Primary Actor: Agent

Description: Cancellation attempt for a booking that cannot be found.

Preconditions: - GoBookingCode is invalid or does not belong to the agency

Steps: 1. Agent submits cancellation for an invalid booking code 2. GoGlobal returns error

Expected Result: - Error response

Error Code Description
401 Booking not found
402 Booking not found for this agency

11. UC-9: Voucher Generation (GoGlobal Op 8)

UC-9.1: Generate Voucher for Confirmed Booking

Primary Actor: Agent

Description: Generate a hotel voucher for a confirmed booking.

Preconditions: - Booking is confirmed (status C) - Agency is authorized to generate vouchers

Steps: 1. Agent requests voucher generation for a confirmed booking 2. System builds Op 8 request with GoBookingCode 3. GoGlobal generates the voucher 4. Response includes VoucherDownloadURL

Expected Result: - VoucherDownloadURL - URL to download the voucher PDF - Booking status may change to VCH (Voucher Issued)

UC-9.2: Download Voucher PDF

Primary Actor: Agent

Description: Download the voucher PDF using the URL obtained in UC-9.1.

Preconditions: - VoucherDownloadURL obtained from Op 8 response

Steps: 1. Agent (or system) accesses the VoucherDownloadURL 2. GoGlobal serves the PDF document 3. PDF contains: hotel details, check-in/out dates, guest names, booking reference

Expected Result: - PDF voucher document suitable for hotel check-in

UC-9.3: Voucher with Emergency Phone (v2.3+)

Primary Actor: Agent

Description: Generate a voucher that includes emergency contact phone number.

Preconditions: - GoGlobal API v2.3 or later - Booking confirmed

Steps: 1. Agent requests voucher generation 2. Response includes emergency phone number on the voucher 3. Voucher PDF contains local emergency contact information

Expected Result: - Voucher includes emergency contact phone number for traveler use

UC-9.4: Voucher Failure - Booking Not Confirmed

Primary Actor: Agent

Description: Attempt to generate a voucher for a booking that is not confirmed.

Preconditions: - Booking status is not C (e.g., RQ, RJ, X)

Steps: 1. Agent requests voucher for a non-confirmed booking 2. GoGlobal returns error 700

Expected Result: - Error: "Voucher cannot be generated - booking not confirmed" (error code 700)

UC-9.5: Voucher Failure - Agency Not Allowed or Credit Limit

Primary Actor: Agent

Description: Voucher generation fails due to agency restrictions.

Preconditions: - Agency does not have voucher generation permission, or credit limit exceeded

Steps: 1. Agent requests voucher 2. GoGlobal returns error

Expected Result:

Error Code Description
701 Agency not authorized for voucher generation
702 Credit limit exceeded

12. UC-10: Booking Amendment (GoGlobal Ops 15 and 16)

UC-10.1: Get Amendment Options (Op 15)

Primary Actor: Agent

Description: Retrieve the amendment options for an existing booking, including room IDs and pax IDs.

Preconditions: - Booking is confirmed (status C) - Booking is amendable

Steps: 1. Agent requests amendment options for a booking 2. System builds Op 15 request with GoBookingCode 3. GoGlobal returns the current booking structure with IDs for amendment

Expected Result: - Room list with RoomId for each room - Pax list with PersonId for each guest in each room - Current room basis, dates, and configuration - These IDs are required for the amendment request (Op 16)

Business Rules: - Op 15 must be called before Op 16 to get the correct IDs - The IDs returned are specific to the amendment context

UC-10.2: Amend Room Basis (Meal Plan Change)

Primary Actor: Agent

Description: Change the meal plan (room basis) for a room in an existing booking.

Preconditions: - Amendment options retrieved (UC-10.1)

Steps: 1. Agent selects a room and changes the room basis (e.g., BB to HB) 2. System builds Op 16 request with the RoomId and new RoomBasis 3. GoGlobal processes the amendment 4. Response includes updated pricing

Expected Result: - Room basis updated - Price adjusted accordingly - Booking details updated

UC-10.3: Amend Pax Details

Primary Actor: Agent

Description: Change guest name or title for a booking.

Preconditions: - Amendment options retrieved (UC-10.1)

Steps: 1. Agent provides updated guest details using PersonId from Op 15 2. System builds Op 16 request with pax amendments 3. GoGlobal updates guest details

Expected Result: - Guest details updated in the booking

Business Rules: - Same validation rules as booking: Latin characters, valid titles, min 2-letter last name

UC-10.4: Add Room to Booking

Primary Actor: Agent

Description: Add a new room to an existing booking.

Preconditions: - Amendment options retrieved (UC-10.1)

Steps: 1. Agent specifies new room to add with RoomId="new" (case-sensitive) 2. System builds Op 16 request with the new room details 3. GoGlobal adds the room to the booking

Expected Result: - New room added to the booking - Total price increased accordingly

Business Rules: - RoomId must be exactly "new" (case-sensitive) for adding a room - New room configuration must include adults, guests, and optional children

UC-10.5: Remove Room from Booking

Primary Actor: Agent

Description: Remove a room from a multi-room booking.

Preconditions: - Amendment options retrieved (UC-10.1) - Booking has multiple rooms

Steps: 1. Agent selects room to remove using RoomId from Op 15 2. Agent inserts the text "delete" in the room element 3. System builds Op 16 request marking the room for deletion 4. GoGlobal removes the room

Expected Result: - Room removed from the booking - Total price decreased accordingly - Remaining rooms unaffected

Business Rules: - To mark a room for deletion, insert the text "delete" in the room data - Cannot remove the last room (at least one room must remain) - Cancellation policies may apply to the removed room

UC-10.6: Add Pax to Room

Primary Actor: Agent

Description: Add a new guest to an existing room.

Preconditions: - Amendment options retrieved (UC-10.1)

Steps: 1. Agent specifies new pax with PersonId="new" (case-sensitive) 2. System builds Op 16 request with the new pax details 3. GoGlobal adds the guest to the room

Expected Result: - New guest added to the specified room

Business Rules: - PersonId must be exactly "new" (case-sensitive) for adding a guest - Room occupancy constraints still apply

UC-10.7: Remove Pax from Room

Primary Actor: Agent

Description: Remove a guest from a room.

Preconditions: - Amendment options retrieved (UC-10.1) - Room has multiple guests

Steps: 1. Agent selects pax to remove using PersonId from Op 15 2. Agent inserts the text "delete" in the pax element 3. System builds Op 16 request marking the pax for deletion 4. GoGlobal removes the guest

Expected Result: - Guest removed from the room - Room occupancy updated

Business Rules: - Insert "delete" text to mark a pax for removal - Cannot remove the last guest from a room - At least one adult must remain in each room

UC-10.8: Amendment Not Available

Primary Actor: Agent

Description: Attempt to amend a booking that is not amendable.

Preconditions: - Booking exists but amendment is not available

Steps: 1. Agent requests amendment options (Op 15) 2. GoGlobal returns error 704

Expected Result: - Error 704: "Booking is not amendable"

Business Rules: - Not all bookings support amendments - Non-refundable bookings are typically not amendable - RQ (pending) bookings may not be amendable until confirmed

UC-10.9: Type vs Adults Consistency Rule

Primary Actor: Agent

Description: Ensure room type and adult count remain consistent during amendments.

Preconditions: - Amendment options retrieved (UC-10.1)

Steps: 1. Agent amends a room's configuration 2. System validates that Type (room type) and Adults count are consistent 3. If inconsistent, GoGlobal returns an error

Expected Result: - Amendment succeeds if type and adults are consistent - Error if they conflict

Business Rules: - Room Type determines the expected adult capacity - Changing adults may require changing room type and vice versa - GoGlobal enforces this consistency server-side

13. UC-11: End-to-End Flows

UC-11.1: Happy Path - Full Booking Lifecycle

Primary Actor: Agent

Description: Complete end-to-end flow from search to voucher generation.

Preconditions: - GoGlobal plugin initialized - Static data cache populated

Steps and Data Flow:

sequenceDiagram
    participant Agent
    participant TQPro
    participant GoGlobal

    Note over Agent,GoGlobal: Step 1: Availability Search (Op 11)
    Agent->>TQPro: searchHotelOffers(city, dates, rooms)
    TQPro->>GoGlobal: Op 11 (Availability)
    GoGlobal-->>TQPro: JSON: Hotels[].Offers[].HotelSearchCode
    TQPro-->>Agent: List<CHotelOffer>

    Note over Agent,GoGlobal: Step 2: Hotel Info (Op 6/61)
    Agent->>TQPro: getHotelInfo(HotelSearchCode)
    TQPro->>GoGlobal: Op 6/61 (Hotel Info)
    GoGlobal-->>TQPro: XML: Hotel details, images, facilities
    TQPro-->>Agent: GGHotelInfo

    Note over Agent,GoGlobal: Step 3: Price Breakdown (Op 14)
    Agent->>TQPro: getPriceBreakdown(HotelSearchCode)
    TQPro->>GoGlobal: Op 14 (Price Breakdown)
    GoGlobal-->>TQPro: XML: Nightly rates per room
    TQPro-->>Agent: GGPriceBreakdown

    Note over Agent,GoGlobal: Step 4: Valuation (Op 9)
    Agent->>TQPro: valuateOffer(HotelSearchCode, ArrivalDate)
    TQPro->>GoGlobal: Op 9 (Valuation)
    GoGlobal-->>TQPro: XML: Confirmed price, CXL deadline, remarks
    TQPro-->>Agent: Validated offer

    Note over Agent,GoGlobal: Step 5: Booking (Op 2)
    Agent->>TQPro: createBooking(HotelSearchCode, guests)
    TQPro->>GoGlobal: Op 2 (Insert Booking)
    GoGlobal-->>TQPro: XML: GoBookingCode, Status=C
    TQPro-->>Agent: Booking confirmed

    Note over Agent,GoGlobal: Step 6: Status Check (Op 5)
    Agent->>TQPro: getBookingStatus(GoBookingCode)
    TQPro->>GoGlobal: Op 5 (Booking Status)
    GoGlobal-->>TQPro: XML: Status=C
    TQPro-->>Agent: Confirmed

    Note over Agent,GoGlobal: Step 7: Voucher (Op 8)
    Agent->>TQPro: generateVoucher(GoBookingCode)
    TQPro->>GoGlobal: Op 8 (Voucher)
    GoGlobal-->>TQPro: XML: VoucherDownloadURL
    TQPro-->>Agent: PDF voucher URL

Key Field Flow Between Operations:

From Operation Field To Operation
Op 11 (Search) HotelSearchCode Op 6/61 (Info), Op 14 (Breakdown), Op 9 (Valuation)
Op 9 (Valuation) HotelSearchCode (confirmed) Op 2 (Booking)
Op 2 (Booking) GoBookingCode Op 5 (Status), Op 4 (Details), Op 3 (Cancel), Op 8 (Voucher), Op 15 (Amend)

UC-11.2: Book and Cancel (Free)

Primary Actor: Agent

Description: Search, book, then cancel before the deadline.

Steps: 1. Search (Op 11) -> Receive HotelSearchCode 2. Valuate (Op 9) -> Confirm price and CancellationDeadline 3. Book (Op 2) -> Receive GoBookingCode, status C 4. Cancel (Op 3) before CancellationDeadline -> Status X (no charges)

Expected Result: - Booking cancelled with no penalty - Status: C -> X

UC-11.3: Book and Cancel with Penalty

Primary Actor: Agent

Description: Search, book, then cancel after the deadline.

Steps: 1. Search (Op 11) -> Receive HotelSearchCode 2. Valuate (Op 9) -> Confirm price, note CancellationDeadline and policies 3. Book (Op 2) -> Receive GoBookingCode, status C 4. Wait until after CancellationDeadline 5. Cancel (Op 3) -> Status XP (penalty charged)

Expected Result: - Booking cancelled with penalty per cancellation policy - Status: C -> XP - Penalty calculated: Mode=PCT, Value=50 -> 50% of total price

UC-11.4: Book and Amend

Primary Actor: Agent

Description: Search, book, then amend the booking.

Steps: 1. Search (Op 11) -> Book (Op 2) -> GoBookingCode, status C 2. Get Amendment Options (Op 15) -> Room IDs and Pax IDs 3. Submit Amendment (Op 16) with changes (e.g., change meal plan, update guest name) 4. Get Updated Details (Op 4) -> Confirm changes applied

Expected Result: - Booking amended successfully - Updated pricing and details reflected

Primary Actor: Agent

Description: Compare the same search criteria across online (GoGlobal) and contracted (NTS) modes.

Steps: 1. Search with searchMode=online: - hotel/searchOffers -> OnlineHotelSupplierI.searchOffers() -> GoGlobal Op 11 - Returns GoGlobal hotel offers (international/online rates) 2. Search with searchMode=contracted: - hotel/searchOffers -> NTSHotelFacade.searchAllHotels() - Returns contracted hotel offers (local contracted rates from NTS database) 3. Agent compares results from both sources

Expected Result: - Online results: International hotels from GoGlobal - Contracted results: Local contracted hotels from NTS - Different pricing, availability, and hotel selection per mode

UC-11.6: TripMaker Integration

Primary Actor: Agent (via TripMaker)

Description: TripMaker trip planner searches for accommodation using the GoGlobal supplier.

Steps: 1. Agent uses TripMaker to plan a trip itinerary 2. TripMaker calls searchAccommodations() on TripMakerApi 3. TripMakerApi delegates to HotelSearchFacade 4. HotelSearchFacade uses OnlineHotelSupplierRegistry.getActiveSupplier() -> GoGlobal 5. GoGlobal returns hotel offers 6. TripMaker displays accommodation options within the trip itinerary

Expected Result: - Hotel offers appear in the TripMaker interface - Agent can add selected hotel to the trip itinerary

Business Rules: - TripMaker always uses the online supplier (no contracted mode) - Works automatically with GoGlobal once registered via OnlineHotelSupplierRegistry - No hardcoded Amadeus dependency

UC-11.7: Stale Offer Recovery

Primary Actor: Agent

Description: Handle the case where an offer expires between search and booking.

Steps: 1. Search (Op 11) -> Receive HotelSearchCode 2. Agent takes more than 20 minutes to decide 3. Valuate (Op 9) -> Error 312 (offer expired) 4. System detects expiration, prompts agent to re-search 5. Re-search (Op 11) with same criteria -> New HotelSearchCode 6. Valuate (Op 9) -> Success 7. Book (Op 2) -> Success

Expected Result: - Agent recovers from expired offer by re-searching - Booking completes successfully with fresh offer

Business Rules: - System should track search timestamps and warn at ~15 minutes - Re-search may return different prices (dynamic pricing)

UC-11.8: Multi-Room Lifecycle

Primary Actor: Agent

Description: Complete lifecycle for a multi-room booking including amendment.

Steps: 1. Search 3 rooms (Op 11) -> HotelSearchCode 2. Book 3 rooms (Op 2) -> GoBookingCode, status C 3. Amendment Options (Op 15) -> Get Room IDs 4. Add 4th room (Op 16, RoomId="new") -> Updated booking 5. Cancel entire booking (Op 3) -> Status X or XP

Expected Result: - Multi-room booking created, amended to add a room, then cancelled - All operations use the same GoBookingCode

14. UC-12: Static Data Management

UC-12.1: Initial Static Data Load

Primary Actor: System

Description: Load GoGlobal static data (countries, cities, hotels) into the local cache on first initialization.

Preconditions: - GoGlobal plugin starting for the first time - goglobal database schema exists - GoGlobal API credentials configured

Steps: 1. GoGlobalPlugin.initializePlugin() detects empty goglobal.refresh_log table 2. System triggers StaticDataRefresher.refreshAll() 3. Refresher fetches countries from GoGlobal static data feed -> inserts into goglobal.country 4. Refresher fetches cities -> inserts into goglobal.city with country foreign key 5. Refresher fetches hotels -> inserts into goglobal.hotel with city foreign key 6. System logs refresh in goglobal.refresh_log (type, date, count, status)

Expected Result: - goglobal.country table populated with all GoGlobal countries - goglobal.city table populated with all GoGlobal cities - goglobal.hotel table populated with hotel reference data (name, address, star rating, coordinates) - goglobal.refresh_log entry with status = "COMPLETED"

Business Rules: - Initial load may take several minutes due to large dataset - Batch processing for efficiency (bulk inserts) - Failed load should be retried on next plugin startup

UC-12.2: Scheduled Static Data Refresh

Primary Actor: System Scheduler

Description: Periodically refresh static data to keep the cache current.

Preconditions: - Plugin initialized - Refresh interval configured via goglobal.staticdata.refresh.days property

Steps: 1. SDRefreshRunner checks goglobal.refresh_log for last successful refresh 2. If elapsed days >= configured interval (default: 7 days), trigger refresh 3. StaticDataRefresher.refreshAll() updates all static data tables 4. Log entry created in goglobal.refresh_log

Expected Result: - Static data tables updated with latest GoGlobal data - New hotels, renamed hotels, deactivated hotels reflected in cache

Business Rules: - Configurable refresh interval (default: 7 days) - Refresh runs in background thread, does not block API requests - Previous data remains available during refresh - Failed refresh does not corrupt existing data

UC-12.3: Search Hotels by Name from Cache

Primary Actor: Customer/Agent

Description: Search for hotels by name using the local static data cache.

Preconditions: - Static data cache populated (UC-12.1 or UC-12.2)

Steps: 1. User provides keyword (e.g., "Hilton") 2. System queries goglobal.hotel table: WHERE hotel_name ILIKE '%keyword%' 3. Optionally filtered by city_id 4. System returns matching hotels from cache

Expected Result: - List of hotels matching the keyword - Each result includes: hotel ID, name, city, star rating, coordinates

Business Rules: - Uses PostgreSQL ILIKE for case-insensitive partial matching - Results come from local cache (no GoGlobal API call) - This is the searchHotelsByName() method of OnlineHotelSupplierI

UC-12.4: Get Hotels by City from Cache

Primary Actor: Customer/Agent

Description: Get all hotels in a specific city from the local cache.

Preconditions: - Static data cache populated

Steps: 1. User provides city code or city ID 2. System queries goglobal.hotel table: WHERE city_id = ? 3. System returns all hotels in that city

Expected Result: - List of all cached hotels in the specified city

Business Rules: - This is the getHotelsByCity() method of OnlineHotelSupplierI - City code is resolved to city ID using the goglobal.city table

UC-12.5: Enrich Availability Results with Cached Hotel Details

Primary Actor: System

Description: Augment availability search results with additional hotel details from the local cache.

Preconditions: - Availability search completed (UC-1) - Static data cache populated

Steps: 1. System receives availability results from GoGlobal (Op 11) 2. For each hotel in results, system looks up goglobal.hotel by hotelCode/hotelId 3. System enriches CHotelOffer with cached data: - Full description (if not in search response) - Higher-resolution images - Detailed address - Precise coordinates 4. System returns enriched results

Expected Result: - Hotel offers with additional detail from the local cache - Better user experience with richer hotel information

Business Rules: - Enrichment is best-effort: if hotel not in cache, search data is used as-is - Enrichment does not modify pricing or availability data - Cache lookup is fast (indexed by hotel ID)

15. UC-13: Dual-Mode Search (TQPro-Specific)

UC-13.1: searchMode=online

Primary Actor: Customer/Agent

Description: Search hotel offers using the configured online supplier (GoGlobal).

Preconditions: - hotel.online.supplier property set to GoGlobalServiceFactory in tourlinq-config.xml - GoGlobal plugin registered in OnlineHotelSupplierRegistry

Steps: 1. User calls hotel/searchOffers with searchMode=online (or no searchMode, as online is default) 2. HotelApi routes to online supplier path 3. OnlineHotelSupplierRegistry.getActiveSupplier() returns GoGlobalHotelFacade 4. GoGlobalHotelFacade.searchOffers() executes GoGlobal Op 11 5. Results mapped to CHotelOffer and returned

Expected Result: - Hotel offers from GoGlobal online inventory - International hotels with dynamic pricing

UC-13.2: searchMode=contracted

Primary Actor: Customer/Agent

Description: Search hotel offers from the NTS contracted hotel database.

Preconditions: - NTS plugin active - Contracted hotels configured in NTS database

Steps: 1. User calls hotel/searchOffers with searchMode=contracted 2. HotelApi routes to contracted hotel path 3. NTSHotelFacade.searchAllHotels() queries local PostgreSQL database 4. Results include contracted rates from room calendar

Expected Result: - Hotel offers from locally contracted hotels - Fixed rates per room calendar configuration

Business Rules: - Contracted mode always uses NTS plugin regardless of online supplier configuration - Contracted hotels are managed via hotel/listHotels, hotel/saveHotel, etc. - Contracted search uses date-based room calendar pricing

UC-13.3: Default searchMode

Primary Actor: Customer/Agent

Description: Search without specifying searchMode (defaults to online).

Preconditions: - Same as UC-13.1

Steps: 1. User calls hotel/searchOffers without searchMode parameter 2. System defaults to searchMode=online 3. Proceeds as UC-13.1

Expected Result: - GoGlobal online results (same as UC-13.1)

Business Rules: - Default searchMode is online for: searchOffers, searchByName, getByCity - Default searchMode is contracted for: listHotels

UC-13.4: searchByName - Online vs Contracted

Primary Actor: Customer/Agent

Description: Hotel name search behavior differs between online and contracted modes.

Steps:

Online mode (searchMode=online): 1. User calls hotel/searchByName with keyword 2. System delegates to OnlineHotelSupplierI.searchHotelsByName(keyword, cityCode) 3. GoGlobalHotelFacade queries goglobal.hotel cache (ILIKE) 4. Returns GoGlobal hotel reference data

Contracted mode (searchMode=contracted): 1. User calls hotel/searchByName with searchMode=contracted 2. System delegates to NTS hotel search 3. NTS queries the hotel table in the main database 4. Returns contracted hotel data

Expected Result: - Online: Hotels from GoGlobal cache - Contracted: Hotels from NTS database

UC-13.5: Supplier Registry Configuration and Resolution

Primary Actor: System

Description: How the active online hotel supplier is resolved at runtime.

Steps: 1. During startup, GoGlobalPlugin.initializePlugin() registers: 

OnlineHotelSupplierRegistry.register("GoGlobalServiceFactory", GoGlobalHotelFacade.getInstance());
2. When a hotel API request arrives, OnlineHotelSupplierRegistry.getActiveSupplier() reads: 
<property name="hotel.online.supplier" value="GoGlobalServiceFactory"/>
3. Registry looks up the registered supplier by factory name 4. Returns the GoGlobalHotelFacade instance

Expected Result: - Active supplier resolved dynamically from configuration - No hardcoded supplier dependencies in HotelApi or HotelSearchFacade

Business Rules: - Supplier can be changed by modifying the hotel.online.supplier config property - Future suppliers (e.g., new GDS provider) can be added by implementing OnlineHotelSupplierI and registering - Only one online supplier is active at a time - Amadeus hotel supplier is disabled in config but code retained for potential future use

16. UC-14: Online Hotel Booking Journey (API Wiring)

This section documents the use cases for the four hotel booking journey steps wired through the GoGlobal online supplier. These use cases describe the API-level interaction from the frontend perspective, focusing on the TQPro endpoint signatures, parameters, and expected behavior.

UC-HOTEL-SEARCH: Search for Available Hotels

Primary Actor: Customer/Agent

Description: Search for available hotel offers in a city using the online supplier.

API Endpoint: POST /hotel/searchOffers

Preconditions: - GoGlobal plugin initialized and registered as active online supplier - Static data cache populated with city codes

Steps: 1. User submits search parameters: cityCode, checkInDate, checkOutDate, adults, roomQuantity, currency 2. searchMode defaults to "online" (or explicitly set) 3. System routes to HotelSearchFacade which calls OnlineHotelSupplierRegistry.getActiveSupplier() 4. GoGlobalHotelFacade.searchOffers() builds GoGlobal Op 11 request 5. GoGlobal returns JSON availability response 6. System maps GGHotelOffer native entities to CHotelOffer canonical entities 7. Results enriched with cached hotel data (thumbnail, description, star rating) 8. Paginated CHotelOfferSet returned to frontend

Expected Result: - CHotelOfferSet containing paginated hotel offers - Each offer contains offerId (= GoGlobal HotelSearchCode) for use in subsequent steps - Search metadata: searchId, pageId, totalRes

Request Example: 

{
    "session": "user-session-token",
    "searchMode": "online",
    "cityCode": "1234",
    "checkInDate": "2026-03-15",
    "checkOutDate": "2026-03-18",
    "adults": 2,
    "roomQuantity": 1,
    "currency": "USD"
}

Error Scenarios: - No availability: empty offers array (not an error) - Invalid city code: GoGlobal error 209 - Invalid dates: GoGlobal error 208 - GoGlobal unreachable: connection timeout error

UC-HOTEL-INFO: Get Detailed Hotel Information

Primary Actor: Customer/Agent

Description: Retrieve detailed hotel information (description, facilities, images, geo-coordinates) for a hotel selected from the search results. This is the first step in the booking journey after the user selects an interesting hotel from the search results.

API Endpoint: POST /hotel/getHotel with searchMode="online"

Preconditions: - Hotel availability search completed (UC-HOTEL-SEARCH) - GoGlobal hotel ID known (from hotelId field in search results)

Steps: 1. User selects a hotel from search results, frontend sends GoGlobal hotel ID 2. searchMode="online" routes the request through OnlineHotelSupplierRegistry 3. GoGlobalHotelFacade.getHotelInfo(hotelId) calls GoGlobalHotelService 4. GoGlobalRequestBuilder.buildHotelInfoRequest(hotelId) creates Op 6 XML 5. GoGlobalSoapClient.sendRequest(6, xml) sends SOAP request 6. GoGlobal returns XML response with hotel details 7. GoGlobalResponseParser.parseHotelInfoResponse() parses into GGHotelInfoResponse DTO 8. Native GGHotelInfo entity mapped to response object 9. Hotel details returned to frontend

Expected Result: - Hotel name, address, star rating, description - Hotel-level and room-level facility lists - Thumbnail and image URLs - Geo-coordinates (latitude, longitude) for map display

Request Example: 

{
    "session": "user-session-token",
    "id": 56789,
    "searchMode": "online"
}

Error Scenarios: - Invalid hotel ID: GoGlobal returns empty or error response - GoGlobal unreachable: connection timeout - Without searchMode="online", request is handled by the contracted hotel system (different data source)

Business Rules: - The id parameter is the GoGlobal internal hotel ID (integer) - Hotel info is available independently of the HotelSearchCode (uses hotel ID) - Op 6 uses version attribute 2.2 on the <Main> element - Response is always XML format (not JSON)

UC-HOTEL-VALUATE: Valuate Selected Offer

Primary Actor: Agent

Description: Validate the current price, cancellation policies, and booking terms for a selected hotel offer before proceeding to booking. This confirms whether the price from the availability search is still valid and provides detailed cancellation rules.

API Endpoint: POST /hotel/valuateOffer

Preconditions: - Hotel availability search completed (UC-HOTEL-SEARCH) - User has selected an offer with a specific HotelSearchCode (returned as offerId) - HotelSearchCode is still valid (within ~20 minute window)

Steps: 1. User selects an offer and requests valuation 2. Frontend sends hotelSearchCode from the selected offer's offerId 3. OnlineHotelSupplierRegistry.getActiveSupplier() resolves to GoGlobalHotelFacade 4. GoGlobalHotelFacade.valuateOffer(hotelSearchCode) calls GoGlobalHotelService 5. GoGlobalRequestBuilder.buildValuationRequest(hotelSearchCode) creates Op 9 XML 6. GoGlobalSoapClient.sendRequest(9, xml) sends SOAP request 7. GoGlobal returns XML with confirmed price, rates, taxes, CXL deadline, remarks, cancellation policies 8. GoGlobalResponseParser.parseValuationResponse() parses into GGValuationResponse DTO 9. Validated offer returned to frontend with confirmed pricing and CXL terms

Expected Result: - Confirmed total price (NewRate) -- may differ from search price - Nightly rates per room - Total tax amount - Cancellation deadline (ISO 8601 datetime) - Non-refundable flag - Detailed cancellation policies (when to cancel, penalty percentage/amount) - Hotel-specific remarks and conditions

Request Example: 

{
    "session": "user-session-token",
    "hotelSearchCode": "HSC-2026031500001"
}

Error Scenarios: - Offer expired (GoGlobal error 312): HotelSearchCode no longer valid, user must re-search - GoGlobal unreachable: connection timeout - Price changed: the NewRate in the response differs from the original TotalPrice -- frontend should alert the user

Business Rules: - HotelSearchCode is valid for approximately 20 minutes from the time of the availability search - The NewRate is the confirmed price that will be charged at booking time - Cancellation policies define penalty rules by date range, mode (PCT or ABS), and value - NonRef=true means the offer is non-refundable -- full penalty applies regardless of cancellation timing - Op 9 uses version attribute 2.0 on the <Main> element - Response is always XML format

UC-HOTEL-BREAKDOWN: Get Price Breakdown

Primary Actor: Customer/Agent

Description: Retrieve the nightly price breakdown per room for a selected offer. This provides the granular pricing detail so the user can see how the total price is distributed across each night of the stay.

API Endpoint: POST /hotel/getPriceBreakdown

Preconditions: - Hotel availability search completed (UC-HOTEL-SEARCH) - User has selected an offer with a specific HotelSearchCode - HotelSearchCode is still valid

Steps: 1. User requests price breakdown for a selected offer 2. Frontend sends hotelSearchCode 3. OnlineHotelSupplierRegistry.getActiveSupplier() resolves to GoGlobalHotelFacade 4. GoGlobalHotelFacade.getPriceBreakdown(hotelSearchCode) calls GoGlobalHotelService 5. GoGlobalRequestBuilder.buildPriceBreakdownRequest(hotelSearchCode) creates Op 14 XML 6. GoGlobalSoapClient.sendRequest(14, xml) sends SOAP request 7. GoGlobal returns XML with per-night pricing per room 8. GoGlobalResponseParser.parsePriceBreakdownResponse() parses into GGPriceBreakdownResponse DTO 9. Native GGPriceBreakdown entity populated and returned

Expected Result: - Per-room, per-night pricing breakdown - Each night entry includes: date, price, currency - For multi-room bookings, each room has its own breakdown

Request Example: 

{
    "session": "user-session-token",
    "hotelSearchCode": "HSC-2026031500001"
}

Error Scenarios: - Offer expired (GoGlobal error 312): HotelSearchCode no longer valid - GoGlobal unreachable: connection timeout

Business Rules: - Op 14 does not use a version attribute on the <Main> element - Response is always XML format - Nightly prices may vary (e.g., weekend vs weekday rates) - The sum of nightly prices may differ slightly from the total due to rounding at the GoGlobal side - Price breakdown is optional in the booking flow -- it provides informational detail only

UC-HOTEL-BOOK: Create Booking

Primary Actor: Agent

Description: Create a hotel booking for a validated offer. This is the final step in the booking journey. The agent provides guest details and the system submits the booking to GoGlobal.

API Endpoint: POST /hotel/createBooking

Preconditions: - Hotel availability search completed (UC-HOTEL-SEARCH) - Offer valuated successfully (UC-HOTEL-VALUATE) -- price confirmed - HotelSearchCode is still valid - Agent has guest details (name, email, phone)

Steps: 1. Agent provides guest details: title, firstName, lastName, email, phone 2. Agent optionally provides a client reference code 3. Frontend sends hotelSearchCode along with guest details and room-level pax data 4. OnlineHotelSupplierRegistry.getActiveSupplier() resolves to GoGlobalHotelFacade 5. GoGlobalHotelFacade.createBooking(hotelSearchCode, bookingData) calls GoGlobalHotelService 6. GoGlobalRequestBuilder.buildBookingRequest(hotelSearchCode, clientRef, title, firstName, lastName, email, phone) creates Op 2 XML 7. GoGlobalSoapClient.sendRequest(2, xml) sends SOAP request 8. GoGlobal returns XML with booking confirmation: GoBookingCode, GoReference, BookingStatus, pricing, hotel details 9. GoGlobalResponseParser.parseBookingResponse() parses into GGBookingResponse DTO 10. Native GGBooking entity populated from DTO 11. Booking stored in TQPro database for management 12. Booking confirmation returned to frontend

Expected Result: - GoBookingCode -- permanent booking identifier for all subsequent operations - GoReference -- supplier reference number - BookingStatus: - C = Confirmed (immediately confirmed by hotel) - RQ = On Request (hotel needs to confirm; poll via booking status endpoint) - RJ = Rejected (booking was rejected) - Total price, currency, hotel name, hotel confirmation number

Request Example: 

{
    "session": "user-session-token",
    "hotelSearchCode": "HSC-2026031500001",
    "clientRef": "TQ-BK-2026-0001",
    "title": "MR.",
    "firstName": "John",
    "lastName": "Smith",
    "email": "john.smith@example.com",
    "phone": "+44123456789",
    "rooms": [
        {
            "adults": 2,
            "pax": [
                { "title": "MR.", "firstName": "John", "lastName": "Smith" },
                { "title": "MRS.", "firstName": "Jane", "lastName": "Smith" }
            ]
        }
    ]
}

Error Scenarios: - Offer expired (GoGlobal error 312): HotelSearchCode no longer valid, must re-search - Invalid pax data (GoGlobal error 314): name format, title, or missing required fields - Room configuration mismatch (GoGlobal error 315): room config does not match search config - GoGlobal unreachable: connection timeout

Business Rules: - Op 2 uses version attribute 2.3 on the <Main> element - Response is always XML format - Lead guest (Leader) must be one of the room pax - Room configuration must exactly match the search configuration (same number of rooms, adults, children) - ClientBookingCode is optional but recommended for agency tracking - Title format: MR., MRS., MS., MISS (with period) - For RQ status bookings, the agent should poll the booking status endpoint periodically until the status changes to C or RJ - Once a GoBookingCode is obtained, it is used for all subsequent operations: status check (Op 5), details (Op 4), cancellation (Op 3), voucher (Op 8), amendment (Op 15/16)

17. GoGlobal Error Code Reference (formerly Section 16)

Search Errors (Op 11)

Code Description
207 No availability found
208 Invalid date format
209 City does not exist
210 Number of nights exceeds maximum (99)
211 Too many extra beds or cots
214 Room limit exceeded (max 8)
143 Pax per room exceeded (max 8)

Booking Errors (Op 2)

Code Description
312 Offer expired (>20 min since search)
314 Invalid pax data (name format, title)
315 Room configuration mismatch

Cancellation Errors (Op 3)

Code Description
401 Booking not found
402 Booking not found for this agency

Voucher Errors (Op 8)

Code Description
700 Booking not confirmed
701 Agency not authorized
702 Credit limit exceeded

Amendment Errors (Ops 15/16)

Code Description
704 Booking not amendable

General Errors

Code Description
100 General server error
101 Authentication failure
102 Invalid API version
103 Invalid operation

18. Booking Status State Machine (formerly Section 17)

stateDiagram-v2
    [*] --> RQ : Booking Created (on-request)
    [*] --> C : Booking Created (instant confirm)
    [*] --> RJ : Booking Created (instant reject)

    RQ --> C : Hotel Confirms
    RQ --> RJ : Hotel Rejects

    C --> RX : Cancellation Requested
    C --> VRQ : Voucher Requested
    C --> VCH : Voucher Issued

    RX --> X : Cancelled (Free)
    RX --> XP : Cancelled (Penalty)
    RX --> C : Cancellation Denied (rare)

    VRQ --> VCH : Voucher Generated

    X --> [*]
    XP --> [*]
    RJ --> [*]

Status Descriptions:

Status Name Description
RQ Requested Booking submitted, awaiting hotel confirmation
C Confirmed Booking confirmed by hotel, ready for voucher
RJ Rejected Booking rejected by hotel, no charges
RX Cancellation Requested Cancellation submitted, awaiting processing
X Cancelled Booking cancelled with no penalty
XP Cancelled with Penalty Booking cancelled with penalty charges
VRQ Voucher Requested Voucher generation requested
VCH Voucher Issued Voucher has been generated and is downloadable

Document Information

Document Version: 1.1 Date: 2026-02-10 Status: Implementation Author: System Architecture Team

Changelog: - v1.1 (2026-02-10): Added Section 16 (UC-14): Online Hotel Booking Journey use cases. Documents five use cases covering the end-to-end API wiring for the hotel booking journey through GoGlobal: UC-HOTEL-SEARCH (Op 11), UC-HOTEL-INFO (Op 6), UC-HOTEL-VALUATE (Op 9), UC-HOTEL-BREAKDOWN (Op 14), UC-HOTEL-BOOK (Op 2). Each use case includes API endpoint, request/response examples, entity conversion steps, error scenarios, and business rules. Renumbered subsequent sections (Error Code Reference is now Section 17, Booking Status State Machine is now Section 18). - v1.0 (2026-02-09): Initial document.

Related Documents: - Implementation Details - Technical implementation details - Integration Plan - Implementation plan - Hotel API Specification - Hotel API specification - Hotel Management Requirements - Local hotel management requirements