Hotel Bookings API

Insert a Hotel Booking

Type: hotel_bookings POST

Insert a hotel booking into TOWeRS.

Request

Endpoint: POST /manager/hotel_bookings

Headers:

  • Authorization: ApiKey YOUR_API_KEY
  • Content-Type: application/json

Request fields:

  • hotel_booking - hotel booking object
    • hotel (integer, mandatory): Hotel ID in TOWeRS system
    • checkin (string, mandatory): Check-in date in YYYY-MM-DD format
    • checkout (string, mandatory): Check-out date in YYYY-MM-DD format
    • currency (string, mandatory): Purchase currency (ISO 4217, e.g., EUR)
    • sell_currency (string, mandatory): Selling currency (ISO 4217, e.g., EUR)
    • customerreference (string, mandatory): Your unique booking reference
    • supplierreference (string, mandatory): Supplier's reference
    • supplier (string, mandatory): Supplier name/code
    • suppliercode (string, mandatory): Supplier code in TOWeRS
    • status (string, mandatory): Booking status (CNF, PND, CXL, SNT, SND, REJ, WIT, SUP, CLI)
    • configuration (object, mandatory): Custom configuration (must be a valid object, can be empty {})
    • roombasis (string, mandatory): Room basis code (e.g., RO for room only)
    • mealbasis (string, mandatory): Meal basis code (e.g., BB for bed & breakfast)
    • accommodation (array, mandatory): List of rooms/accommodations (at least one)
      • type (string, mandatory): Room type (e.g., DBL, SGL, TRP)
      • num (integer, optional): Number of rooms
      • prices (object, optional): Pricing details
      • paxes (array, optional): Passengers assigned to this room
        • initial (string): Guest first name
        • surname (string): Guest last name
        • title (string, optional): Mr, Ms, Miss
    • remarks (array, optional): Special remarks
      • code (string, mandatory): Remark code
      • when (string, mandatory): Creation date in YYYY-MM-DDTHH:MM format
      • text (string, mandatory): Remark text
      • visibility (array, mandatory): Who can see (customers, suppliers, owners)
      • from (string, mandatory): Who created (customers, suppliers, owners)
      • target (array, mandatory): When visible (availability, booking, voucher)
      • checked (boolean, mandatory): Should be notified
    • returnpoints (array, optional): Return point definitions

If remarks is provided, every remark item must include all remark attributes listed above.

Note: actor and login fields are extracted from API key context.

Request example:

{
  "hotel_booking": {
    "hotel": 12345,
    "checkin": "2024-02-12",
    "checkout": "2024-02-14",
    "currency": "EUR",
    "sell_currency": "EUR",
    "customerreference": "HOT-20240101-001",
    "supplierreference": "SUPP-98765",
    "supplier": "Best Hotels Ltd",
    "suppliercode": "BHL",
    "status": "CNF",
    "roombasis": "RO",
    "mealbasis": "BB",
    "configuration": {
      "notes": "Early check-in request"
    },
    "accommodation": [
      {
        "type": "DBL",
        "num": 1,
        "prices": {
          "nett": 150.0,
          "gross": 180.0
        },
        "paxes": [
          {
            "initial": "Mario",
            "surname": "Rossi",
            "title": "Mr"
          },
          {
            "initial": "Anna",
            "surname": "Rossi",
            "title": "Ms"
          }
        ]
      }
    ],
    "remarks": [
      {
        "code": null,
        "when": "2024-01-31T10:56:00",
        "text": "Guest requests non-smoking room",
        "visibility": ["customers", "suppliers"],
        "from": "customers",
        "target": ["booking"],
        "checked": true
      }
    ]
  }
}

Response

Success response:

{
  "name": "H012B456",
  "status": "CNF",
  "dossier": "D012B456",
  "customerreference": "HOT-20240101-001",
  "__metadata__": {
    "app_server": "ns001tow:6002",
    "timestamp": "2024-01-31T10:56:27",
    "request_id": "8bae9fc8-2f9c-4791-911e-237b324b34cc"
  }
}

Error response (invalid status):

{
  "error": "Cannot parse request",
  "debug_info": "Attribute status does not validate to its defined type: validate_status - invalid literal for int() with base 10: 'INVALID'",
  "__metadata__": {
    "app_server": "ns001tow:6002",
    "timestamp": "2024-01-31T10:56:27",
    "request_id": "8bae9fc8-2f9c-4791-911e-237b324b34cc"
  }
}

