Generic Bookings API

Insert One or More Bookings

Type: generic_bookings POST

Insert one or more generic service bookings (e.g., transport, entertainment, tours).

Request

Endpoint: POST /manager/generic_bookings

Headers:

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

Request fields:

The request body must contain either a single generic_booking object or a generic_bookings array.

Single Booking Structure

• generic_booking - single booking object (or generic_bookings for array)
• • actor (string, mandatory): TOWeRS customer code on whose behalf the booking will be inserted
• • login (string, mandatory): TOWeRS login of the customer user
• • servicetype (integer, mandatory): Service type code provided by Netstorming
• • suppliercode (integer, mandatory): Supplier code provided by Netstorming
• • city (string, mandatory): TOWeRS code of the city where the booking takes place
• • startdate (string, mandatory): Service start date in YYYY-MM-DD format
• • starttime (string, optional): Service start time in HH:MM format (24-hour)
• • deadline (integer, mandatory): Cancellation deadline in hours before startdate
• • buy (number, mandatory): Purchase price
• • sell (number, mandatory): Selling price to client
• • 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 for the booking
• • status (string, mandatory): Booking status (CNF, PND, CXL, SNT, SND, REJ, WIT, SUP, CLI)
• • paxes (array, mandatory): List of passengers (at least one)
• • • initial (string, mandatory): Passenger first name
• • • surname (string, mandatory): Passenger last name
• • • title (string, optional): Mr, Ms, Miss
• • • leader (boolean, optional): True if this is the leader/reference passenger
• • remarks (array, optional): Special remarks and requests
• • • code (string, mandatory): Remark code in TOWeRS
• • • when (string, mandatory): Creation date in YYYY-MM-DDTHH:MM format
• • • text (string, mandatory): Remark text
• • • visibility (array, mandatory): Who can see the remark (customers, suppliers, owners)
• • • from (string, mandatory): Who created the remark (customers, suppliers, owners)
• • • target (array, mandatory): When remark is visible (availability, booking, voucher)
• • • checked (boolean, mandatory): Whether remark should be notified to owner
• • attachments (array, optional): Files to attach to the booking
• • • title (string, mandatory): Attachment name (must be unique)
• • • url (string, optional): URL to download the attachment (either url or data, not both)
• • • data (string, optional): Base64-encoded file content (either url or data, not both)
• • dossier (string, optional): Container name for grouping multiple bookings
• • configuration (object, optional): Custom configuration fields
• • returnpoints (array, optional): Return point definitions
• • description (string, optional): Additional booking description

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

Request example (single booking):

{
  "generic_booking": {
    "actor": "TESTCUSTOMER",
    "login": "api_user",
    "servicetype": 106,
    "suppliercode": 2,
    "city": "VCEI",
    "startdate": "2024-02-12",
    "starttime": "14:30",
    "deadline": 48,
    "buy": 100.0,
    "sell": 120.0,
    "currency": "EUR",
    "sell_currency": "EUR",
    "customerreference": "ref-20240101-001",
    "supplierreference": "SUP-12345",
    "status": "CNF",
    "paxes": [
      {
        "initial": "Mario",
        "surname": "Rossi",
        "title": "Mr",
        "leader": true
      },
      {
        "initial": "Anna",
        "surname": "Bianchi",
        "title": "Ms",
        "leader": false
      }
    ],
    "remarks": [
      {
        "code": null,
        "when": "2024-01-31T10:56:00",
        "text": "Special request for non-smoking room",
        "visibility": ["customers", "suppliers"],
        "from": "customers",
        "target": ["booking"],
        "checked": true
      }
    ],
    "attachments": [
      {
        "title": "contract-front",
        "url": "https://example.com/contract.pdf"
      }
    ]
  }
}

Request example (multiple bookings in same container):

{
  "generic_bookings": [
    {
      "actor": "TESTCUSTOMER",
      "login": "api_user",
      "servicetype": 106,
      "suppliercode": 2,
      "city": "VCEI",
      "startdate": "2024-02-12",
      "deadline": 48,
      "buy": 100.0,
      "sell": 120.0,
      "currency": "EUR",
      "sell_currency": "EUR",
      "customerreference": "ref-001",
      "supplierreference": "SUP-001",
      "status": "CNF",
      "paxes": [{"initial": "Mario", "surname": "Rossi", "leader": true}]
    },
    {
      "actor": "TESTCUSTOMER",
      "login": "api_user",
      "servicetype": 106,
      "suppliercode": 2,
      "city": "ROME",
      "startdate": "2024-02-13",
      "deadline": 48,
      "buy": 80.0,
      "sell": 100.0,
      "currency": "EUR",
      "sell_currency": "EUR",
      "customerreference": "ref-002",
      "supplierreference": "SUP-002",
      "status": "CNF",
      "dossier": "D012A923",
      "paxes": [{"initial": "Mario", "surname": "Rossi", "leader": true}]
    }
  ]
}

