Update consignment

Update consignment API

To update a consignment, send an HTTP POST request to https://ecargo.co.nz/api.v3/UpdateConsignment or https://test.ecargo.co.nz/api.v3/UpdateConsignment.

This API accepts a list of actions to apply to a consignment that already exists in eCargo. The actions are applied in the order they are specified in the request. If any of the actions in a single request fail, they will all be rolled back and no changes will be applied.

Ensure that you have the correct authorisation scheme information in the request headers. See the authorisation section for details.

An XML schema (XSD) is downloadable below. Your API requests must be valid according to that document, so it’s recommended that you download the XSD and validate your request body prior to sending it to eCargo. Note that the XSD uses a sequence element, which means that the payloads must be submitted in a specific order; see the XSD for more detail.

Example

This is an example of a complete HTTP request, including the required headers:

POST /api.v3/UpdateConsignment HTTP/1.1
Host: ecargo.co.nz
Content-Type: application/xml; charset=utf-8
Authorization: eCargoApiKey senderId=10000,senderApiKey=...

<UpdateConsignment>
  <ConsignmentNumber>CON12345</ConsignmentNumber>
  <ConsignmentOwner>10001</ConsignmentOwner>
  <Updates>
    <UpdatePickupDueAt>
      <Date>2015-03-04</Date>
      <Time>09:00</Time>
    </UpdatePickupDueAt>
    <UpdateDeliveryDueAt>
      <Date>2015-03-04</Date>
      <Time>15:00</Time>
    </UpdateDeliveryDueAt>
    <AddProofOfDeliveryDocument>
      <MimeType>image/png</MimeType>
      <Base64EncodedContent>iVBORw0KGgoAAAANSUhEUgAABGAAAA...</Base64EncodedContent>
    </AddProofOfDeliveryDocument>
  </Updates>
</UpdateConsignment>

HTTP requests

In order to send documents to us, the documents must have a Content-Type header of application/xml. For example application/xml; charset=utf-8. The Accept header is optional, but be aware that if supplied the only acceptable type is application/xml.

Authorisation

The authorisation scheme for the API is the eCargoApiKey authorisation scheme which is stored in the Authorization header.

eCargo will provide the value of the 2 required parameters for authorisation with the API:

  • senderId
  • senderApiKey

Example

POST /api.v3/UpdateConsignment HTTP/1.1
Host: ecargo.co.nz
Content-Type: application/xml; charset=utf-8
Authorization: eCargoApiKey senderId=10000,senderApiKey=...

HTTP responses

Responses will use standard HTTP response codes.

The response for a successful submission will be an HTTP 2xx, with no content.

You will never receive a 3xx response.

Error responses will be in the 4xx and 5xx ranges, with details in the response body:

<Error>
    <ErrorType>The broad category of the error.</ErrorType>
    <Reason>The reason for rejecting your request.</Reason>
    <PossibleSolution>A suggestion that may assist in rectifying the issue.</PossibleSolution>
    <ActivityId>An ID that will assist eCargo in diagnosing the cause of failure.</ActivityId>
</Error>

Authentication failures will return the standard, unauthorized HTTP status code of 401.

For security reasons, if eCargo is unable to automatically determine the cause of a failure, a generic error will be returned.

All responses will include an eCargo-ActivityId header. This is a unique identifier that you can quote to eCargo support and will assist us in diagnosing the cause of failure. Error responses will usually also include the ‘Activity ID’ in the XML body.

Note that, if any of the actions in a single request fail, they will be rolled back and no changes will be applied. It is safe to retry requests because the API is idempotent.

Also note that there is no X- prefix on the custom activity ID header because this practice has been deprecated by RFC 6648.

XML schema definition

An XSD can be downloaded from here.

Fields

There are two ways to specify a consignment in eCargo: by eCargo consignment ID, or by a combination of consignment number and consignment owner. Which one you choose to use will depend on what information you have available in your system. If you specify the consignment ID, the consignment number and consignment owner will be ignored.

Specify a consignment by owner and number

If you do not specify the consignment ID, you’ll need to specify both the ConsignmentNumber and ConsignmentOwner. These are used to determine the specific consignment to be updated.