Modify a Hotel Booking

Type: hotel_bookings PUT

Modify an existing hotel booking.

Request

Endpoint: PUT /manager/hotel_bookings/{book_name}

Headers:

  • Authorization: ApiKey YOUR_API_KEY
  • Content-Type: application/json

Path parameters:

  • book_name (string, mandatory): TOWeRS booking name/reference

Request body fields:

  • hotel_booking - object containing only the fields to be modified
    • actor (string, mandatory): TOWeRS customer code on whose behalf the booking will be inserted
    • login (string, mandatory): TOWeRS login of the customer user
    • checkin (string, optional): New check-in date in YYYY-MM-DD format
    • checkout (string, optional): New check-out date in YYYY-MM-DD format
    • currency (string, optional): New purchase currency
    • sell_currency (string, optional): New selling currency
    • status (string, optional): New booking status
    • roombasis (string, optional): New room basis code
    • mealbasis (string, optional): New meal basis code
    • accommodation (array, optional): Updated accommodation details
    • remarks (array, optional): Updated remarks

Request example:

{
  "hotel_booking": {
    "checkout": "2024-02-15",
    "status": "CNF",
    "remarks": [
      {
        "code": null,
        "when": "2024-02-01T14:00:00",
        "text": "Late checkout approved",
        "visibility": ["customers", "suppliers"],
        "from": "customers",
        "target": ["booking"],
        "checked": true
      }
    ]
  }
}

Response

Success response:

{
  "name": "H012B456",
  "status": "CNF",
  "dossier": "D012B456",
  "customerreference": "HOT-20240101-001",
  "__metadata__": {
    "app_server": "ns001tow:6002",
    "timestamp": "2024-01-31T10:57:15",
    "request_id": "8bae9fc8-2f9c-4791-911e-237b324b34cc"
  }
}

Cancel a Hotel Booking

Type: hotel_bookings DELETE

Cancel an existing hotel booking.

Request

Endpoint: DELETE /manager/hotel_bookings/{book_name}

Headers:

  • Authorization: ApiKey YOUR_API_KEY

Path parameters:

  • book_name (string, mandatory): TOWeRS booking name/reference

Response

Success response:

{
  "name": "H012B456",
  "status": "CXL",
  "dossier": "D012B456",
  "customerreference": "HOT-20240101-001",
  "__metadata__": {
    "app_server": "ns001tow:6002",
    "timestamp": "2024-01-31T10:58:00",
    "request_id": "8bae9fc8-2f9c-4791-911e-237b324b34cc"
  }
}

Search Hotel Bookings

Type: hotel_bookings GET

Search for hotel bookings by modification date range.

Request

Endpoint: GET /manager/hotel_bookings?modified_from=TIMESTAMP_FROM_YYYYMMDDHHMMSS&modified_to=TIMESTAMP_TO_YYYYMMDDHHMMSS

Headers:

  • Authorization: ApiKey YOUR_API_KEY

Query parameters:

  • modified_from (string, mandatory): Start of modification date range in YYYYMMDDHHmmss format
  • modified_to (string, mandatory): End of modification date range in YYYYMMDDHHmmss format

Request example:

GET /manager/hotel_bookings?modified_from=20240101000000&modified_to=20240131235959
Authorization: ApiKey your-api-key

Response

Success response:

[
  {
    "name": "H012B456",
    "status": "CNF",
    "dossier": "D012B456"
  },
  {
    "name": "H012B457",
    "status": "CNF",
    "dossier": "D012B456"
  }
]

Get Hotel Booking Details

Type: hotel_bookings GET

Retrieve details of a specific hotel booking.

Request

Endpoint: GET /manager/hotel_bookings/{book_name}

Headers:

  • Authorization: ApiKey YOUR_API_KEY

Path parameters:

  • book_name (string, mandatory): TOWeRS booking name/reference

Request example:

GET /manager/hotel_bookings/H012B456
Authorization: ApiKey your-api-key

Response

Success response:

{
  "name": "H012B456",
  "status": "CNF",
  "dossier": "D012B456",
  "__metadata__": {
    "app_server": "ns001tow:6002",
    "timestamp": "2024-01-31T10:56:27",
    "request_id": "8bae9fc8-2f9c-4791-911e-237b324b34cc"
  }
}