{
  "openapi": "3.0.3",
  "info": {
    "title": "BookingClub Inner API",
    "version": "1.0.0",
    "description": "BookingClub Inner API v1 for reference data, properties, availability, bookings, cancellation and booking modification. Price-changing modification is supported for direct internal pending hotel items and direct TL2 API bookings when provider penalty is zero and only date/occupancy changes are requested; WTX-backed, room/rate/property/nationality, paid or commission-paid items require manual review."
  },
  "servers": [
    {
      "url": "https://api.bookingclub.net/v1"
    },
    {
      "url": "https://bookingclub.net/api/v1"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/": {
      "get": {
        "summary": "API metadata",
        "responses": {
          "200": {
            "$ref": "#/components/responses/JsonResponse"
          }
        }
      }
    },
    "/reference/{resource}": {
      "get": {
        "summary": "List reference data",
        "parameters": [
          {
            "name": "resource",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": ["countries", "regions", "cities", "airports", "currencies", "currency-rates", "nationalities", "languages", "meal-plans"]
            }
          },
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "countryId",
            "in": "query",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "regionId",
            "in": "query",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "cityId",
            "in": "query",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200
            }
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/JsonResponse"
          }
        }
      }
    },
    "/properties": {
      "get": {
        "summary": "List visible properties",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "countryId",
            "in": "query",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "cityId",
            "in": "query",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "source",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/JsonResponse"
          }
        }
      }
    },
    "/properties/{propertyId}": {
      "get": {
        "summary": "Get property details",
        "parameters": [
          {
            "name": "propertyId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/JsonResponse"
          }
        }
      }
    },
    "/hotels/availability": {
      "post": {
        "summary": "Search hotel availability",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/HotelAvailabilityRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/JsonResponse"
          }
        }
      }
    },
    "/tours": {
      "get": {
        "summary": "List tours",
        "responses": {
          "200": {
            "$ref": "#/components/responses/JsonResponse"
          }
        }
      }
    },
    "/tours/{tourId}": {
      "get": {
        "summary": "Get tour details",
        "parameters": [
          {
            "name": "tourId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/JsonResponse"
          }
        }
      }
    },
    "/tours/availability": {
      "post": {
        "summary": "Search tour availability",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TourAvailabilityRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/JsonResponse"
          }
        }
      }
    },
    "/transfers": {
      "get": {
        "summary": "List transfers",
        "responses": {
          "200": {
            "$ref": "#/components/responses/JsonResponse"
          }
        }
      }
    },
    "/transfers/{transferId}": {
      "get": {
        "summary": "Get transfer details",
        "parameters": [
          {
            "name": "transferId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/JsonResponse"
          }
        }
      }
    },
    "/transfers/availability": {
      "post": {
        "summary": "Search transfer availability",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TransferAvailabilityRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/JsonResponse"
          }
        }
      }
    },
    "/bookings": {
      "get": {
        "summary": "List bookings",
        "responses": {
          "200": {
            "$ref": "#/components/responses/JsonResponse"
          }
        }
      },
      "post": {
        "summary": "Create booking",
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateBookingRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/JsonResponse"
          }
        }
      }
    },
    "/bookings/{bookingNumber}": {
      "get": {
        "summary": "Get booking",
        "parameters": [
          {
            "$ref": "#/components/parameters/BookingNumber"
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/JsonResponse"
          }
        }
      },
      "patch": {
        "summary": "Compatibility alias for modify",
        "parameters": [
          {
            "$ref": "#/components/parameters/BookingNumber"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ModifyBookingRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/JsonResponse"
          }
        }
      }
    },
    "/bookings/{bookingNumber}/cancel-quote": {
      "post": {
        "summary": "Get cancellation quote",
        "parameters": [
          {
            "$ref": "#/components/parameters/BookingNumber"
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/JsonResponse"
          }
        }
      }
    },
    "/bookings/{bookingNumber}/cancel": {
      "post": {
        "summary": "Cancel booking or selected items",
        "parameters": [
          {
            "$ref": "#/components/parameters/BookingNumber"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/JsonResponse"
          }
        }
      }
    },
    "/bookings/{bookingNumber}/modify-quote": {
      "post": {
        "summary": "Get modify quote",
        "parameters": [
          {
            "$ref": "#/components/parameters/BookingNumber"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ModifyBookingRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/JsonResponse"
          }
        }
      }
    },
    "/bookings/{bookingNumber}/modify": {
      "post": {
        "summary": "Apply modify",
        "parameters": [
          {
            "$ref": "#/components/parameters/BookingNumber"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ModifyBookingRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/JsonResponse"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    },
    "parameters": {
      "BookingNumber": {
        "name": "bookingNumber",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string"
        }
      },
      "IdempotencyKey": {
        "name": "Idempotency-Key",
        "in": "header",
        "required": true,
        "schema": {
          "type": "string",
          "maxLength": 128
        }
      }
    },
    "responses": {
      "JsonResponse": {
        "description": "BookingClub JSON envelope",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/JsonEnvelope"
            }
          }
        }
      }
    },
    "schemas": {
      "JsonEnvelope": {
        "type": "object",
        "required": ["success", "requestId", "data", "errors"],
        "properties": {
          "success": {
            "type": "boolean"
          },
          "requestId": {
            "type": "string"
          },
          "data": {
            "type": "object",
            "nullable": true
          },
          "errors": {
            "type": "array",
            "items": {
              "type": "object"
            }
          }
        }
      },
      "HotelAvailabilityRequest": {
        "type": "object",
        "required": ["propertyId", "checkIn", "checkOut", "currency", "rooms"],
        "properties": {
          "propertyId": {
            "type": "string"
          },
          "checkIn": {
            "type": "string",
            "format": "date"
          },
          "checkOut": {
            "type": "string",
            "format": "date"
          },
          "currency": {
            "type": "string"
          },
          "nationalityId": {
            "type": "integer"
          },
          "rooms": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/RoomRequest"
            }
          }
        }
      },
      "RoomRequest": {
        "type": "object",
        "required": ["adults"],
        "properties": {
          "adults": {
            "type": "integer",
            "minimum": 1
          },
          "childrenAges": {
            "type": "array",
            "items": {
              "type": "integer",
              "minimum": 0,
              "maximum": 17
            }
          }
        }
      },
      "TourAvailabilityRequest": {
        "type": "object",
        "required": ["tourId", "checkIn", "checkOut", "currency", "adults"],
        "properties": {
          "tourId": {
            "type": "integer"
          },
          "checkIn": {
            "type": "string",
            "format": "date"
          },
          "checkOut": {
            "type": "string",
            "format": "date"
          },
          "currency": {
            "type": "string"
          },
          "adults": {
            "type": "integer",
            "minimum": 1
          },
          "childrenAges": {
            "type": "array",
            "items": {
              "type": "integer"
            }
          },
          "vehicleId": {
            "type": "integer"
          },
          "languageId": {
            "type": "integer"
          },
          "nationalityId": {
            "type": "integer"
          }
        }
      },
      "TransferAvailabilityRequest": {
        "type": "object",
        "required": ["transferKind", "checkIn", "currency", "adults"],
        "properties": {
          "transferKind": {
            "type": "integer",
            "enum": [1, 2, 3]
          },
          "checkIn": {
            "type": "string",
            "format": "date"
          },
          "currency": {
            "type": "string"
          },
          "adults": {
            "type": "integer",
            "minimum": 1
          },
          "pickupAirportId": {
            "type": "integer"
          },
          "dropOffAirportId": {
            "type": "integer"
          },
          "pickupCityId": {
            "type": "integer"
          },
          "dropOffCityId": {
            "type": "integer"
          },
          "pickupHotelId": {
            "type": "integer"
          },
          "dropOffHotelId": {
            "type": "integer"
          },
          "transferId": {
            "type": "integer"
          },
          "vehicleId": {
            "type": "integer"
          },
          "childrenAges": {
            "type": "array",
            "items": {
              "type": "integer"
            }
          },
          "nationalityId": {
            "type": "integer"
          },
          "flightNumber": {
            "type": "string"
          },
          "time": {
            "type": "string"
          }
        }
      },
      "CreateBookingRequest": {
        "type": "object",
        "required": ["holder", "items"],
        "properties": {
          "clientReference": {
            "type": "string"
          },
          "holder": {
            "$ref": "#/components/schemas/Holder"
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BookingItemRequest"
            }
          },
          "note": {
            "type": "string"
          }
        }
      },
      "Holder": {
        "type": "object",
        "required": ["firstName", "lastName"],
        "properties": {
          "firstName": {
            "type": "string"
          },
          "lastName": {
            "type": "string"
          },
          "email": {
            "type": "string"
          },
          "phone": {
            "type": "string"
          }
        }
      },
      "BookingItemRequest": {
        "type": "object",
        "required": ["type", "rateToken", "guests"],
        "properties": {
          "type": {
            "type": "string",
            "enum": ["hotel", "tour", "transfer"]
          },
          "rateToken": {
            "type": "string"
          },
          "guests": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Guest"
            }
          },
          "specialRequests": {
            "type": "string"
          }
        }
      },
      "Guest": {
        "type": "object",
        "required": ["firstName", "lastName"],
        "properties": {
          "firstName": {
            "type": "string"
          },
          "lastName": {
            "type": "string"
          },
          "gender": {
            "type": "integer"
          },
          "type": {
            "type": "string",
            "enum": ["adult", "child"]
          },
          "age": {
            "type": "integer"
          }
        }
      },
      "ModifyBookingRequest": {
        "type": "object",
        "required": ["itemId"],
        "properties": {
          "itemId": {
            "type": "integer"
          },
          "confirm": {
            "type": "boolean"
          },
          "changes": {
            "$ref": "#/components/schemas/ModifyBookingChanges"
          },
          "guests": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Guest"
            }
          },
          "specialRequests": {
            "type": "string"
          },
          "bookingComment": {
            "type": "string"
          },
          "customerComment": {
            "type": "string"
          },
          "checkIn": {
            "type": "string",
            "format": "date"
          },
          "checkOut": {
            "type": "string",
            "format": "date"
          },
          "roomId": {
            "type": "string"
          },
          "contractId": {
            "type": "integer"
          },
          "rateId": {
            "type": "string"
          },
          "adults": {
            "type": "integer"
          },
          "childrenAges": {
            "type": "array",
            "items": {
              "type": "integer"
            }
          },
          "nationalityId": {
            "type": "integer"
          },
          "currency": {
            "type": "string",
            "description": "Required when date, room, rate, occupancy, nationality or currency is changed."
          }
        }
      },
      "ModifyBookingChanges": {
        "type": "object",
        "description": "Same fields as top-level modify body except itemId and confirm. Use this object for clearer request bodies.",
        "properties": {
          "guests": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Guest"
            }
          },
          "specialRequests": {
            "type": "string"
          },
          "bookingComment": {
            "type": "string"
          },
          "customerComment": {
            "type": "string"
          },
          "checkIn": {
            "type": "string",
            "format": "date"
          },
          "checkOut": {
            "type": "string",
            "format": "date"
          },
          "roomId": {
            "type": "string"
          },
          "contractId": {
            "type": "integer"
          },
          "rateId": {
            "type": "string"
          },
          "adults": {
            "type": "integer"
          },
          "childrenAges": {
            "type": "array",
            "items": {
              "type": "integer"
            }
          },
          "nationalityId": {
            "type": "integer"
          },
          "currency": {
            "type": "string"
          }
        }
      }
    }
  }
}