The restful API is a layer of a programming architecture that exposes a fixed, documented set of GET and POST methods that can be used to integrate advanced backend customer systems with MachShip. This layer of integration is the most advanced offered by MachShip and allows your customers to programmatically integrate their systems with MachShip and exposes all of the capabilities of the MachShip system for use from the customer's system; whilst the RESTful API offers the highest level of integration, it is also the most complex form of integration and as such, using it requires expert programming knowledge. To integrate with MachShip via RESTful API, a web developer/programmer would be required to implement the changes needed in the customer's system.
RESTful API is the industry standard method of integration between systems and is the most recommended form of integration with MachShip. RESTful APIs are two-way communication mechanisms and as such, they offer the ability for the systems to have a "conversation." This conversation allows well-structured information and errors can be raised between the systems so that programmers can "plan ahead" for these scenarios and know immediately as soon as something goes wrong.
An example of this conversation would be creating a consignment in MachShip via the RESTful API. When the customer's system creates a consignment, MachShip's API also returns information for the created consignment such as the MS Number, Carrier Consignment ID, ETA, etc. If there was an issue creating the consignment in MachShip, the API will also inform the calling system that the consignment was not created which allows the customer's system to catch the issue and run alternative actions (eg. email their IT admin, try again in a few minutes, etc.)
This API can also be used by the customer for follow up calls to ‘poll’ (ask) MachShip’s systems for information on a scheduled basis. For example, the customer's systems can ‘ask’ MachShip for the tracking history for a given consignment which can then be fed back into their own system).
An example workflow:
- Consignment created in the customer's system
- Customer's system tells MachShip's API to create the consignment in MachShip
- MachShip returns a success/error message to the customer's system. This message contains additional information that can be used by the customer
- If there are any issues, the API response will tell the customer's system EXACTLY what went wrong with the call and the customer's system can manage their own workflow accordingly
Customer Technical Level: Web Developer / Programmer
- Customer's system
- Implement code in the customer's system to interact with MachShip 's API
- MachShip system
- MachShip team
- All capabilities of MachShip including but not limited to:
- Get Prices and Routes
- Creating Consignments
- Getting Carrier References and Tracking numbers so the client can update their own ERP
- Manifesting Consignments
- Tracking Consignment Statuses
- Retrieving Consignment PODs and attachments
- Automatically download labels
- Create, Update and View Company Items
- Create, Update and View Company Locations
API Endpoint Documentation
Our API documentation is available via https://demo.machship.com/swagger. This online documentation shows the most commonly used subset of the functionality available via MachShip's API. If the customer has credentials for the demo app, they can log in to our demo system at https://demo.machship.com. Once logged in, the customer can use this API documentation tool to test the API and send test information through to the demo system.
API General Documentation
As well as our API documentation, we also provide a higher level of documentation regarding using the API which is available here.
Setup Required for API Integration
No specific setup is required for API Integration. By default, the entire API is available to all users. However, before your customer can utilise the API, they will need to be set up within MachShip like any account, with a company, user, rates, etc.
We recommend that all API users test their code against our demo and testing system at https://demo.machship.com. Our demonstration environment is completely sandboxed and no consignments, emails or manifests will be generated out into the real world, however, the full system is available for the user to integrate against. Once the customer is ready to go live, they will need to change their URL so it points to https://live.machship.com.
Once you have sent through the API documentation to your customer, MachShip can take over and help the customer with their integration. Please email us at firstname.lastname@example.org with the subject of ‘Customer API Integration Request’.
In the request, please include the following:
- Customer name.
- Customer contact details. This needs to include the contact details for both the decision makers and the technical people/developers.
- List of functionality that they would like to use (see functionality list above).
- Any other important information relating to the integration (ie. the ERP the customer is using, the programming language, etc).
- Any questions that the customer may have in regard to the integration.