Introduction

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:

Job status 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.