RESTful APIs – V6 Consignments

RESTful APIs - V6 Consignments

The document is to provide an instruction to access v6 APIs.

The following are available API interfaces. Customers will be provided with an API key in order to access the APIs; also, each API key is associated with a valid v6 CUSTOMER_SERVICE or CUSTOMER_ROLE user.

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 field is 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",
     "reveiverPostcode": "5221",
     "receiverState": "SA",
     "reveiverContact": "Bjarni Herjolfsson",
     "receiverEmail": "receiver@mail.com",
     "deliveryDate": "2017-03-12 07:00",
 
      "totalQuantity": "43",
     "totalPallets": "5",
     "totalWeight": "128",
     "totalVolume": "4.15",
 
 
     "senderReference": "ABA1345",
     "description": "Maps and Paperwork",
     "specialInsructions": "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": {
               "freightline": [
               {
                         "itemCode": "MAP001",
                         "scanCodes" ["MPAG10293456"],
                         "freightCode": "GEN",
                         "itemReference": "ABA1345-01/01",
                         "description": "Map of vinland",
                         "quantity": 20,
                         "labels": 20,
                         "totalWeight": 10,
                         "totalVolume": 0.1,
                         "length": 0.10,
                         "width": 0.1,
                         "height": 0.5,
                         "weight": 0.5,
                },
               {
                         "itemCode": "DOC8390".
                         "scanCode": [
                         "C00001000100001",
                         "C0000100010002",
                         ],
                         "freightCode": "FRG",
                         "itemReference": ABA1345-002",
                         "description": "contracts for sale of Vinland",
                         "quantity": 3,
                         "labels": 5
                         "totalWeight": 2.0,
                         totalVolume" : 0.05,
          },
          {
                         "itemCode": "ARCH111",
                         "scanCodes": ["ARCH12309674093"],
                         "freightCode": "FRG",
                         "itemReference": "ABA1345-X86",
                         "description": "Legal archives 995-1010",
                         "quantity": 20,
                         "pallets": 5,
                         "labels": 5,
                         "length": 0.50,
                         "width": .50,
                         "height": 0.8,
                         "weight": 5.8
          }
          ]
    }
 }

Example JSON creating a new consignment with warehouse order:

