Create consignment API
XML schema definition
The intention of this file is to allow third parties to conveniently generate code based on this schema. In no way should it be used to comprehensively validate the create consignment content.
An XSD can be downloaded from here.
Data driven changes
You can update a consignment once it has been created by sending an updated version of the consignment document.
Most aspects of the consignment can be updated, including consignment details, partners, consignment items, and containers.
However, changes to consignments are only possible before the consignment has been dispatched in eCargo. After the consignment is dispatched further changes can only be made manually by an administrator user in the eCargo application.
One exception to this rule are containers which can be updated even when the consignment has been dispatched or delivered. See containers documentation for more detail.
For further details of which fields can be updated consult the reference documentation for each section.
Getting started
In order to create and update consignments in eCargo, you’ll need to create a consignment XML file, then send it to us.
The file must be a well formed XML document and start with an XML declaration. The file should also conform to the other specifications mentioned in the XML specification.
The basic skeleton for the XML required is as follows.
<?xml version="1.0" encoding="utf-8"?>
<Message>
<Header>
<SenderID>MyCompany</SenderID>
<APIKey>MyApiKey</APIKey>
<MessageType>CONSIGNMENT</MessageType>
</Header>
<Body>
..Consignment information...
</Body>
</Message>
Header
The Header
element contains information for authentication, along with the document type so eCargo knows what the document is for.
Authentication
The SenderId
and APIKey
elements are how eCargo authenticates consignment documents. You will be supplied the values you need for these elements by eCargo before you start using the API. If these values are incorrect, your document will be rejected by eCargo.
MessageType
This is just so that eCargo knows what type of document we are receiving, for your purposes this will always be consignment
.
For further information on the header element and the associated elements, please see the message header documentation.
Message body
This is where the actual information for updating and creating consignments is placed.
<Message>
<Header>
<SenderID>MyCompany</SenderID>
<APIKey>MyApiKey</APIKey>
<MessageType>CONSIGNMENT</MessageType>
</Header>
<Body>
<Consignment>
<ConsignmentNumber>ABCD123</ConsignmentNumber>
<PickupDueDate>2017-06-01T15:30:00</PickupDueDate>
<DeliverDueDate>2017-06-15T18:00:00</DeliverDueDate>
</Consignment>
</Body>
</Message>
Each Consignment
element contains several other elements which together describe a consignment in eCargo, and should be in the Body
element.
The three elements shown, ConsignmentNumber
, PickupDueDate
, and DeliverDueDate
, must always be specified and describe fundamental information for the consignment.
For the full list of available elements, please see the consignment details documentation.
Partners
A partner is a business that plays a particular role in the delivery of the consignment.
A Partner
element must include its Role
and Code
elements. The value given for the Role
element is case sensitive.
The PICKUP_FROM
and DELIVER_TO
partners must always be included. You can add a CARRIER
partner as well if required.
<?xml version="1.0" encoding="utf-8"?>
<Message>
<Header>
<SenderID>MyCompany</SenderID>
<APIKey>MyApiKey</APIKey>
<MessageType>CONSIGNMENT</MessageType>
</Header>
<Body>
<Consignment>
<ConsignmentNumber>ABCD123</ConsignmentNumber>
<PickupDueDate>2017-06-01T15:30:00</PickupDueDate>
<DeliverDueDate>2017-06-15T18:00:00</DeliverDueDate>
<Partner>
<Role>PICKUP_FROM</Role>
<Code>PortA</Code>
</Partner>
<Partner>
<Role>DELIVER_TO</Role>
<Code>WarehouseB</Code>
</Partner>
</Consignment>
</Body>
</Message>
For a full list of available elements and further details about consignment partners, please see the consignment partners documentation.
Now to specify what it’s actually transporting.
Consignment items
A consignment item is a group of different products which are summarised together. The products are summarized together in order to calculate rates correctly. A consignment can have more than one consignment item.
<?xml version="1.0" encoding="utf-8"?>
<Message>
<Header>
<SenderID>MyCompany</SenderID>
<APIKey>MyApiKey</APIKey>
<MessageType>CONSIGNMENT</MessageType>
</Header>
<Body>
<Consignment>
<ConsignmentNumber>ABCD123</ConsignmentNumber>
<PickupDueDate>2017-06-01T15:30:00</PickupDueDate>
<DeliverDueDate>2017-06-15T18:00:00</DeliverDueDate>
<Partner>
<Role>PICKUP_FROM</Role>
<Code>PortA</Code>
</Partner>
<Partner>
<Role>DELIVER_TO</Role>
<Code>WarehouseB</Code>
</Partner>
<Items>
<Item>
<Description>TEU</Description>
<Measure Type="WEIGHT">
<Value>20</Value>
<Unit>kg</Unit>
</Measure>
<Measure Type="VOLUME">
<Value>4</Value>
<Unit>m3</Unit>
</Measure>
<Measure>
<Value>40</Value>
<Unit>Pallets</Unit>
</Measure>
</Item>
</Items>
</Consignment>
</Body>
</Message>
A consignment item is represented by the Item
element. Each item should always consist of a Description
and at least one Measure
element. You can of course also specify more than one Measure
element. Each Measure
element must in turn contain a Value
and Unit
field. There are two special cases, when the measure is Volume or Weight, then the Type
attribute on the Measure
element must be set. You can safely ignore this attribute otherwise.
All of the Item
elements should be encapsulated by an Items
element, regardless of how many there are.
For a more detailed explanation on consignment items, please see the consignment items documentation.
Order line items
An order line item is typically a single product or SKU. Each consignment can have zero or more order line items.
<?xml version="1.0" encoding="utf-8"?>
<Message>
<Header>
<SenderID>MyCompany</SenderID>
<APIKey>MyApiKey</APIKey>
<MessageType>CONSIGNMENT</MessageType>
</Header>
<Body>
<Consignment>
<ConsignmentNumber>ABCD123</ConsignmentNumber>
<PickupDueDate>2017-06-01T15:30:00</PickupDueDate>
<DeliverDueDate>2017-06-15T18:00:00</DeliverDueDate>
<Partner>
<Role>PICKUP_FROM</Role>
<Code>PortA</Code>
</Partner>
<Partner>
<Role>DELIVER_TO</Role>
<Code>WarehouseB</Code>
</Partner>
<OrderItems>
<OrderItem>
<Code>ABC123</Code>
<Description>Delicious Soup</Description>
<Measure Type="WEIGHT">
<Value>64.0000</Value>
<Unit>kg</Unit>
</Measure>
<Measure Type="VOLUME">
<Value>0.2050</Value>
<Unit>m3</Unit>
</Measure>
<Measure>
<Value>32.0000</Value>
<Unit>cartons</Unit>
</Measure>
</OrderItem>
</OrderItems>
</Consignment>
</Body>
</Message>
An order line item is represented by the OrderItem
element. Each order line should always consist of a Code
, a Description
, and one or more Measure
elements.
Each Measure
element must in turn contain a Value
and Unit
field.
There are two special cases: when the measure is volume or weight, then the Type
attribute on the Measure
element must be set. You can safely ignore this attribute otherwise.
Weight measures must use kg
and volume measures must use m3
as the unit.
All of the OrderItem
elements must be encapsulated by an OrderItems
element - regardless of how many OrderItem
elements there are.
For a more detailed explanation on order line items, please see the order line items documentation.
Shipping containers
A container is intended to represent a physical shipping container that is transported as a part of the consignment.
In order to specify Container
elements, the transportation mode must be set to Shipping
.
You must specify the container number and type for each Container
. A Container
like consignment items, must also be encapsulated in a Containers
element, regardless of how many there are.
<?xml version="1.0" encoding="utf-8"?>
<Message>
<Header>
<SenderID>MyCompany</SenderID>
<APIKey>MyApiKey</APIKey>
<MessageType>CONSIGNMENT</MessageType>
</Header>
<Body>
<Consignment>
<ConsignmentNumber>ABCD123</ConsignmentNumber>
<PickupDueDate>2017-06-01T15:30:00</PickupDueDate>
<DeliverDueDate>2017-06-15T18:00:00</DeliverDueDate>
<TransportationMode>Shipping</TransportationMode>
<Partner>
<Role>PICKUP_FROM</Role>
<Code>PortA</Code>
</Partner>
<Partner>
<Role>DELIVER_TO</Role>
<Code>WarehouseB</Code>
</Partner>
<Items>
<Item>
<Description>TEU</Description>
<Measure Type="WEIGHT">
<Value>75000.00</Value>
<Unit>kg</Unit>
</Measure>
<Measure Type="VOLUME">
<Value>120</Value>
<Unit>m3</Unit>
</Measure>
<Measure>
<Value>3</Value>
<Unit>cntnrs</Unit>
</Measure>
</Item>
</Items>
<Containers>
<Container>
<ContainerNumber>MTSU0000113</ContainerNumber>
<Type>22G1</Type>
</Container>
<Container>
<ContainerNumber>MTSU0000114</ContainerNumber>
<Type>22G1</Type>
</Container>
</Containers>
</Consignment>
</Body>
</Message>
For a detailed explanation on containers, please see the containers documentation.
Sending the XML document
Now that you have an XML document, the only thing left to do is send it to eCargo. There are currently two ways to do that.
- Drop the XML file into the FTPS folder using credentials and location provided by eCargo.
- Send an HTTP POST request to a target endpoint with the XML as content.
If you take the latter option, note that there is a Test
environment for your use. It is advisable to use the Test
environment initially for your development. Once you are satisfied with your functionality, then it should progress to the live Production
environment.
The endpoints are:
Environment | HTTP POST endpoint |
---|---|
Production | https://www.ecargo.co.nz/interface/consignment |
Test | https://test.ecargo.co.nz/interface/consignment |
Errors
When you send a consignment document to the API the consignment is always processed offline. When sending the consignment document via HTTP you may receive a HTTP response code such as a 200
which indicates that your document has been succesfully received for processing. It does not indicate that the consignment document has been successfully processed.
If errors do occur while processing the consignment you will be notified via email. The error message will be sent to any email addresses that you have already nominated to receive them.
Before you use the API eCargo support will ask you to nominate one or more email addresses that will receive error notifications from the API. Ensure that you are able to access the email addresses that you have nominated.
Documentation
Message header
The header section contains a combination of mandatory authentication information and optional diagnostic information.
Field | Required | Description |
---|---|---|
SenderID | Yes | Required for authentication (see below) |
APIKey | Yes | Required for authentication (see below) |
MessageType | Yes | Always has value consignment |
Timestamp | No | A datetime in the format yyyy-mm-ddThh:nn:ss , see datetime |
MessageID | No | A unique identifier |
Authentication details
SenderID
and APIKey
must contain valid credentials for any processing to occur. eCargo will provide these values prior to you using the API.
Optional diagnostic fields
We strongly encourage you to add a field such as a timestamp or unique message identifier to assist in diagnosing issues when dealing with eCargo support.
Example
<?xml version="1.0" encoding="utf-8"?>
<Message>
<Header>
<SenderID>MyCompany</SenderID>
<APIKey>MyApiKey</APIKey>
<MessageType>CONSIGNMENT</MessageType>
<TimeStamp>2017-03-17T09:30:08</TimeStamp>
<MessageID>3668755826</MessageID>
</Header>
...
</Message>
Consignment details
Field | Required | Format | Description |
---|---|---|---|
ConsignmentNumber | Yes | Free text (20) | Customer consignment identifier 1 |
PickupDueDate | Yes | Datetime | When the consignment is due to be picked up from the pickup point in the format yyyy-MM-ddTHH:mm:ss |
DeliverDueDate | Yes | Datetime | When the consignment is due to be delivered to the delivery point in the format yyyy-MM-ddTHH:mm:ss |
SalesOrderNo | No | Free text (50) | Customer sales order number 2 |
PurchaseOrderNo | No | Free text (50) | Customer purchase order number 2 |
BookingReferenceNo | No | Free text (1000) | Booking reference number 3 |
Protection | No | Protection type | Temperature requirements for the goods to be moved |
HazardClass | No | Hazard class | Identifies which ERMA hazardous goods classification the consignment belongs to |
HazardUNNo | No | Number (4) | If the consignment contains hazardous goods, use the correct 4 digit UN number for hazardous materials |
Comments | No | Free text (500) | Relevant comments against the job |
IsPriority | No | Priority flag | Flags the consignment as a priority job, by default the consignment is not prioritised |
TransportationMode | No | Transportation mode | Identifies the mechanism to be used to transport the consignment, the default is Road |
Instructions | No | Free text (500) | Instructions as passed from an ERP source |
All consignment details can be updated before the consignment is dispatched.
Purchase and sales order number
- The value will be adjusted down to the maximum length if it is greater than the maximum length.
- If only the letter casing of the value has been changed, the value will not be updated.
- If no value is provided or just blank spaces are provided, the existing value is not modified.
Booking reference number
- The value will be adjusted down to the maximum length if it is greater than the maximum length.
- If there has been merely a change in the letter casing, the value will still be updated.
- If no value is provided or just blank spaces are provided, the existing value is not modified.
Consignment number prefixes
Customisation is available for consignment number prefixes. This means that the user of the API does not need to know about the prefix in order to create a consignment. Be aware, this also means the consignment number supplied will not always be the one that is persisted to the eCargo system. The prefix itself cannot be altered by the create consignment API. If you wish to create or change a prefix, please contact eCargo support.
Examples:
Consignment Number | Pre-defined Prefix | Consignment Number in eCargo |
---|---|---|
‘1234’ | ‘PREFIX’ | ‘PREFIX1234’ |
‘1234’ | -None- | ‘1234’ |
Auto-lead times
A business can define auto-lead time rules in eCargo that will automatically adjust the deliver-to due date based on the consignment’s:
- pickup-from
- deliver-to
- pickup-from due date.
If a matching auto-lead time rule is found for a consignment then the deliver-to due date specified in the consignment message is replaced by the value calculated using the rule.
For information about auto-lead time rules see this article.
Hazard class
The supported hazard class values are:
Value | Description |
---|---|
1 | Explosive |
1.1 | Explosive (Mass) |
1.2 | Explosive (Projectile) |
2 | Gas |
2.1 | Gas (Flammable) |
2.2 | Gas |
2.3 | Gas (Toxic) |
3 | Liquid (Flammable) |
4 | Solid (Flammable) |
5 | Oxidizing |
6 | Toxic |
7 | Radioactive |
8 | Corrosive |
9 | Dangerous |
Priority flag
The supported priority flag values are:
Value | Description |
---|---|
Y | Consignment to be flagged as a priority |
N | Removes the priority off a prioritised consignment |
If the priority is specified for a new consignment the consignment will be flagged as a priority otherwise it will default to unprioritised.
When a consignment is flagged as a priority
-
The consignment is highlighted in eCargo with a priority icon.
-
The consignment is added to the priority category in the consignment summary screen.
When the consignment priority is modified
-
If the IsPriority value is
Y
and the consignment is not currently a priority it will be flagged as a priority. -
If the IsPriority value is
N
and the consignment is currently a priority then the consignment is no longer flagged as a priority.
Priority notification
A business can opt in to receive an alert via eCargo when the priority on the consignment has been added or removed.
Protection type
The supported protection types are:
Value | Description |
---|---|
Ambient | Freight is transported without temperature regulation |
Chilled | Freight is transported chilled |
Frozen | Freight is transported frozen |
Produce | Freight is transported at produce optimal temperature |
These values are not case-sensitive.
Transportation mode
The supported transportation modes are:
Value | Description |
---|---|
Road | Consignment is delivered by road |
Rail | Consignment is delivered by rail |
Shipping | Consignment is delivered by ship |
These values are not case-sensitive.
If the transportation mode is not specified for a new consignment it will default to Road
.
Example
...
<Body>
<Consignment>
<ConsignmentNumber>12345</ConsignmentNumber>
<SalesOrderNo>Sales000001</SalesOrderNo>
<PurchaseOrderNo>Purchase001</PurchaseOrderNo>
<BookingReferenceNo>BookingReference001</BookingReferenceNo>
<Protection>Ambient</Protection>
<HazardClass>1.2</HazardClass>
<HazardUNNo>0398</HazardUNNo>
<Comments>13/10. Not booked on earlier vessel as due into despatch.</Comments>
<IsPriority>Y</IsPriority>
<TransportationMode>Road</TransportationMode>
<Instructions>Careful handling required, dangerous goods.</Instructions>
<PickupDueDate>2017-09-19T05:30:00</PickupDueDate>
<DeliverDueDate>2017-09-23T16:15:00</DeliverDueDate>
...
</Consignment>
</Body>
Consignment partners
A partner is a business that plays a particular role in the delivery of the consignment.
Each individual partner is represented in a partner element.
<Partner>
<Role></Role>
<Code></Code>
</Partner>
Field | Required | Format | Description |
---|---|---|---|
Role | Yes | Role | The role that the partner plays in the delivery of the document |
Code | Yes | Code | A unique value used to identify a partner |
Notes
When specifying either the pickup-from and deliver-to partner the business name and address will automatically default to what is in eCargo.
To view these details in eCargo see maintaining business details.
-
To assign a different business name from what is stored in eCargo see specifying a different name for the pickup-from or deliver-to business.
-
To assign a different address from what is stored in eCargo see specifying a pickup-from or deliver-to address.
Role
The supported Role
values are:
Value | Required |
---|---|
PICKUP_FROM | Yes |
DELIVER_TO | Yes |
OWNER | Only required if you are creating consignments on behalf of another business that owns the goods |
CARRIER | No |
Please note that the values for Role
are case sensitive
For further details see the sections on how to specify the various partners.
Code
The Code
is a unique value used to identify a partner.
Please contact eCargo to discuss where you can source these codes from.
Changing consignment partners
To change a partner submit a document with the updated partner. The new partner will replace the previous value with the same role.
You may not change partners once the consignment has been dispatched in eCargo. Partners can still be adjusted manually after the consignment has been dispatched.
Specify a pickup-from or deliver-to partner that exists in eCargo
The site that the consignment is to be picked up from or delivered to. The address details will default to the address details stored in eCargo for that business. See maintaining business details.
<Partner>
<Role>DELIVER_TO</Role>
<Code>2399</Code>
</Partner>
To supply an address that is different from what is held in eCargo see specifying a pickup-from or deliver-to address.
To specify a different business name see specifying a different name for the pickup-from or deliver-to business.
Specify a pickup-from or deliver-to partner that does not exist in eCargo
To specify a business to pick up from or deliver to that does not exist in eCargo:
-
Assign a new partner
Code
that is not being used. -
Assign a business
Name
. -
Assign their address details.
Note that the address details that are specified when the new partner is created will become the default in eCargo. You cannot update the default address details via the API. You can still override the default address details for a consignment, see specifying a pickup-from or deliver-to address.
Example
The business New Horizon Limited
does not exist in eCargo. To associate a code that references this new business submit a new code that is not already being used along with the business name and address details.
<Partner>
<Role>PICKUP_FROM</Role>
<Code>0088179469</Code>
<Name>New Horizon Limited</Name>
<Address1>23 Street Address</Address1>
<Address2>Mairangi Bay</Address2>
<City>Auckland</City>
<PostCode>0630</PostCode>
<Region>Auckland</Region>
</Partner>
Specifying a different name for the pickup-from or deliver-to business
If the name is not supplied for the pickup-from and deliver-to partner it will automatically default to what is held in eCargo. To change the business name that will appear on the consignment supply a value in the Name
field.
Examples
Example 1. Change the pickup-from partner business name to Apollo Wholesale Limited
rather than using the business name held in eCargo.
<Partner>
<Role>PICKUP_FROM</Role>
<Code>0083054007</Code>
<Name>Apollo Wholesale Limited</Name>
</Partner>
Example 2. Change the deliver-to partner name to Omega International
rather than using the business name held in eCargo.
<Partner>
<Role>DELIVER_TO</Role>
<Code>2399</Code>
<Name>Omega International</Name>
</Partner>
Note Specifying a business name will not change the default name held in eCargo.
Specifying a pickup-from or deliver-to address
If the address details are not supplied for the pickup-from and deliver-to partner it will automatically default to what is held in eCargo. To view these details in eCargo see maintaining business details.
To specify an address that is different from the one held in eCargo the following fields are available.
Field | Format | Description |
---|---|---|
Address1 | Free text (64) | Street address |
Address2 | Free text (64) | Suburb |
City | Free text (32) | City |
PostCode | Free text (16) | Postal code |
Region | Free text (64) | Region |
Note
When changing the address at least one of the following fields need to be populated:
- Address1
- Address2
- City
If none of these fields are populated it will default to the address held in eCargo.
Examples
Example 1. Specify a new delivery address.
<Partner>
<Role>DELIVER_TO</Role>
<Code>2399</Code>
<Address1>2 Street Address</Address1>
<Address2>Mirimar</Address2>
<City>Wellington</City>
<PostCode>6022</PostCode>
<Region>Wellington</Region>
</Partner>
Example 2. Change the pickup-from street address and leave all the other address fields blank.
<Partner>
<Role>DELIVER_TO</Role>
<Code>0083054007</Code>
<Address1>2 Merry Lane</Address1>
</Partner>
Example 3. The following will default to the address held in eCargo as Address1
, Address2
and City
have been left blank.
<Partner>
<Role>DELIVER_TO</Role>
<Code>2399</Code>
<Address1></Address1>
<Address2></Address2>
<City></City>
<PostCode>6022</PostCode>
<Region>Wellington</Region>
</Partner>
Note Specifying an address will not change the default address held in eCargo.
Specify consignment owner partner
The consignment owner partner is the business that owns the goods to be delivered. They will also be the business charged for the freight costs.
The OWNER
partner is only required if the consignment is being created on behalf of another business.
If you are creating a consignment for your own business the OWNER
partner is not required. The owner partner will automatically default to the business associated with the Sender ID.
Examples
In the following example the code 0083054007
is associated with the business Apollo Wholesale Limited
.
Example 1. Assign the business Apollo Wholesale Limited
as the owner of the goods.
<Partner>
<Role>OWNER</Role>
<Code>0083054007</Code>
</Partner>
Example 2. A business that is not Apollo Wholesale Limited
is sending documents to create consignments on behalf of Apollo Wholesale Limited
. In this case the OWNER
partner is required.
<Message>
<Header>
<SenderID>ANOTHER_CO</SenderID>
...
</Header>
<Body>
<Consignment>
<Partner>
<Role>OWNER</Role>
<Code>0083054007</Code>
</Partner>
...
</Consignment>
Example 3. Apollo Wholesale Limited
is sending documents to create consignmemts for its own business. In this case an OWNER
partner is not required. The owner will automatically default to Apollo Wholesale Limited
.
<Header>
<SenderID>SENDER_0083054007</SenderID>
...
</Header>
Specify a carrier
The carrier is the business expected to transport the consignment. See also automatically assigning a carrier.
Example
Example 1. Assign the carrier business associated with the code 004775826
<Partner>
<Role>CARRIER</Role>
<Code>004775826</Code>
</Partner>
Automatically assigning a carrier
eCargo has a feature that will automatically assign a carrier to a consignment. If this feature is enabled, a CARRIER
partner is not required.
To override the auto assigned carrier specify a carrier partner. See specify a carrier.
Consignment items
Summary
Each consignment contains a collection of one or more consignment items.
<Items>
<Item>
<Description>Timber</Description>
<Measure Type="WEIGHT">
<Value>10845.9720</Value>
<Unit>kg</Unit>
</Measure>
<Measure Type="VOLUME">
<Value>24.3050</Value>
<Unit>m3</Unit>
</Measure>
</Item>
<Item>
<Description>Packaging</Description>
<Measure Type="WEIGHT">
<Value>10845.9720</Value>
<Unit>kg</Unit>
</Measure>
<Measure Type="VOLUME">
<Value>24.3050</Value>
<Unit>m3</Unit>
</Measure>
</Item>
</Items>
Consignment item
A consignment item is used for summarising product groups for the carrier and for rating, so a consignment item typically groups together different products which are summarised and rated together.
<Item>
<Description>Palleted Goods</Description>
<Measure Type="WEIGHT">
<Value>10845.9720</Value>
<Unit>kg</Unit>
</Measure>
<Measure Type="VOLUME">
<Value>24.3050</Value>
<Unit>m3</Unit>
</Measure>
<Measure>
<Value></Value>
<Unit>lifts</Unit>
</Measure>
<Measure>
<Value>25.0000</Value>
<Unit>pallets</Unit>
</Measure>
<Measure>
<Value>4233.0000</Value>
<Unit>cartons</Unit>
</Measure>
<Measure>
<Value>25.0000</Value>
<Unit>chep plts</Unit>
</Measure>
<Measure>
<Value></Value>
<Unit>loscam plts</Unit>
</Measure>
</Item>
Field | Required | Format | Description |
---|---|---|---|
Description | Yes | Description | A description of the product |
Measure | Yes | Measure | The metric for the consignment |
Notes
You can update consignment items by specifying updated consignment items in the update document. Any previous consignment items will be removed completely and replaced by the new consignment items.
You can only update consignment items before the consignment has been dispatched in eCargo. After the consignment has been dispatched, consignment items can still be updated manually.
Description
This field is required when specifying a consignment item. The value of this field should be the same as the product description maintained in eCargo. This value is not case-sensitive. To see where it is maintained in eCargo, look here.
Products
Each consignment item groups and summarises a product for rating. The type of product is specified by the Description
field. The product determines which units of measure we can specify quantities for and can also specify whether those are quantities are required or optional.
You can see a list of the products that are used by your business in eCargo, here.
Measure
Each consignment item contains one or more measures depending on the product specified in the Description
field. A measure contains a decimal Value
field and a Unit
field which contains a unit of measure code.
Some measures with particular units of measure can be set to be mandatory in eCargo, forcing you to attach them to certain consignments.
<Measure Type="WEIGHT">
<Value>10845.9720</Value>
<Unit>kg</Unit>
</Measure>
<Measure Type="VOLUME">
<Value>24.3050</Value>
<Unit>m3</Unit>
</Measure>
<Measure>
<Value>10</Value>
<Unit>cartons</Unit>
</Measure>
<Measure>
<Value>2</Value>
<Unit>lifts</Unit>
</Measure>
Field | Required | Format | Description |
---|---|---|---|
Value | Yes | Decimal | The quantity of the associated unit, this field may be left blank |
Unit | Yes | Unit | Unit of measure |
Unit
Unit of measure codes are look up values specified on the target product in eCargo, see here . These values are not case-sensitive. You can find the unit of measure codes that you need to send us on the units of measure page. This API uses the Legacy APIs codes.
Weight and volume
There are two special measures WEIGHT
and VOLUME
which must be specified with the Type
attribute. The values are case sensitive. Other measures do not require this attribute.
The weight and volume columns are shown separately from other units of measure when viewing the product.
<Measure Type="WEIGHT">
<Value>10845.9720</Value>
<Unit>kg</Unit>
</Measure>
Order line item
Summary
Each consignment contains a collection of zero or more order line item items. Each order line item is typically a single product or SKU.
<OrderItems>
<OrderItem>
<Code>ABC123</Code>
<Description>Delicious Soup</Description>
<Measure Type="WEIGHT">
<Value>64.0000</Value>
<Unit>kg</Unit>
</Measure>
<Measure Type="VOLUME">
<Value>0.2050</Value>
<Unit>m3</Unit>
</Measure>
<Measure>
<Value>32.0000</Value>
<Unit>cartons</Unit>
</Measure>
</OrderItem>
</OrderItems>
Field | Required | Format | Description |
---|---|---|---|
Code | Yes | Code | A code/SKU for the item. Maximum length of 200 characters. |
Description | Yes | Description | A description of the item. Maximum length of 64 characters. |
Measure | Yes | Measure | The measures for the item |
Code
This field is required when specifying an order line item.
Description
This field is required when specifying an order line item.
Measure
Each order line item can contain zero or more measures. A measure contains a decimal Value
field and a Unit
field which contains a unit of measure code.
<Measure Type="WEIGHT">
<Value>64.0000</Value>
<Unit>kg</Unit>
</Measure>
<Measure Type="VOLUME">
<Value>0.2050</Value>
<Unit>m3</Unit>
</Measure>
<Measure>
<Value>32.0000</Value>
<Unit>cartons</Unit>
</Measure>
Field | Required | Format | Description |
---|---|---|---|
Value | Yes | Decimal | The quantity of the associated unit. This field may be left blank |
Unit | Yes | Unit | Unit of measure |
Unit
Unit of measure codes are look up values specified by eCargo. You can find the unit of measure codes that you need to send us on the unit of measure page. This API uses the Legacy APIs codes.
Weight and volume
There are two special measures WEIGHT
and VOLUME
which must be specified with the Type
attribute. The values are case sensitive. Other measures do not require this attribute.
The weight and volume columns are shown separately from other units of measure when viewing the order line item.
<Measure Type="WEIGHT">
<Value>64.0000</Value>
<Unit>kg</Unit>
</Measure>
Containers
The <Containers>
section contains a collection of shipping containers and their details.
<Containers>
<Container>
<ContainerNumber>TCNU8840179</ContainerNumber>
<Type>42G1</Type>
</Container>
</Containers>
Note that container information can be updated by submitting an updated XML document even when the consignment has been dispatched or delivered.
Container
A container specifies the details for a single physical shipping container. Currently the only required fields are the ContainerNumber
and the Type
.
Field | Required | Format | Description |
---|---|---|---|
ContainerNumber | Yes | Container number | ISO 6436 container number |
Type | Yes | Container type code | ISO 6436 container type |
Container number
Container numbers should follow the ISO 6346 standard for container numbers.
Container numbers have a three character owner code prefix then a single character category identifier followed by a six-digit serial number and end in a single check digit. For example, TCNU8840179
is a valid container number.
Container type code
Container type codes are four character alphanumeric codes that represent the specific container type. Container type codes are case sensitive.
Container type codes in eCargo are sourced from the ISO 6346 standard for container type codes.
The container type codes below are supported by the API:
Value | Description |
---|---|
22G1 | 20 Foot General Purpose |
42G1 | 40 Foot General Purpose |
45G1 | 40 Foot High Cube |
Data types
Free text
Free text values allow only ASCII alphanumeric characters and some punctuation characters.
The following punctuation characters are supported by the API:
<space>, %, & (&), (, ), *, +, <comma>, -, ., /, :, _
Example
<Comments>Goods to be unloaded on site.</Comments>
Number
Number fields are text fields where only numeric characters are allowed.
Example
<HazardUNNo>1106</HazardUNNo>
Integer
Integer values are whole numbers without the decimal component.
The allowed characters for this value are the numeric characters.
Example
<Packet>25</Packet>
Decimal
Decimal values are numeric values with a total of 18 digits, the decimal part of the value can be a maximum of 4 digits which are counted towards the total number of digits.
The allowed characters for this value are the numeric characters and the .
decimal separator.
Order line item values with greater precision than four decimal places will be rejected; other values with greater precision will simply be rounded to four decimal places. Order line item values greater than 92,000,000,000 will also be rejected.
Example
<Weight1>8000</Weight1>
<Weight2>700.56</Weight2>
<Weight3>24850.4045</Weight3>
<Weight4>0.8795</Weight4>
Datetime
The standard format is yyyy-MM-ddTHH:mm:ss
.
Note that datetime in eCargo does not correspond to a particular timezone, please ensure that the datetime value being passed into eCargo from your system via the API are internally consistent to your system.
Section | Description |
---|---|
- | Literal character ‘-’, used as a separator within the date text |
: | Literal character ‘:’, used as a separator within the time text |
yyyy | The year as a 4 digit number |
MM | The month of the year from 01 through to 12 |
dd | The day of the month from 01 through to 31 |
T | Literal character T, used as a separator for the date and time parts |
HH | The hour using a 24 hour clock from 00 through to 23 |
mm | The minute of the hour from 00 through to 59 |
ss | The second of the minute from 00 through to 59 |
Example
<PickupDueDate>2017-09-11T08:00:10</PickupDueDate>
<DeliverDueDate>2017-09-20T13:30:00</DeliverDueDate>