ConsignmentNumber is the primary reference number of the consignment as viewed in eCargo. It is often referred to as the delivery number.

ConsignmentOwner represents the Customer as viewed in eCargo.

To determine the ConsignmentOwner value.

  1. Log in eCargo Online with a user that has administrative rights.
  2. Go to the Admin menu and select My Customers.
  3. From the list select the business owning the consignment you are interested in.
  4. In the Details tab use the Business Id value as the ConsignmentOwner.
<UpdateConsignment>
  <ConsignmentNumber>CON12345</ConsignmentNumber>
  <ConsignmentOwner>10001</ConsignmentOwner>
  <Updates>
    ...
  </Updates>
</UpdateConsignment>

Specify a consignment by eCargo consignment ID

The ConsignmentId field unambiguously identifies a unique consignment in eCargo. If you specify this, the consignment number and consignment owner fields will be ignored. To get the consignment ID, you’ll need to be using another API, which you would have set up previously with eCargo support. If you have not done this, use the consignment number / consignment owner combination above.

<UpdateConsignment>
  <ConsignmentId>123456</ConsignmentId>
  <Updates>
    ...
  </Updates>
</UpdateConsignment>

Updates

Updates is the list of one or more updates to apply to the consignment. The commands that are accepted are in this section.

Update pickup due at

UpdatePickupDueAt accepts the date and time as separate fields. The date is a simple ISO 8601 date of the format YYYY-MM-DD. The time can either be a 24 hour local time in the format HH:MM, or one of PreserveExisting or ClearExisting. Both parts are mandatory. PreserveExisting means to keep the time that is currently associated with the pickup date in eCargo. ClearExisting will remove any time that was associated with the pickup date; if that time was not previously set, then nothing will change, but if a time was previously set either via the API or another interface to eCargo, then that time will be cleared.

Sample valid updates:

<UpdatePickupDueAt>
  <Date>2015-04-03</Date>
  <Time>18:00</Time>
</UpdatePickupDueAt>

<UpdatePickupDueAt>
  <Date>2015-04-03</Date>
  <Time>PreserveExisting</Time>
</UpdatePickupDueAt>

<UpdatePickupDueAt>
  <Date>2015-04-03</Date>
  <Time>ClearExisting</Time>
</UpdatePickupDueAt>

Sample invalid updates:

<UpdatePickupDueAt></UpdatePickupDueAt>

<UpdatePickupDueAt>
  <Date></Date>
  <Time>PreserveExisting</Time>
</UpdatePickupDueAt>

<UpdatePickupDueAt>
  <Date>ClearExisting</Date>
  <Time>12:00</Time>
</UpdatePickupDueAt>

Update delivery due at

UpdateDeliveryDueAt accepts the date and time as separate fields. The date is a simple ISO 8601 date of the format YYYY-MM-DD. The time can either be a 24 hour local time in the format HH:MM, or one of PreserveExisting or ClearExisting. Both parts are mandatory. PreserveExisting means to keep the time that is currently associated with the delivery date in eCargo. ClearExisting will remove any time that was associated with the delivery date; if that time was not previously set, then nothing will change, but if a time was previously set either via the API or another interface to eCargo, then that time will be cleared.

Sample valid updates:

<UpdateDeliveryDueAt>
  <Date>2015-04-03</Date>
  <Time>18:00</Time>
</UpdateDeliveryDueAt>

Sample invalid updates:

<UpdateDeliveryDueAt>
  <Date>2015-04-03</Date>
</UpdateDeliveryDueAt>

<UpdateDeliveryDueAt>
  <Date>2015-04-03</Date>
  <Time></Time>
</UpdateDeliveryDueAt>

Assign vehicle

The AssignVehicle command must have a vehicle name value, which is a free text field with a maximum length of 50 characters.

Sample valid updates:

<AssignVehicle>
  <VehicleName>3485/3780STRAIGHTDUNEDIN</VehicleName>
</AssignVehicle>

Sample invalid updates:

<AssignVehicle>
  <VehicleName/>
