Hi-Trans Express Freight API (beta)

The Freight API allows REST functionality to connect with our core information. Currently as the API is under development, this is limited to consignment status and POD information as a GET method. Requests are returned in the form of JSON bodied responses.

The Freight API is still largely under testing but can be provided as a workable interface

Contents

Authentication

The Freight API supports HTTP basic authentication.

For HTTP Basic authentication, you will use the username and auth token provided to you by Hi-Trans Express:

1 2 CURL -G https://api.hi-trans.com.au:9093/ws/rest/freight/Status/$ConsignmentNo -U $Username:$Token

Errors

The Freight API produces the following standard errors, a summary of these are below:

200 - OK

Request successful.

400 - Bad Request

Couldn’t submit request. Check parameters.

401 - Unauthorized

Authentication failed.

402 - Request Failed

The parameters were valid but the request failed.

403 - Forbidden

User doesn’t have permissions to perform request.

404 - Not Found

The requested resource doesn't exist.

409 - Conflict

The request conflicts with another request.

429 - Too Many Requests

Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.

500, 502, 503, 504 - Server Errors

Server issue on our end.

Consignment Status

The current status of a consignment can be requested through a GET call to the API. Currently, it is only possible to retrieve a single status using the consignment number within the endpoint.

Retrieve Consignment Status

1 CURL -G https://api.hi-trans.com.au:9093/ws/rest/freight/Status/$ConsignmentNo/

Where $ConsignmentNo is the Consignment Number you wish to retrieve.

Attributes

ConsignmentID integer

Unique Record ID for the consignment record


ConsignmentNo String

The consignment number


DespatchDateTime String

The time at which the consignment was despatched


ConsignmentStatus String

The current delivery status of the consignment. Possible values:

Awaiting Pickup Allocation

The consignment is currently waiting to be allocated to a fleet for pickup

Pickup Allocated

The consignment has been allocated to a fleet for pickup

Pickup Acknowledged

The fleet has acknowledged pickup allocation for consignment

Arrived at Sender

The fleet has arrived at pickup location of consignment

Departed Sender

The fleet has complete the consignment pickup

Futile Pickup

The fleet was unable to pick up consignment

Unshipped

The consignment is awaiting to be placed on a linehaul truck

Manifested - Pending Arrival

The consignment has been placed on a linehaul manifest

Arrived at Receiving Depot

The consignment has arrived in the receiving depot

Delivery Allocated

The consignment has been put on-board a local truck or freight forwarder for delivery

Arrived at Receiver

The consignment has arrived at the delivery location.

Departed Receiver

The consignment has been delivered at the delivery location.

Futile Delivery

The consignment was unable to be delivered to the delivery location.


PickupArriveDateTime String

The time the pickup fleet arrived at the pickup location.


PickupCompletedDateTime String

The time the pickup for the consignment was complete at the pickup location. May contain a date only value if pickup was completed by a fleet without a PDA unit


ManifestDate String

The date the consignment was placed onto a linehaul manifest,


RunsheetDate String

The date the consignment was placed onto a delivery vehicle or freight forwarder vehicle.


DeliveryArrivedDateTime String

The time the delivery fleet arrived at the delivery location.


DeliveryCompleteDateTime String

The time the delivery for the consignment was complete. May contain a date only value if delivery was completed by a fleet without a PDA unit.


Request Example

1 2 CURL -G https://api.hi-trans.com.au:9093/ws/rest/freight/Status/ETS188 -U $Username:$Token

Response Example

1 2 3 4 5 6 7 8 9 10 11 12 { "ConsignmentID": 2241045, "ConsignmentNo": "ETS188", "DespatchDateTime": "16-10-2020T14:29:28", "ConsignmentStatus": "Departed Receiver", "PickupArriveDateTime": "19-10-2020T14:53:41", "PickupCompletedDateTime": "19-10-2020T15:14:42", "ManifestDate": "26-10-2020", "RunsheetDate": "21-10-2020", "DeliveryArrivedDateTime": "26-10-2020T08:30:16", "DeliveryCompleteDateTime": "26-10-2020T08:37:59" }

Consignment POD

The POD and scanned documents can be requested through a GET call to the API. Currently you can retrieve all documents for an individual consignment.

Retrieve Consignment POD and Scanned Docs

