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
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
Suite 35
Mezzanine Level, Aspley hypermarket
59 Albany Creek Rd,
Aspley QLD 4034
Call us free: 1800 666 490
