TABLE OF CONTENTS


Introduction

ARI API is used by DerbySoft to sync ARI from the supplier and publish it to distributors automatically. DerbySoft does support two ways to sync ARI: With CDS API - DerbySoft does get ARI changes by calling CDS API with a regular schedule and then get ARI to change details accordingly; Without CDS API - DerbySoft will get ARI details on a regular schedule.

In this article, 3 types of ARI API will be interpreted in detail:

  • Daily ARI (/ari/daily/details) - Get daily ARI of one hotel to one distributor.

  • LOS ARI (/ari/los/details) - Get LOS ARI of one hotel to one distributor.

  • CDS (/ari/changes) - Change discover by one hotel to one distributor.



Daily ARI

This is an API for DerbySoft to call the Supplier's system to get the daily ARI of one hotel by date range.

POST /ari/daily/details HTTP/1.1
URL: {{endpoint}}/ari/daily/details
Authorization: 53ac07777cdffac2d53000002d698728ce964432d7167596bc005c5fc
Accept-Encoding: gzip
Content-Encoding: gzip
Content-Type: application/json;charset=utf-8

Request  Specification

Element

Type

Required

Description

Example

header

Object

Y

 /

 /

@sourceId

String

Y

maxLength: 32

id of hotel's source in DerbySoft's system

HHBIJSOPLS

@distributorId

String

Y

maxLength: 32

id of distributor in DerbySoft's system

HOTELBEDS

@version

String

Y

maxLength: 20

version of API

v4

@token

String 

Y

maxLength: 64

A unique id to identify request and response, normally it should be UUID.

18393849028490234

hotelId

String

Y

 /

100001

dateRange

Object

 /

 /

 /

@startDate

String

Y

start date of date range, format with yyyy-MM-dd

2018-01-01

@endDate

String

Y

end date of date range, format with yyyy-MM-dd

2018-01-04


Request Example

{
  "header": {
    "sourceId": "HHBIJSOPLS",
    "distributorId": "HOTELBEDS",
    "version": "v4",
    "token": "18393849028490234"
  },
  "hotelId": "100001",
  "dateRange": {
    "startDate": "2018-01-01",
    "endDate": "2018-01-04"
  }
}

Response Specification

Element

Type

Required

Description

Example

header

Object

Y

 /

 /

@sourceId

String

Y

maxLength: 32

id of hotel's source in DerbySoft's system

HHBIJSOPLS

@distributorId

String

Y

maxLength: 32

id of distributor in DerbySoft's system

HOTELBEDS

@version

String

Y

maxLength: 20

version of API

v4

@token

String 

Y

maxLength: 64

A unique id to identify request and response, normally it should be UUID.

18393849028490234

hotelId

String

Y

 /

100001

dateRange

Object

 

 /

 /

@startDate

String

Y

start date of date range, format with yyyy-MM-dd

2018-01-01

@endDate

String

Y

end date of date range, format with yyyy-MM-dd

2018-01-04

currency

String

Y

currency code[ISO-4217]

USD

dailyAris

Array

Y

daily rate & inventory within the date range

 /

@roomId

String

Y

room id in supplier's system

10000101

@rateId

String

Y

rate id in supplier's system

123456

@mealPlans

Array[string]

N

meal plan of each date

[ "BB", "BB", "BB", "BB" ]

@inventories

Array[integer]

Y

room inventory of each date

[ 9, 0, 9, 9 ]

dailyAris / rates

 /

Y

 /

 /

@type

Enum

Y

Enum: [ OccupancyRate, CommonRate ]

Indicates which rate model to use: OccupancyRate or CommonRate.,

 /

rates / rates

Array[object]

Y

The node disappears if it’s the Common Rate Model.

 /

@adultCount

Integer

N

 /

 /

@childCount

Integer

N

 /

 /

@amountBeforeTax

Array[number]

N

 /

[ 502.19, 502.19, 502.19, 502.19 ]

@amountAfterTax

Array[number]

N

 /

[ 623.23, 623.23, 623.23, 623.23 ]

availStatuses

 /

 /

 /

 /

