Consignment webhook

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.

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. In no way should it be used to comprehensively validate the consignment webhook content.

In the future additional optional 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 and Comments, see Consignment details.
  • One or more Partner elements for each consignment partner, see Consignment partners.
  • The Items element which contains Item elements for each consignment item, see Consignment items.
  • The OrderItems element which contains OrderItem elements for each order line item, see Order items.
  • The Charges element which contains Charge 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>
        <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>

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 Unit field which contains a unit of measure code.

Field Format Description
Value Decimal The quantity of the associated unit
Unit 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.

Unit

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>
    <Unit>KG</Unit>
</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:

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 and Extra 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>