</AssignVehicle>

<AssignVehicle/>

Assign carrier subcontractor

The AssignCarrierSubcontractor command must have a SubcontractorCode.

To determine the SubcontractorCode value:

  1. Log in eCargo Online with a user that has administrative rights.
  2. Go to the Admin menu and select My Carriers.
  3. From the list select the carrier you are interested in.
  4. In the Details tab use the Business Id value as the SubcontractorCode.

When there is an existing subcontractor on the consignment assigning a different subcontractor via the AssignCarrierSubcontractor command will update the subcontractor on the consignment with the new value.

Sample valid updates:

<AssignCarrierSubcontractor>
  <SubcontractorCode>1234</SubcontractorCode>
</AssignCarrierSubcontractor>

Sample invalid updates:

<AssignCarrierSubcontractor>
  <SubcontractorCode></SubcontractorCode>
</AssignCarrierSubcontractor>

<AssignCarrierSubcontractor/>

Set booking reference

The SetBookingReference command can have a booking reference value, which is a free text field with a maximum length of 1000 characters. If an empty value is supplied, it will remove the existing value.

Sample valid updates:

<SetBookingReference>
  <BookingReference>VLM155019</BookingReference>
</SetBookingReference>

<SetBookingReference>
  <BookingReference/>
</SetBookingReference>

Sample invalid updates:

<SetBookingReference/>

Dispatch consignment

The DispatchConsignment command takes a time-zone neutral local date and time in the format YYYY-MM-DDTHH:MM:SS.

The DepartedAt date/time is the movement date used for billing purposes, and is usually the date/time that the vessel or vehicle left the pickup point.

For those who use the “dwell time” feature, there are two date/times relevant to the pickup and delivery points - when the vehicle arrived, and when it left. If the arrival date/time is not set when this command is used, the arrival date/time will be set to the departure date/time.

If the vehicle name was not set prior to this command being used, the vehicle name will be set to “Unassigned”.

Sample valid updates:

<DispatchConsignment>
  <DepartedAt>2017-01-16T08:45:00</DepartedAt>
</DispatchConsignment>

Sample invalid updates:

<DispatchConsignment>
  <DepartedAt>2017-01-16</DepartedAt>
</DispatchConsignment>

<DispatchConsignment>
  <DepartedAt>16/1/2017 8:45 a.m.</DepartedAt>
</DispatchConsignment>

<DispatchConsignment>
  <DepartedAt></DepartedAt>
</DispatchConsignment>

<DispatchConsignment />

Deliver consignment

The DeliverConsignment command takes a time-zone neutral local date and time in the format YYYY-MM-DDTHH:MM:SS.

The ArrivedAt date/time is the movement date used for reporting purposes, and is usually the date/time that the vessel or vehicle arrived at the delivery point.

For those who use the “dwell time” feature, there are two date/times relevant to the pickup and delivery points - when the vehicle arrived, and when it left. When this command is used, both the arrival date/time and the departure date/time will be set to the ArrivedAt date/time value.

Sample valid updates:

<DeliverConsignment>
  <ArrivedAt>2017-01-16T08:45:00</ArrivedAt>
</DeliverConsignment>

Sample invalid updates:

<DeliverConsignment>
  <ArrivedAt>2017-01-16</ArrivedAt>
</DeliverConsignment>

<DeliverConsignment>
  <ArrivedAt>16/1/2017 8:45 a.m.</ArrivedAt>
</DeliverConsignment>

<DeliverConsignment>
  <ArrivedAt></ArrivedAt>
</DeliverConsignment>

<DeliverConsignment />

Set quantity for unit of measure on consignment item

The SetQuantityForUnitOfMeasureOnConsignmentItem command sets the quantity of a single unit of measure on a single consignment item. Two of the fields, ItemDescription and UnitOfMeasureCode, are used to select the quantity to set.

The ItemDescription is the description of the consignment item. The description for a given consignment can be found in the Job Details page of Web Dispatch in the Item column e.g. Palleted Goods.

Duplicate consignment items on the same consignment are not supported. A consignment cannot, for example, have 2 or more Palleted Goods items.