@close

Array[boolean]

Y

close or not for each date.

[ false, false, false, false ]

@minStayArrival

Array[integer]

N

Minimal length of stay based on checkin for each date, zero means no restriction.

[ 0, 2, 0, 0 ]

@maxStayArrival

Array[integer]

N

Maximal length of stay based on checkin for each date, zero means no restriction.

[ 0, 2, 0, 0 ]

@minStayThrough

Array[integer]

N

Minimal length of stay based on a date through for each date, zero means no restriction.

[ 0, 2, 0, 0 ]

@maxStayThrough

Array[integer]

N

The maximum length of stay based on a date through for each date, zero means no restriction.

[ 0, 2, 0, 0 ]

@minAdvanceDay

Array[integer]

N

Minimal days to book in advance for each date, zero means no restriction.

[ 0, 2, 0, 0 ]

@maxAdvanceDay

Array[integer]

N

Maximum days to book in advance for each date, zero means no restriction.

[ 365, 365, 365, 365 ]

@cta

Array[boolean]

N

close to arrival for each date

[ false, false, false, true ]

@ctd

Array[boolean]

N

close to departure for each date

[ false, false, false, true ]

@fplos

Array[string]

N

Full pattern length of stay to indicate if the stay is available.

[ "1111111", "1001111", "1000001", "0000000" ]

rateChangeIndicators

Array[boolean]

N

rate change indicator of each date.

[ true, false, true, false ]

extensions

Object

N

a common extension object for extra attributes like account, extra setting required by a distributor, etc

 /



Response Example 

Common Rate Success Response (HTTP Status 200)

{
  "header": {
    "sourceId": "HHBIJSOPLS",
    "distributorId": "HOTELBEDS",
    "version": "v4",
    "token": "18393849028490234"
  },
  "hotelId": "100001",
  "dateRange": {
    "startDate": "2018-01-01",
    "endDate": "2018-01-04"
  },
  "currency": "USD",
  "dailyAris": [
    {
      "roomId": "10000101",
      "rateId": "123456",
      "mealPlans": [
        "BB",
        "BB",
        "BB",
        "BB"
      ],
      "inventories": [
        9,
        0,
        9,
        9
      ],
      "rates": {
        "type": "CommonRate",
        "amountAfterTax": [
          623.23,
          623.23,
          623.23,
          623.23
        ]
      },
      "availStatuses": {
        "close": [
          false,
          false,
          false,
          false
        ],
        "minStayArrival": [
          0,
          2,
          0,
          0
        ],
        "maxStayArrival": [
          0,
          2,
          0,
          0
        ],
        "minStayThrough": [
          0,
          2,
          0,
          0
        ],
        "maxStayThrough": [
          0,
          2,
          0,
          0
        ],
        "minAdvanceDay": [
          0,
          2,
          0,
          0
        ],
        "maxAdvanceDay": [
          365,
          365,
          365,
          365
        ],
        "cta": [
          false,
          false,
          false,
          true
        ],
        "ctd": [
          false,
          false,
          false,
          true
        ],
        "fplos": [
          "1111111",
          "1001111",
          "1000001",
          "0000000"
        ]
      },
      "rateChangeIndicators": [
        true,
        false,
        true,
        false
      ],
      "extensions": {
        "key": "value"
      }
    }
  ]
}

Occupancy Rate Success Response (HTTP Status 200)

