TABLE OF CONTENTS

Query Reservation List API

The Query Reservation List API allows distributors to retrieve a list of reservations from both DerbySoft's system and the hotel supplier's system. The query is based on a specified date range of the reservation’s last modified date, ensuring that only relevant and updated reservation information is fetched. This API is essential for managing and tracking reservations over time, providing distributors with up-to-date insights into their bookings. To ensure proper functionality, both DerbySoft and the hotel supplier must implement this API. By doing so, distributors can query reservations across both systems, offering a comprehensive view of reservation statuses and updates, which is crucial for effective booking management.

POST /reservations HTTP/1.1
URL: {BookingUSB-Endpoint}/reservations
Authorization: 53ac07777cdffac2d53000002d698728ce964432d7167596bc005c5fc
Accept-Encoding: gzip
Content-Encoding: gzip
Content-Type: application/json;charset=utf-8

Reservation List Request Schema

Request

Level

Field Name

Data Type

Required

Description

Example

1

header

object

Y

 /

 

2

@supplierId

string

Y

The ID of the hotel supplier in DerbySoft's system

Max Length: 32

HILTON

2

@distributorId

string

Y

The ID of the distributor in DerbySoft's system

MaxLength: 32

GTA

2

@version

string

Y

Max Length: 20

Version of API

v4

2

@token

string

Y

Max Length: 64

A unique identifier is used for requests and responses, typically a UUID. Note that this is an echo token, not an access token.

18393849028490234

1

dateRange

object

Y

Date range of last modified date of reservation

 /

2

@startDate

string

Y

Start date of date range expressed as YYYY-MM-DD

2028-01-01

2

@endDate

string

Y

End date of the date range expressed as YYYY-MM-DD

2028-01-04

1

hotelId

string

N

Supplier hotel ID in DerbySoft's system

GATHI

Reservation List Request Example

Reservation List Request Example
{
  "header": {
    "supplierId": "HILTON",
    "distributorId": "GTA",
    "version": "v4",
    "token": "18393849028490234"
  },
  "dateRange": {
    "startDate": "2028-01-01",
    "endDate": "2028-01-04"
  },
  "hotelId": "GATHI"
}

Reservation List Response Schema

Response

Level

Field Name

Data Type

Required

Description

Example

1

header

object

Y

 /

 /

2

@supplierId

string

Y

The ID of hotel supplier in DerbySoft's system

Max Length: 32

HILTON

2

@distributorId

string

Y

The ID of the distributor in DerbySoft's system

MaxLength: 32

GTA

2

@version

string

Y

Max Length: 20

Version of API

v4

2

@token

string

Y

A unique identifier is used for requests and responses, typically a UUID. MaxLength: 64

Note that this is an echo token, not an access token.

18393849028490234

1

reservations

array[object]

N

 /

 /

2

reservationIds

object

N

 /

 /

2

@distributorResId

string

Y

Distributor's reservation ID. Distributors should keep the ID unique on their system to avoid any potential issues caused by duplicate reservation IDs.

C2084DFL0

2

@derbyResId

string

Y

Reservation ID in Derbysoft's system, this is a unique ID as DerbySoft would be splitting the reservation.

D15F893D34DF

2

@supplierResId

string

Y

Reservation ID in supplier's system

89389494

1

@iata

string

N

 /

 /

1

@hotelId

string

Y

Hotel IDs provided by hotel suppliers, only the following characters are allowed.

1. Digits (0-9) 

2. Uppercase letters (A-Z) 

3. Hyphen ('-')

100001

GATHI

00016

PEP-B3T2

B8W7

1

stayRange

object

Y

 /

 /

2

@checkin

string

Y

Check in date expressed YYYY-MM-DD

2028-01-01

2

@checkout

string

Y

Check out date expressed YYYY-MM-DD

2028-01-04

1

roomCriteria

object

Y

 /

 

2

@roomCount

integer

Y

Total room count per request

 

2

@adultCount

integer

Y

Adult count per room

 

2

@childCount

integer

N

Child count per room

 

2

@childAges

array

N

For child ages for each child, array size MUST be the same as the child count.

 [ 4, 8 ]

2connectionTypeenumNo

Enum: [Exchange, Standard]

Indicates the connection type of product. 

Notes: If the field is omitted, it means the Connection Type is Standard.

Exchange
2

total

object

Y

 /

 /

3

@amountBeforeTax

number

C

ABT, mandatory if AAT is not provided

640

3

@amountAfterTax

number

C

AAT, mandatory if ABT is not provided

700

2commissionobjectNNotes: If the connection type is "Exchange" and "Retail" Rate Model, the node will be visible; otherwise, it will not appear./
3@valuenumberY/10
3@typeenumY

