MachShip – Customer-Side Integrations

We offer several methods of integration so that a customer's system can integrate directly with MachShip so as to avoid manual intervention or duplicate data entry. These systems differ in complexity and capability and as such, this document is designed to guide you through the process of choosing the most appropriate method of integration.

There are two main types of automated integration offered by MachShip:

1. RESTful API
2. File API

These integrations are completely automated and require varying degrees of input from the customer. Alternatively, if automatic integration is not possible, the customer can use MachShip's website to create consignments and use tools such as the consignment import to speed up their processes.

Here is a brief description of each API.

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

Integration Level: High

Customer Technical Skill Level Required: High

Additional Setup Required: Low

Further information and setting up a client with MachShip's RESTful API

File API

As many customer systems may be limited in their flexibility and programmability, the File API is designed to support integration with existing file-based transfer mechanisms employed by many older software systems. The File API is designed with flexibility and ease of use in mind and as such, it can support the transfer of information from customer systems via two methods: ‘FTP/SFTP’ and ‘Folder Polling’.

File transfer methods of integration are one-way communication mechanisms and as such, they offer no error checking or bi-directional/conversational programming options (often referred to as ‘fire and forget’ APIs). File transfer methods do not initiate a conversation which means the customer's system has no way of knowing whether an action was successful or not. For example, a file is sent to MachShip to create a consignment however the suburb is invalid. File transfer offers no feedback and there is no way of the customer's system automatically knowing if an action completed successfully.

Use of File APIs is less desirable that the more modern RESTful APIs and other two-way communication mechanisms for systems, however, MachShip recognises that they are a necessary evil because of the age and inflexibility of many customer systems and as such, we offer methods of use for these File based transfer systems.

All of the File API options require some setup in the MachShip system, potentially the customer systems and in the case of Folder Polling, some setup is required locally on the computer on which the MachShip App is installed.

MachShip specifies a "generic" file format that will cater to the needs of most customers. If possible, it is recommended that the customer uses MachShip standard file format for the File API. If the customer is not able to generate MachShip's standard file format, MachShip can be configured to use the customer's own custom format, however, this work is charged at the rate at which you have agreed when signing up with MachShip.

FTP/SFTP

FTP refers to ‘File Transfer Protocol’ which is an internet-based data transfer mechanism much like HTTP (Hyper-Text Transfer Protocol) which is what you would be used to seeing at the start of web addresses that you type into your browser.

SFTP is ‘Secure FTP’ and is designed to encrypt file data sent across the internet similar to HTTPS (HTTP Secure) whilst using the same base protocol of FTP.

Both methods of FTP are essentially the same from the user’s point of view as both will likely require the use of a username and password for MachShip to point to.

Integration Level: Medium

Customer Technical Skill Level Required: Medium

Additional Setup Required: High

Folder Polling and Pushing

Folder Polling and Pushing is an alternative to FTP based file transfer which is intended for use in circumstances where the customer's systems do not offer even an FTP based file transfer mechanism.

The Folder Polling and Pushing is facilitated by the use of the ‘MachShip App’, which is the same program that MachShip produces to allow for automatic printing of documentation and labels at customer sites.

‘Folder Polling’ refers to a practice whereby the installed MachShip App will ‘watch’ a folder(s) on a customer's server or computer for files and wait for those files to appear. When the files eventually appear, the MachShip App will pick them up and transfer them to MachShip using the RESTful API so that the appearance and functionality of an FTP transfer method are realised and achieved.

'Folder Pushing' is the reverse of Polling where MachShip will 'push' a file out to the MachShip App, which will then put the file in a specific folder. The customer's system can then monitor this folder and use these files internally.

Integration Level: Medium

Customer Technical Skill Level Required: Low

Additional Setup Required: Low

Website

The website is literally the MachShip website. This is the lowest level of integration and requires human interaction. Whilst the MachShip website is fully featured, it is designed purely for human interaction and is actually built directly on top of the RESTful API. Whilst use of the website for systems integration is possible through means such as ‘web-scraping’, these methods are extremely inefficient and in circumstances where one may be tempted to use web-scraping or the like, they likely have the knowledge and experience which would allow them to use the RESTful API and as such, no support for such methods of integration are offered by MachShip .

Through the MachShip website, the user can still use tools such as the consignment import or batch consignments to manage large rollouts.

Functionality

• All MachShip functionality

Which one to use?

With all of the APIs mentioned above, you may be wondering, “Which one is for me?”.

The information below should help guide you through the process of choosing the most appropriate integration method. Follow the instructions below and skip to the steps where advised – at the end of the process, you should know which method is best suited for your customer.

Integration Tiers

The integrations listed above can be used by your customers to interact with MachShip, however, each integration will have varying costs to set up for either your customer or your organisation. These costs vary based on the type of integration is required by your customer and we have broken these integrations into 3 tiers:

Tier 1: Out of the box Integrations

These integrations can be set up through MachShip without needing approval or customisation from the MachShip team. These methods can be offered to all customers and MachShip will provide supporting documentation to help integrate your customers. Where possible, this is the recommended level of integration that can be offered to all customers. 

• RESTful API
• Folder Polling with MachShip's generic file importer

Tier 2: Out of the box Integrations with well structured CSV, XML or TXT files

Tier 2 integrations would exist under the circumstances that a clients system can produce a well-structured XML or delimited file which can be mapped through the MachShip workflow engine.

Information on how this can be completed can be found in the section linked below:

Workflows

• FTP/SFTP or Folder Polling with well-structured custom file format
  • Any deviation from the standard "generic" file format requires development on MachShip's end and will be charged at the rate at which you have agreed when signing up with MachShip.

All of this can be configured within MachShip. Should you utilise an ftp method please look to raise a support ticket with the MachShip support team so that the setup can be completed to poll the required ftp server. 

Tier 3: Custom Integrations

Tier 3 integrations require complete customisation and MachShip will need to be heavily involved in the scoping process to determine what developments need to be done, which will be charged at the rate at which you have agreed when signing up with MachShip.

• Any work or alterations that have not been listed above. Examples of this include:
  • Sending a custom file at a specific time of day
  • Any other form of work or integration required by the customer.

Understanding and evaluating the Customer Questionnaire

Below is a guide on how to read and understand which API would be suitable for your customer and how to determine which integration is the most suitable for your customer based on the answers they have provided for the below questions.

What systems does your organisation use that would need to integrate with MachShip? For example, your ERP system.

This is good background information which in itself does not point to an integration, but it will let the MachShip team start researching the platform and determine its capabilities.

Which of the following pieces of functionality would your system require to be automated? Which pieces of functionality will be manually triggered/entered by a member of your organisation?

• Get Prices and Routes (RESTful API only)
• Creating Consignments or Orders (these are known as Pending consignments in MachShip) (Any integration method)
• Updating information such as Carrier References and Tracking numbers in your own system (RESTful API, FTP) 
• Manifesting Consignments (RESTful API only)
• Tracking Consignment Statuses (RESTful APII and Integration Events)
• Retrieving Consignment PODs and attachments (RESTful API and Integration Events)
• Downloading labels (RESTful API or automatic printing through the MachShip App)
• Create, Update and View Saved Items (RESTful API only)
• Create, Update and View Saved Locations (RESTful API only) 

Are you currently integrated with another Freight Management System (FMS) like MachShip? If so:

• Which pieces of functionality does your current integration currently implement?
• Which pieces of functionality from the list above are required for integration with MachShip?
• How are you currently integrated? Please provide as much information as possible
  • Do you use their API?
  • Does your system send files to the FMS via FTP?
  • Does the FMS read from your FTP?
  • Does the FMS read from a folder inside your network?
  • Do you upload a file once a day?
  • If the integration is any other form, please provide as much detail as possible
• Can you please provide example files / API calls with what your system is currently producing for integration?

This is background information and will help determine which integration path the customer will most likely want to pursue. For example, if the customer is currently using FTP, they will most likely want to continue using FTP as it is less change on their end.

Do you have a developer/programmer as part of your IT team OR do you have an external developer available capable of integrating with MachShip's RESTful API?

Are you interested in integration via MachShip's API? MachShip's API provides the highest level of integration, however, development will be required from within your systems.

These 2 questions are very important to determine the technical skill level and desire of their organisation. If possible, we always recommend integration via API as this provides the deepest level of integration possible. However, the technical skill needs to be there on the customers' end, whether that be in-house developers or an external resource that can implement the changes on their behalf.

If you or your customer has answered YES to both of these questions, it is HIGHLY RECOMMENDED that they use MachShip's RESTful API for integration.

If they answered NO to either of these questions, please continue on to the next set of questions.

If you are looking to create consignments or orders via integration, is your system capable of exporting well structure file like a CSV, JSON or XML file containing information.

If the client can export a well-structured file then the potential is there to use the MachShip Workflow engine to map up a custom import for this file. Please contact support@machship.com if you require any help with this. 

Would you like to or do you currently send the files through to an FTP server? 

If YES, the customer can be integrated via FTP. Once the file has been mapped up using the MachShip workflow engine please contact support@machship.com to have an FTP directory created for you. 

Do the files get written to a directory on a computer for which you are able to install the MachShip App to monitor and poll this folder? Can this computer communicate out to the public internet?

If YES, the customer can be integrated via the MachShip App's Folder polling.

If the customer answered NO to the last 2 questions, then integration with MachShip is either not possible or an entire custom solution will need to be developed. If you are certain that some kind of integration is necessary, you will need to approach MachShip to discuss the scoping of some extra programming to facilitate the integration, however, requests for custom integrations are not guaranteed to be approved.