Valid values for the UnitOfMeasureCode field can be found in the New APIs column on the units of measure page.

The Quantity is a decimal field which can be empty (denoting no value), zero, or any positive value in the range which decimal supports. Negative values are not allowed.

An empty quantity value will erase the existing quantity value.

Sample valid updates:

<SetQuantityForUnitOfMeasureOnConsignmentItem>
    <ItemDescription>Palleted Goods</ItemDescription>
    <UnitOfMeasureCode>kg</UnitOfMeasureCode>
    <Quantity>12.3456</Quantity>
</SetQuantityForUnitOfMeasureOnConsignmentItem>

<SetQuantityForUnitOfMeasureOnConsignmentItem>
    <ItemDescription>Palleted Goods</ItemDescription>
    <UnitOfMeasureCode>pallet</UnitOfMeasureCode>
    <Quantity>1234</Quantity>
</SetQuantityForUnitOfMeasureOnConsignmentItem>

<SetQuantityForUnitOfMeasureOnConsignmentItem>
    <ItemDescription>Palleted Goods</ItemDescription>
    <UnitOfMeasureCode>pallet</UnitOfMeasureCode>
    <Quantity></Quantity>
</SetQuantityForUnitOfMeasureOnConsignmentItem>

Sample invalid updates:

<!-- Missing item description. -->
<SetQuantityForUnitOfMeasureOnConsignmentItem>
    <ItemDescription></ItemDescription>
    <UnitOfMeasureCode>pallet</UnitOfMeasureCode>
    <Quantity>1234</Quantity>
</SetQuantityForUnitOfMeasureOnConsignmentItem>

<!-- Missing unit of measure code. -->
<SetQuantityForUnitOfMeasureOnConsignmentItem>
    <ItemDescription>Palleted Goods</ItemDescription>
    <UnitOfMeasureCode></UnitOfMeasureCode>
    <Quantity>1234</Quantity>
</SetQuantityForUnitOfMeasureOnConsignmentItem>

<!-- Negative quantity. -->
<SetQuantityForUnitOfMeasureOnConsignmentItem>
    <ItemDescription>Palleted Goods</ItemDescription>
    <UnitOfMeasureCode>kg</UnitOfMeasureCode>
    <Quantity>-12.3456</Quantity>
</SetQuantityForUnitOfMeasureOnConsignmentItem>

<SetQuantityForUnitOfMeasureOnConsignmentItem>
    <ItemDescription>Palleted Goods</ItemDescription>
    <UnitOfMeasureCode>pallet</UnitOfMeasureCode>
    <Quantity>-1</Quantity>
</SetQuantityForUnitOfMeasureOnConsignmentItem>

<!-- Invalid decimal quantity. -->
<SetQuantityForUnitOfMeasureOnConsignmentItem>
    <ItemDescription>Palleted Goods</ItemDescription>
    <UnitOfMeasureCode>pallet</UnitOfMeasureCode>
    <Quantity>abcd</Quantity>
</SetQuantityForUnitOfMeasureOnConsignmentItem>

Set multiple quantities

The SetQuantityForUnitOfMeasureOnConsignmentItem command can be repeated to set other quantities on the same consignment item or quantities on a different consignment item on the same consignment using a single API request.

Sample multiple update:

<UpdateConsignment>
    <ConsignmentNumber>CON12345</ConsignmentNumber>
    <ConsignmentOwner>10001</ConsignmentOwner>
    <Updates>
        <SetQuantityForUnitOfMeasureOnConsignmentItem>
            <ItemDescription>Palleted Goods</ItemDescription>
            <UnitOfMeasureCode>kg</UnitOfMeasureCode>
            <Quantity>50.5</Quantity>
        </SetQuantityForUnitOfMeasureOnConsignmentItem>
        <SetQuantityForUnitOfMeasureOnConsignmentItem>
            <ItemDescription>Palleted Goods</ItemDescription>
            <UnitOfMeasureCode>pallet</UnitOfMeasureCode>
            <Quantity>12</Quantity>
        </SetQuantityForUnitOfMeasureOnConsignmentItem>
        <SetQuantityForUnitOfMeasureOnConsignmentItem>
            <ItemDescription>Palleted Goods</ItemDescription>
            <UnitOfMeasureCode>lift</UnitOfMeasureCode>
            <Quantity>40</Quantity>
        </SetQuantityForUnitOfMeasureOnConsignmentItem>
        <SetQuantityForUnitOfMeasureOnConsignmentItem>
            <ItemDescription>Cartons</ItemDescription>
            <UnitOfMeasureCode>carton</UnitOfMeasureCode>
            <Quantity>13</Quantity>
        </SetQuantityForUnitOfMeasureOnConsignmentItem>
    </Updates>
