This document describes the eCargo application programming interface (API).
The production environment can be found at
https://ecargo.co.nz. There is also a test environment that we recommend
for use during development, which is available at
https://test.ecargo.co.nz. The data in the test environment is a
historical copy of the production environment, and is refreshed from time to time. All new features are deployed to the
test environment prior to deployment to production, so there may be slight differences in functionality between the two
environments. Usually, features are promoted to production after being in the test environment for several days, so the
differences between the environments should be small.
eCargo operates from a range of IP addresses as detailed below. If you require IP allow-listing for additional security, be sure to allow all of the IPs listed.
When making requests, you must use ecargo.co.nz (or test.ecargo.co.nz); do not hard code a particular IP address.
|Environment||Direction of traffic||IP addresses|
|Production - ecargo.co.nz||Ingress to eCargo||126.96.36.199 or 188.8.131.52|
|Egress from eCargo||184.108.40.206 or 220.127.116.11|
|Test - test.ecargo.co.nz||Ingress to eCargo||18.104.22.168 or 22.214.171.124|
|Egress from eCargo||126.96.36.199, 188.8.131.52, or 184.108.40.206|
All requests must present valid credentials before any processing can occur. The credentials identify who the sender of the request is and an API key to identify who they are. Refer to the documentation of each request to see how these should be presented. eCargo will provide these values prior to you using the API.
It is acceptable to add additional elements or comments into the payload to assist debugging - for example time stamps or internal reference numbers. These values will be ignored when processed by the API, but may be useful when communicating with eCargo Support.
Please note that the API is only available over HTTPS. You will receive an HTTP 404 response if you attempt to use unencrypted HTTP. You can see the versions of TLS and cipher suites supported here:
We will occasionally add new fields to an API to support new functionality, so any consumers of eCargo APIs must allow for this. However, if we rename, restructure, or remove any existing fields or features, we will publish the API under a different URL to preserve backwards compatibility.
We will contact anybody using a legacy API if we deprecate it before turning off the functionality so that you have time to move to a more recent version.
Overview of concepts
The status of a consignment changes according to the following workflow:
More detail on how this workflow can be applied can be found here:
For more details about each API see the following: