PrixCar Transport Bookings Web Services API

Working with the Bookings API

The Booking API allows clients to create applications and automatically issue requests for vehicle movements.

The Booking API is intended to work in conjunction with the Quotes API. A booking cannot be created without a corresponding Quote.

The Booking API can be accessed by any third-party system such as industry partners, web applications or third-party applications.

The JSON Booking Object

The following is an example representation of a single booking proposal sent to the PrixCar Transport API, represented in JSON (and reformatted to make it easier to read):

{
    "QuoteRef": "QMI36139153",
    "TransportType": 3,
    "PickupLocation": {
        "StreetAddress1": "123 Southern Street",
        "StreetAddress2": "",
        "Contact": {
            "Title": "Mr",
            "FirstName": "Fred",
            "LastName": "Smith",
            "PhoneNo": "0394332321"
        },
        "PickupDate": "2018-04-06",
        "Instructions": "Please arrange to pick up my car in the morning."
    },
    "DeliveryLocation": {
        "StreetAddress1": "Unit 1",
        "StreetAddress2": "23 Fredrick Ave",
        "Contact": {
            "Title": "Mr",
            "FirstName": "Fred",
            "LastName": "Smith",
            "PhoneNo": "0394332321"
        },
        "Instructions": "Delivery is around the back of the nominated address"
    },
    "VehicleRow": [
        {
            "Make": "Asia Motors",
            "Model": "Rocsta",
            "VehicleID": "ABC123",
            "Colour": "Blue"
        },
        {
            "Make": "Ford",
            "Model": "Falcon",
            "VehicleID": "RFG456",
            "Colour": "Red"
        }
    ],
    "PayerDetails": {
        "Account": "FRE01",
        "Title": "Mr",
        "FirstName": "Fred",
        "LastName": "Smith",
        "BusinessName": "Business Inc",
        "PhoneNo": "0394332321",
        "Email": "fred.smith@email.com",
        "PaymentReference": "PO: 1234"
    }
}

Explanation of the Booking Object

QuoteRef Attribute

    "QuoteRef": "QMI36139153",

The Quoteref attribute refers to the QuoteId received when the original Quote was obtained.

TransportType

    "TransportType": 3,

The TransportType attribute is an integer value obtained from one of the transport types obtained during the quoting process.

The TransportType specified at the time of booking will determine how pickup and delivery location segments are interpreted. (See below for specific details.)

PickupLocation Segment

    "PickupLocation": {
        "StreetAddress1": "123 Southern Street",
        "StreetAddress2": "",
        "Contact": {
            "Title": "Mr",
            "FirstName": "Fred",
            "LastName": "Smith",
            "PhoneNo": "0394332321"
        },
        "PickupDate": "2014-07-21",
        "Instructions": "Please arrange to pick up my car in the morning."
    }

The StreetAddress1 attribute contains the first line of the pickup address. PO Boxes and Mail Drops are not allowed.

The StreetAddress2 attribute contains the second line of the pickup address.

The PickupDate attribute refers to the desired pickup date using the format “YYYY-MM-DD” (E.g. 2014-07-21)

The Instructions attribute contains any special notices and instructions at the time of pickup.

It is assumed that the country of pickup is Australia.

The TransportType attribute specified at the time of booking will determine how pickup and delivery location segments are interpreted. Interpretation is as follows:

  • If TransportType is either a 0 or 1, the PickupLocation segment is ignored.
  • If TransportType is 2 or 3, then StreetAddress1 and StreetAddress2 will be used as the pickup addresses.

Suburb, State and Postcode will be retrieve from the original quote.

DeliveryLocation Segment

    "DeliveryLocation": {
        "StreetAddress1": "Unit 1",
        "StreetAddress2": "23 Fredrick Ave,
        "Contact": {
            "Title": "Mr",
            "FirstName": "Fred",
            "LastName": "Smith",
            "PhoneNo": "0394332321",
        },
        "Instructions": "Delivery is around the back of the nominated address",
    },

The StreetAddress1 attribute contains the first line of the delivery address. PO Boxes and Mail Drops are not allowed.

