openapi: 3.0.3
info:
  title: Gate2hotels B2B Distribution API
  version: 1.0.0
  description: |
    Production-ready B2B hotel distribution and channel management platform focused exclusively on hotels located in Iraq (Baghdad, Erbil, Karbala, Najaf, Basra, Sulaymaniyah, Duhok, Kirkuk, etc.).
    Authorized API partners consume real-time hotel inventory, rates, availability, and execute atomic reservation lifecycles.
  contact:
    name: Gate2hotels API Engineering
    email: api-support@gate2hotels.online
    url: https://docs.gate2hotels.online
servers:
  - url: https://api.gate2hotels.online/v1
    description: Production B2B API Gateway
  - url: https://sandbox.gate2hotels.online/v1
    description: Partner Testing Sandbox Gateway
  - url: http://localhost:3000/v1
    description: Local Sandbox / Development Gateway

security:
  - ApiKeyAuth: []
    ClientIdAuth: []

paths:
  /health:
    get:
      summary: Health Check & System Status
      description: Returns operational status of the API Gateway, latency metrics, and current UTC timestamp.
      security: []
      responses:
        '200':
          description: Gateway is healthy and operational.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  status:
                    type: string
                    example: OPERATIONAL
                  version:
                    type: string
                    example: 1.0.0
                  timestamp:
                    type: string
                    format: date-time

  /hotels:
    get:
      summary: List Authorized Hotels
      description: Returns all Iraqi properties currently whitelisted for the calling API Client with contracted commission terms.
      responses:
        '200':
          description: Manifest of authorized Iraqi hotels.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Hotel'
        '401':
          $ref: '#/components/responses/UnauthorizedError'

  /hotels/{hotelId}:
    get:
      summary: Get Hotel Details
      description: Returns comprehensive metadata for a specific authorized hotel including coordinates, amenities, and policies.
      parameters:
        - name: hotelId
          in: path
          required: true
          schema:
            type: string
          description: Hotel UUID or Public ID (e.g. HTL-2026-0001)
      responses:
        '200':
          description: Detailed property profile.
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'

  /room-types:
    get:
      summary: List Room Types
      description: Fetches active room types for an authorized hotel with max occupancy, bed configuration, and amenities.
      parameters:
        - name: hotelId
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Room type categories.

  /rates:
    get:
      summary: List Rate Plans
      description: Retrieves active pricing models (Room Only, Bed & Breakfast, Half Board, Full Board) with single, double, and child pricing.
      parameters:
        - name: hotelId
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Available rate plans.

  /availability:
    get:
      summary: Get Calendar Availability Matrix
      description: Returns daily room allotment, booked count, blocked count, available inventory, and restriction flags (Stop Sell, CTA, CTD).
      parameters:
        - name: hotelId
          in: query
          required: true
          schema:
            type: string
        - name: roomTypeId
          in: query
          required: true
          schema:
            type: string
        - name: days
          in: query
          schema:
            type: integer
            default: 14
        - name: startDate
          in: query
          schema:
            type: string
            format: date
      responses:
        '200':
          description: Calendar availability matrix.

  /search:
    post:
      summary: Search Multi-Hotel Availability
      description: Performs high-speed availability search across all whitelisted properties for specified dates and party size.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchRequest'
      responses:
        '200':
          description: Matching hotels with real-time room availability.

  /price-check:
    post:
      summary: Live Price Check & Price Lock
      description: Validates inventory availability and calculates itemized rates, taxes (5%), and service charges (10%).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PriceCheckRequest'
      responses:
        '200':
          description: Live quote with breakdown and lock state.
        '409':
          description: Insufficient inventory for requested dates.

  /prebook:
    post:
      summary: Prebook & 15-Minute Allotment Lock
      description: Validates guest data and issues a temporary 15-minute lock token prior to committing payment.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - hotelId
                - roomTypeId
                - ratePlanId
                - checkIn
                - checkOut
                - guestName
                - guestPhone
              properties:
                hotelId:
                  type: string
                roomTypeId:
                  type: string
                ratePlanId:
                  type: string
                checkIn:
                  type: string
                  format: date
                checkOut:
                  type: string
                  format: date
                guestName:
                  type: string
                guestPhone:
                  type: string
      responses:
        '200':
          description: Temporary lock granted with prebook token.

  /bookings:
    post:
      summary: Create Confirmed Booking (Atomic Mutex)
      description: Atomically reserves inventory using FIFO mutex locks, verifies Idempotency-Key, and issues official IHC-YYYY-XXXXXX voucher.
      parameters:
        - name: Idempotency-Key
          in: header
          schema:
            type: string
          description: Unique client token to guarantee exactly-once reservation processing.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BookingRequest'
      responses:
        '200':
          description: Booking confirmed with voucher details.
        '409':
          description: Inventory depleted or price changed during checkout.

  /bookings/{bookingId}:
    get:
      summary: Get Booking Details
      description: Fetches full reservation details, voucher status, guest manifest, and audit logs.
      parameters:
        - name: bookingId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Reservation details.

  /bookings/{bookingId}/modify:
    post:
      summary: Modify Reservation
      description: Atomically updates stay dates, room type, or guest details while swapping inventory allocations.
      parameters:
        - name: bookingId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                checkIn:
                  type: string
                  format: date
                checkOut:
                  type: string
                  format: date
                guestName:
                  type: string
                guestPhone:
                  type: string
                specialRequests:
                  type: string
      responses:
        '200':
          description: Modification applied successfully.

  /bookings/{bookingId}/cancel:
    post:
      summary: Cancel Reservation
      description: Cancels reservation, applies cancellation policy rules, and atomically returns inventory to the available pool.
      parameters:
        - name: bookingId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                reason:
                  type: string
                  example: Guest flight rescheduled
      responses:
        '200':
          description: Reservation cancelled and inventory restored.

  /cancellation-policies:
    get:
      summary: List Cancellation Policies
      description: Returns cancellation rules and penalty timelines for authorized hotels.
      responses:
        '200':
          description: Policy specifications.

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Api-Key
      description: Issued secret API Key (Format: g2h_live_... or g2h_test_...)
    ClientIdAuth:
      type: apiKey
      in: header
      name: X-Client-Id
      description: Partner Client Identifier (e.g. api-partner-01)

  schemas:
    Hotel:
      type: object
      properties:
        id:
          type: string
          format: uuid
        public_id:
          type: string
          example: HTL-2026-0001
        name_en:
          type: string
          example: Babylon Rotana Baghdad
        name_ar:
          type: string
          example: فندق بابل روتانا بغداد
        star_rating:
          type: integer
          example: 5
        city:
          type: string
          example: Baghdad
        governorate:
          type: string
          example: Baghdad
        status:
          type: string
          example: ACTIVE
        currency:
          type: string
          example: IQD
        commission_rate:
          type: number
          example: 12.0

    SearchRequest:
      type: object
      required:
        - checkIn
        - checkOut
      properties:
        checkIn:
          type: string
          format: date
          example: '2026-09-25'
        checkOut:
          type: string
          format: date
          example: '2026-09-28'
        destination:
          type: string
          example: Baghdad
        adults:
          type: integer
          default: 2
        children:
          type: integer
          default: 0
        roomsCount:
          type: integer
          default: 1

    PriceCheckRequest:
      type: object
      required:
        - hotelId
        - roomTypeId
        - ratePlanId
        - checkIn
        - checkOut
      properties:
        hotelId:
          type: string
        roomTypeId:
          type: string
        ratePlanId:
          type: string
        checkIn:
          type: string
          format: date
        checkOut:
          type: string
          format: date
        adults:
          type: integer
          default: 2
        children:
          type: integer
          default: 0
        roomsCount:
          type: integer
          default: 1

    BookingRequest:
      type: object
      required:
        - hotelId
        - roomTypeId
        - ratePlanId
        - checkIn
        - checkOut
        - guestName
        - guestPhone
      properties:
        hotelId:
          type: string
        roomTypeId:
          type: string
        ratePlanId:
          type: string
        checkIn:
          type: string
          format: date
        checkOut:
          type: string
          format: date
        roomsCount:
          type: integer
          default: 1
        adults:
          type: integer
          default: 2
        children:
          type: integer
          default: 0
        guestName:
          type: string
        guestPhone:
          type: string
        guestEmail:
          type: string
        specialRequests:
          type: string
        channelReference:
          type: string
          description: External partner booking reference ID

  responses:
    UnauthorizedError:
      description: Authentication failed due to missing or invalid API Key.
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                type: boolean
                example: false
              error:
                type: object
                properties:
                  code:
                    type: string
                    example: INVALID_API_KEY
                  message:
                    type: string

    ForbiddenError:
      description: Hotel is not whitelisted or permission scope is denied.
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                type: boolean
                example: false
              error:
                type: object
                properties:
                  code:
                    type: string
                    example: HOTEL_ACCESS_DENIED
                  message:
                    type: string

    NotFoundError:
      description: Resource was not found.