</UpdateConsignment>

Add proof of delivery document

The AddProofOfDeliveryDocument command adds a proof of delivery document in the form of an image file to the consignment. The consignment must have a supported status of Open, Offered, Assigned, Dispatched or Delivered before a proof-of-delivery document can be added.

There are two mandatory values used by the command, MimeType and Base64EncodedContent.

  • MimeType denotes the file type of the proof of delivery document.
  • Base64EncodedContent is the binary data of the document encoded in base64.

The supported MimeType values are:

  • image/png denotes a Portable Network Graphics file (PNG).
  • image/tiff denotes a Tag Image File Format file (TIFF).
  • image/jpeg denotes a Joint Photographic Experts Group image file (JPG, JPEG).
  • application/pdf denotes an Adobe Portable Document Format file (PDF).

The allowed MimeType value must match exactly e.g. iMAgE/pNg will be rejected as unsupported.

Formats which support multiple pages such as TIFF and PDF must only include a single page.

References to MIME types can be found on this Internet Assigned Numbers Authority page.

The command allows up to a maximum of 5 MiB for the proof of delivery document, please ensure that the document size is not over this limit before encoding it in base64 for Base64EncodedContent.

Note that this command is idempotent and will not add duplicate proof of delivery documents to the same consignment.

Sample valid updates:

<AddProofOfDeliveryDocument>
    <MimeType>image/png</MimeType>
    <Base64EncodedContent>iVBORw0KGgoAAAANSUhEUgAABGAAAA...</Base64EncodedContent>
</AddProofOfDeliveryDocument>

Sample invalid updates:

<AddProofOfDeliveryDocument>
    <MimeType>image/bmp</MimeType>
    <Base64EncodedContent>iVBORw0KGgoAAAANSUhEUgAABGAAAA...</Base64EncodedContent>
</AddProofOfDeliveryDocument>

<AddProofOfDeliveryDocument>
    <MimeType>image/png</MimeType>
    <Base64EncodedContent>iVB%*@#goAAAANS(@!)UgA    A~A...</Base64EncodedContent>
</AddProofOfDeliveryDocument>

<AddProofOfDeliveryDocument>
    <MimeType>image/png</MimeType>
</AddProofOfDeliveryDocument>

<AddProofOfDeliveryDocument>
    <MimeType>image/png</MimeType>
    <Base64EncodedContent></Base64EncodedContent>
</AddProofOfDeliveryDocument>

<AddProofOfDeliveryDocument>
    <MimeType></MimeType>
</AddProofOfDeliveryDocument>

<AddProofOfDeliveryDocument />

Adding multiple proof of delivery documents

A consignment can have multiple proof of delivery documents and this can be achieved with a single API request with multiple update commands.

Note that you may make multiple API requests to add more proof of delivery documents to the consignment.

Sample multiple update:

<UpdateConsignment>
  <ConsignmentNumber>CON12345</ConsignmentNumber>
  <ConsignmentOwner>10001</ConsignmentOwner>
  <Updates>
    <AddProofOfDeliveryDocument>
      <MimeType>image/png</MimeType>
      <Base64EncodedContent>iVBORw0KGgoAAAANSUhEUgAABGAAAA...</Base64EncodedContent>
    </AddProofOfDeliveryDocument>
    <AddProofOfDeliveryDocument>
      <MimeType>image/png</MimeType>
      <Base64EncodedContent>iVBORw0KGgoAAAANSUhEUgAABG8AAA...</Base64EncodedContent>
    </AddProofOfDeliveryDocument>
  </Updates>
