Our API documentation is designed to be used as a guide for integrating your system directly into MachShip.
This documentation describes the technical details of dealing with MachShip’s API layer, the security requirements and provides links to further API definition documentation.
The current API is currently version 2 and all our documentation relates to this version of the API.
All MachShip's functionality is available via the API, however, we have documented a subset of the most commonly used functions with MachShip. If you require further documentation on functionality that is not currently documented, please email the MachShip team at email@example.com
MachShip API Introduction
MachShip provides a fully featured, first class RESTful API layer using well-defined JSON objects. All requests to MachShip are either a POST or a GET which is documented in our API technical documentation.
The API layer can only be communicated via HTTPS over SSL.
All API calls require a valid API token which is described below.
MachShip provides a testing mode which can be utilized when training a new user or testing an integration. This mode is completely sandboxed which means that it will not issue any external API calls to carriers but will show you exactly how MachShip would work under those circumstances.
To learn more about the test environment. Please go to this link.
In order to generate a Test API user, you will first need to create a user in Test mode where you will also be able to generate an API token.
To learn on how to create test API user, click on this link.
Once you are ready to use the live environment, you can update your user to stop them from being in test mode. This will allow a user to see and create live consignments and manifest them.
Authentication with MachShip
All requests to MachShip require a valid API token. This token can be generated by logging in to MachShip and adding a new token to your user. Our authentication uses a bearer token to authenticate the caller and must be provided on each request to MachShip. This bearer token must be added as a header like so:
If you created a Test API user and generated an API token, it will be the same API token you will use when you decide to stop your user from being in test mode. There is no need to regenerate a new API token.
We provide a ping endpoint which you can use to test that your token is valid. If it returns a 200 and object = true, then you have successfully authenticated with MachShip.
POST https://demo.machship.com/apiv2/authenticate/ping HTTP/1.1
Successful Ping Response:
If you are receiving a 401 Unauthorized response, please check the following:
- You have correctly entered your API token as a header with the token as the key
- Contact the API token issuer to check that the token is still valid
Our online API definition documentation can be found at https://live.machship.com/swagger.
If you click the Authorize button at the top of the page and enter your API token, you can then call MachShip’s API directly from within this documentation. This allows you to test your API calls and JSON objects directly through the browser. Examples of the objects in both the requests and responses can be found in this API help documentation.
Questions and API Help
If you have any questions regarding the API or you are after additional documentation, please email the MachShip team at firstname.lastname@example.org