Document Create
Allows customers to create a new Document for Transport movements. Required fields are in bold text.
Access
To get access to this API, please fill in the Developer Registration form
Resource URI
Make an HTTP POST request to:
Environment | URL | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
LIVE |
https://api.mainfreight.com/document/1.1/transportdocument?servicetype={servicetype}®ion={region} |
|||||||||||
UAT |
|
Resource Information
Type | Value | ||
---|---|---|---|
Authentication | API Key | ||
Response Formats | JSON | ||
HTTP Methods | POST | ||
API Version | 1.1 |
HTTP Headers
You must add the following HTTP Headers to your request:
Header | Description | Type | Required |
---|---|---|---|
Content-Type | Request content type. Supported types are "application/json" or "application/xml" | string | Yes |
Authorization |
The word " Secret" followed by a space, then your unique Transport API Key e.g: Secret wdnOId93-VXZECxvVRPQEJZNxPB5XZ... |
string | Yes |
Accept |
Result content type. Supported types are "application/json" or "application/xml" |
string | No |
Parameters
You must provide the parameters marked as required:
HTTP Request Parameters
Header | Description | Type | Required |
---|---|---|---|
servicetype |
Indicates Service Type. Required type is system. e.g: https://api.mainfreight.com/document/1.1/transportdocument?servicetype=system®ion={region} |
string | Yes |
region |
Region code, a list of available regions can be found here
|
string | Yes |
Request Body
Field | Description | Type | Length | Required |
---|---|---|---|---|
type | Document Type. Currently supported types are NZLabel & AUSLabel | string | 20 | Yes |
pageSize | Document Size. Currently supported sizes are A4 & STOCK_4X6 | string | 20 | Yes |
format | Document Format. Currently supported formats are IMG & PDF | string | 5 | Yes |
shipment | Shipment Details | object | Yes | |
housebillNumber | A reference that identifies the shipment | string | 14 | Yes |
account | Account involved in the shipment | object | Yes | |
code | Shorthand code to identify the account | string | 50 | Yes |
serviceLevel | An entity used to express the duration of transportation (available codes can be found here ) | object | Yes | |
code | Shortland code to identify the service level | string | 50 | Yes |
transportMode | A term used to distinguish between different ways of transportation of goods (available codes can be found here ) | string | 50 | Yes |
freightTerms | An entity used to express how the shipment starts and ends (available codes can be found here ) | string | 50 | Yes |
routingType | An entity used to express the optimal carrier and mode to ship a shipment (available codes can be found here ) | string | 50 | Yes |
systemOfMeasurement | What measurement type the units are specified on the shipment (available codes can be found here ) | string | 50 | |
origin | Defines the specifics of the starting point of the shipment | object | Yes | |
sender | The owner of the goods that need to be shipped | object | Yes | |
code | Shortland code of the sender | string | 50 | |
name | Full name of the sender | string | 200 | |
address | Physical address | object | Yes | |
premises | Indicates a named location, usually a building or collection of buildings with a common name | string | 200 | |
streetNumber | Indicates a street number | string | 20 | |
address1 | Indicates a street name | string | 200 | Yes |
address2 | Indicates other address identifiers | string | 200 | |
residential | Indicates whether a residential address | boolean | ||
suburb | Indicates the suburb | string | 500 | Yes |
postCode | Indicates the postcode | string | 10 | Yes (AU) |
town | Indicates the town | string | 50 | |
city | Indicates the city/place | string | 50 | Yes |
stateCode | Shorthand code to identify the state | string | 50 | Yes (AU) |
countryCode | Shorthand code to identify the country (available codes can be found here ) | string | 50 | |
geometry | Contains GPS location information | object | ||
location | Contains the geocoded latitude, longitude value | object | ||
latitude | Latitude value | decimal | ||
longitude | Longitude value | decimal | ||
contact | Contact point for sender | object | ||
name | Full name of the contact | string | 200 | |
phone | Phone number of the contact | string | 150 | |
phoneExtension | Phone number extension of the contact | string | 20 | |
emailAddress | Email address of the contact | string | 200 | |
pickupTime | Indicates pickup time information for sender | object | ||
toDateTime |
The end date time of the pickup time Required format: yyyy-MM-ddThh:mm:ss |
dateTime | ||
referenceNumber | Indicates reference corresponding to the sender | string | 50 | |
instructions | Indicates an instruction note corresponding to the sender | string | 200 | |
destination | Defines the specifics of the ending point of the shipment | object | Yes | |
receiver | The party who physically receives the goods | object | Yes | |
name | Full name of the receiver | string | 200 | |
address | Physical address | object | Yes | |
premises | Indicates a named location, usually a building or collection of buildings with a common name | string | 200 | |
streetNumber | Indicates a street number | string | 20 | |
address1 | Indicates a street name | string | 200 | Yes |
address2 | Indicates other address identifiers | string | 200 | |
residential | Indicates whether a residential address | boolean | ||
suburb | Indicates the suburb | string | 50 | Yes |
town | Indicates the postcode | string | 10 | |
postCode | Indicates the town | string |
50 |
Yes (AU) |
city | Indicates the city/place | string | 50 | Yes |
stateCode | Shorthand code to identify the state | string | 50 | Yes (AU) |
countryCode | Shorthand code to identify the country (available codes can be found here ) | string | 50 | |
geometry | Contains GPS location information | object | ||
location | Contains the geocoded latitude, longitude value | object | ||
latitude | Latitude value | decimal | ||
longitude | Longitude value | decimal | ||
contact | Contact point for receiver | object | ||
name | Full name of the contact | string | 200 | |
phone | Phone number of the contact | string | 150 | |
phoneExtension | Phone number extension of the contact | string | 20 | |
emailAddress | Email address of the contact | string | 200 | |
deliveryTime | Indicates delivery time information for receiver | object | ||
toDateTime |
The end date time of the delivery time Required format: yyyy-MM-ddThh:mm:ss |
dateTime | ||
referenceNumber | Indicates reference corresponding to the receiver | string | 50 | |
instructions | Indicates an instruction note corresponding to the receiver | string | 500 | |
freightDetails | Defines information about types and dimensions of goods shipped on this shipment | array of objects | Yes | |
freightDetail | Defines a single goods line of all goods on the shipment | object | Yes | |
ssccNumber | Serial Shipping Container Code can be used to identify a logistic unit | string | 50 | |
packTypeCode | Shorthand code identifying the type of goods on the freight line (available codes can be found here ) | string | 50 | Yes |
description | Description of the goods on the freight line | string | 200 | |
weight | Physical weight of the goods on the freight line | integer | ||
volume | Physical volume of the goods on the freight line | decimal | ||
length | Length of goods on the freight line | decimal | ||
width | Width of goods on the freight line | decimal | ||
height | Height of goods on the freight line | decimal | ||
stackable | Whether the goods on the freight line can be stacked | boolean | ||
freightClass | Freight classification code | string | 50 | |
foodGrade | Whether the freight line satisfy the classification of highest standard of internal cleanliness | boolean | ||
itemLines | Further breakdown of freight line (Said to Contain) | array of objects | ||
itemLine | One single Item line | object | ||
units | Units | integer | ||
packTypeCode | Shorthand code identifying the type of goods on the item line (available codes can be found here ) | string | 50 | |
description | Description of the goods on the item line | string | 500 | |
dangerousGoodsLines | Identification of materials or items with hazardous properties | array of objects | ||
dangerousGoodsLine | Identifies one line of dangerous goods (DG) | object | ||
class | Classification of DG Class | string | 50 | |
unNumber | A four-digit code used to identify hazardous materials and articles | string | 50 | |
variant | Identify variant of DG | string | 50 | |
properName | Identification of proper name of DG | string | 255 | |
technicalName | Identification of technical name of DG | string | 255 | |
commonName | Identification of common name of DG | string | 50 | |
subRisk | Identification of hazards referred to as Subsidiary Risks | string | 50 | |
tertiarySubRisk | Another breakdown of sub risk | string | 50 | |
hazChem | hazardous chemicals | string | 50 | |
packingGroup | Packing group indicates the degree of danger | string | 50 | |
flashPoint | In Centigrade | string | 50 | |
additionalInfo | Additional notes associated with DG | string | 255 | |
packageType | How DG is contained | string | 50 | |
packageInstruction | Instructions regarding package | string | 50 | |
marinePollutant | Whether DG is a Marine Pollutant | boolean | ||
acid | Whether DG is acidic | boolean | 50 | |
alkali | Whether DG is alkali | boolean | 50 | |
grossWeight | Physical weight of the goods on the DG line | integer | ||
volume | Physical volume of the goods on the DG line | decimal | ||
units | Units of DG line | integer | ||
description | Description of the goods on the DG line | string | ||
hireLines | Define information about Hire on the shipment | array of objects | ||
hireLine | Identifies one line of hire | object | ||
supplier | Supplier of hire (available codes can be found here ) | string | 50 | |
palletType | Type of pallet (available codes can be found here ) | string | 50 | |
toAccount | To account of hire | string | 50 | |
fromAccount | From account of hire | string | 50 | |
transactionType | Transaction type of hire (available codes can be found here ) | string | 50 | |
quantity | Quantity of pallets of hire | integer | ||
references | Reference types that goes against the shipment | array of objects | ||
reference | Single reference type line | object | ||
type | Shorthand code of reference type | string | 50 | |
value | Reference value | string | 50 | |
dangerousGoodsSignatory | Identifier party responsible for signing for DG | object | ||
name | Name of person | string | 200 | |
title | Title of person | string | 10 | |
location | Location of person | string | 50 | |
signature | Name on signature | string | 200 | |
emergencyPhone | Phone number of person | string | 150 | |
cover | Identifies Cover related information | object | ||
insuredType | Type of Insurance (available codes can be found here ) | string | 50 | |
insuredValue | Value of Insurance | decimal | ||
declaredValue | The amount stated to be the value of cover | decimal |
Response Body
Field | Description | Type | Length | |
---|---|---|---|---|
type | Document Type. Currently supported types are NZLabel & AUSLabel | string | 20 | Yes |
pageSize | Document Size. Currently supported sizes are A4 & STOCK_4X6 | string | 20 | Yes |
format | Document Format. Currently supported formats are IMG & PDF | string | 5 | Yes |
content | Document Content. (PDF format will provide a single Base64 string and IMG format may or may not provide a number of Base64 Strings.) | string | Yes |
Code samples
To Generate a Shipment in JSON format you will need to POST a JSON object:
- URL
https://api.mainfreight.com/document/1.1/transportdocument?servicetype=system®ion=NZ
You are going to send a JSON object similar to this:
- REQUEST JSON
[ { "type": "NZLabel", "pageSize": "A4", "format": "PDF", "shipment": { "account": { "code": "{YOUR_ACCOUNT_CODE}" }, "housebillNumber": "{YOUR_HOUSEBILLNUMBER}", "serviceLevel": { "code": "LCL" }, "transportMode": "ROAD", "freightTerms": "D2D", "routingType": "LCL", "systemOfMeasurement": "Metric", "origin": { "sender": { "code": null, "name": "TEST SENDER" }, "address": { "premises": null, "streetNumber": "42", "address1": "O'Rorke Road", "address2": null, "residential": false, "suburb": "Penrose", "postCode": "1061", "town": null, "city": "Auckland", "stateCode": null, "countryCode":"NZ", "geometry": { "location": { "latitude": null, "longitude": null } } }, "contact": { "name": "John Doe", "phone": "+64 000 000000", "phoneExtension": "856", "emailAddress": "example@email.com" }, "pickupTime": { "toDateTime": "2023-06-18T09:00:00" }, "referenceNumber": "OriginReferenceNumber", "instructions": "Origin Instructions" }, "destination": { "receiver": { "name": "TEST RECEIVER" }, "address": { "premises": null, "streetNumber": "21", "address1": "Hayton Road", "address2": null, "residential": false, "suburb": "Wigram", "postCode": "8042", "town": null, "city": "Christchurch", "stateCode": null, "countryCode": "NZ", "geometry": { "location": { "latitude": -43.542202, "longitude": 172.558036 } } }, "contact": { "name": "Jim Doe", "phone": "+64 000 000000", "phoneExtension": "856", "emailAddress": "example@email.com" }, "referenceNumber": "DestinationReferenceNumber", "instructions": "Destination Instructions" }, "freightDetails": [{ "ssccNumber": "123456789012345678", "customerItemNumber": "TEST1111", "packTypeCode": "Bag", "description": "These are the goods", "weight": 50, "volume": 0.5, "length": 0.2, "width": 0.25, "height": 0.15, "stackable": true, "freightClass": "100", "foodGrade": false, "itemLines": [{ "units": 100, "packTypeCode": "CTN", "description": "These are the detailed descriptions of the goods", "dangerousGoodsLines": [{ "class": "3", "unNumber": "1123", "variant": "1", "properName": "Butyl", "technicalName": "Desmoph", "commonName": "Desmoph", "subRisk": "1", "tertiarySubRisk": "2", "hazChem": "3[Y]", "packingGroup": "III", "flashPoint": "52", "additionalInfo": "Do not store in dir", "packageType": "Metal Drum", "packageInstruction": "DangerousGoodsLine PackageInstruction", "marinePollutant": false, "acid": false, "alkali": false, "grossWeight": 10, "volume": 0.2, "units": 2, "description": "DangerousGoodsLine Description" } ] } ], "hireLines": [{ "supplier": "C", "palletType": "B", "toAccount": "0000000000", "fromAccount": "111111111", "transactionType": "T", "quantity": 10 } ] } ], "references": [{ "type": "ReceiverReference", "value": "ReceiverReference" }, { "type": "SenderReference", "value": "SenderReference" } ], "dangerousGoodsSignatory": { "name": "Example DG", "title": "Dispatch", "location": "160 Plank Ave", "signature": "Example DG", "emergencyPhone": "6400000000" }, "cover": { "insuredType": "DV", "insuredValue": 1000.00, "declaredValue": 1000.00 }, "notifications": [{ "eventTypeCode": "StatusUpdate", "transport": { "code": "Email", "destination": "noemail@mainfreight.com" }, "events": [{ "code": "StatusUpdateShipmentPODReceived" } ] } ] } } ]
You are going to get another JSON object similar to this:
- RESPONSE JSON
[ { "type": "NZLabel", "pageSize": "A4", "format": "PDF", "content": [ "{YOUR_BASE64_STRING_RESULT}" ] } ]