API
This document describes the eCargo application programming interface (API).
Testing environment
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.
IP addresses
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 | 34.87.239.246 or 35.197.190.183 |
Egress from eCargo | 34.87.201.78 or 35.244.118.33 | |
Test - test.ecargo.co.nz | Ingress to eCargo | 35.201.0.42 or 35.244.82.21 |
Egress from eCargo | 34.87.237.15, 35.197.162.138, or 122.56.82.80 |
Requests
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.
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:
Versioning
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:
Terms of use
Use of the eCargo API constitutes acceptance of the API terms of use.