Being able to easily and accessibly obtain tracking, pricing and consignment information from despatched orders is another core capability of the MachShip platform. Furthermore, MachShip's RESTful API can be utilized in order to allow for easy passing of this information between any of your business other management systems.
MachShip's vast range of API endpoints allows a user to leverage any number of key references in order to pull back consignment information. This article will outline the properties and steps required to
GET Consignment Request Parameters
The GET Consignments endpoints are GET endpoints that allow a user to be able to query for the latest information for an individual consignment:
This is completed by passing through either
Order (Pending Consignment)
/apiv2/consignments/getConsignmentByPendingConsignmentId?id=<Integer>
Consignment
/apiv2/consignments/getConsignment?id=<Integer>
Return Consignment Request Parameters
The Return Consignments endpoints are POST endpoints that allow a user to be able to query for the latest information for multiple consignments. Each endpoint is restricted to 10 examples per request.
The available options to query include:
MachShip Consignment Id
/apiv2/consignments/returnConsignments
{
...
"12345",
"<Integer>"
...
}MachShip Pending Consignment Id
/apiv2/consignments/returnConsignmentsByPendingConsignmentIds
{
...
"12345",
"<Integer>"
...
}
Carrier Consignment Number
/apiv2/consignments/returnConsignmentsByCarrierConsignmentId
{
...
"ABC12345",
"String"
...
}Reference 1
/apiv2/consignments/returnConsignmentsByReference1
{
...
"Reference 1",
"String"
...
}Reference 2
/apiv2/consignments/returnConsignmentsByReference2
{
...
"reference 2",
"String"
...
}
Get Recently Updated or Created Consignments
The Get Recently Updates or Created Consignment Endpoint is a GET endpoint that can remove the need for high levels of inefficient polling to allow users to just request that MachShip returns consignment information that has changed during a time period.
The endpoint will allow a user to specify:
- Company Id (Optional): The company id for the consignments that are being queried
- From Date Utc: This time period from which the consignment updates are to be queried from
- To Date Utc (Optional): This is the max time period which the consignment updates are to be queried from
- Start Index (Optional): MachShip will return a maximum of 200 entries per request. Should there be more than 200 updated or created consignments during the requested time period then you can utilise this index to obtain the next 200 entries by setting this to be 201. This can then be repeated until all updates have been obtained.
- Retrieve Size (Optional) This will be between 40 and 200 and will be the number of consignments returned in the request. If not provided the default returned will be 40.
- Carrier Id (Optional) If you wish to restrict the updates to a set carrier then you can set the id of that carrier in the request
- Include Child Companies (Optional) If the query is desired to be made for an organisation that has multiple companies you can set this field to be true
/apiv2/consignments/getRecentlyCreatedOrUpdatedConsignments
A standard request example for this endpoint is shown below and will include the consignmentid, the from date, the to date and the include child companies field at true.
Get or Return Consignment Response
- carrierConsignmentId: This will be the carrier consignment number, This is the reference that will be used by the carrier
- status: This is the current status for the consignment, this will contain
- manifestId - The id of the manifest for this consignment - if the consignment is currently in a status of unmanifested, no manifest id will exist.
- bookedDate - The date that the consignment was set for Despatch
- completedDate - The local time that the consignment was marked as completed (Delivered)
- completedDateUtc - The UTC time that the consignment was marked as completed (Delivered)
- attachmentCount - The current number of attachments that are uploaded against the consignment. This will commonly be deemed as an indicator of if there is a current Proof of Pickup (POP) or Proof of Delivery (POD) against the consignment
- important- Will state if the consignment is currently been flagged as important or not
- carrierName- The name of the carrier the consignment has been declared with
- statusHistory: This is the full listing of all status events that have occurred against this consignment and will include the status id, status name, status description, status time, carrier status description and also the id of the user who updated the status - Any update made by User id 31 will have been an automated update from the carrier's system.
{
.........
"carrierConsignmentId": "ABC123456",
"status": {
"id": 7,
"name": "Complete",
"description": "Complete"
},
"manifestId": 12365,
"bookedDate": "2014-11-13T00:05:00.000",
"completedDate": "2014-11-18T11:00:00.00",
"completedDateUtc": "2014-11-18T00:00:00.00",
"attachmentCount": 1,
"important": false,
"carrierName": "VT Freight Express",
"statusHistory": [
{
"consignmentId": 12345,
"createdByName": "",
"statusIsPartial": false,
"consignmentTrackingStatus": {
"id": 2,
"name": "Unmanifested",
"description": "Unmanifested"
},
"statusDateLocal": "2014-11-12T17:00:00.000",
"statusDateUtc": null,
"carrierStatus": null,
"carrierStatusDescription": null,
"createdByUserId": 123398,
"statusInformation": null
},
{
"consignmentId": 12345,
"createdByName": "",
"statusIsPartial": false,
"consignmentTrackingStatus": {
"id": 3,
"name": "Manifested",
"description": "Manifested"
},
"statusDateLocal": "2014-11-13T16:00:00.000",
"statusDateUtc": null,
"carrierStatus": null,
"carrierStatusDescription": null,
"createdByUserId": 123398,
"statusInformation": null
},
{
"consignmentId": 12345,
"createdByName": "",
"statusIsPartial": false,
"consignmentTrackingStatus": {
"id": 5,
"name": "In Transit",
"description": "In Transit"
},
"statusDateLocal": "2014-11-17T12:00:00.000",
"statusDateUtc": null,
"carrierStatus": null,
"carrierStatusDescription": null,
"createdByUserId": 123398,
"statusInformation": null
},
{
"consignmentId": 12345,
"createdByName": "",
"statusIsPartial": false,
"consignmentTrackingStatus": {
"id": 7,
"name": "Complete",
"description": "Complete"
},
"statusDateLocal": "2014-11-18T11:00:00.000",
"statusDateUtc": null,
"carrierStatus": null,
"carrierStatusDescription": null,
"createdByUserId": 123398,
"statusInformation": null
}
],
.......
}- surcharges: Breakdown of the surcharges that have been flagged against the consignment including the price, name and the quantity. Note that surcharges that have an item based aspect - i.e a manual handling charge can have a quantity greater than 1.
{
..........
"surcharges": [
{
"costPrice": 0,
"sellPrice": 43,
"quantity": 1,
"name": "Example Surcharge 1"
},
{
"costPrice": 0,
"sellPrice": 10,
"quantity": 2,
"name": "Example Surcharge 2"
}
}
]
........
}- trackingPageAccessToken - The access token to the unique public tracking page for this consignment. The token can be appended to the URL below to allow for public access to the tracking page
https://live.machship.com/tracking/#/consignments/<Token> - id- The id of the consignment within the MachShip system
- companyId - The Id of the company that the consignment has been created against
- company - The name of the company that the consignment has been created against
- Carrier Service Information - Information relating to the service that the consignment was booked on. This will include names and id's
{
.......
"trackingPageAccessToken": "y1y1Q535Q0uVsOzvxNZ9WQ",
"id": 12345,
"companyId": 1,
"company": {
"id": 1,
"name": "Acme Enterprises",
"accountCode": "ACME",
"displayName": "Acme Enterprises (ACME)"
}, - Carrier Zone Information - Information relating to the charge from zone and the charge to zone utilised to generate the route pricing. This will include names and id's
"carrierServiceId": 23,
"carrierService": {
"id": 23,
"name": "General",
"abbreviation": "GENERAL",
"displayName": "General (GENERAL)"
},
"subServiceId": null,
"subService": null,
"fromCarrierZoneId": 511,
"fromCarrierZone": {
"id": 511,
"name": "M1",
"abbreviation": "M1",
"displayName": "M1 (M1)"
},
"toCarrierZoneId": 515,
"toCarrierZone": {
"id": 515,
"name": "V3",
"abbreviation": "V3",
"displayName": "V3 (V3)"
},
.........
}- consignmentNumber - Also referred to as the MS Number. This will be the MachShip reference of the consignment
- dateCreated - The creation date and time of the consignment
- createdByUserId - The Id of the user who created the consignment
- despatchDate - Despatch Date and Time in UTC
- despatchDateUtc - Despatch Date and Time in UTC
- despatchDateLocal - Despatch Date and Time based on the user's local timezone
- eta - Estimated Date and Time of the delivery in local time
- etaUtc - Estimated Date and Time of the delivery in UTC Time
{
.......
"consignmentNumber": "MS00012345",
"dateCreated": "2014-11-12T17:05:03.08",
"createdByUserId": 109,
"despatchDate": "2014-11-11T13:00:00",
"despatchDateUtc": "2014-11-11T13:00:00",
"despatchDateLocal": "2014-11-12T00:00:00",
"eta": "2014-11-13T12:59:59",
"etaUtc": "2014-11-13T12:59:59",
.......
}- From Location Information - All details about the sending location of the consignment
{
.......
"fromCompanyLocationId": 1111,
"fromName": "Sending Enterprises",
"fromContact": "John Citizen",
"fromPhone": "03 9876 4321",
"fromEmail": john@sending.com,
"fromAddressLine1": "Level 1, 678 Enterprises Street",
"fromAddressLine2": "Rear of Building",
"fromLocation": {
"id": 5426,
"postcode": "3195",
"state ": {
"code": "VIC",
"name": "Victoria",
"id": 1
},
"timeZone": "Australia/Sydney",
"suburb": "BRAESIDE",
"subLocality": null,
"country": {
"id": 1,
"name": "Australia",
"code2": "AU",
"code3": "AUS",
"numeric": "036",
"taxPercentage": 10
},
"description": "BRAESIDE, 3195, VIC",
"locationType": 0
}, - To Location Information - All the details about the delivery location of the consignment
"toLocation": {
"id": 6572,
"postcode": "3500",
"state": {
"code": "VIC",
"name": "Victoria",
"id": 1
},
"timeZone": "Australia/Sydney",
"suburb": "MILDURA",
"subLocality": null,
"country": {
"id": 1,
"name": "Australia",
"code2": "AU",
"code3": "AUS",
"numeric": "036",
"taxPercentage": 10
},
"description": "MILDURA, 3500, VIC",
"locationType": 0
},
"toCompanyLocationId": nulll,
"toName": "Raisens and Sultanas Pty Ltd",
"toContact": Milly Durra,
"toPhone": 05 9321 6547,
"toEmail": milly@r&s.com.au,
"toAddressLine1": "263 Street avenue",
"toAddressLine2": "",
"specialInstructions": null, - Reference Information - Reference 1 (customerReference) and Reference 2 (customerReference2) of the consignment
- companyCarrierAccount - The linked account details that the consignment was booked on
"customerReference": "PO12345",
"customerReference2": "SO9876",
"companyCarrierAccount": {
"id": 111,
"companyId": 1,
"carrierAccountId": 1,
"carrierAccount": 1,
"name": "Acme_VT_Freight",
"abbreviation": "ACME_1234",
"displayName": "Acme_VT_Freight (ACME_1234)"
},
.......
}Pricing Breakdown:
- sellPricesCleared: If your user does not have access to sell price information then this Boolean will show as true
- consignmentCarrierSurchargesCostPrice / consignmentCarrierSurchargesSellPrice: This will be the total price of all surcharges that have also attracted the fuel levy
- consignmentCarrierSurchargesFuelExemptCostPrice/ consignmentCarrierSurchargesFuelExemptSell Price : This is the total price of all surcharges that have not attracted the fuel levy
- totalConsignmentCarrierSurchargesCostPrice / totalConsignmentCarrierSurchargesSellPrice: This is the total surcharge component of the price
- totalSellPrice / totalCostPrice: The total price of the consignment inclusive of all charges and taxes
- totalBaseSellPrice / totalBaseCostPrice: The total price of the consignment including the ratecard pricing (route) and any surcharges
- totalTaxCostPrice / totalTaxSellPrice: The total tax component of the price
- costFuelLevyPrice / sellFuelLevyPrice: The total fuel levy price
- consignmentRouteCostPrice / consignmentRouteSellPrice: The total composition of the consignments price due to the carrier ratecard
- totalCostBeforeTax / totalSellBeforeTax: The total price of the consignment excluding and tax component.
{
............
"consignmentTotal": {
"sellPricesCleared": false,
"consignmentCarrierSurchargesCostPrice": 0,
"consignmentCarrierSurchargesSellPrice": 0,
"consignmentCarrierSurchargesFuelExemptCostPrice": 0,
"consignmentCarrierSurchargesFuelExemptSellPrice": 0,
"totalConsignmentCarrierSurchargesCostPrice": 0,
"totalConsignmentCarrierSurchargesSellPrice": 0,
"totalSellPrice": 12.86,
"totalCostPrice": 0,
"totalBaseSellPrice": 10.62,
"totalBaseCostPrice": 0,
"totalTaxSellPrice": 1.17,
"totalTaxCostPrice": 0,
"costFuelLevyPrice": 0,
"sellFuelLevyPrice": 1.,
"consignmentRouteCostPrice": 0,
"consignmentRouteSellPrice": 120.62,
"totalCostBeforeTax": 0,
"totalSellBeforeTax": 11.68
}
..........
}- totalWeight - Total weight of all items on the consignment
- totalCubic - Total cubic weight of all items on the consignment - this will be the volume multiplied by the cubic conversion factor
- totalVolume - Total volume of all the items on the consignment
- heaviestWeight - The charge weight of the consignment - this will be the higher of either the cubic weight or the weight.
- totalItemCount - Total quantity of the consignment
- insertedBy - The Id of the user who created the consignment
- insertedByUserName - The name of the user who created the consignment
- permanentPickup - true or false if there was a daily pickup flagged against the sending location
- distance - If the price is based on a distance charge the number of charged kilometers will be indicated here.
- isHourly - an indicator of if the service is hourly based - if true MachShip's pricing will indicate the known minimum charge and the potential will exist for price differences upon billing
- isTest - Indicator of if the consignment is a test consignment or a live consignment
"totalWeight": 1,
"totalCubic": 0.75,
"totalVolume": 0.003,
"heaviestWeight": 1,
"totalItemCount": 1,
"insertedBy": 109,
"insertedByUserName": null,
"permanentPickup": false,
"distance": null,
"isHourly": false,
"isTest": false,This section will break down the consignments items
- companyItemId - The id of the saved company item (if used)
- itemType - This will be the item type selected for the line item
- name - The Name entered for the line item
- sku- The SKU of the line item
- quantity - Quantity of the line item
- height - Height of the line item (cm)
- weight - Weight of the line item (kg)
- length - Length of the line item (cm)
- width - Width of the line item (cm)
- references - This will be the individual item identifiers (label barcodes) for these consignments
{
..........
"consignmentItems": [{
"companyItemId": 0,
"itemType": "Bag",
"name": "BAG",
"sku": null,
"quantity": 1,
"height": 5,
"weight": 1,
"length": 30,
"width": 20,
"references": [
ABC123456001
]
}]
............
}
GET Attachment Request Parameters (POD)
If the Consignment query returns a complete status and an attachment count greater than zero there is then MachShip should have stored a POD image against the consignment. The Get Attachments by Consignment Id is a GET endpoint that allows a user to return the POD image to be stored in an external system. This endpoint can query an individual or multiple consignment ids. It is suggested that this is limited to 10 IDs at a time.
https://live.machship.com/apiv2/attachments/getAttachmentsByConsignmentIds?
Individual Consignment request example
https://live.machship.com/apiv2/attachments/getAttachmentsByConsignmentIds?ids=<Integer>
The response from this endpoint will be the image of the attachment for that consignment. If there are multiple images then a zip file will be returned containing the images.
Multiple Consignment request example
The response from this call will be a zip file containing the image files.