On this page:
Table of Contents | ||||||||
---|---|---|---|---|---|---|---|---|
|
Info |
---|
The below outlines the parameters that are to be used for API requests to OmniParcel. |
2.1 Sender / Receiver Information
Details of where the package is being sent to or from.
Parameter | Mandatory | Type | Description |
---|---|---|---|
Name | Y | String (50 characters) | Consignee name/Business name |
Y | String (200 characters) | Email address | |
ContactPerson | Y | String (50 characters) | Contact person at delivery |
PhoneNumber | Y | String (50 characters) | Phone contact number at delivery |
ID | N | Integer | Address book ID. Only applicable if you have saved addresses in OmniParcel |
RecipientTaxId | N | String (100 characters) | To be used in receiver information only. Not a mandatory field in the system, but some carriers require this information |
2.2.1 Address Information
Info |
---|
All addresses imported into OmniParcel are validated when imported. This is to prevent connotes being created with invalid addresses. |
Parameter | Mandatory | Type | Description | ||||
---|---|---|---|---|---|---|---|
BuildingName | N | String (50 characters) | Address identifier, e.g. Unit 1, Level 2 | ||||
StreetAddress | Y | String(50 characters) | Street address e.g. 32 Sommer Place | ||||
Suburb | Y | String(50 characters) | Suburb Name / City name. See Suburb / State mapping below | ||||
City | Y | String(50 characters) | City/State Name. See Suburb / State mapping below
| ||||
PostCode | Y | String(10 characters) | Postal code
| ||||
CountryCode | Y | String(2 characters) | 2 letter country code, eg, US, NZ, AU, CN, CA, etc
|
2.2.2 Suburb/State/Province mapping
Info |
---|
OmniParcel is based on New Zealand address format, where the address format is built up the following way: Street Suburb City Post code What this means is that for any region where either suburb or city does not exist, or where there is a city and a state rather than a suburb and a city, the smaller of the two should always be mapped to ‘Suburb’ and the bigger of the two should be mapped to ‘City’. Both suburb and city are mandatory fields. |
Example 1:
Suburb + State (or province)
Origin/destination address field | OmniParcel Parameter |
---|---|
Street number | BuildingName or StreetAddress* |
Street name | BuildingName or StreetAddress* |
Suburb | Suburb |
State (or province) | City |
Postcode | PostCode |
Country | CountryCode |
Example 2
City + State (or province)
Origin/destination address field | OmniParcel Parameter |
---|---|
Building name | BuildingName or StreetAddress* |
Street number | BuildingName or StreetAddress* |
Unit number | BuildingName or StreetAddress* |
Street name | BuildingName or StreetAddress* |
City | Suburb |
State (or province) | City |
Postcode | PostCode |
Country | CountryCode |
Example 3
Suburb + City
Origin/destination address field | OmniParcel Parameter |
---|---|
Street number and street name | BuildingName or StreetAddress* |
Suburb | Suburb |
City | City |
Postcode | PostCode |
Country | CountryCode |
Example 4
City only
Origin/destination address field | OmniParcel Parameter |
---|---|
Street number and street name | BuildingName or StreetAddress* |
City | Suburb (Same value mapped to Suburb + City) |
City | City (Same value mapped to Suburb + City) |
Postcode | PostCode |
Country | CountryCode |
Info |
---|
*BuildingName is optional, but StreetAddress is mandatory. Data can be provided in both fields, or all data can be provided in StreetAddress |
Info |
---|
Canada provinces and province codes AB - ALBERTA |
2.3 Package Information
Parameter | Mandatory | Type | Description |
---|---|---|---|
Name | C (Required by some carriers) | String (50 characters) | Name of the package |
Length | Y | Decimal ( 4dp) | Length of package in centimetres |
Width | Y | Decimal ( 4dp) | Width of package in centimetres |
Height | Y | Decimal ( 4dp) | Height of package in centimetres |
Kg | Y | Decimal ( 4dp) | Weight of package in Kilos |
Type | Y | String(30 characters) | Package type, Valid values are: Bag, Box, Carton, Container, Crate, Envelope, Pail, Pallet, Satchel, Tube, Custom |
OverLabelBarcode | N | String(50 characters) | This barcode is mandatory if overlabel process is required. This functionality will work for one package per consignment only if we are using customer’s own label as final mile label. |
Info |
---|
Note: OmniParcel will accept minimum 0.01gm as weight and 1CM X 1CM X 1CM as minimum dimension. |
2.4 Commodity information
NOTE: Commodity information is mandatory for international shipments, and in most cases optional for domestic shipments. More and more carriers are requesting commodity information for all shipments, so it’s recommended that it is always passed.
Parameter | Mandatory | Type | Description | ||
---|---|---|---|---|---|
Description | Y | String(200 characters) | A brief description of the goods. Please ensure you are always providing accurate item descriptions. | ||
HarmonizedCode | C | String(50 characters) | The internationally standardised system of names and numbers to classify traded products. HS codes are mandatory for all international shipments.
| ||
Units | Y | Integer | Number of inner pieces. | ||
UnitValue | Y | Decimal ( 4dp) | Individual value of the unit.
| ||
UnitKg | Y | Decimal ( 4dp) | Total weight (KG) of all units. | ||
Currency | Y | String(3 characters) | Currency code, NZD, AUD, USD, etc | ||
Country | Y | String(2 Characters) | Country of Manufacture 2 Alpha code, NZ, AU, US, GB, etc | ||
itemSKU | N | String(30 characters) | SKU details of the consignment | ||
IsDG | C | Boolean | Is this a Dangerous Goods item; true (1) or false (0). For any consignments where you are shipping dangerous goods, this field must be “1”.
| ||
DangerousGoodsItem | C |
Info |
---|
Note: For import/export the minimum commodities value allowed is 0.01 |
2.5 Output information*
Parameter | Mandatory | Type | Description | ||
---|---|---|---|---|---|
LABEL_PDF | C | String(200 characters) | Label is presented on an A4 page | ||
LABEL_PNG_100X175 | C | String(200 characters) | Label is presented as a PNG image with dimension 100mm x 175mm (4x7) | ||
LABEL_PNG_100X150 | C | String(200 characters) | Label is presented as a PNG image with dimension 100mm x 150mm (4x6) | ||
LABEL_PDF_100X175 | C | String(200 characters) | Label is presented as a PDF with dimension 100mm x 175mm (4x7) | ||
LABEL_PDF_100X150 | C | String(200 characters) | Label is presented as a PDF with dimension 100mm x 150mm (4x6) | ||
LABEL_ZPL_100X175 | C | String(200 characters) | Label is presented in ZPL format with dimension 100mm x 175mm (4x7)
| ||
LABEL_ZPL_100X150 | C | String(200 characters) | Label is presented in ZPL format with dimension 100mm x 150mm (4x6)
|
Info |
---|
One label format is required |
2.6 Tax IDs
Parameter | Mandatory | Type | Description |
---|---|---|---|
IdType | Conditional* Depending on the import/export rules of your origin and destination countries | String(200 characters) | User can pass the IdType in this field. eg: XIEORINumber IOSSNUMBER GBEORINumber See full list below |
IdNumber | Conditional | String(200 characters) | This conditional field is required if there is a value in IdType |
Info |
---|
Tax IDs by country
|
2.7 DangerousGoods
Info |
---|
If shipping dangerous goods to New Zealand: DangerousGoods and DangerousGoodsItems must be populated, and isDG must be true |
Parameter | Mandatory | Mandatory | Mandatory |
---|---|---|---|
AdditionalHandingInfo | Conditional | String (100 characters) | Additional handing information |
HazchemCode | Conditional | String | Hazchem code |
IsRadioActive | Conditional | Boolean | Is goods radio active |
CcargoAircraftOnly | Conditional | Boolean | Is Cargo Aircraft Only |
IsDGLQ | Conditional | Boolean | Is dangerous goods limited quantities |
TotalQuantity | Conditional | String (200 characters) | Total quantity of dangerous goods |
TotalKg | Conditional | Decimal | Total weight KG of dangerous goods, required |
SignoffName | Conditional | String (50 characters) | Signoff name |
SignoffRole | Conditional | String (50 characters) | Signoff role |
Conditional | Object list |
2.8 DangerousGoodsItem
Info |
---|
If shipping dangerous goods to New Zealand: DangerousGoods and DangerousGoodsItems must be populated, and isDG must be true |
Attribute | Mandatory | Type | Description |
---|---|---|---|
Description | Mandatory if DangerousGoods is populated | String (100 characters) | |
ClassRrDivision | Mandatory if DangerousGoods is populated | String (50 characters) | |
UnorIDNno | Mandatory if DangerousGoods is populated | String (50 characters) | |
PackingGroup | Mandatory if DangerousGoods is populated | String (50 characters) | |
SubsidaryRisk | Mandatory if DangerousGoods is populated | String (50 characters) | |
Packing | Mandatory if DangerousGoods is populated | String (50 characters) | |
PackingInstr | Mandatory if DangerousGoods is populated | String (50 characters) | |
Authorization | Mandatory if DangerousGoods is populated | String (50 characters) |