Response

Success response (single booking):

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

Success response (multiple bookings):

{
  "results": [
    {
      "name": "B012A924",
      "status": "CNF",
      "dossier": "D012A923",
      "customerreference": "ref-001"
    },
    {
      "name": "B012A925",
      "status": "CNF",
      "dossier": "D012A923",
      "customerreference": "ref-002"
    }
  ],
  "__metadata__": {
    "app_server": "ns001tow:6002",
    "timestamp": "2024-01-31T10:56:27",
    "request_id": "8bae9fc8-2f9c-4791-911e-237b324b34cc"
  }
}

Error response:

{
  "error": "Cannot parse request",
  "debug_info": "Missing mandatory field: status",
  "__metadata__": {
    "app_server": "ns001tow:6002",
    "timestamp": "2024-01-31T10:56:27",
    "request_id": "8bae9fc8-2f9c-4791-911e-237b324b34cc"
  }
}

Modify a Booking

Type: generic_bookings PUT

Modify an existing generic service booking.

Request

Endpoint: PUT /manager/generic_bookings/{book_name}

Headers:

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

Path parameters:

• book_name (string, mandatory): TOWeRS booking name/reference as returned in the insert response

Request body fields:

• generic_booking - object containing only the fields to be modified
• • startdate (string, optional): New start date in YYYY-MM-DD format
• • starttime (string, optional): New start time in HH:MM format
• • deadline (integer, optional): New cancellation deadline in hours
• • buy (number, optional): New purchase price
• • sell (number, optional): New selling price
• • currency (string, optional): New purchase currency
• • sell_currency (string, optional): New selling currency
• • status (string, optional): New booking status
• • paxes (array, optional): Updated passenger list
• • remarks (array, optional): Updated remarks
• • attachments (array, optional): Additional attachments

Note: actor and login fields are ignored if provided; they are recovered from the stored booking context.

Request example:

{
  "generic_booking": {
    "startdate": "2024-02-13",
    "status": "CNF",
    "sell": 125.0,
    "remarks": [
      {
        "code": null,
        "when": "2024-02-01T15:30:00",
        "text": "Updated special requests",
        "visibility": ["customers"],
        "from": "customers",
        "target": ["booking"],
        "checked": true
      }
    ]
  }
}

Response

Success response:

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

Error response (booking not found):

{
  "error": "Booking does not exists or does not belong to the endpoint requested",
  "debug_info": "",
  "__metadata__": {
    "app_server": "ns001tow:6002",
    "timestamp": "2024-01-31T10:57:15",
    "request_id": "8bae9fc8-2f9c-4791-911e-237b324b34cc"
  }
}

Cancel a Booking

Type: generic_bookings DELETE

Cancel an existing generic service booking.

Request

Endpoint: DELETE /manager/generic_bookings/{book_name}

Headers:

• Authorization: ApiKey YOUR_API_KEY

Path parameters:

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

Response

Success response:

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

Search Bookings

Type: generic_bookings GET

Search for generic service bookings by modification date range.

Request

Endpoint: GET /manager/generic_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/generic_bookings?modified_from=20240101000000&modified_to=20240131235959
Authorization: ApiKey your-api-key

Response

Success response:

[
  {
    "name": "B012A923",
    "status": "CNF",
    "dossier": "D012A923"
  },
  {
    "name": "B012A924",
    "status": "CNF",
    "dossier": "D012A923"
  }
]

Get Booking Details

Type: generic_bookings GET

Retrieve details of a specific generic service booking.

Request

Endpoint: GET /manager/generic_bookings/{book_name}

Headers:

• Authorization: ApiKey YOUR_API_KEY

Path parameters:

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

Request example:

GET /manager/generic_bookings/B012A923
Authorization: ApiKey your-api-key

Response

Success response:

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