{
  "header": {
    "sourceId": "HHBIJSOPLS",
    "distributorId": "HOTELBEDS",
    "version": "v4",
    "token": "18393849028490234"
  },
  "hotelId": "100001",
  "dateRange": {
    "startDate": "2018-01-01",
    "endDate": "2018-01-04"
  },
  "currency": "USD",
  "dailyAris": [
    {
      "roomId": "10000101",
      "rateId": "123456",
      "mealPlans": [
        "BB",
        "BB",
        "BB",
        "BB"
      ],
      "inventories": [
        9,
        0,
        9,
        9
      ],
      "rates": {
        "type": "OccupancyRate",
        "rates": [
          {
            "adultCount": 2,
            "childCount": 1,
            "amountBeforeTax": [
              502.19,
              502.19,
              502.19,
              502.19
            ],
            "amountAfterTax": [
              623.23,
              623.23,
              623.23,
              623.23
            ]
          }
        ]
      },
      "availStatuses": {
        "close": [
          false,
          false,
          false,
          false
        ],
        "minStayArrival": [
          0,
          2,
          0,
          0
        ],
        "maxStayArrival": [
          0,
          2,
          0,
          0
        ],
        "minStayThrough": [
          0,
          2,
          0,
          0
        ],
        "maxStayThrough": [
          0,
          2,
          0,
          0
        ],
        "minAdvanceDay": [
          0,
          2,
          0,
          0
        ],
        "maxAdvanceDay": [
          365,
          365,
          365,
          365
        ],
        "cta": [
          false,
          false,
          false,
          true
        ],
        "ctd": [
          false,
          false,
          false,
          true
        ],
        "fplos": [
          "1111111",
          "1001111",
          "1000001",
          "0000000"
        ]
      },
      "rateChangeIndicators": [
        true,
        false,
        true,
        false
      ],
      "extensions": {
        "key": "value"
      }
    }
  ]
}

Error Response (HTTP Status 500)

{
  "errorCode": "InvalidField",
  "errorMessage": "Invalid Message"
}


LOS ARI

This is an API for DerbySoft to call the Supplier's system to get LOS ARI of one hotel by date range.

Notes：
① Full length of stay ARI for each date should be included in the response. Any missing ARI of the length of stay CANNOT be pushed out to the distributor.
② If no rate in the supplier's system, it's recommended to set both of rate and inventory to zero.
③The meal plan is an optional field, as some distributors get this offline instead of through the API.
POST /ari/los/details HTTP/1.1
URL: {{endpoint}}/ari/los/details
Authorization: 53ac07777cdffac2d53000002d698728ce964432d7167596bc005c5fc
Accept-Encoding: gzip
Content-Encoding: gzip
Content-Type: application/json;charset=utf-8

Request  Specification

Element

Type

Required

Description

Example

@sourceId

string

Yes

maxLength: 32

id of hotel's source in DerbySoft's system

HHBIJSOPLS

@distributorId

string

Yes

maxLength: 32

id of distributor in DerbySoft's system

HOTELBEDS

@version

string

Yes

maxLength: 20

version of API

v4

@token

string 

Yes

maxLength: 64

A unique id to identify request and response, normally it should be UUID.

18393849028490234

hotelId

string

Yes

 /

100001

dateRange

object

 /

 /

 /

@startDate

string

Yes

start date of date range, format with yyyy-MM-dd

2018-01-01

@endDate

string

Yes

end date of date range, format with yyyy-MM-dd

2018-01-04


Request Example

{
  "header": {
    "sourceId": "HHBIJSOPLS",
    "distributorId": "HOTELBEDS",
    "version": "v4",
    "token": "18393849028490234"
  },
  "hotelId": "100001",
  "dateRange": {
    "startDate": "2018-01-01",
    "endDate": "2018-01-04"
  }
}

Response Specification

Element

Type

Required

Description

Example

header

Object

Y

 /

 /

@sourceId

String

Y

maxLength: 32

id of hotel's source in DerbySoft's system

HHBIJSOPLS

@distributorId

String

Y

maxLength: 32

id of distributor in DerbySoft's system

HOTELBEDS

@version

String

Y

maxLength: 20

version of API

v4

@token

String 

Y

maxLength: 64

A unique id to identify request and response, normally it should be UUID.

18393849028490234

hotelId

String

Y

 /

100001

dateRange

Object

 

 /

 /

@startDate

String

Y

start date of date range, format with yyyy-MM-dd

2018-01-01

@endDate

String

Y

end date of date range, format with yyyy-MM-dd

2018-01-04

currency

String

Y

currency code[ISO-4217]

USD

losAris

Array

Y

Full length of stay ARI for each date should ALL be included in the response. Any missing ARI of the length of stay CANNOT be pushed out to the distributor.

