Getting Started with Post Booking API

Getting Started with Post Booking API

Introduction

Version 3.2 of the Post-Booking API allows web developers to access the core post-booking methods for Rental Car Manager systems. Note that the methods in this document all refer to post-booking methods, i.e. involving the update of existing bookings. We have separated post-booking functions into its own API with different access requirements, hence the existence of this as a standalone document.

Why two separate APIs?

We have decided to put in place some additional security requirements for the API functions that “pull” existing booking data from the Rental Car Manager System, as opposed to those functions that “push” data in to create new bookings. It seemed logical to separate these as “Booking API” and “Post-Booking API”.

Who is this document for?

This document gives an overview of the steps required to update existing bookings. It is intended for web developers who will be creating booking maintenance pages from scratch, or heavily customising our provided sample booking-update pages. If you are confident in making AJAX or server-side API calls and manipulating returned datasets, for selection and display, then this is for you.

Who is this document not for?

If you are looking for API methods to make a booking, please refer to the current API V3.2 area from RCM’s Developers’ Sandbox area.

If you are not confident in building a post-booking module from scratch, or if you are short on time/resources, we can provide you with a working solution “out of the box”. Please contact RCM Support (support@rentalcarmanager.com) to enquire about our RCM-hosted post-booking update pages, e.g. “Online Check In” or “Kiosk Check In”.

Getting Started

If you are currently our v3.2 API to create new bookings, you may already have the Sandbox & API Credentials as defined below. In this case you will need to contact RCM Support (support@rentalcarmanager.com) to grant access to the Post-Booking API for your API Key.

Developer Sandbox Area

The first thing you need to do is contact Rental Car Manager (RCM) and ask for a Sandbox Login. If you are an agency working with one or more companies, we will need the company to set you up as an Agency within their RCM system first.
The Sandbox Area allows you to download sample code, test all the different API methods, and access and test your Live API Key.

API Credentials

Every API request requires two pieces of information that is unique to you, as an API user.
  1. API Key
    The API key identifies you to RCM. It is used only for the initial Authorisation Request. This forms the “username” for the token request (see “Authorisation Token Request” below for more details)
  2. Shared Secret
    The shared secret forms your password for the initial Authorisation Request. It is essential that this value remains secure, i.e. do not publish it to the browser.
Your API Key along with the Shared Secret will be available to you through the sandbox area: https://sandbox.rentalcarmanager.com/developer/credentials.



If you are an agent that connects to more than one RCM company, you will be given one API Key/Shared Secret pair for each company.

Each API key is linked to an Agent Branch inside RCM, so if you have multiple Agent Branches you wish to use the Agent API for, you will need a key for each branch.

Request Structure - Authorisation

The first call that you make to the API must be to request an Authorisation Token. Once you have received an Authorisation Token, you can use the token value with every subsequent request until the token has reached its expiry time.

Note that tokens are valid for 30 minutes. Once this period has expired you will need to re-authorise by requesting another token. Tokens are valid for multiple API calls.

IMPORTANT: Your shared secret value (which is used as the password) MUST be kept on your server and not sent out to the browser in HTML or javascript. This method call must be made from your server rather than client-side/ajax.

URL

Request Headers

The request body will be in name/value pairs “form” format, so you include the following header value:
  1. Content-Type : application/x-www-form-urlencoded

Request Body

The request body for authorisation is three name/value pairs in “form” format as follows:
username=<api_key>&password=<shared_secret>&grant_type=password

Only the green text above will need substituting for your values. The grant_type=password is fixed text, do not substitute your password here.

Note that if your api_key or your shared_secret contain any non-url-friendly characters (such as ‘&’ or ‘=’) you will need to UrlEncode them first.

Response Structure

The response will be in JSON format as in the following sample:

{"access_token":"GthjLr8m4ovocrNyr7oWWWGbUuC3bnfVAs1Pt2aaPtOk9ys_oeMtidDGN2fzWnTeYDufxO4LFFdg4BKjhBdpihw3mWoxpnhC9QimgwWYNF6aOtP0TdsYUNn59kW7qVMOCsZPq26HLn12XwAYhuxRkUMNre_P3kBLy29DDHDbY-wSIAC-3UZKQb-VsawJKixStJoJ80vM-dW4bqPDsc49zO6MtCTnu51KnJojqx9fOU_dkZvhob3TGtHp98eQ_NHVta6k_-NOyHK1-B5-uMnED7SfXLfkfB6azfUx4TgcDLan_O-qfBAFd7MU_OEfpZlKHfJc8FOukmqEdYlAajprQ-Cnv7_SRGfvgH7urqvpHoKxMHsAHkekC9oGBGwiwPAj70XD8NRAqHmwss-mdiD7keUHHAe6UDqgkaYsdHUEMKmfvNHFO-TeRQBd5HsQIdwf8Z-phRyCjG-4qe7yhHD-0kKNPBuWPFDhwedBGmuayRSu2_AiJCyHRaYimAX0xskX",
"token_type":"bearer",
"expires_in":1799,
"userName":"<your api key>",
".issued":"Fri, 06 Jul 2018 04:33:37 GMT",
".expires":"Fri, 06 Jul 2018 05:03:37 GMT"}

You will need to pull out the value for “access_token” and forward this value with all api requests as described below.

Request Structure - API Method Calls

Once you have gained your authorisation token using the above token call, you can then proceed to call the relevant API method. Each API method call will follow the same structure:

URL

Request Headers

You will need to include the Authorization header with the auth token value that you received in the Authorisation request described previously:
  1. Authorization : Bearer <auth token value> (Note that there is a single space between “Bearer” and the auth token value.)
The request body will need to be in JSON format, so add the header to indicate this:
  1. Content-Type : application/json

Request Body

The request body is a JSON structure, which includes the method name, followed by the name/value pairs of request data. For example:
{"method":"bookinginfo","reservationref":"123456ABCDEFGHIJ"}

Response Structure

The response from each API method call is in JSON format, and is in the general structure below:

{"status":"OK", "error": "", "results":{<results here>},"ms":100,"issues":[]}

status: either “OK” or “ERR”. If “ERR”, then refer to the error field below for more information

error: Empty if no errors encountered, otherwise a description of the error. E.g. “Err - ExtraDriver: Parameter[customerid]. Invalid value [0] expecting valid customerid.”

results: Results from the method call are output here. It could be a few values e.g. {"reservationref":"123456ABCDEFGHIJ"}, or it could be a large series of datasets e.g. the method “bookinginfo” returns a large volume of data including datasets named “bookinginfo”, “customerinfo”, “companyinfo”, “rateinfo”, etc. An empty dataset could be a valid result.

ms: The length of time, in milliseconds, that it took to process the request on RCM’s server. Examining this value if you are getting slow requests may help pinpoint where the delay is.

issues: Any warnings about the API request that didn’t prevent the request from executing. For example, an invalid value for a non-mandatory field, or where the main request succeeded but a secondary function failed.

Testing

You can make test API calls, using our Test API Key for each step of the booking process at https://sandbox.rentalcarmanager.com/developer/apitest_postbooking_3_2




You will need a username and password to be able to log in to the sandbox area and download the sample code. Please contact RCM Support (support@rentalcarmanager.com) if you do not have sandbox credentials.

Datasets Returned - Specs and Format

A listing of the datasets that are returned for each of the methods can be found in our sandbox area. https://sandbox.rentalcarmanager.com/developer/apitest_postbooking_3_2


Checking for Errors

After making an API call, always check the error JSON field first. If this is empty, it is safe to proceed. See the Troubleshooting section for more information.

API Methods and how to use them

The API methods that make up the Post Booking API and the process to use them in is described in the article Post Booking API Process.

Other Useful API Methods

There are other methods which make up this API, which are not part of the post booking process, but which are helpful. They are discussed in more detail in the following article Useful Post Booking API Methods.

Dataset Reference

All of the datasets are defined in our Sandbox area.

Notes:

All fieldnames are lower case! Make sure you use lower case to access the correct field.
Please note that <int_id> is not the same as <int>, <int_id> refers to an integer value that reflects the ID within the RCM system for that particular dataset, and in case this value is 0 that means it is valid for all.

Example:

If we have the next Driver’s age table within the system:



An age_id of 4 equals an age of 25. An age_id of 0 passed to a method means any age, in this case above 18, 19, 20, 25 and 26+

Field types:

Possible field types / options are displayed in the dataset definition as <option1/option2/...>.
<True/False> means we have only 2 possibilities either
  1. True
  2. False
<0/1> means we have only 2 possibilities either
  1. 0
  2. 1
<Sunday/Monday/Tuesday/Wednesday/Thursday/Friday/Saturday> gives the next possibilities
  1. Sunday
  2. Monday
  3. Tuesday
  4. Etc...

Troubleshooting

The first stage of your testing should be to make sure that your key is valid and working. You can do this at https://sandbox.rentalcarmanager.com/developer/postbooking_livetest_3_2. Select your key from the list and click the Test button. You should receive a message saying “The key works!”. If you don’t, or if there is an error returned, then please contact RCM Support (support@rentalcarmanager.com) as it is possible that there is an issue with your key.

Any errors generated from your API calls will be returned in the “errors” field in your response.

For more help with API implementation problems, please contact RCM Support (support@rentalcarmanager.com).

If you are having problems with the API please ensure that you include debugging information in your email.

For server side debugging, include the full request, and details of the response that you are getting from our API server.

For client side debugging, you can use the developer tools in your browser. Here is an example of the network tool in Firefox showing an API call to step 2:



For more information about browser developer tools go to:

    Important Articles


      • Related Articles

      • Getting Started with API V3.2

        Overview Rental Car Manager (RCM) provides a Web API through which you are able to use to build a set of booking steps which you can plug into your website. This API also allows for Agents to have access and search for availability of vehicles and to ...

      • Updating Bookings using Post Booking API

        Overview The Post Booking contains methods which allow you to perform different actions on a booking in RCM. Two of the methods allow you to update the booking information. The difference between the two methods is the information that you are able ...

      • Post Booking API Process

        Overview The RCM Post Booking API allows you to retrieve booking information and also update bookings that already exist within RCM.  The following information cannot be changed on the booking using the Post Booking API: Pickup/drop off locations ...

      • Useful Post Booking API Methods

        Overview As well as the methods which are used in the Post Booking Process, there are other methods which are part of the Post Booking API. They are all discussed below. Get Location Details (locationdetails) The locationdetails method can be used to ...

      • Getting Started with Export API

        Overview Rental Car Manager offers an Export API to export certain datasets. There is a cost to set up these APIs, please contact RCM support (support@rentalcarmanager.com) for more information. Instructions for Use All data can be retrieved by ...