A guide to creating Dangerous Goods Consignments via the API – Machship

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 consignment is linked to a specific carrier, service, and account which describes who will be transporting this consignment.

Moreover, Dangerous Goods Consignments are consignments that will be sent that contain hazardous items that require special care to be taken by the transport provider. It is important to ensure that you fully declare all information that relates to the dangerous goods being sent so that you are compliant with your local regulations.

When creating a consignment via the API, the standard workflow process is:

You generate prices and routes from Machship's /apiv2/routes/returnRoutes endpoint
Your user or system selects the route and despatch option they want to use
You create a consignment in MachShip based on that route

This article will outline the properties and steps required to create a dangerous goods consignment in MachShip. This article assumes you have read the Generating Prices and Routes article as routing is a precursor to creating a consignment. Note that it is not required to generate routes before creating consignments, however, this is only recommended for advanced users.

Create Consignment Request Parameters

All these details must be provided to the /apiv2/consignments/createConsignmentwithComplexItems for MachShip to return your valid despatch options. Please refer to our API documentation for further technical documentation regarding creating consignments.

Despatch DateTime (optional)

MachShip allows you to specify the despatch date and time of the consignment. Please refer to our Working with Despatch Dates when Routing and Creating Consignments documentation for further information on specifying the Despatch DateTime.

Pickup and Delivery Locations

Please refer to our Working with Locations when Routing and Creating Consignments documentation for details on how to specify locations when generating a routing request.

Special Instructions

Special Instructions allow you to specify any special instructions that need to be passed on to the carrier regarding the delivery location. This could include instructions such as 'leave at the front door'.

Items

The Items Please refer to our Working with Items when Routing and Creating Consignments documentation for details on how to specify items when generating a routing request. Below details discuss specifically the differences for the creation of a consignment using Complex Items:

Item Type (required). You should choose the item type that best describes the goods that you are sending. ItemType must be one of the following values: 'Carton', 'Skid', 'Pallet', 'Crate', 'Satchel', 'Roll', 'Panel', 'Bag', 'Tube', 'Stillage', 'Envelope', 'Pack', 'Rails', 'TimberPack', 'Pipe', 'BDouble', 'Semi', 'TwentyFootContainer', 'FortyFootContainer', 'Bundle', and 'Case'
Name (required). A brief description of the item
SKU (optional). The SKU of the item from your calling system
Quantity (required). The number of this item that you are sending. For example, if you were sending 5 cartons with the same dimensions, you would send through 1 item object with a Quantity of 5.
Weight (required). The weight of the item in kg
Length (required). The length of the item in cm
Width (required). The width of the item in cm
Height (required). The height of the item in cm