If no rate in the supplier's system, it's recommended to set both rate and inventory to zero.

The meal plan is an optional field, as some distributors get this offline instead of through the API.

 /

@roomId

String

Y

room id in supplier's system

10000101

@rateId

String

Y

rate id in supplier's system

123456

@los

Integer

Y

length of stay

1

@mealPlans

Array[String]

N

meal plan of each date

[ "BB", "BB", "BB", "BB" ]

@inventories

Array[Integer]

Y

room inventory of each date

[ 9, 0, 9, 9 ]

losAris / rates

 /

Y

 /

 /

@type

Enum 

Y

Enum: [ OccupancyRate, CommonRate ]

indicates which rate model be used: OccupancyRate or CommonRate

 /

rates / rates

Array[Object]

Y

The node disappears if it’s the Common Rate Model.

 /

@adultCount

Integer

N

 /

 /

@childCount

Integer

N

 /

 /

@amountBeforeTax

Array[Number]

N

 /

[ 502.19, 502.19, 502.19, 502.19 ]

@amountAfterTax

Array[Number]

N

 /

[ 623.23, 623.23, 623.23, 623.23 ]

rates / extraChildRates

Object

N

Extra child rate is only used with occupancy rate, max child age must be provided for available hotel product.

 /

@minAge

Integer

Y

Minimal child age is greater than or equal to zero.

0

@maxAge

Integer

Y

Maximum child age is less than or equal to maxChildAge.

2

@amountBeforeTax

Array[Number]

N

 /

[ 40, 40 ]

@amountAfterTax

Array[Number]

N

 /

[ 40, 40 ]

extensions

Object

N

a common extension object for extra attributes like account, extra setting required by a distributor, etc

 /


Response Example

Common Rate Success Response (HTTP Status 200)

{
  "header": {
    "sourceId": "HHBIJSOPLS",
    "distributorId": "HOTELBEDS",
    "version": "v4",
    "token": "18393849028490234"
  },
  "hotelId": "100001",
  "dateRange": {
    "startDate": "2018-01-01",
    "endDate": "2018-01-04"
  },
  "currency": "USD",
  "losAris": [
    {
      "roomId": "10000101",
      "rateId": "123456",
      "los": 1,
      "mealPlans": [
        "BB",
        "BB",
        "BB",
        "BB"
      ],
      "inventories": [
        9,
        0,
        9,
        9
      ],
      "rates": {
        "type": "CommonRate",
        "amountAfterTax": [
          623.23,
          623.23,
          623.23,
          623.23
        ]
      },
      "extensions": {
        "key": "value"
      }
    },
    {
      "roomId": "10000101",
      "rateId": "123456",
      "los": 2,
      "mealPlans": [
        "BB",
        "BB",
        "BB",
        "BB"
      ],
      "inventories": [
        9,
        0,
        9,
        9
      ],
      "rates": {
        "type": "CommonRate",
        "amountBeforeTax": [
          1004.38,
          1004.38,
          1004.38,
          1004.38
        ]
      },
      "extensions": {
        "key": "value"
      }
    }
  ]
}

Occupancy Rate Success Response (HTTP Status 200)

{
  "header": {
    "sourceId": "HHBIJSOPLS",
    "distributorId": "HOTELBEDS",
    "version": "v4",
    "token": "18393849028490234"
  },
  "hotelId": "100001",
  "dateRange": {
    "startDate": "2018-01-01",
    "endDate": "2018-01-04"
  },
  "currency": "USD",
  "losAris": [
    {
      "roomId": "10000101",
      "rateId": "123456",
      "los": 1,
      "mealPlans": [
        "BB",
        "BB",
        "BB",
        "BB"
      ],
      "inventories": [
        9,
        0,
        9,
        9
      ],
      "rates": {
        "type": "OccupancyRate",
        "rates": [
          {
            "adultCount": 2,
            "childCount": 1,
            "amountBeforeTax": [
              502.19,
              502.19,
              502.19,
              502.19
            ],
            "amountAfterTax": [
              623.23,
              623.23,
              623.23,
              623.23
            ]
          }
        ]
      },
      "extensions": {
        "key": "value"
      }
    },
    {
      "roomId": "10000101",
      "rateId": "123456",
      "los": 2,
      "mealPlans": [
        "BB",
        "BB",
        "BB",
        "BB"
      ],
      "inventories": [
        9,
        0,
        9,
        9
      ],
      "rates": {
        "type": "OccupancyRate",
        "rates": [
          {
            "adultCount": 2,
            "childCount": 1,
            "amountBeforeTax": [
              1004.38,
              1004.38,
              1004.38,
              1004.38
            ],
            "amountAfterTax": [
              1246.46,
              1246.46,
              1246.46,
              1246.46
            ]
          }
        ]
      },
      "extensions": {
        "key": "value"
      }
    }
  ]
}



