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.

Please note that the API is only available over HTTPS. You will receive an HTTP 404 response if you attempt to use unencrypted HTTP.

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.

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.

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.