Commission type

Enum: [Percent, Amount]

Percent
2suggestedTotalPriceobjectNNotes: If the connection type is "Exchange" and "Net" Rate Model, the node will be visible; otherwise, it will not appear./
3@amountBeforeTaxnumberN/600
3@amountAfterTaxnumberN/700
2

@status

enum

Y

Enum: [ Confirmed, Modified, Cancelled ]

Status of reservation

 /

2

cancellationId

string

N

Cancel confirmation number in supplier's system

C89389494

2

@result

enum

Y

Enum: [ Successful, Failed, Processing ]

Status of the reservation to send to suppliers.

 /

2

failCause

object

C

Note: If the reservation fails, the node will be visible; otherwise, it will not appear.

 /

3

@errorCode

string

C

Refer to Error Code Appendix

InvalidField

3

@supplierErrorCode

string

C

Error code from the supplier's system

InvalidField

3

@errorMessage

string

C

Error message

Invalid Message

Reservation List Response Example

Success Response (HTTP Status 200) 
{
  "header": {
    "supplierId": "HILTON",
    "distributorId": "GTA",
    "version": "v4",
    "token": "18393849028490234"
  },
  "reservations": [
    {
      "reservationIds": {
        "distributorResId": "C2084DFL0",
        "derbyResId": "D15F893D34DF",
        "supplierResId": "89389494"
      },
      "iata": "string",
      "hotelId": "GATHI",
      "stayRange": {
        "checkin": "2028-01-01",
        "checkout": "2028-01-04"
      },
      "roomCriteria": {
        "roomCount": 2,
        "adultCount": 1,
        "childCount": 2,
        "childAges": [
          4,
          8
        ]
      },
      "total": {
        "amountBeforeTax": 640,
        "amountAfterTax": 700
      },
      "status": "Confirmed",
      "cancellationId": "C89389494",
      "result": "Successful",
      "failCause": {
        "errorCode": "string",
        "supplierErrorCode": "string",
        "errorMessage": "string"
      }
    }
  ]
}

Successful Response from Exchange Connection and Retail Rate Model(HTTP Status 200)
{
  "header": {
    "supplierId": "HILTON",
    "distributorId": "GTA",
    "version": "v4",
    "token": "18393849028490234"
  },
  "reservations": [
    {
      "reservationIds": {
        "distributorResId": "C2084DFL0",
        "derbyResId": "D15F893D34DF",
        "supplierResId": "89389494"
      },
      "iata": "string",
      "hotelId": "GATHI",
      "stayRange": {
        "checkin": "2028-01-01",
        "checkout": "2028-01-04"
      },
      "contactPerson": {
        "firstName": "James",
        "lastName": "Bond",
        "email": "007@james.com",
        "phone": "string",
        "address": "string"
      },
      "roomCriteria": {
        "roomCount": 2,
        "adultCount": 1,
        "childCount": 2,
        "childAges": [
          4,
          8
        ]
      },
      "connectionType": "Exchange",
      "total": {
        "amountBeforeTax": 640,
        "amountAfterTax": 700
      },
      "commission": {
        "value": 10,
        "type": "Percent"
      },
      "status": "Confirmed",
      "cancellationId": "C89389494",
      "result": "Successful"
    }
  ]
}

Successful Response from Exchange Connection and Net Rate Model(HTTP Status 200)
{
  "header": {
    "supplierId": "HILTON",
    "distributorId": "GTA",
    "version": "v4",
    "token": "18393849028490234"
  },
  "reservations": [
    {
      "reservationIds": {
        "distributorResId": "C2084DFL0",
        "derbyResId": "D15F893D34DF",
        "supplierResId": "89389494"
      },
      "iata": "string",
      "hotelId": "GATHI",
      "stayRange": {
        "checkin": "2028-01-01",
        "checkout": "2028-01-04"
      },
      "contactPerson": {
        "firstName": "James",
        "lastName": "Bond",
        "email": "007@james.com",
        "phone": "string",
        "address": "string"
      },
      "roomCriteria": {
        "roomCount": 2,
        "adultCount": 1,
        "childCount": 2,
        "childAges": [
          4,
          8
        ]
      },
      "connectionType": "Exchange",
      "total": {
        "amountBeforeTax": 640,
        "amountAfterTax": 700
      },
      "suggestedTotalPrice": {
        "amountBeforeTax": 600,
        "amountAfterTax": 700
      },
      "status": "Confirmed",
      "cancellationId": "C89389494",
      "result": "Successful"
    }
  ]
}

Error Response (HTTP Status 403)
{
  "error": "Key not authorized"
}

Error Response (HTTP Status 500) 
{
  "errorCode": "InvalidField",
  "errorMessage": "Invalid Message"
}