Error Response (HTTP Status 500)

{
  "errorCode": "InvalidField",
  "errorMessage": "Invalid Message"
}


CDS

This is an API for DerbySoft to call the Supplier's system to get daily ARI changes for one hotel. It's an optional function, but it is recommended for the Supplier's system to implement.

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

Request  Specification

Element

Type

Required

Description

Example

header

Object

Y

 /

 /

@sourceId

String

Y

MaxLength: 32

ID of hotel's source in DerbySoft's system.

HHBIJSOPLS

@distributorId

String

Y

MaxLength: 32

The ID of the distributor in DerbySoft's system.

HOTELBEDS

@version

String

Y

MaxLength: 20

The version of API.

v4

@token

String 

Y

MaxLength: 64

A unique id to identify request and response, normally it should be UUID.

18393849028490234

timestamp

String

Y

Timestamp to request changes in UTC timezone.

2017-07-21T17:32:28.000Z

dateRange

Object

 /

 /

 /

@startDate

String

Y

Start date of date range, format with yyyy-MM-dd.

2018-01-01

@endDate

String

Y

End date of date range, format with yyyy-MM-dd.

2018-01-04

hotelIds

Array[String]

Y

Hotel IDs in supplier's system

[ "100001", "100002", "100003" ]



Request Example

{
  "header": {
    "sourceId": "HHBIJSOPLS",
    "distributorId": "HOTELBEDS",
    "version": "v4",
    "token": "18393849028490234"
  },
  "timestamp": "2017-07-21T17:32:28.000Z",
  "dateRange": {
    "startDate": "2018-01-01",
    "endDate": "2018-01-04"
  },
  "hotelIds": [
    "100001",
    "100002",
    "100003"
  ]
}

Response Specification

Element

Type

Required

Description

Example

@sourceId

String

Y

MaxLength: 32

ID of hotel's source in DerbySoft's system

HHBIJSOPLS

@distributorId

String

Y

MaxLength: 32

ID of distributor in DerbySoft's system

GTA

@version

String

Y

MaxLength: 20

Version of API

v4

@token

String 

Y

maxLength: 64

A unique id to identify request and response, normally it should be UUID.

18393849028490234

timestamp

String

Y

Timestamp to request changes in UTC timezone

2017-07-21T17:32:28.000Z

dateRange

Object

 

 

 

@startDate

String

Y

Start date of date range, format with yyyy-MM-dd

2018-01-01

@endDate

String

Y

End date of date range, format with yyyy-MM-dd

2018-01-04

changes

Object

Y

Aate format: yyyy-MM-dd

A changed date array by each hotel

2018-01-01



Response Example

Success Response (HTTP Status 200)

{
  "header": {
    "sourceId": "HHBIJSOPLS",
    "distributorId": "HOTELBEDS",
    "version": "v4",
    "token": "18393849028490234"
  },
  "timestamp": "2017-07-21T17:32:28.000Z",
  "dateRange": {
    "startDate": "2018-01-01",
    "endDate": "2018-01-04"
  },
  "changes": {
    "100001": [
      "2018-01-01",
      "2018-01-02"
    ],
    "100002": [
      "2018-01-02"
    ]
  }
}

Error Response (HTTP Status 500)

{
  "errorCode": "InvalidField",
  "errorMessage": "Invalid Message"
}