TABLE OF CONTENTS

• Overview
  • Property Creation sequence chart
  • Product Creation sequence chart
  • ARI sequence chart
  • Channel Setting sequence chart
  • Reservation sequence chart
• Security & Authentication
• JSON Service
• Message Header
• Property Connector Endpoints
• Outbound IP Addresses
• Success & Failure
  • Error Handling
  • Error Response

Overview

Property Connector APIs allow PMS Company to integrate DerbySoft Property Connector for data exchange on ARI, Reservation, and Stay Record as well as the creation of Property, RatePlan, and Roomtype. PMS company can step into DerbySoft connectivity platform through the PMS Integration API to empower the PMS distribution capability.

DerbySoft designed the PUSH/PUSH model for ARI & Reservation data exchange between PMS and DerbySoft Property Connector. Please refer to the diagram below:

1. PMS push Property data to Derbysoft to create the Property in Property Connector.
2. PMS push Rateplan&Roomtype data to Derbysoft to create the product in PropertyConnector.
3. PMS push ARI to DerbySoft, and DerbySoft process the data into the database in the async model.
4. PMS push channel setting data to Derbysoft to create or update the settings of the specific channel in PropertyConnector.
5. PMS push channel mapping data to Derbysoft to create or update the mapping between channel product and hotel product in PropertyConnector.
6. DerbySoft push reservations from distributors to PMS and deliver back the confirmation or errors to distributors directly.
7. PMS push Stay Record to Derbysoft, Derbysoft generates report accordingly.

Property Creation sequence chart

Product Creation sequence chart

ARI sequence chart

Channel Setting sequence chart

Reservation sequence chart

Security & Authentication

DerbySoft Property Connector process the access authentication with Bearer Token. Our system validates every message while calling our API service. 

Please contact pms.service@derbysoft.net to acquire Client ID and Client Secret while integrating to our system, then call Token Obtain&Refresh API to get bearer token. Here is an exmaple to explain how to access our APIs. 

POST /pcapigateway/tunnel/{accountId}/rate HTTP/1.1
Authorization: Bearer 53ac07777cdffac2d53000002d698728ce964432d7167596bc005c5fc
Accept-Encoding: gzip
Content-Type: application/json;charset=utf-8

Important: 
Our system can only support TLSv1.2 and above via HTTPS, please make sure your application can be compatible with it.

JSON Service

DerbySoft PMS Integration API is well designed under JSON restful API, which is following the specification of RFC4627. Please add “Content-Type: application/json;charset=utf-8“ in your HTTP request header to ensure our application can parse your request correctly.

Important:
UTF-8 is the only charset supported by us for characters encoding & decoding, which ensures your application can accept some non-Latin characters like guest name, comments, etc.

Message Header

There is a common message header in each request and response to trace the transaction between PMS and DerbySoft Property Connector. DerbySoft records them in the log system for troubleshooting. It’s recommended that your PMS system can also log them and provide them to us for issue investigation in the future.

Property Connector Endpoints

Outbound IP Addresses

Please find the below IP addresses if you have to set up the IP whitelist: 

Success & Failure

DerbySoft Property Connector follows HTTP status code standard to indicate successful response or failure response. HTTP status code 200 means the requests are well processed in the servers, HTTP status code 500 means there is an error occurred. Please follow this standard as it’s useful to integrate with some third-party monitoring system and tracing system.

Error Handling

It is expected that your PMS has a robust error handling process in place. This includes a queuing mechanism and a robust retry strategy. An error response should contain a short description of the error to assist our support teams.

{
  "header": {
    "echoToken": "f67ade36-0b83-49cf-bfb1-b932c45b7d34",
    "timeStamp": "2018-06-27T17:09:04.674Z",
    "version": "1.00"
  },
  "errorCode": "InvalidField",
  "errorMessage": "Invalid token"
}

Error Response

The common error response when there is a business error occurred.

Note:
The error response always be with the message header, and only appears in the HTTP status code 500.