The StreetAddress2 attribute contains the second line of the delivery address.

It is assumed that the country of delivery is Australia.

The TransportType attribute specified at the time of booking will determine how pickup and delivery location segments are interpreted. It is interpreted as follows:

  • If TransportType is either a 0 or 2, the DeliveryLocation segment is ignored.
  • If TransportType is 1 or 3, then StreetAddress1 and StreetAddress2 will be used as the pickup addresses.

Suburb, State and Postcode will be retrieved from the original quote.

Why can we not change the Suburb, State or Postcode during Booking?

The original quote was derived by passing the information entered through a series of complex calculations. Suburb, State and Postcodes, just like the vehicles specified, play an important part in the calculation and our ability to guarantee each of the prices.

VehicleRows Segment

The VehicleRows segment comprises an array vehicles to be transported and must match those for which the quote was originally created.

    "VehicleRow": [
        {
            "Make": "Asia Motors",
            "Model": "Rocsta",
            "VehicleID": "ABC123",
            "Colour": "Blue",
        },
        {
            "Make": "Ford",
            "Model": "Falcon",
            "VehicleID": "RFG456",
            "Colour": "Red"
        }
    ]

Each array element contains a combination of Vehicle Make & Model, VIN/Rego and Colour.

The Vehicle Make and Vehicle Model attributes must refer to the same vehicle makes and models found in the VehicleRows segment of the Quote

The VehcileID attribute refers to a unique identification for the vehicle. It is recommended to use either a Vehicle Identification Number or local registration number for the vehicle.

The PrixCar Transport Booking API will not accept booking request for partial vehicle lists. I.e. if three vehicles were quoted, the Booking API expects three vehicles to be booked.

In the example segment above, the VehicleRow array contains two vehicles. A blue Asia Motors Rocsta (with Registration ABC123) and a red Ford Falcon (with Registration RFG456).

PayerDetails Segment

    "PayerDetails": {
        "Account": "FRE101",
        "Title": "Mr",
        "FirstName": "Fred",
        "LastName": "Smith",
        "PhoneNo": "0394332321",
        "Email": "fred.smith@email.com",
        "TotalPaymentAmt": "1024",
        "PaymentReference": "PO: 1234"
    }

The PayerDetails attribute segment contains the necessary contact details for issuing Tax Invoices and receipts.

The tax invoice will be sent to the contact details provided in the PayerDetails. We will use the address details we have on file.

The Account attribute is the PrixCar supplied account number that specifies you are authorised to make a booking through the PrixCar Transport API. This is a required field.

The Account number is validated in real-time and if it is invalid, will cause the entire booking request to fail.

The Title, FirstName, LastName, PhoneNo and Email attributes refer to the Payer’s first name, last name, contact number and email address respectively.

The PaymentReference attribute refers to your reference for the booking. It can be a Purchase Order number or other reference that can be easily traceable.

Working with Bookings

Create Booking

Creates a new booking record from the data passed as HTTP POST variables.

Usage

http://appname/WEBAPI/create_booking?APIKey=ff6f3bdb-e1d8-4dfb-bd78-9aa838bed114&UserName=prixcar

Required HTTP POST Parameters

Header-level
NameTypeDefinition
booking-request-detailsstringA JSON object as per the JSON Booking Request Object

The system will perform a validation across all fields in the Booking Request Object. If the Booking Request Object is successfully validated, an attempt will be made to create the booking.

A JSON Object will be returned as a response.

Booking API Responses

Several responses are possible from the Booking API. The responses are defined below.

Error Responses

If an error is detected, the Booking API will return an Error response in the following format.

{
   "Error":{
      "Reason": "Authentication Error",
      "Action": "Please call PrixCar Technical Support on 1300 660 616"
   }
}

The Reason attribute provides a brief explanation of the error.

The Action attribute provide a possible path to resolution of the problem.

The system will stop processing the booking request is an error is encountered.

Booking Success Response

If a booking request is accepted without errors, the Booking API will return a Success response in the following format.

{
   "Success":{
      "Reference": "QMI36139153",
      "Date": "2014-07-24T11:40:32.368+10:00"
   }
}