omnix-logo.png

V6RESTful APIs - Consignments

Create a new consignment

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

Description

This API interface 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/consignments/{ids}

Method: GET

Param:{ids} the consignment Id, separated by comma (,)

ex: GET /v6-api/rest/tracking/consignments/1,2,3,4
Response: consignments' tracking data (events)
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"
                }
            ]
        },
        {
            "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"
                }
            ]
        }
    ]
}

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

Retrieve tracking labels from V6

Description

This API interface 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

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