{
  ......
"items": [
    {    
      "itemType": "Carton",
      "name": "string",
      "sku": "string",
      "quantity": 0,     
      "standardItem": {
        "height": 0,
        "weight": 0,
        "length": 0,
        "width": 0
      }  ...
}

- unNumber (required). This will be the United Nations Number which represents the global identifier for that dangerous goods product
- Packing Group (required). MachShip will require you to provide one of the enums below based on the pack group that represents the product being sent
  - 1 - Pack Group 1
  - 2 - Pack Group 2
  - 3 - Pack Group 3
  - 4 - Pack Group N/A
- Container Type (required). enum for the container type for the DG. Needs to be one of the below:
  - 1 - Drum
  - 2 - Carton
  - 3 - IBC
  - 4 - Pail
  - 5 - Demountable Tank
  - 6 - Bottle
  - 7 - Pressure Drum
  - 8 - Tube
  - 9 - MEGC
  - 10 - Aerosol
  - 11 - Bag
- Aggregate Quantity (required). The number of this item that you are sending. For example, if you were sending 5 cartons with the same dimensions, you would send through 1 item object with a Quantity of 5.
- isAggregateQuantityWeight (required). This will be either true or false based on if the aggregate quantity amount provided is in kilos (true) or litres (false).
- numberofContainers (required). The number of containers which contain dangerous goods
- isMarinePollutant (required). Either true or false based on if the dangerous goods item is a marine pollutant or not
- isTemperatureControlled (required). Either true or false based on if the dangerous goods item requires being temperature controlled or not.
- isEmptyDgContainer (required). Either true or false based on if the dangerous goods item is an empty uncleaned container or not
- dgClassType. (optional) enum which advises the primary class of the DG
  - 1 - Class 1 Explosive (cannot be consigned in MachShip)
  - 2 - Class 2.1 Flammable Gas
  - 3 - Class 2.2 Other Gas
  - 4 - Class 2.3 Toxic Gas
  - 5 - Class 3 Flammable Liquid
  - 6 - Class 4.1 Flammable Solid
  - 7 - Class 4.2 Spontaneously Combustible
  - 8 - Class 4.3 Dangerous When Wet
  - 9 - Class 5.1 Oxidising Agent
  - 10 - Class 5.2 Organic Peroxide
  - 11 - Class 6.1 Toxic Substance
  - 12 - Class 6.2 Infections Substance
  - 13 - Class 7 Radioactive (Cannot be consigned in MachShip)
  - 14 - Class 8 Corrosive
  - 15 - Class 9 - Miscellaneous
- subDgClassTypes (optional). An array of enum's which advice on all of the secondary classes of the DG
  - 1 - Class 1 Explosive (cannot be consigned in MachShip)
  - 2 - Class 2.1 Flammable Gas
  - 3 - Class 2.2 Other Gas
  - 4 - Class 2.3 Toxic Gas
  - 5 - Class 3 Flammable Liquid
  - 6 - Class 4.1 Flammable Solid
  - 7 - Class 4.2 Spontaneously Combustible
  - 8 - Class 4.3 Dangerous When Wet
  - 9 - Class 5.1 Oxidising Agent
  - 10 - Class 5.2 Organic Peroxide
  - 11 - Class 6.1 Toxic Substance
  - 12 - Class 6.2 Infections Substance
  - 13 - Class 7 Radioactive (Cannot be consigned in MachShip)
  - 14 - Class 8 Corrosive
  - 15 - Class 9 - Miscellaneous

{
......
"items": [
    {    
      "itemType": "Carton",
      "name": "string",
      "sku": "string",
      "quantity": 0,     
      "standardItem": {
        "height": 0,
        "weight": 0,
        "length": 0,
        "width": 0
      },
      "consignmentItemDgItems": [
        {          
          "unNumber": 0,
          "packingGroup": 1,
          "containerType": 1,
          "aggregateQuantity": 0,
          "isAggregateQuantityWeight": true,
          "numberOfContainers": 0,
          "isMarinePollutant": true,
          "isTemperatureControlled": true,
          "technicalOrChemicalGroupNames": "string",
          "dgClassType": 1,
          "subDgClassTypes": [
            1
          ]
          }
         ]
        }
      ]
.....
}

Company ID (optional)

Company ID can be used if you wish to get routes for a specific company in MachShip. This is useful if you have multiple companies in MachShip and need to get routing and pricing for different companies. If no company ID is provided, the company that your user is assigned to will be used to return routes. Please refer to /apiv2/companies for company documentation.

{
  ...
  "companyId": 9999
  ...
}

Carrier Selection:

Carrier ID (Optionally required)

Carrier ID tells MachShip which carrier should be used for this consignment. This should be taken from the selected route using the carrier.id property.

Carrier Account ID ( Optional )

Carrier Account ID tells MachShip which account should be used for this consignment. This should be taken from the selected route using the carrierAccount.id property.

Company Carrier Account ID ( Optional )

Company Carrier Account ID tells MachShip which carrier should be used for this consignment. This should be taken from the selected route using the companyCarrierAccountId property.

Carrier Service ID ( Optional )

Carrier ID tells MachShip which carrier should be used for this consignment. This should be taken from the selected route using the carrierService.id property.

Alternatively you can have MachShip select either the cheapest or the fastest available option by not providing any of the above and setting

Default Route Selection (Optional)

Should you not know the carrier you have the option to allow MachShip to select either the "cheapest" or the "Fastest" carrier option.

This would be passed through as:

{
  ...
  "defaultRouteSelection": "cheapest",
  ...
}

Note that you will need to either pass through the Default Route Selection or at a minimum the CarrierId when creating a consignment.

Customer References (optional)

You can provide 2 customer references when creating a consignment. These could be a Purchase Order number, an internal reference to your system, etc. These can be provided using the following properties.

{
  ...
  "customerReference": "testRef",
  "customerReference2": "testRef2"
  ...
}

Question IDs (optional)

Question IDs allow you to pass in answers to questions that allow MachShip to further restrict routes. This should not be specified unless advised to do so by the MachShip support team.

"questionIds": [0]

Send Tracking Emails (optional)

If you wish to send out a tracking email (ASN) to a client you would provide the SendTrackingEmail option as true and then provide an email address(es) in the toEmail field.

{
  ...
 "sendingTrackingEmail": true,
  ...
}

Send Custom Values (optional)

Custom Values are in MachShip are consignment specific integration options that exist for a carrier. These are shown within the platform like the below:

To Set these via the API you would set the property name (email us at support@machship.com) if you are looking for a specific property and then set the value for that property.

{
  ...
  "customValues": [
    {
      "propertyName": "string",
      "value": "string"
    }
  ]
  ...
}

Printer Token (optional)

When using the MachShip Printing Application to automate the printing process in MachShip a user has the facility to utilise an internal identifier to direct the printing. Via the API this can be set as the printerToken. If you are using this then you would configure it internally via with a Printer Configuration Evaluation. See the instructions linked below:

Printer Configuration Evaluation

{
  ...
 "printerToken": "string",
  ...
}

ReceieverAccount(s) (optional)

Should you wish to generate a receiver pays consignment in MachShip to charge the consignment to a third party or receiver then you would provide either the receiverAccountCode or the save receiverAccountId.

Note when booking Receiver Pays there is a requirement to pass through the Carrierid and the CarrierAccountId for the sending account. The account must also be configured to allow receiver pays based on the instructions below:

How to allow a Company to Consign Receiver Pays

{
  ...
  "receiverAccountCode": "string",
  "receiverAccountId": 0,
  ...
}

Staff Member Name (optional)

The staff member name is a free text field that is optional which will allow a user to set which internal team member has generated the consignment.

{
  ...
"staffMemberName": "string",
  ...
}

Dangerous Goods Declaration (Required)

This should be set to true

{
  ...
"dgsDeclaration": true,
  ...
}

Elective Surcharge Id's (Optional)

If you have an elective surcharge that you wish to include in this consignment creation, an example would be a hydraulic tailgate or hand unload the delivery, pass through the id of this surcharge in the array provided. These ids will be provided back as options to you when generating routes.

{
  ...
"electiveSurchargeIds": [
   11,12
 ]
  ...
}

Create Consignment with complex Items Request Example

{
  "dgsDeclaration": true,
  "items": [
    {
      "itemType": "carton",
      "name": "Test Carton",
      "sku": "CART",
      "quantity": 1,
      "standardItem": {
        "height": 25,
        "weight": 5,
        "length": 20,
        "width": 20
      },
      "consignmentItemDgItems": [
        {
          "unNumber": 1263,
          "packingGroup": 3,
          "containerType": 1,
          "aggregateQuantity": 20,
          "isAggregateQuantityWeight": false,
          "numberOfContainers": 1,
          "isMarinePollutant": true,
          "isTemperatureControlled": false
          "dgClassType": 5
        }
      ]
    }
  ],
  "carrierId": 11,
  "carrierServiceId": 123,
  "carrierAccountId": 456,
  "companyCarrierAccountId": 789,
  "fromName": "My Warehouse",
  "fromContact": "Bob Jones",
  "fromPhone": "123123123",
  "fromEmail": "test@test.com",
  "fromAddressLine1": "testAddressLine1",
  "fromAddressLine2": "testAddressLine2",
  "fromLocation": {
    "suburb": "melbourne",
    "postcode": "3000"
  },
  "toName": "Customers House",
  "toContact": "Stacy Smith",
  "toPhone": "123123123",
  "toEmail": "test@test.com",
  "toAddressLine1": "testAddressLine1",
  "toAddressLine2": "testAddressLine2",
  "toLocation": {
    "suburb": "Sydney",
    "postcode": "2000"
  },
  "specialInstructions": "leave at front door"
}

Create Consignment Response

If a consignment is created successfully, MachShip will return an object with a subset of the properties relating to the consignment including:

ID: this is the unique identifier that you should reference for all other API calls relating to this consignment. For future API calls, it is recommended that this ID is stored within your system
ConsignmentNumber: This the ID with a MS prefix. This is the human-friendly ID that is used in MachShip's UI and is also the main reference that is sent through to the carrier
CarrierConsignmentID: This is the reference that will be used by the carrier
Status: Most consignments, when created, will remain in an unmanifested state until a user manifests the consignment. Unmanifested means that it exists solely in MachShip and has not been transmitted to the carrier. Note that some carriers and accounts are configured to automatically manifest on consignment creation. This means that a status of Manifested would be returned for these consignments and that details of the consignment have been transmitted to the carrier.
Pricing: This will provide the pricing of the consignment and also breakdown the surcharges.
Items - this will provide a breakdown of the consignments Items information including the dimensions, weights, references (barcode data) and item contents

  {
  "object": {
  "carrierConsignmentId": "ABC000123456",
  "status": {
  "id": 2,
  "name": "Unmanifested",
  "description": "Unmanifested"
  },
  "trackingPageAccessToken": "<tracking page token>",
  "consignmentTotal": {
  "sellPricesCleared": false,
  "consignmentCarrierSurchargesCostPrice": 0.00000,
  "consignmentCarrierSurchargesSellPrice": 0.00000,
  "consignmentCarrierSurchargesFuelExemptCostPrice": 0.00000,
  "consignmentCarrierSurchargesFuelExemptSellPrice": 0.00000,
  "totalConsignmentCarrierSurchargesCostPrice": 0.00000,
  "totalConsignmentCarrierSurchargesSellPrice": 0.00000,
  "totalSellPrice": 20.30691,
  "totalCostPrice": 0.00000,
  "totalBaseSellPrice": 16.78257,
  "totalBaseCostPrice": 0.00000,
  "totalTaxSellPrice": 1.84608,
  "totalTaxCostPrice": 0.00000,
  "costFuelLevyPrice": 0.00000,
  "sellFuelLevyPrice": 1.6782,
  "consignmentRouteCostPrice": 0.00000,
  "consignmentRouteSellPrice": 16.78257,
  "totalCostBeforeTax": 0.00000,
  "totalSellBeforeTax": 18.46083
  },
  "consignmentHourlyPricing": null,
  "consignmentCarrierSurcharges": [],
  "printSettings": {
  "printConsignmentLabels": false,
  "printItemLabels": true,
  "printSpecialInstructionsLabels": true
  },
  "items": [{
  "companyItemId": 0,
  "itemType": "Carton",
  "name": "test",
  "sku": null,
  "quantity": 1,
  "height": 10.00000,
  "weight": 10.00000,
  "length": 10.00000,
  "width": 10.00000,
  "references": [
  "ABC000123456001"
  ],
  "consignmentItemContents": null
  }],
  "id": 123456,
  "consignmentNumber": "MS00123456",
  "despatchDateLocal": "2018-07-02T09:00:00",
  "despatchDateUtc": "2018-07-01T23:00:00",
  "etaLocal": "2018-07-04T17:00:00",
  "etaUtc": "2018-07-04T07:00:00",
  "carrier": {
  "id": 11,
  "name": "TNT Express",
  "abbreviation": "TNT",
  "displayName": "TNT Express (TNT)"
  },
  "carrierService": {
  "id": 123,
  "name": "Road Express",
  "abbreviation": "76",
  "displayName": "Road Express (76)"
  },
  "isTest": false
  },
  "errors": [
  ]
  }

Related articles