1 CURL -G https://api.hi-trans.com.au:9093/ws/rest/freight/PODs/$ConsignmentNo/

Where $ConsignmentNo is the Consignment Number you wish to retrieve the documents for.

Attributes

PODs Array

ConsignmentNo String

The linked consignment note number


FileExt String

The file extension type


FileData String Base64 Encoded

The document encoded as Base64

 

Request Example

1 2 CURL -G https://api.hi-trans.com.au:9093/ws/rest/freight/PODs/ETS188 -U $Username:$Token

Response Example

1 2 3 4 5 6 7 8 9 10 11 12 13 14 { "POD": [ { "ConsignmentNo": "ETS188", "FileExt": "jpg", "FileData": "Base64datahere" }, { "ConsignmentNo": "ETS188", "FileExt": "jpg", "FileData": "Base64datahere" } ] }

Consignment Import

Consignment manifests can be imported using a POST request to the API. Multiple consignments can be imported at the same time with pickup requests being created from the included details.

Import Consignments

1 CURL -H "Content-Type: application/json" -X POST https://api.hi-trans.com.au:9093/ws/rest/freight/import/

Attributes

ConsignmentNo String MaxLength:15 *Required

The newly created consignment note number. This must be unique and not repeat a previous consignment number. The consignment prefix will be used to determine the charge account.


DespatchDate String MaxLength:20 *Required

The date of consignment despatch. Date must be in format : dd-MM-yyyy


SenderReference String

An additional user reference for the consignment note. Eg. a purchase order number.


SenderName String MaxLength:50 *Required

The business name of the sender


SenderAddress1 String MaxLength:50 *Required

The sender’s address


SenderAddress2 String MaxLength:50

The sender’s address


SenderAddress3 String MaxLength:50

The sender’s address


SenderSuburb String *Required

The sender’s suburb. Our database contains all suburbs from the Australia Post database which can be found here: Postcodes Australia | Postcode Search & Finder - Australia Post (auspost.com.au)


SenderState String

The sending state. Options are ‘SA’, ‘QLD’, ‘VIC’, ‘NSW’, ‘ACT', ‘NT’, ‘WA’, 'TAS’


SenderPostcode String *Required

The sender postcode. Our database contains all suburbs from the Australia Post database which can be found here: Postcodes Australia | Postcode Search & Finder - Australia Post (auspost.com.au)


SenderContactName String MaxLength:30

The contact name of the sender


SenderContactPhone String MaxLength:25

The contact number of the sender.


SenderInstructions String MaxLength:120

Any additional instructions for pickup of the freight.


ReceiverName String MaxLength:50 *Required

The business name of the receiver


ReceiverAddress1 String MaxLength:50 *Required

The receiver’s address


ReceiverAddress2 String MaxLength:50

The receiver’s address


ReceiverAddress3 String MaxLength:50

The receiver’s address


ReceiverSuburb String *Required

The receiver’s suburb. Our database contains all suburbs from the Australia Post database which can be found here: Postcodes Australia | Postcode Search & Finder - Australia Post (auspost.com.au)


ReceiverState String

The receiving state. Options are ‘SA’, ‘QLD’, ‘VIC’, ‘NSW’, ‘ACT', ‘NT’, ‘WA’, 'TAS’


ReceiverPostcode String *Required

The receiver postcode. Our database contains all suburbs from the Australia Post database which can be found here: Postcodes Australia | Postcode Search & Finder - Australia Post (auspost.com.au)


ReceiverContactName String MaxLength:30

The contact name of the receiver


ReceiverContactPhone String MaxLength:25

The contact number of the receiver. Useful if we need to call upon delivery


ReceiverInstructions String MaxLength:120

Additional instructions for consignment delivery


ServiceCode String *Required

The service level of the consignment. Options are below, pending customer rates agreement

G

General Service

X

Express Service

L

Local Service. Eg. Metro Adelaide > Metro Adelaide job

F

Full Load Service


GeneralInstructions String MaxLength:120

Additional Instructions field for consignment. List and further requirements here.


TotalPalletSpaces integer *Required

The total number of pallet spaces the consignment covers.


TotalChepPallets integer *Required

The total number of chep pallets transferred. Required zero value if there are none


TotalChepPallets integer *Required

The total number of loscam pallets transferred. Required zero value if there are none