</UpdateConsignment>

Add proof of delivery URL

The AddProofOfDeliveryUrl command adds a link to a proof-of-delivery page or website, in the form of a URL attached to the consignment. The consignment must have a supported status of Open, Offered, Assigned, Dispatched or Delivered before a proof-of-delivery URL can be added.

There is a single mandatory value used by this commmand: Url, which must contain a valid HTTPS URL.

Please note that this command is idempotent and will not add duplicate URLs to the same consignment.

Sample valid updates:

<AddProofOfDeliveryUrl>
    <Url>https://example.com/document</Url>
</AddProofOfDeliveryUrl>

Sample invalid updates:

<AddProofOfDeliveryUrl>
    <Url>http://example.com/document</Url>
</AddProofOfDeliveryUrl>

<AddProofOfDeliveryUrl>
    <Url></Url>
</AddProofOfDeliveryUrl>

<AddProofOfDeliveryUrl />

Adding multiple proof-of-delivery URLs

A consignment can have multiple proof-of-delivery URLs and this can be achieved with a single API request with multiple commands.

Note that you may also make multiple API requests to add more proof-of-delivery URLs to the consignment.

Sample multiple update:

<UpdateConsignment>
  <ConsignmentNumber>CON12345</ConsignmentNumber>
  <ConsignmentOwner>10001</ConsignmentOwner>
  <Updates>
    <AddProofOfDeliveryUrl>
      <Url>https://example.com/document1</Url>
    </AddProofOfDeliveryUrl>
    <AddProofOfDeliveryUrl>
      <Url>https://example.com/document2</Url>
    </AddProofOfDeliveryUrl>
  </Updates>
</UpdateConsignment>

Set received order line items

Received order line items represent the actual order line items received at the delivery point. They can be compared with the expected order line items. Received order line items can be set on consignments with any status.

<SetReceivedOrderLineItems>
    <OrderLineItems>
        <OrderLineItem>
            <Code>ABC123</Code>                         <!-- mandatory - see details below -->
            <Description>Delicious Soup</Description>   <!-- mandatory - see details below -->
            <WeightKilogram>64</WeightKilogram>         <!-- optional, maximum 4 d.p. -->
            <VolumeCubicMetre>0.2050</VolumeCubicMetre> <!-- optional, maximum 4 d.p. -->
            <Measure>                                   <!-- optional, but no more than five -->
                <Value>32.0000</Value>                  <!-- mandatory, maximum 4 d.p. -->
                <Unit>cartons</Unit>                    <!-- mandatory, see detail in documentation -->
            </Measure>
        </OrderLineItem>
        <!-- More OrderLineItem elements are allowed here -->
    </OrderLineItems>
</SetReceivedOrderLineItems>

The Code is limited to 200 characters, and Description is limited to 60 characters. Combined, they uniquely identify the order line item. The Unit can be found on the units of measure page. You will need to send us the value in the New APIs column.

Withdraw consignment

The WithdrawConsignment command takes an optional comment, which is a free text field, with a maximum length of 2000 characters. This command must be the only or last command to appear in the request.

Sample valid updates:

<WithdrawConsignment>
  <Comment>This is a comment.</Comment>
</WithdrawConsignment>

<WithdrawConsignment>
  <Comment></Comment>
</WithdrawConsignment>

<WithdrawConsignment/>

Sample invalid updates:

<WithdrawConsignment>
  <Comment>... over 2000 characters ...</Comment>
</WithdrawConsignment>

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

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>, %, & (&amp;), (, ), *, +, <comma>, -, ., /, :, _

Example

<Comments>Goods to be unloaded on site.</Comments>

Decimal

Decimal values are non-negative values with up to 4 decimal places and a maximum allowable value of 99,999,999.9999.

The allowed characters for this value are the numeric characters and the . decimal separator. No thousands separator is supported.

Example

<Rate>8000</Rate>
<Rate>700.56</Rate>
<Rate>24850.4045</Rate>
<Rate>0.8795</Rate>