Consignment webhook
The consignment webhook automatically sends consignment related data from eCargo to your system.
It automatically sends the data based on a set of configurable rules e.g consignment has been assigned to a Carrier or consignment has been confirmed as dispatched. Contact eCargo regarding the setup of these rules.
When a carrier is removed from the consignment as the carrier then a withdrawn consignment webhook message is sent to the de-assigned carrier.
To subscribe to this webhook please contact eCargo support.
Authorisation and security
You will need to provide us with your HTTPS URL and credentials. Webhooks support basic authentication, so you will need to respond to unauthenticated requests with a WWW-Authenticate: Basic
header.
Response codes
When the request is posted to the subscriber’s destination endpoint, the webhook’s behaviour differs depending on the HTTP status code returned.
Status code class | Behaviour |
---|---|
2xx success | Will complete request processsing. Marked as successfully sent in eCargo. |
4xx client errors | Will not retry sending the request. Marked as failed to send in eCargo. |
5xx server errors | Will retry sending the request up to a maximum of 13 attempts. Retransmissions are spaced out using a backoff algorithm. Once all attempts fail, the message is marked as failed to send in eCargo. |
Messages will be sent sequentially to the endpoint to preserve the order of events. This means that continued 5xx errors will prevent further messages from being sent until the error is resolved or the retry limit is reached.
XML schema definition
The intention of this file is to allow third parties to conveniently generate code based on this schema. Do not use it to validate the consignment webhook content.
In the future additional elements may be added and any new additions should not be treated as a breaking change.
An XSD can be downloaded from here.
Basic structure
The consignment webhook message is a well formed XML document. It conforms to the specifications mentioned in the XML specification.
The basic structure of the message consists of the XML declaration at the top, followed by the Message
section, which contains the major sections Header
and Body
.
<?xml version="1.0"?>
<Message Version="1.0">
<Header>
...
</Header>
<Body>
...
</Body>
</Message>
Message header
The header section contains the sending and receiving party information. It also contains some diagnostic information.
Field | Format | Description |
---|---|---|
SenderID | Text | This field always has the value of ECARGO |
RecipientID | Text | Code provided by eCargo to identify recipient of the message |
Timestamp | Datetime | The date and time when this message was generated, in the format yyyy-MM-ddTHH:mm:ss |
MessageID | Text | A unique identifier for this message |
MessageType | Text | This field always has the value of CONSIGNMENT |
MessageTypeVersion | Text | This field always has the value of 1.0 |
Example
<Header>
<SenderID>ECARGO</SenderID>
<RecipientID>12345</RecipientID>
<Timestamp>2017-11-05T07:04:08</Timestamp>
<MessageID>1000000</MessageID>
<MessageType>CONSIGNMENT</MessageType>
<MessageTypeVersion>1.0</MessageTypeVersion>
</Header>
Message body
The Body
section follows on from the Header
and includes one Consignment
field which contains:
- Consignment details in the form of multiple individual fields such as
ConsignmentNumber
andComments
, see Consignment details. - One or more
Partner
elements for each consignment partner, see Consignment partners. - The
Items
element which containsItem
elements for each consignment item, see Consignment items. - The
OrderItems
element which containsOrderItem
elements for each order line item, see Order items. - The
Charges
element which containsCharge
elements for each consignment charge, see Charges. - The
StatusChange
section which is obsolete, see Status change.
<Body>
<Consignment>
...
</Consignment>
</Body>
Consignment details
Field | Format | Description |
---|---|---|
ConsignmentNumber | Text | Your consignment identifier |
ConsignmentID | Integer | eCargo unique consignment identification number |
ConsignmentStatus | Consignment status | Status of the consignment |
ManifestNumber | Text | Used if the consignment is attached to a manifest |
SalesOrderNo | Text | Your sales order number |
PurchaseOrderNo | Text | Your purchase order number |
Vehicle | Text | Name of the vehicle assigned to pick up the consignment |
Protection | Protection type | Temperature requirements for the goods to be moved |
HazardClass | Hazard class | Identifies which ERMA hazardous goods classification the consignment belongs to |
HazardUNNo | Text | The 4 digit UN number for hazardous materials |
Instructions | Text | Specific delivery instructions as passed from an ERP source |
Comments | Text | Relevant comments against the job |
IsDangerousGoods | Dangerous goods flag | Flags the consignment with dangerous goods |
IsReturn | Return flag | Flags the consignment as a return |
IsPriority | Priority flag | Flags the consignment as a priority job |
PickupDueDate | Datetime | When the consignment is due to be picked up from the pickup point in the format yyyy-MM-ddTHH:mm:ss |
DeliverDueDate | Datetime | When the consignment is due to be delivered to the delivery point in the format yyyy-MM-ddTHH:mm:ss |
PickupActualDate | Datetime | When the consignment is actually picked up from the pickup point in the format yyyy-MM-ddTHH:mm:ss |
DeliverActualDate | Datetime | When the consignment is actually delivered to the delivery point in the format yyyy-MM-ddTHH:mm:ss |
BookingRef | Text | Your booking reference |
Note that some fields will still exist in the message if it is not set on the consignment. The XML element will have no content.
Consignment status
Value | Description |
---|---|
OPEN | The consignment has not yet being offered to a carrier |
OFFERED | A carrier has been assigned to the consignment |
ASSIGNED | The carrier has allocated a pickup vehicle |
DISPATCHED | Consignment is loaded onto the vehicle and actual pickup is confirmed |
DELIVERED | Consignment has being physically delivered |
WITHDRAWN | The consignment has been cancelled |
Protection type
Value | Description |
---|---|
Ambient | Freight is transported without temperature regulation |
Chilled | Freight is transported chilled |
Frozen | Freight is transported frozen |
Hazard class
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 |
Dangerous goods flag
Value | Description |
---|---|
Y | The consignment contains dangerous goods |
N | The consignment does not contain any dangerous goods |
Return flag
Value | Description |
---|---|
Y | The consignment is a return on an originating consignment |
N | The consignment is not a return on an originating consignment |
Priority flag
Value | Description |
---|---|
Y | Consignment has been flagged as a priority job |
N | Consignment is not a priority job |
Example
<Consignment>
<ConsignmentNumber>12345</ConsignmentNumber>
<ConsignmentID>87654</ConsignmentID>
<ConsignmentStatus>ASSIGNED</ConsignmentStatus>
<ManifestNumber/>
<SalesOrderNo>45454</SalesOrderNo>
<PurchaseOrderNo>55555</PurchaseOrderNo>
<Vehicle>Truck001</Vehicle>
<Protection>Chilled</Protection>
<HazardClass/>
<HazardUNNo/>
<Instructions/>
<Comments/>
<IsDangerousGoods>N</IsDangerousGoods>
<IsReturn>N</IsReturn>
<IsPriority>N</IsPriority>
<PickupDueDate>2017-11-05T00:00:00</PickupDueDate>
<DeliverDueDate>2017-11-06T00:00:00</DeliverDueDate>
<PickupActualDate/>
<DeliverActualDate/>
<BookingRef/>
...
</Consignment>
Consignment partners
A partner is a business or a resource that plays a particular role in the delivery of the consignment.
Each individual partner is represented in a partner element.
The basic partner element contains the role, a unique identifier and the business or resource name of the partner.
Field | Format | Description |
---|---|---|
Role | Partner role | The role that the partner plays in the delivery of the consignment |
Code | Text | A unique value used to identify a partner |
Name | Text | The partner business or resource name |
Example
<Consignment>
...
<Partner>
<Role>OWNER</Role>
<Code>0083054007</Code>
<Name>Apollo Wholesale Limited</Name>
</Partner>
...
</Consignment>
The extended partner element contains address details in addition to the basic information.
This is applicable to pickup and delivery points which can be a mill or a DC, who uses eCargo to manage their inwards and outwards consignments.
Field | Format | Description |
---|---|---|
Address1 | Text | Street address |
Address2 | Text | Suburb |
City | Text | City |
PostCode | Text | Postal code |
Region | Text | Region |
Example
<Consignment>
...
<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>
...
</Consignment>
Note that partner elements will only exist if the consignment contains a partner with the particular role.
Partner role
Value | Description |
---|---|
OWNER | The business that created the consignment in eCargo, normally the customer |
PICKUP_FROM | The pickup location of the consignment |
DELIVER_TO | The delivery location of the consignment |
SOLD_TO | The business who ordered the products from the owner |
CARRIER | The prime carrier assigned to transport the consignment |
CREATED_BY | The business which created the consignment on behalf of the owner |
SUBCONTRACTOR | The sub-contractor assigned to transport the consignment |
LOGISTICS_PROVIDER | The business responsible for providing transportation services |
Consignment items
Each consignment contains a collection of one or more consignment items.
<Consignment>
...
<Items>
...
</Items>
...
</Consignment>
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.
Field | Format | Description |
---|---|---|
Description | Text | A description of the product |
Measure | Measure | The metric for the consignment item |
Example
<Item>
<Description>Palleted Goods</Description>
<Measure Type="WEIGHT">
<Value>10845.9720</Value>
<Units>kg</Units>
</Measure>
<Measure Type="VOLUME">
<Value>24.3050</Value>
<Units>m3</Units>
</Measure>
<Measure>
<Value></Value>
<Units>lifts</Units>
</Measure>
<Measure>
<Value>25.0000</Value>
<Units>pallets</Units>
</Measure>
<Measure>
<Value>4233.0000</Value>
<Units>cartons</Units>
</Measure>
<Measure>
<Value>25.0000</Value>
<Units>chep plts</Units>
</Measure>
<Measure>
<Value></Value>
<Units>loscam plts</Units>
</Measure>
</Item>
Order items
Each consignment may contain a collection of one or more order line items.
<Consignment>
...
<OrderItems>
...
</OrderItems>
...
</Consignment>
Order item
An order item is a specific product that is delivered on the consignment.
These items describe individual products that would be summarised in a consignment item.
Fields | Format | Description |
---|---|---|
OrderItemNumber | Text | Identifier for this product in your system |
Code | Text | Code used to reference the order item e.g. SKU or material number |
Description | Text | A description of the product |
Measure | Measure | The metric for the order item |
SalesOrderNumber | Text | Your sales order number |
SalesOrderLineItemNumber | Text | The sales number of the item |
Notes
The SalesOrderNumber
and SalesOrderLineItemNumber
identifies the item in the original order.
An order could consist of a large amount of items that requires multiple consignments to transport the goods to the delivery point.
These fields will be present if the value exists.
Example
<OrderItem>
<OrderItemNumber>9001</OrderItemNumber>
<Code>00002125139</Code>
<Description>LVL,R;HS,240X45,UT,A,3000</Description>
<Measure Type="VOLUME">
<Value>32.4</Value>
<Units>dm3</Units>
</Measure>
<Measure Type="WEIGHT">
<Value>19.764</Value>
<Units>Kilogram</Units>
</Measure>
<Measure>
<Value>1</Value>
<Units>Piece</Units>
</Measure>
<Measure>
<Value>3</Value>
<Units>MaxLength</Units>
</Measure>
<SalesOrderNumber>45454</SalesOrderNumber>
<SalesOrderLineItemNumber>0010</SalesOrderLineItemNumber>
</OrderItem>
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 Units
field which contains a unit of measure code.
Field | Format | Description |
---|---|---|
Value | Decimal | The quantity of the associated unit |
Units | Text | Unit of measure |
Products
Each consignment item groups and summarises a product for rating. The type of product is specified by the Description
field.
You can see a list of the products that are used by your business in eCargo, as described here.
Units
Unit of measure codes are look up values specified on the target product in eCargo, as described here. This webhook uses the Premium codes.
Weight and volume
There are two special measures with the Type
attribute.
The Type
attribute can have the value WEIGHT
or VOLUME
.
Example
<Measure Type="WEIGHT">
<Value>10845.9720</Value>
<Units>KG</Units>
</Measure>
SSCC codes
The Serial Shipping Container Code is an 18 digit code which uniquely identifies a logistic unit such as a pallet.
A consignment may contain 0 or more pallets.
This information will only be present if the relevant SSCC data exists for the consignment.
Example
<Consignment>
...
<SsccCodes>
<SsccCode>012345678902222281</SsccCode>
<SsccCode>012345678902222282</SsccCode>
<SsccCode>012345678902222283</SsccCode>
</SsccCodes>
...
</Consignment>
Field | Format | Description |
---|---|---|
SsccCode | Text | The 18 digit SSCC for a logistic unit e.g. pallet |
For more information on SSCC codes please refer to the following external links:
- GS1 New Zealand: https://www.gs1nz.org/standards/identify/sscc
- GS1 Global: https://www.gs1.org/standards/id-keys/sscc
Charges
The Charges
element contains the various charges for the associated consignment. This element always exists, even when there are no charges sent. Inside, there can be multiple Charge
elements, which define each charge for the consignment.
Charge information, when it exists, will be sent only when the recipient:
- is the carrier or owner for the consignment.
- is a logistics provider for the consignment.
Example
<Charges>
<Charge>
<RateTableType>SUPPLIER</RateTableType>
<ChargeCode>1046838</ChargeCode>
<Supplier>Reindeer Express</Supplier>
<Category>NZ_ROAD</Category>
<ChargeType>C-NZ_ROAD</ChargeType>
<MovementDate>2017-11-06T00:00:00</MovementDate>
<FromZone>North Pole</FromZone>
<ToZone>Auckland Central</ToZone>
<NetValue>49.99</NetValue>
<Extras>
<Extra>
<ExtraRate>-1.64</ExtraRate>
<ExtraValue>-0.7727</ExtraValue>
<ExtraName>Fuel Surcharge</ExtraName>
</Extra>
</Extras>
<GrossValue>46.3472</GrossValue>
<Currency>NZD</Currency>
</Charge>
</Charges>
Field | Format | Description |
---|---|---|
RateTableType | Text | The type of rate used. This field should always have the value SUPPLIER |
ChargeCode | Text | A unique identifier for the customer/supplier used by the Logistics Provider’s accounts system. |
Supplier | Text | The name of the service provider on the charge |
Category | Text | The category that the charge falls under. |
ChargeType | ChargeType | The type of charge calculation |
MovementDate | DateTime | The date the consignment moved |
FromZone | Text | The zone the consignment started from |
ToZone | Text | The zone the consignment was delivered to |
NetValue | Decimal | The base charge of the consignment |
Extras | Extras | Any additional charges incurred |
GrossValue | Decimal | The gross charge for the consignment, the sum of all base charges and extra charges. |
Currency | Text | ISO 4217 currency code |
Zones
Zones are text descriptions of geographical areas that determine a route and what is charged. FromZone
is the zone that the consignment was moved from, ToZone
is the zone that the consignment was moved to. These zones are maintained by the carrier or logistics provider in eCargo. For further details, see this guide.
Charge type
Value | Description |
---|---|
C-NZ_ROAD | A charge for road freight in New Zealand |
C-NZ_RAIL | A charge for rail freight in New Zealand |
Note: These are only the most common types, not an exhaustive list. If you receive another type, please contact eCargo support.
Example
<ChargeType>C-NZ_ROAD</ChargeType>
Extras
The Extras
element is a collection of additional charges that cannot be broken down to a typical charge.
Field | Format | Description |
---|---|---|
ExtraRate | Decimal | The rate of the additional charge |
ExtraValue | Decimal | The value of what is being charged |
ExtraName | Text | The name of the charge. This field should always have the value Fuel Surcharge |
Note
Extra Rate
andExtra Value
can be negative numbers.
Status change
This element exists as the final section of the Consignment
field.
This element is obsolete. Do not use even if value is present for any or the child elements.
<Consignment>
...
<StatusChange>
<Action/>
<Date/>
<ChangedBy/>
<Vehicle/>
<Comments/>
</StatusChange>
</Consignment>
Data types
Text
Text fields consists of alphanumeric characters and punctuation characters.
Example
<Comments>Goods to be unloaded on site.</Comments>
Number
Number fields are text fields which contains only numeric characters.
Example
<HazardUNNo>1106</HazardUNNo>
Integer
Integer values are whole numbers without the decimal component.
Example
<Packet>25</Packet>
Decimal
Decimal values are numeric values with a whole and optionally a decimal part separated by the .
decimal separator.
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.
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>