TotalPlainPallets integer *Required

The total number of customer own pallets used on the consignment. Required zero value if there are none


DeliveryRequiredDate String

For Timeslot use only. If delivery is required within a timeslot, please provide the date here. Date must be in format : dd-MM-yyyy


DeliveryRequiredTime String

For Timeslot use only. If delivery is required within a timeslot, please provide the time here. Time must be in 24hr format : 13:00


PickupReadyDate String

The date the pickup is ready to be collected from the sender. Date must be in format : dd-MM-yyyy


PickupReadyTime String

The time the pickup is ready to be collected from the sender. Time must be in 24hr format : 13:00


PickupCloseTime String

The time the senders business closes for freight pickups. Time must be in 24hr format : 16:00


LineItems array

LineItemReference String MaxLength:25

User reference number for freight line item. Eg. A purchase order number.


LineItemUnitName String MaxLength:20

The unit name for the freight line item. Must correspond to the rate units found on the customer account. For accounts using weight (c/kg) rates, leave this field blank.


LineItemDescription String MaxLength:20

A brief description of the freight items. Eg. Electronic Goods


LineItemQuantity integer

The quantity of this freight line item.


LineItemWeight number

The total weight for this line item in tonnes. Eg if there are 5x 0.200t pallets, the total weight would be 1.000t


LineItemLength number

The length of each individual item in metres.


LineItemWidth number

The width of each individual item in metres.


LineItemDepth number

The depth of each individual item in metres.


LineItemCubic number

The total volume for this line item in cubic metres. Eg if there are 4x 1.2mx1.2mx1.2m pallets, the total volume would be 6.912


LineItemUNNumber String MaxLength:4

If containing dangerous goods, the UN number for this freight. Please refer to the latest version of the Dangerous Goods Code Australian Dangerous Goods Code | National Transport Commission (ntc.gov.au)
Freight with mixed dangerous goods can use the value 0000 to provide the ‘Mixed DG’ flag.


LineItemDGAmount number

The amount of dangerous goods in litres or kilograms


Request Body JSON Example

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 [ { "ConsignmentNo": "TEST1234", "DespatchDate": "10-02-2021", "SenderReference": "TEST", "SenderName": "TEST Sender", "SenderAddress1": "Test Sender Address", "SenderAddress2": "TEST", "SenderAddress3": "TEST", "SenderSuburb": "Gillman", "SenderState": "SA", "SenderPostcode": "5013", "SenderContactName": "BOB", "SenderContactPhone": "1234567890", "SenderInstructions": "Test Instructions", "ReceiverName": "Test Receiver", "ReceiverAddress1": "Test Receiver Address", "ReceiverAddress2": "TEST", "ReceiverAddress3": "TEST", "ReceiverSuburb": "Chelsea Heights", "ReceiverState": "VIC", "ReceiverPostcode": "3196", "RecevierContactName": "John", "ReceiverContactPhone": "1234567890", "ReceiverInstructions": "Test Receiver Instructions", "ServiceCode": "G", "GeneralInstructions": "Test General Instructions", "TotalPalletSpaces": 1, "TotalChepPallets": 0, "TotalLoscamPallets": 0, "TotalPlainPallets": 1, "DeliveryRequiredDate": "15-02-2021", "DeliveryRequiredTime": "14:00", "PickupReadyDate": "10-02-2021", "PickupReadyTime": "7:00", "PickupCloseTime": "17:00", "LineItems": [ { "LineItemReference": "ABC1234", "LineItemUnitName": "PALLET", "LineItemDescription": "Electronic Goods", "LineItemQuantity": 1, "LineItemWeight": 1.000, "LineItemLength": 1.200, "LineItemWidth": 1.200, "LineItemDepth": 1.200, "LineItemCubic": 1.728, "LineItemUNNumber": "0000", "LineItemDGAmount": 4 }, { "LineItemReference": "ABC1235", "LineItemUnitName": "PALLET", "LineItemDescription": "More Electronics", "LineItemQuantity": 2, "LineItemWeight": 2.000, "LineItemLength": 1.200, "LineItemWidth": 1.200, "LineItemDepth": 1.200, "LineItemCubic": 3.456, "LineItemUNNumber": "0000", "LineItemDGAmount": 4 } ] } ]