RESTful API

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

Setup

• Customer's system
  • Implement code in the customer's system to interact with MachShip 's API
• MachShip system
  • None
• MachShip team
  • None

Functionality

• 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://live.machship.com/swagger/.  This online documentation shows the most commonly used subset of the functionality available via MachShip's API. If the customer has username credentials for the Machship system, they can log in at https://live.machship.com. If the user is in test mode, once logged in, they can use this API documentation tool to test the API by sending test information through to the MachShip.

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 new users or clients use our testing mode where they can create test carrier accounts, test consignments and even manifests without pushing any data to transport providers. Our testing environment is completely sandboxed.

MachShip Support

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 support@machship.com 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.