V6RESTful APIs - Consignments

Create consignment or warehouse request

This API is used to create a new consignment in v6 or an warehouse request (inbound/outbound/transfer request).

Since: 1.0

POST /v6-api/rest/consignments

Request payload: refer to Appendix A.

For fixed values (item codes, job types, service types, priority types, vehicle types, freightCode), refer to master data API

Please note: the ???? needs to be filled with appropriate value from master data API

 

Example creating a new consignment without warehouse order.

{

  "connoteNo": "123456",

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

  "customer": "?????????????",

  "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": "?????????????",

  "serviceType": "?????????????",

  "vehicleType": "?????????????",

  "docAmount": "0",

  "freightLines": [

{

   "itemCode": "MAP001",

   "scanCodes": [

     "MPAG10293456"

   ],

   "freightCode": "?????????????",

   "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": "?????????????",

   "itemReference": "ABA1345-022",

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

   "quantity": 1,

   "labels": 5,

   "totalWeight": 2,

   "totalVolume": 0.05

},

{

   "itemCode": "ARCH111",

   "scanCodes": [

     "ARCH12309674093"

   ],

   "freightCode": "?????????????",

   "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": "?????????????",

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

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

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

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

    "jobType": "?????????????",

    "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": "?????????????",

    "priorityType": "URGENT",

    "vehicleType": "?????????????",

    "dangerousGood": "YES",

    "chargeTo": "SENDER",

    "specialInstruction": "special instruction",

    "description": "doc description",

    "senderReference": "sendRef",

    "warehouseOrderType": "TRANSFER",

    "receiverCode": "BRI",

    "senderCode": "MELB",

    "noConnote": "Y",

    "freightLines": [

    {

    "itemCode": "3KGSUGAR",

    "freightCode": "?????????????",

    "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"

}

Update consignment

This API is to update ONE consignment.

Since: 1.0

PUT /v6-api/rest/consignments/{id}

Param: {id}: the consignment id returned by the create consignment API,

Payload: same as create consignment API.

Retrieve consignment

This API  is for retrieval of ONE consignment.

Since: 1.0

GET /v6-api/rest/consignments/{id}

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 of a consignment

This API is for retrieval of stage of ONE consignment.

NOTE: NOTE: keep this API access rate at every 10+ minutes is recommended for performance reason.

Since: 20200300

GET /v6-api/rest/tracking/stages/{id}

Param:{id} the consignment Id OR reference number
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)

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: keep this API access rate at every 10+ minutes is recommended for performance reason.

Since: 20200300

GET /v6-api/rest/tracking/consignments/{id}

 

Param:{id} the consignment Id or reference number


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

This API is for updating  stage of consignment by a client application.

Since: 20200300

PATCH /v6-api/rest/consignments/stage

 

Request payload: patch model (json array)

[

 {"op":"replace",

 "path":"/stage/VXGZ2000", //VXGZ200:connote reference number

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

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

 }

]

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

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

Since: 20200300

POST /v6-api/rest/consignments/pod

Request payload:

{

     connoteNo: //reference No 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 signature, pod)

     stage: POD (set consignment to POD stage)

     rawData: POD image data in base64 encoded.

}

Update driver job times to v6

This API is to update driver times of a job to v6.

 

Since: 20200812

POST /v6-api/rest/tracking/jobtimes/{id}

Param:{id} the consignment Id OR reference number


Payload: (time is in yyyy-MM-dd HH:mm:ss timezone)

{

 "timeArrivedDelivery":"2017-11-24 15:00:00 Australia/Sydney",

  "timeDelivered":"2017-11-24 15:03:00 Australia/Sydney",

  "comment":"" //optional

}

supported timing fields:

timeArrivedPickup,timePickedUp,timeArrivedDelivery,timeDelivered

Obtain a quote from V6

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

Since: 20200300

POST /v6-api/rest/quotes/query

Payload sample:

{
    "customer": "
????",//client application account code with the transport company
    "jobType": "
???????",
    "pickupDate":"2020-02-20 11:30",
    "senderSuburb": "CLAYFIELD ",
    "senderPostcode": "4011",
    "senderState": "QLD",
    "receiverPostcode": "4855",
    "receiverState": "QLD",
    "receiverSuburb": "MAADI",
    "serviceType": "
????????",
    "priorityType": "
???????",
    "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"
        }
    ],

     "expiryDate":"yyyy-mm-dd" //since 20200820
}

 

Retrieve delivery estimate 

This API is for retrieving delivery estimate from v6

Since: 20200300

GET /v6-api/rest/util/delivery/estimate

Params on the URL

 pickupDate: <<yyyy-mm-dd>>

 frSuburb,frPostCode,frState: from Suburb,postcode, state

 toSuburb,toPostCode,toState: destination suburb, postcode, state,

 jobType,serviceType: job type and service type for the consignment

 state: the state in which the holiday is taken into account (usually it's the destination state)

 dg: true/false if consignment has dangerous goods

Response payload:

{"estimatedDeliveryDate":<<yyyy-MM-dd>>}

Print tracking labels from V6

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

Since: 20200300

GET /v6-api/rest/tracking/labels/{connoteNo}

Param:{connoteNo} the consignment reference number

Response payload:

{data:

     {pdf: <<the pdf URL>>}

}

client receives this resonse need to download the Pdf following the URL provided in the response

 

Retrieve routing information (Depots)

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.

Since: 20200500

GET /v6-api/rest/tracking/routing?senderSuburb=&senderState=&senderPostcode=&receiverSuburb=&receiverState=&receiverPostcode=&csvSeparator=&serviceCode=&itemCode=

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

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)

Since: 20200500

GET /v6-api/rest/pods/consignments/{id}

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

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)

Since: 20200500

GET /v6-api/rest/pods/{podId}

Parameters: {podId} as received from the search POD api

Manifest consignments

This API is to manifest a list of consignments (to confirm the consignments are ready for despatch)

Since: 20201000

POST /v6-api/rest/manifests/manifestConsignments

Request payload: array of connote reference number as below example:

{ "connoteNos":["A","b","c"]}

Example response payload:

{"manifestId":1111,"manifestNo":"AC"}

Cancel consignment

This API is to cancel a consignment. Consignments can only be cancelled when the transport company has not performed any action on it. Specifically, the consignment must not have been manifested by the client application.

Since: 20201000

DELETE /v6-api/rest/consignments/{id}

Parameter: {id} consignment Id or reference number

Example:

DELETE /v6-api/rest/consignments/123456

 
Appendix A: JSON fields in consignment API

1/96 Jephson Street, Toowong

Call us free: 1800 666 490

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