Courier Integration: MyDHL API
Overview
Khaos Control have created an integration with DHL API (MyDHL API) as a courier Neo service.
Specification
This integration will include all mandatory fields for international and domestic shipping, as well as paperless trade.
Customers will not be required to use the DHL Easyship software, but will be required to pass on MyDHL credentials to be configured in [ Courier | Shipping | Couriers ] configuration screen against the DHL API Courier integration.
Notes:
- Service codes are not configured in Khaos Control itself. Khaos Control sends up data (see note ii for more information on this) from the Sales Order to DHL, DHL then returns a list of applicable services, Khaos Control then selects the cheapest option available.
- Data sent up to DHL includes item weights, item dimensions, order value, delivery destination and delivery date. All of these factors may affect the services sent back to Khaos Control from DHL's API.
Configuration
An update and a changelog will be applied as a part of this update. DLL files will be added to the Khaos Control Applic\Courier\ folder by a member of the Khaos Control support team:
Keystone.Kos.RawPrint.dll
Kos.Couriers.MyDHL.dll
Microsoft.Web.Services2.dll
Note: This information is for reference purposes only. Should these files need to be moved, added or updated, please contact KCSL. Under no circumstances should you attempt to modify these files yourself.
Other steps for configuration are as follows:
Create a new DHL API Courier:
- Open a System Data screen.
- Double click on
[ Courier | Shipping | Couriers ]. - In edit mode Press F3 or click
to add a new item. - Give the item line an appropriate name, i.e. "MyDHL"
- Set the "Export Type" as "MyDHL"
- Press Ctrl+S or click
to save.
Configuring the new courier once the courier has been created:
- Right click the courier line > Configure.
- Configure the courier as per the below table:
| Option | Description | Example |
|---|---|---|
| MyDHL Username | The username provided by DHL this will be the same as the login information that you use to log in to DHL. | Username |
| MyDHL Password | The password provided by DHL this will be the same as the login information that you use to log in to DHL. | Password |
| MyDHL Endpoint | The endpoint Khaos Control will use to contact MyDHL | Can be left blank |
| MyDHL Payment Info Specification | Details the potential terms of trade for this specific shipment, and the possible enumerated values for this field are; - CFR - Cost and Freight Defaults to CFR if left blank. | Can be left blank |
| MyDHL Shipping Payment Type | Sets the payment type, whether the shipper account or billing account will be billed. Possible values are: - S (use Shipper Account Number as payer) Please note if you use value R or T in this tag then the next tag Billing Account Number is also mandatory. | S |
| MyDHL Billing Account Number | The DHL account number used for the shipment, if Shipping Payment Type is either R or T. This will be provided by DHL. | 019221214124 |
| Default Package Width | The default width for boxes that have no width defined against them. The MyDHL integration uses cm. | 60 |
| Default Package Length | The default Length for boxes that have no length defined against them. The MyDHL integration uses cm. | 60 |
| Default Package Height | The default height for boxes that have no height defined against them. The MyDHL integration uses cm. | 60 |
| Shipping Time | Time at which the parcel will be ready to be shipped. | 8.45 |
| Premises Close Time | The time that the collection point for parcels closes. | 17:00 |
| Goods Description | Generic Package description | General Goods |
| Label Type | The label type that is returned from MyDHL. Choices can be: - PDF | |
| Label Folder | Folder where labels and documents will be saved to. | C:\KeystoneSoftware\CourierLabels |
| Drop Off Type | DHL Dropoff type. Choices can be: - REQUEST_COURIER | REGULAR_PICKUP |
| Shipper Address | The address and contact information for the collection point. This includes: - Address 1 | 1-3 Priest Court, Caunt Road, |
| Minimum Item Weight | The minimum weight an item can be. If you have zero (0) weight items this can be set so that the items can be exported to MyDHL courier correctly. The MyDHL integration uses Kg. (Note that this is not multiplied by the weight scale.) | 1 |
| Dutiable | Mark shipments from this courier as dutiable. This should be checked if shipping outside of the UK and EU. | Ticked. |
| Enable Paperless Trade | Mark Shipments as being eligible for paperless trade. This will tell DHL to generate a customs invoice for the shipment, if one is required. | Ticked |
| DHL Service Type | The service type to request from DHL. If left blank, Khaos Control will automatically select the cheapest service from those returned as being available by DHL. | (See below for possible values) |
| Disable Document Printing | By default, any extra documents from DHL are printed from the same printer as the label. If you are using a label printer, this can be undesirable, so using this option in conjunction with the label path option allows you to save the documents and print them yourself later. | Ticked |
| Declaration Text | Declaration Text to send to DHL. This has a default that DHL have suggested, only change this if DHL or Khaos Control have advised you to. | |
| Shipper EORI Number | EORI Number to send to DHL | GB0000001 |
| Shipper VAT Number | VAT Number to send to DHL | GB0000002 |
| Special Services | Special services to request from DHL. Separate with commas. | |
| Use Commodity Description | Use the commodity code description as the stock description to send to My DHL instead of the individual stock description | Ticked |
| Take DHL Commodity Desc from Items | By default, the commodity description field in MyDHL data can be defined in the "Goods Description" option. This option will override this and use commodity descriptions from stock items on the order instead. | Ticked |
| Reason For Export | Descriptive field for why a shipment has been exported. Defaults to "Goods Sold" | |
| Reason For Export Type | Field that tells DHL in their terms why you have exported the shipment. Defaults to "PERMANENT". Acceptable options are:
| |
| Place of Incoterm | Describes the origin of the incoterms. Defaults to United Kingdom. | |
| Use Air Waybill (AWB) Number | When enabled, and an Air Waybill (AWB) number is returned, this will be used as the consignment ref for the order. | Ticked |
| Signature Image | Image to be sent up to MyDHL and used as the signature on the request. | |
| DHL Customs Invoice Type | Type to be used for Labels Options. | Choices are 'Commercial' and 'Proforma'. |
| Weight Scale | The weight against your shipments will be multiplied by this factor before being sent to the courier. The MyDHL integration uses Kg. | 0.001 |
| Nominal Weight | When set, if your shipment has no weight against it then this nominal weight will be used instead. Note: this functionality will only work when order items are packed into boxes. | 1 |
| Dimension Scale | The dimensions against your shipment will be multiplied by this scaling factor before being sent to MyDHL. The MyDHL integration uses cm. | 100 |
| Requires Consignment Ref | When ticked, Sales Invoices cannot be moved past the Shipping stage in SIM unless a consignment ref has been applied to them | Ticked |
| Printer Name | Printer to use for this courier | Microsoft Print to PDF |
DHL have provided the following list of Service Types (also known as Global Product Codes):
| Global Product Name | Global Product Codes | Contents | Dutiable |
|---|---|---|---|
| DOMESTIC EXPRESS | N | DOCUMENTS | N |
| DOMESTIC EXPRESS 12:00 | 1 | DOCUMENTS | N |
| DOMESTIC EXPRESS 9:00 | I | DOCUMENTS | N |
| ECONOMY SELECT | H | NON_DOCUMENTS | Y |
| ECONOMY SELECT EU | W | DOCUMENTS | N |
| EXPRESS 10:30 | L | DOCUMENTS | N |
| EXPRESS 10:30 (NON DOC) | M | NON_DOCUMENTS | Y |
| EXPRESS 12:00 | T | DOCUMENTS | N |
| EXPRESS 12:00 (NON DOC) | Y | NON_DOCUMENTS | Y |
| EXPRESS 9:00 (NON DOC) | E | NON_DOCUMENTS | Y |
| EXPRESS 9:00 | K | DOCUMENTS | N |
| EXPRESS WORLDWIDE | D | DOCUMENTS | N |
| EXPRESS WORLDWIDE (NON DOC) | P | NON_DOCUMENTS | Y |
| EXPRESS WORLDWIDE EU | U | DOCUMENTS | N |
Notes:
- The value from the Global Product Codes column can be used as the DHL Shipment Type option in right click > Configure... settings as above.
- The Dutiable column shows whether the Dutiable option's tickbox should be ticked or unticked for each service.
- In order for the Customer GST Type code to be included in the export, a UDA needs to added to customers as follows:
- Create a new entry if one does not already exist called GSTIN with a type of text, see How To: Setup Company User Defined Attributes (UDAs).
- Populate with the GST Type code for customers, see:
- This list was provided on 07/07/2020. Please contact DHL to receive the most up to date list.
Usage
Once configured, steps for usage are as follows:
- Create a new Sales Order for any customer,
- Add stock items and a payment line to the Sales Order, Save.
- Open the Sales Order in the
[ Sales Invoice Manager ]and move to the Shipping stage. - Green select the Sales Order in the shipping stage, click confirm shipment
- Set the date for delivery, move the sales order into the lower grid.
- Click ok.
- Click Assign to Courier, Khaos Control will contact MyDHL API and find services available for the order. The information sent to the MyDHL API for this purpose is as per the Specification section.
- The Sales Order will now be assigned to the MyDHL service where Khaos Control will pick the cheapest shipping fare returned from MyDHL as being available for this order, unless the DHL Service Type has been specified. If the DHL Service Type was specified, the service type selected will be requested from DHL.
- A label and any other documents will be returned and printed/saved based on your configuration.
- A dialog will ask if you wish to move the invoice to the next stage.
- If the Sales Invoice failed to assign to the courier it will not prompt to move the invoice to the next stage. In this case:
- Green select the sales invoice and click Confirm Shipment,
- Scroll across to the end of the grid and any errors will be displayed in the "Shipping error" column.
Notes:
- The service selected from those MyDHL return will not be displayed within Khaos Control. Only the courier name as configured in
[ Courier | Shipping | Couriers ]will appear in the Confirm Shipment screen and the Sales Order Courier field. - DHL have previously required that test labels, one of each type intended to be used of the following be generated and sent to them. This procedure is done using the MyDHL test system before the MyDHL account credentials are set by DHL to use the production (live) system. For generating the test labels, use the test URL (https://wsbexpress.dhl.com/sndpt/expressRateBook) This test URL is also the default that will be used if the MyDHLEndpoint option in the right click > Configure... menu is left blank.
- Domestic - i.e. UK
- EU
- Dutiable - i.e. non-EU, non-UK shipment
- When DHL update the credentials to be on the live system, they will also provide a new, live URL to use. This may look something like
https://wsbexpress.dhl.com/gbl/expressRateBookThe live URL may not be exactly as above and will not work until the MyDHL credentials are switched to be live by DHL. - DHL have recently stated that they do not use ICN (International Commodity Numbers) thus only Harmonisation Codes linked to the correct item and stock type, with a country (or zone) that matches the country of the delivery address of the order will be used. To set up harmonisation codes please see the following wiki pages:
- The IOSS number is passed in the same way as other 'registration numbers' (e.g. EORI) in Shipper.RegistrationNumbers, with the NumberTypeCode = 'SDT' and Number = the IOSS number from the Sales Order.
- If the Postcode field for the delivery address is populated with a US zip code in the format XXXXX-YYYY where X and Y are numerical values, MyDHL may fail to return a Rate Response, causing an error. This can be resolved by shortening the ZIP code to only be the first 5 digits.