RESTful APIs – V6 Manifests

RESTful APIs - V6 Manifests

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 CUSTOMERS_SERVICES or CUSTOMERS_ROLE user.

Create a new Manifest

Description

This API interface can be used to create a new manifest in v6.

Protocol

URL:

{domain_name} /v6-api/rest/manifests

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-apo-key}"; for example "ApiKey rGwXXurMoOd9ooSrOZ4UO2izAXHfzVU"

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.


{

     "manifestDate": "2018-03-26",
     "departureDate": "2018-03-27",
     "departureTime": "12:00",
     "estimatedArrivalDate": "2018-03-30",
     "complete": false,
     "docStatus": "ACTIVE",
     "stage": "NEW",
     "fullLoadCategory": "MC",
     "fromLocationCode": "TOOWONG",
     "fromLocationSuburb": "TOWOONG",
     "fromLocatoinPostcode": "4066",
     "fromLocationState": "QLD",
     "toLocationCode": "TOOWONG",
     "agent": "APT",
     "fromDepot": "ACR",
     "toDepot": "ACR",
     "hours": "01:00",
     "manualCharge": true,
     "usePercentage": true,
     "hourlyCharge": true,
     "dangerousGood": true,
     "manifestedConsignments": ["c28256"] 


}

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": "Created: Manifest 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 the 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 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 the following JSON
{

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

   }
}

Example of Bad Request response

{
     "violations": [
     "manifestDate - required field - must exist and must not be empty"
     ],

     "httpStatusCode: 400,
     "msg": "Bad Request"

}

Appendix A: JSON fields applied for creating a new manifest

JSON supported fields Content Data-Type Constraints Req Notes
manifestNo string 40 char max no If supplied, this will become the manifest number in the system. if not supplied a unique manifest number will be generated.
manifestDate string yyyy-MM-dd no if not supplied defaults to date of processing
departureDate string yyyy-MM-dd no Note: this is date only
departureTime string HH:mm    
estimatedArrivalDate string yyyy-MM-dd    
estimatedArrivalTime string HH:mm    
complete boolean      
docStatus string     One of the following values: CANCELLED, ACTIVE or POSTED
stage string     One of the following value:

NEW ("New"),
ALO ("Allocated"),
ACC ("Accepted"),
PIC ("Picked Up"),
POP ("In Transit"),
DEL ("Delivered"),
POD ("Proof of Delivery"),
fullLoadCategory string     Confirm with the Customer Service for available values. Only halfLoadCategory or fullLoadCategory specified when submitting data
halfLoadCategory string     Confirm with the Customer Service for available values
fromLoadCategory string     Should be a valid v6 location code
fromLocationSuburb string     Should be a valid postal suburb
fromLocationPostcode string     Should be a valid postal postcode
fromLocationState string     should be a valid postal state
toLocationCode string     Should be a valid v6 location code
toLocationSuburb string     Should be a valid postal suburb
toLocationState string      
agent string     sub contractor
fromDepot string     Should be a v6 depot code. If not specifed, the api will look up a depot based on the from location informations
todepot string     should be a valid v6 depot code. If not specified, the api will look up a depot based on the to location infomations
hours string Format: HH:mm    
manualCharge   boolean    
usePercentage boolean      
hourlyCharge boolean      
dangerousGood boolean      
manifestedConsignments   Array of Strings   Contains consignment numbers that will be assigned to the created manifest. Note: these consignments have to be in v6 before the manifest is created