Machship API Integration Workflow Guide

Machship API Integration Workflow Guide

The objective of this article is to give you a quick-start guide in working with our API to achieve common integration workflows, and how that affects which API endpoints you wish to use.

API Authentication & Documentation

  1. Our API accepts and returns JSON - full documentation is here:  https://live.machship.com/swagger/index.html#/
  2. Authentication is achieved by adding a header to your requests called "Token" with the value being your API key
  3. Tokens are generated on a user inside Machship, and inherit that users permissions.
    1. For example, if a user is unable to create consignments, only view, then the API key will have the same restrictions.
  4. We do not have a SEPERATE sandbox environment, instead users are be able to be put into "test mode", and the API key that was generated against that user would inherit that.
    1. Users in test mode create TEST consignments that are not sent to the carrier.
    2. You don't have to change any URLs or credentials when you go from live to production, just update the users test mode setting.
  5. Base URL for endpoints is  https://live.machship.com/
  6. We do not have any firewalls or rate limits on our API
Related Articles:

Important Endpoints

The main API calls you will likely use are:
  1. Generate Prices & See Carrier Options - POST /apiv2/routes/returnroutes (NOTE: do not use quotes)
  2. Create Consignments - POST /apiv2/consignments/createConsignment
    1. Create Consignments With Dangerous Goods or own barcodes - POST /apiv2/consignments/createConsignmentwithComplexItems
    2. Create Draft/Partially Filled Consignment - POST /apiv2/pendingConsignments/createPendingConsignment
    3. Search/Validate Suburb & Postcode - POST /apiv2/locations/returnLocationsWithSearchOptions 
    4. List Available Carriers On Company - GET /apiv2/companies/getAvailableCarriersAccountsAndServices
    5. Status Changes Within a Date Time Range - GET /apiv2/consignments/getRecentlyCreatedOrUpdatedConsignments
    6. Get Labels PDF - GET /apiv2/labels/getItemPdf
      1. note: this would only be used if you were planning to do your own printing internally rather than the Machship printer app
    7. Send Labels To Printer - POST /apiv2/labels/sendLabelsToPrinter
      1. note: this is only used when you don't want printing to occur at the point of consignment creation

    Common Integration Workflows

    Your API workflow will likely be one of these two, or a slight hybrid.

    Workflow #1 - You DON'T collect package dimensions, weights and types in your system

    1. Shipment/order Created in your system
    2. A pending Consignment is created in Machship via the API with FROM, TO address details, and reference numbers.
    3. User picks/packs the order, opens MS and inputs order number to search for the pre-filled consignment from step 2, then adds the packages to the pending consignment and selects a carrier
    4. Labels printed
    5. You collect updates about the consignment and push them back to your system
    While this workflow can be achieved using an API integration, it can also be achieved using a flat file integration, as the latency requirements typically don't exist as no immediate printing is being trigger.

    Further reading:

    Workflow #2 - You DO collect/have the package dimensions, weights and types in your system

    1. Shipment/order Created in your system
    2. Order packed in your system with weights/dimensions input (or known)
    3. You send CreateConsignment API call with PRINTER token. We respond with all consignment details.
    4. We instantly create consignment and trigger printing to the provided printer based on the token
    5. You collect updates and push them back to your system
    Further Reading:

    Clients tend to run either one of these workflows, or a hybrid of them.

    A hybrid example would be you sending all the orders with known dimensions as unmanifested consignments, so your team do not have to input the data, but for complex or larger orders which may be palletised, you send them through to pending.

    There are a few things to note:
    1. You may want to display shipping options/prices in your system - that would use the routes function mentioned
      1. Note - in order for this to work, you must know the packing dimensions of the shipment.
    2. You may want to validate addresses - that would use the locations function mentioned. This isn't required though. You can create consignments and we would respond if the suburb/postcode was invalid.
    3. Printing Labels - it's not required, but we do advise you leave label generation and printing to Machship as we have labels for all the carriers we support and therefore if new carriers ever need to be added or changed then no additional work is required and you can instantly start printing those labels.

    API Call Examples 

    A pending consignment create API call would look like this:

    {
       "companyId":"1234", //references the account, or sub-account, to allocate the consignment to
       "fromCompanyLocationId": "1638944", //references the address the shipment is coming from, that has been added to the Machship locations. This can be substituted for a complete FROM address as per below.
     
       //The below is not required if you use FROM company location id - which is just a stored address from the Machship address book.
       "fromName":"The Big Store",
       "fromContact":"Bob Smith",
       "fromPhone":"1234567",
       "fromAddressLine1":"1212 The Big AVENUE",
       "fromAddressLine2":"",
       "fromLocation":{
           "suburb":"MILDURA",
           "postcode":"3500"
       },
     
       "customerReference":"8855292845", //your order reference
       "customerReference2":"Test00014", //another order reference or PO number
       "specialInstructions": "string", //delivery instructions
     
       "toName":"The Company",
       "toContact":"Mary Jones",
       "toPhone":"0422 222 222",
       "toAddressLine1":"1212 SMALL AVENUE",
       "toLocation":{
           "suburb":"CROYDON",
           "postcode":"3136"
       },
       //this is used to flag some special values to the carriers. 7 is tailgate delivery, 13 means residential delivery.
       "questionIds": [7,13]
    }   
    A standard API call to create a consignment would look like this:
    {
       "companyId":"1234", //references an account of sub-account to allocate the consignment to
       "fromCompanyLocationId": "1638944", //references the address the shipment is coming from, that has been added to the Machship locations. This can be substituted for a complete FROM address as per below.
     
       //The below is not required if you use FROM company location id - which is just a stored address from the Machship address book.
       "fromName":"The Big Store",
       "fromContact":"Bob Smith",
       "fromPhone":"1234567",
       "fromAddressLine1":"1212 The Big AVENUE",
       "fromAddressLine2":"",
       "fromLocation":{
           "suburb":"MILDURA",
           "postcode":"3500"
       },
     
       "customerReference":"8855292845", //your order reference
       "customerReference2":"Test00014", //another order reference or PO number
       "specialInstructions": "string", //delivery instructions
     
       "toName":"The Company",
       "toContact":"Mary Jones",
       "toPhone":"0422 222 222",
       "toAddressLine1":"1212 SMALL AVENUE",
       "toLocation":{
           "suburb":"CROYDON",
           "postcode":"3136"
       },
     
       "items": [ 
           {
              "itemType": "Carton",
              "name": "Box 1",
              "quantity": 1,
              "height": 10,
              "weight": 20,
              "length": 30,
              "width": 40,
           }
       ],
     
       //optional - if you don't set these, it will route to the cheapest available for the job
       "carrierId": 0,
       "carrierServiceId": 0,
     
       //this is a printer token that helps to steer printing
       "printerToken":"DESK1",
     
       //this is used to flag some special values to the carriers. 7 is tailgate delivery, 13 means residential delivery.
       "questionIds": [7,13]
    }   
     

    Error Handling

    If your create consignment call errors, and you want a way for the user to be able to manually fix the issue, we recommend you send this same CreateConsignment to CreatePendingConsignment as this endpoint has less validation and the consignment can then be modified and created.

    Further Reading:

    Additional Workflows

    These workflows are lesser used than the workflows above, but are more common in high volume warehouse situations.

    Workflow #3 - Wave Picking By Carrier, With Creation & Printing At Pick

    You would use this workflow if you wanted to pick by carrier, but not pre-create the consignments. Printing is still done by Machship sending the labels to your printer.
    1. Shipment/order created in your system
    2. API request sent to returnroutes to find cheapest carrier - store cheapest carrier in the response
      1. Final package dimensions may not be known at this stage, but estimated dimensions would be required for us to provide an accurate carrier estimate
    3. Order Picked
    4. You send CreateConsignment API call with PRINTER token. We respond with all consignment details.
    5. We instantly create consignment and trigger printing to the provided printer based on the token
    6. You collect updates and push them back to your system

    Workflow #4 - Wave Picking With Machship API Printing

    You would use this workflow if you wanted to pre-create consignments so you could pick by carrier, but still have  Machship sending the labels to your printer vs doing it internally.
    1. Shipment/order created in your system
    2. You send CreateConsignment API call without printer token. We respond with all consignment details.
    3. Order Picked
    4. You send API call to sendLabelsToPrinter with consignment ID and printer token - labels print
    5. You collect updates and push them back to your system

    Workflow #5 - Wave Picking With Bulk Machship UI Printing

    You would use this workflow if you wanted to pre-create consignments so you could pick by carrier, and trigger the printing of consignments in the Machship UI.
    1. Shipment/order created in your system
    2. You log into Machship, go to the unmanifested consignments page, sort and select those you want to pick - click SEND TO PRINTER
    3. Labels print in bulk.
    4. Order Picked and labels applied.
    5. You collect updates and push them back to your system

    Workflow #6 - Wave Picking With Self Label Printing

    You would use this workflow if you wanted to pick by carrier, pre-create consignments and control your own printing.
    1. Shipment/order created in your system
    2. You send CreateConsignment API call without printer token. We respond with all consignment details.
    3. You hit /apiv2/labels/getItemPdfFileInfo and store the returned PDF document
    4. Order Picked
    5. You trigger printing of the labels internally
    6. You collect updates and push them back to your system

    Workflow #7 - (ADVANCED) Carrier Pre-Allocation, With Final Items Added Later

    You would use this workflow if you wanted to pick by carrier, pre-create consignments to get the consignment ID or barcodes, but then modify the order later.
    1. Shipment/order created in your system
    2. You send CreateConsignment API call without printer token. We respond with all consignment details.
      1. Since you don't have the dimensions yet, you should provide a best guess for an accurate carrier estimate if you're using least cost routing
      2. If you want to extract the barcodes, you need to over request items so you have enough barcodes
    3. Order Picked
    4. You send an /apiv2/consignments/editUnmanifestedConsignment API call providing us with the accurate dimensions AND the barcodes you will be using
      1. You need to ensure you pass in an accurate list of the barcodes used or the carrier will not be able to scan the goods
    5. You trigger printing of the labels internally or via Machship
    6. You collect updates and push them back to your system
    Hope that's helpful.

      • Related Articles

      • RESTful API Integration and Set up

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

      • How to Manifest via the MachShip API

        The manifesting of a consignment or a series of consignments in MachShip will finalise that consignment in the MachShip system and send through the consignment data to the transport provider. This data transfer will take place via the preferred ...

      • Customer integration overview and questionnaire

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

      • A guide to creating Consignments via the API

        Creating consignments is at the core of MachShip's functionality. Consignments describe everything related to a job that needs to travel including the pick-up location, delivery location and the individual items themselves. On top of this, a ...

      • A guide to creating Dangerous Goods Consignments via the API

        Creating consignments is at the core of MachShip's functionality. Consignments describe everything related to a job that needs to travel including the pick-up location, delivery location and the individual items themselves. On top of this, a ...