V6RESTful APIs - Consignments

Create a new consignment

(also inbound-outbound warehouse request)

Description

This API interface can be used to create a new consignment in v6. Also, customers can choose to create warehouse orders or not for the new consignment. In order to create warehouse orders for the new consignment, it requires providing the information for highlighted/orange fields in the table in Appendix A, some which are required to create warehouse orders; please read the description to see if which fields are required for creating warehouse orders or not.

Protocol

Url: {domain_name}/v6-api/rest/consignments

Method: POST

Authentication: ApiKey, embedded in the request header. In details, the request header must contain a key value pair for the authorization; in which the key should be “Authorization” and value is “ApiKey {provided-api-key}”; for example “ApiKey rGzwXXurMoOd9ooSrOZ4UO2izAXHfzVU”

JSON request example: to see all fields please have a look at Appendix A

Note: all fields with empty or null value should be removed from the request.

Example creating a new consignment without warehouse order.

{

  "connoteNo": "TOLL123456",

  "connoteDate": "2006-03-11",

  "customer": "CAPH12",

  "senderName": "Eriksson's Explorers",

  "senderAddress1": "970 Greenland Rd",

  "senderSuburb": "GREENLANDS",

  "senderPostcode": "2330",

  "senderState": "NSW",

  "senderContact": "Leif Eriksson",

  "senderPhone": "066 223355",

  "senderEmail": "sender@mail.com",

  "pickupDate": "2017-03-03 14:30",

  "receiverName": "Herjolfsson Fishmongers",

  "receiverAddress1": "812 Vinland Rd",

  "receiverSuburb": "AMERICAN RIVER",

  "receiverPostcode": "5221",

  "receiverState": "SA",

  "receiverContact": "Bjarni Herjolfsson",

  "receiverPhone": "08 9213 0034",

  "receiverEmail": "receiver@mail.com",

  "deliveryDate": "2017-03-12 07:00",

  "totalWeight": "128",

  "totalVolume": "4.15",

  "senderReference": "ABA1345",

  "description": "Maps and paperwork",

  "specialInstructions": "Sail past the coral reef at Bjorn's point",

  "note": "Please ensure all paperwork is kept sealed and waterproof",

  "jobType": "SAILM",

  "serviceType": "REDHOT",

  "vehicleType": "LONGB",

  "docAmount": "0",

  "freightLines": [

{

   "itemCode": "MAP001",

   "scanCodes": [

     "MPAG10293456"

   ],

   "freightCode": "GEN",

   "itemReference": "ABA1345-01/01",

   "description": "Map of vinland",

   "quantity": 1,

   "labels": 20,

   "totalWeight": 10,

   "totalVolume": 0.1,

   "length": 0.1,

   "width": 0.1,

   "height": 0.5,

   "weight": 0.5

},

{

   "itemCode": "DOC8390",

   "scanCodes": [

     "C0000100010001"

   ],

   "freightCode": "FRG",

   "itemReference": "ABA1345-022",

   "description": "Contracts for sale of Vinland",

   "quantity": 1,

   "labels": 5,

   "totalWeight": 2,

   "totalVolume": 0.05

},

{

   "itemCode": "ARCH111",

   "scanCodes": [

     "ARCH12309674093"

   ],

   "freightCode": "FRG",

   "itemReference": "ABA1345-X86",

   "description": "Legal archives 995-1010",

   "quantity": 1,

   "labels": 5,

   "length": 0.5,

   "width": 0.5,

   "height": 0.8,

   "weight": 5.8

}

  ]

}

 

Example JSON creating a new consignment with warehouse order:

{

    "customer": "001",

    "senderEmail": "apisender@gmail.com",

    "receiverEmail": "apireciever@gmail.com",

    "pickupDate": "2017-12-05 12:00",

    "deliveryDate": "2017-12-07 12:01",

    "jobType": "GEN",

    "senderName": "test sender",

    "senderContact": "sender contact",

    "senderPhone": "08080808",

    "senderAddress1": "1 High St",

    "senderSuburb": "TOOWONG",

    "senderPostcode": "4066",

    "senderState": "QLD",

    "senderCountry": "Australia",

    "receiverName": "Test receiver",

    "receiverContact": "receiver contact",

    "receiverPhone": "09090909",

    "receiverAddress1": "100 High St",

    "receiverPostcode": "4066",

    "receiverState": "QLD",

    "receiverSuburb": "TOOWONG",

    "receiverCountry": "Australia",

    "serviceType": "GEN",

    "priorityType": "URGENT",

    "vehicleType": "GEN",

    "dangerousGood": "YES",

    "chargeTo": "SENDER",

    "specialInstruction": "special instruction",

    "description": "doc description",

    "senderReference": "sendRef",

    "warehouseOrderType": "TRANSFER",

    "receiverCode": "BRI",

    "senderCode": "MELB",

    "noConnote": "Y",

    "freightLines": [

    {

    "itemCode": "3KGSUGAR",

    "freightCode": "GENERAL",

    "quantity": 1,

    "totalVolume": 10,

    "totalWeight": 36,

    "modality": "modality 123",

    "batch": "123",

    "airWaybill": "321"

    }

    ]

 

JSON Response:

The response will be returned in JSON format. The following are the list of some common responses.

 

Data uploaded successfully

{

    "httpStatusCode": 201,

    "msg": "Consignment successfully created",

    "data": {"connoteId": 30, /*the newly created connote id */

            "connoteNo": "reference text" /*the reference supplied by the call or generated by v6*/

      }

}


 

Authentication problem: no API key found in the “Authorization” in request header, or wrong API key. This may provide different warning messages.

{

"httpStatusCode": 401,

     "msg": "Unauthorised: Cannot find API key in the header or the API key is not correct. Make sure the API key is embedded in the request header, under Authorization property. E.x. Auhtorization: apikey provided-api-key"

}

 

{

"httpStatusCode": 401,

     "Msg": "Invalid API key"

}

 

Violating data constraints

There are some constraints that submitted data must follow, for example some malformed data errors but not all:

  • Missing required fields, 

  • Unrecognised fields,

  • string value exceed maximum length or shorter than minimum length, 

  • number is smaller than minimum value or larger than maximum value 

  • and some other logical constraints (e.g. pickup date must be before delivery date). 

All the requests breaking the these rules will result in Bad Request (400). The corresponding responses also contain intuitive error messages informing which fields do not follow which rules. To see all rules please see appendix A.

 

The format of bad request response should look like following JSON

{

     "httpStatusCode": 400,

     "msg": "Bad request"

"violations": {

//a list of violations

[

{fieldName} - {error} - {suggestion},

...

]

}

}

Example of Bad Request response:

{

"violations": [

     "connoteDate - wrong format - the date format should be yyyy-MM-dd",

     "receiverSuburb - required field - must exist and must not be empty",

     "receiverEmail - not a well-formed email address",

     "connoteNo - invalid length - number of characters should be less than 40",

     "receiverState - required field - must exist and must not be empty",

     "vehicleType - invalid vehicle type - cannot find vehicle type ATLR1",

     "senderState - invalid state QLD1 - Must be a legitimate State",

     "senderPostcode - invalid postcode 40321 - must be a legitimate Post postcode",

     "senderSuburb - invalid suburb CHERMSIDE1 - Must be a legitimate Post suburb",

     "customer - invalid customer code 0013 - must be an existing customer code",

     "chargeTo - invalid value SENDER1 - must be one of the following values: SENDER, RECEIVER",

],

"httpStatusCode": 400,

"msg": "Bad Request"

}

Retrieve consignment

Description

This API interface is for retrieval of ONE consignment.

Protocol

Url: {domain_name}/v6-api/rest/consignments/{id}

Method: GET
Param: {id}: the consignment id OR consignment reference  (id is preferred).
If consignment reference with special characters is used, those special characters must be %25-url encoded. Example: REF/K becomes: REF%25%2FK
Response: same as data required in creating consignment.

 

Retrieve stage a consignment

Description

This API is for retrieval of stage of ONE consignment.

NOTE: Excessive use of this API can slow down the v6. To receive stage update, v6 has built-in scheduled jobs to send stage update to other systems. Contact the transport company to arrange this.

Protocol

Url: {domain_name}/v6-api/rest/tracking/stages/{ids}

Method: GET

Param:{ids} the consignment Id

ex: GET /v6-api/rest/tracking/stages/1
Response: consignments' stage data .For list of available stage, see below:

Available stage:

NEW: the code just imported into v6

ALO/ACC: allocated and accepted by carriers

PIC: picked up by driver

POP: in-transit

DEL : on board for delivery

POD: final delivery

Example:
{
    "data": [
        {
            "connoteId": 24338,
            "connoteNo": "C24338",
            "stage": "ACC"
         }
    ]
}

Retrieve tracking information of a consignment

(including signature)

Description

This API interface is for retrieval of tracking information of ONE consignment. If there is signature obtained with the event, it is returned in the "signature" property fo the json.

NOTE: Excessive use of this API can slow down the v6. To receive stage update, v6 has built-in scheduled jobs to send stage update to other systems. Contact the transport company to arrange this.

Protocol

Url: {domain_name}/v6-api/rest/tracking/consignments/{ids}

Method: GET

Param:{ids} the consignment Id

ex: GET /v6-api/rest/tracking/consignments/1
Response: consignments' tracking data (events).For list of available events, see below:

Available events:

ScanCode: the code just imported into v6

ScanIn: connote scanned into depots

ScanOut: connote scanned out from depots

BatchSOG, ExpressSOG, : various function to receive signature at final stage

SOGPhoto, TaskPhoto: users opted to use photo  instead of signature at final stage
Example:
{
    "data": [/* an array of connotes events*/
        {
            "connoteId": 24338,
            "connoteNo": "C24338",
            "events": [
                {
                    "item": "BDLE", /*the item code in the consignment details line*/
                    "action": "ScanIn", /*action: in, out...*/
                    "location": "ACACIA RIDGE", /* the location of the depot */
                    "trackingCode": "10352",/*the scan code of the item*/
                    "time": "2012-11-29 02:16:13.000 Australia/Sydney" /* time and timezone*/
                },
                {
                    "item": "BDLE",
                    "action": "ScanOut",
                    "location": "GLADSTONE",
                    "trackingCode": "10352",
                    "time": "2012-11-29 02:18:13.000 Australia/Sydney"
                },
                {
                    "action": "ExpressSOG",
                    "trackingCode": "C24338",
                    "time": "2012-11-29 02:24:13.000 Australia/Sydney"

                    "signature":{

                           "image": //base64 encoded image

                           "signer"://name of signer

                           "comment": //any comment at the time of signing

                     }
                }
            ]
        },
        {
            "connoteId": 24339,
            "connoteNo": "ACR",
            "events": [
                {
                    "item": "BDLE",
                    "action": "ScanIn",
                    "location": "ACACIA RIDGE",
                    "trackingCode": "10353",
                    "time": "2012-11-29 02:40:15.000 Australia/Sydney"
                },
                {
                    "item": "BDLE",
                    "action": "ScanOut",
                    "location": "ACACIA RIDGE",
                    "trackingCode": "10353",
                    "time": "2012-11-29 02:42:15.000 Australia/Sydney"
                },
                {
                    "action": "ExpressSOG",
                    "trackingCode": "C24339",
                    "time": "2012-11-29 02:44:16.000 Australia/Sydney"
                },
                {
                    "item": "BDLE",
                    "action": "ScanIn",
                    "location": "ACACIA RIDGE",
                    "trackingCode": "10353",
                    "time": "2012-11-29 04:26:19.000 Australia/Sydney"
                },
                {
                    "item": "BDLE",
                    "action": "ScanOut",
                    "location": "ACACIA RIDGE",
                    "trackingCode": "10353",
                    "time": "2012-11-29 04:28:19.000 Australia/Sydney"
                }
            ]
        }
    ]
}

Update stage of a consignment

Description

This API is for updating  stage of consignment.

Protocol

Url: {domain_name}/v6-api/rest/consignments/stage

Method: PATCH

Request payload: patch model (json array)

[

{"op":"replace",

"path":"/stage/<<connoteId>>,

"value": //one of the staged value as below,

"reason":// optional message for reason of updating stage

}

]


Available stage, see below:

Available stage:

NEW: the code just imported into v6

ALO/ACC: allocated and accepted by carriers

PIC: picked up by driver

POP: in-transit

DEL : on board for delivery

POD: final delivery

Sending POD to V6

Description

This API interface is for uploading POD files from external systems to V6

NOTE:

Protocol

Url: {domain_name}/v6-api/rest/tracking/consignments/pod

Method: POST

Param:

     connoteId: document id of the connote

     signerName: signer name

     contentType: content-type of the POD (png, jpeg, pdf, tif are supported)

     podDate: must be in yyyy-MM-dd HH:mm (date of signaure, pod)

    stage: POD (set consignment to POD stage)

     rawData: POD data in base64 encoded.

Obtain a quote from V6

Description

This API interface is for retrieving a quote from V6. It is similar to book a consignment but only return the price.

NOTE:

Protocol

Url: {domain_name}/v6-api/rest/quotes/query

Method: POST

Payload sample:

{
    "customer": "001",
    "jobType": "GEN",
    "pickupDate":"2020-02-20 11:30",
    "senderSuburb": "CLAYFIELD ",
    "senderPostcode": "4011",
    "senderState": "QLD",
    "receiverPostcode": "4855",
    "receiverState": "QLD",
    "receiverSuburb": "MAADI",
    "serviceType": "GEN",
    "priorityType": "URGENT",
    "dangerousGood": "YES",
    "freightLines": [
        {
            "itemCode": "TEST-SERIALISED",
            "quantity": 1,
            "totalVolume": 0.125,
            "totalWeight": 0.5
        }
    ]
}

Response sample:

{
    "totalCharge": 15.39,
    "totalGst": 1.4,
    "ratingLines": [
        {
            "rateType": "Q", //quoted
            "chargeBasis": "Items",
            "chargeQty": "1",
            "charge": 0.39,
            "gstAmount": 0.04,
            "items": 1.0,
            "pallets": 0.0,
            "totalCube": 0.0,
            "volume": 0.125,
            "weight": 13.0,
            "breakFlag": "N"//normal, S=stepped
        },
        {
            "rateType": "B",//basic
            "chargeBasis": "Per Consignment",
            "chargeQty": "1",
            "charge": 13.0,
            "gstAmount": 1.18,
            "items": 1.0,
            "pallets": 0.0,
            "totalCube": 0.0,
            "volume": 0.0,
            "weight": 0.0,
            "breakFlag": "N"
        },
        {
            "rateType": "P",//pickup
            "chargeBasis": "Items",
            "chargeQty": "1",
            "charge": 2.0,
            "gstAmount": 0.18,
            "items": 1.0,
            "pallets": 0.0,
            "totalCube": 0.0,
            "volume": 0.0,
            "weight": 0.0,
            "breakFlag": "N"
        }
    ]
}

Print tracking labels from V6

Description

This API is for retrieving the URL to tracking labels generated by V6.

Protocol

Url: {domain_name}/v6-api/rest/tracking/labels/<<consignment>>

Method: GET

Response payload:

{data:{pdf: <<the pdf URL>>}}

client receives this resonse need to download the Pdf following the URL provided in the response. an apikey must be appended to the request in the form of "apikey={provided-api-key}

 

Print routing information on custom tracking labels

Description

This API is for retrieving the routing information so that the client application can produce custom tracking labels with routing information printed on. This helps automating carrier sorting process.
The routing information is provided as "primaryDepot" and "secondaryDepot". Which depot is printed on the custom label depends on agreement between carrier and the client.
The api is capable of supporting non-rest client by returing information as csv if requested (client need to pass the csvSeparator in the query param)

Client should cache the response to minimise the number of calls to this API.

Protocol

Url: {domain_name}/v6-api/rest/tracking/routing?senderSuburb=&senderState=&senderPostcode=&receiverSuburb=&receiverState=&receiverPostcode=&csvSeparator=

Method: GET

Response payload:

if the csvSeparator is supplied (this is for legacy non-rest client without json support), the response is a csv line as:
"<<primaryDepot>>"<csvSeparator>"<<secondaryDepot>>"

if the csvSeparator is omitted, the response is a json:
{
    data:{
        primaryDepot:
        secondaryDepot:
    }
}

PODs scan search from V6

Description

This API is to search for POD (proof of delivery) image scans uploaded to V6 (not to confused with signature obtained by sign-on-glass which can be retrieved by tracking query API)

Protocol

Url: {domain_name}/v6-api/rest/pods/consignments/{id}

Method: GET

Parameters: consignment refNo

Response payload:

{data:

       {"connoteNo":

        "pods":[{"id": 123456, "uploadDate":"2020-05-01 17:00","scanDate":"2020-05-01 15:00"}.....]

       }

}

Client receives this response can download the POD scan (image of the connote scanned), using POD retrieval API

 

PODs scan retrieval from V6

Description

This API is to retrieve a POD  (proof of delivery) image scans uploaded to V6 (not to confused with signature obtained by sign-on-glass which can be retrieved by tracking query API)

Protocol

Url: {domain_name}/v6-api/rest/pods/{podId}

Method: GET

Parameters: podId as received from the search POD api

Appendix A: JSON fields applied for creating new consignment

1/96 Jephson Street, Toowong

Call us free: 1800 666 490

apple.png
android.png
linkedin.png
youtube.png
omnix-logo.png