{

     "customer": "001",
     "senderEmail": "apisender@gmail.com",
     "receiverEmail": "apireceiver@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",
     "totalPallets": "2",
     "specialInstructions": "special instruction",
     "description": "doc description",
     "senderReference": "senderRef",
     "warehouseOrderType": "TRANSFER",
     "receiverCode": "BRI",
     "senderCode": "MELB",
     "noConnote": "Y",
     "freightLines": [
          {

               "itemCode": "3KGSUGAR",
               "freightCode": "GENERAL",
               "quantity": 1,
               "totalVolume": 10,
               "totalWeight": 36,
               "pallets": 2,
               "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 upload successfully

{  
   "httpStatusCode": 201,
   "msg": "Created: Consignment successfully created"
}

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 API key is embedded in the request header, under Authorization property. E.x. Authorization: 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 these rules will result in Bad Request (400). The corresponding also contains intuitive error messages informing which fields do not follow which rules.To see all the rules, please see appendix A.

The format of bad response should look like following JSON

{
     "httpStatusCode": 400,
     "msg": "Bad Request"
     "violations": {
     //a list of violations
     [
     {fieldName} - {error} - {suggestions},
     ...
     ]
   }
}

Example of Bad Request response:

{
     "violations": [
     "connoteDate - wrong format - the date format should be yyyy-MM-dd",
     "receiverSuburb - required field - must eist 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 not be empty",
     "vehicleType - invalid vehicle type - cannot find vehile 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 sode 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"
}

Appendix A: JSON fields applied for creating new consignment

JSON supported fields     Content Data-Type Constraints Req Notes
connoteNo     string 40 char max no if supplied, this will become the connoteNo in the system. If not supplied a unique connoteNo will be generated
connoteDate     string 40 char max no if not supplied, defaults to date processing
customer     string 10 char id yes Denotes an existing customer id. If not supplied, must be able to identify customer by other b2b details. eg. email address, ftp location, userID, etc
senderName     string 30 char max yes  
senderAddress1     string 30 char max no  
senderAddress2     string 30 char max    
senderAddress3     string 30 char max no  
senderSuburb     string   yes must be a legitimate Australia Post suburb to be recognised
senderPostcode     string 4 char yes must be a legitimate Australia postcode to be recognised
senderState     string 3 char yes  
senderContact     string 30 char max no  
senderPhone     string 20 char max no  
pickupDate     string yyyy-MM-dd HH:mm no Defaults to connoteDate if not supplied
receiverName     string 30 char max yes  
receiverAddress1     string 30 char max no  
receiverAddress2     string 30 char max    
receiverAddress3     string 30 char max no  
receiverSuburb     string   yes must be a legitimate Australia Post suburb to be recognised
receiverPostcode     string 4 char yes must be a legitimate Australia Post postcode to be recognised
receiverState     string 3 char yes  
receiverContact     string 30 char max no  
receiverPhone     string 20 char max no  
deliveryDate     date yyyy-MM-dd HH:mm no defaults to pickupDate if not supplied
totalQuantity     interger > = 0 no This is optional, please refer to freight lines below
totalPallets     interger > = 0 no This is optional, please refer to freight lines below
totalWeight     decimal > = 0.0 no This is optional, please refer to freight lines below
totalVolume     decimal > = 0.0 no This is optional, please refer to freight lines below
senderReference     string 25 char max no e.g. Sales Order Number or Invoice Number for the consignment, or any other Sender's Reference
description     string 30 char max no  
specialInstructions     string 225 char max no  
notes     string   no  
jobType     string 10 char id no if not supplied, a suitable default value must be defined in v6
serviceType     string 10 char id no if not supplied, a suitable default value must be defined in v6
serviceType     string 10 char id no if not supplied, a suitable default value must be defined in v6
priorityType     string 10 char id no  
vehicleType     string 10 char id no if not supplied, a suitable default value must be defined in v6
dangerousGoods     string YES/NO no if not supplied, assume NO
chargeTo     string 10 char no SENDER or RECEIVER
warehouseOrderType     string 30 char max no INBOUND/RECEIPT/OUTBOUND/TRANSFER. This is a required field for creating warehouse orders
senderCode     string 20 char max no for OUTBOUND, the ship warehouse code, for TRANSFER, the from warehouse code.
This is a required field for creating warehouse orders if the warehouse order is OUTBOUND or TRANSFER
receiverCode     string 20 char max no for INBOUND/RECEIPT, the receiver warehouse, for TRANSFER, the to warehouse.
This is a required field for creating warehouse orders if the warehouse order is INBOUND, RECEIPT or TRANSFER
noConnote     string Y/yes/true no if yes, it creates a connote that is cancelled by default
docAmount     decimal   no for credit notes, negative amount is required
freightLines           an array of freightLine objects
  freightLine     1...n lines    
    itemCode string 20 char max yes  
    scanCodes Array of strings   no if not supplied, the system will generate a number automatically
    freightCode string 10 char id yes if not supplied, a suitable default must be defined
    itemReference string 40 char max no  
    description string 60 char max no  
    quantity integer > = 0 yes quantity of items (excluding pallets)
    pallets integer > = 0 no quantity of pallets (not items)
    labels integer > = 0 no # of tracking labels required per line - if not supplied will default to quantity
    totalWeight decimal > = 0.0 no total weight = quantity x weight - not only needs supplying if weight (per item) not supplied. measured in kg
    totalVolume decimal > = 0.0 no total volume = quantity x length x width x height - only needs supplying if individual dimensions not supplied. Measured in m3
    length decimal > = 0.0 no measured in metres
    width decimal > = 0.0 no measured in metres
    height decimal > = 0.0 no measured in metres
    weight decimal > = 0.0 no weight per item (measured in kg)
    serialNumbers Array of strings   no warehouse inbound or outbound serial numbers seperated by commas
    wbDocket string      
    batch string      
    airWaybill string      
    modality string