Courier Integration: MyDHL API

Courier Integration: MyDHL API is not enabled by default.

Please email Development for more information.
Note: there will be additional costs involved if this option is enabled.

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:

  1. 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.
  2. 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:

  1. Open a System Data screen (show me how).
  2. Double click on [ Courier | Shipping | Couriers ].
  3. In edit mode Press F3 or click the NEW ITEM button has an icon that shows two sheets of paper (identified by having the top right corner folded down), arranged diagonally on the icon from top left to bottom right to add a new item.
  4. Give the item line an appropriate name, i.e. "MyDHL"
  5. Set the "Export Type" as "MyDHL"
  6. Press Ctrl+S or click the disk icon is the button bar's SAVE button to save.


Configuring the new courier once the courier has been created:

  1. Right click the courier line > Configure.
  2. 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
- CIF - Cost, Insurance and Freight
- CIP - Carriage and Insurance Paid To
- CPT - Carriage Paid To
- DAF - Delivered at Frontier
- DDP - Delivery Duty Paid
- DDU - Delivery Duty Unpaid
- DAP - Delivered at Place
- DEQ - Delivered Ex Quay (Duty Paid)
- DES - Delivered Ex Ship
- EXW - Ex Works
- FAS - Free Alongside Ship
- FCA - Free Carrier
- FOB - Free on Board

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)
- R (use Billing Account Number as bill-to receiver account number)
- T (use Billing Account Number as bill-to third party account number)

Please note if you use value R or T in this tag then the next tag Billing Account Number is also mandatory.
Defaults to S

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
- ZPL
- EPL

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
Defaults to REGULAR_PICKUP.

REGULAR_PICKUP
Shipper Address The address and contact information for the collection point. This includes:

- Address 1
- Address 2
- Address 3
- Address City
- Address Postcode
- Country Code
- Company Name
- Contact Name
- Address Email
- Address Telephone Number

1-3 Priest Court,

Caunt Road,
Lincs,
Grantham,
NG31 6FZ
GB,
Khaos Control,
Bob Warehouse
support@khaoscontrol.com
0330 223 1111

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 TradeMark 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 TypeThe 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 PrintingBy 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 TextDeclaration 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 NumberEORI Number to send to DHLGB0000001
Shipper VAT NumberVAT Number to send to DHLGB0000002
Special ServicesSpecial services to request from DHL. Separate with commas.
Use Commodity DescriptionUse the commodity code description as the stock description to send to My DHL instead of the individual stock descriptionTicked
Take DHL Commodity Desc from ItemsBy 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 ExportDescriptive field for why a shipment has been exported. Defaults to "Goods Sold"
Reason For Export TypeField that tells DHL in their terms why you have exported the shipment. Defaults to "PERMANENT".

Acceptable options are:

  • PERMANENT
  • TEMPORARY
  • RETURN
  • USED_EXIBITION_GOODS_TO_ORIGIN
  • INTERCOMPANY_USE
  • COMMERCIAL_PURPOSE_OR_SALE
  • PERSONAL_BELONGINGS_OR_PERSONAL_USE
  • SAMPLE
  • GIFT
  • RETURN_TO_ORIGIN
  • WARRANTY_REPLACEMENT
  • DIPLOMATIC_GOODS
  • DEFENCE_MATERIAL
Place of IncotermDescribes the origin of the incoterms. Defaults to United Kingdom.
Use Air Waybill (AWB) NumberWhen enabled, and an Air Waybill (AWB) number is returned, this will be used as the consignment ref for the order.Ticked
Signature ImageImage to be sent up to MyDHL and used as the signature on the request.
DHL Customs Invoice TypeType 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 NDOCUMENTS N
DOMESTIC EXPRESS 12:00 1DOCUMENTS N
DOMESTIC EXPRESS 9:00 IDOCUMENTS N
ECONOMY SELECTHNON_DOCUMENTSY
ECONOMY SELECT EU WDOCUMENTS N
EXPRESS 10:30 LDOCUMENTS N
EXPRESS 10:30 (NON DOC) MNON_DOCUMENTS Y
EXPRESS 12:00 TDOCUMENTS N
EXPRESS 12:00 (NON DOC) YNON_DOCUMENTS Y
EXPRESS 9:00 (NON DOC) ENON_DOCUMENTS Y
EXPRESS 9:00 KDOCUMENTS N
EXPRESS WORLDWIDE DDOCUMENTS N
EXPRESS WORLDWIDE (NON DOC) PNON_DOCUMENTS Y
EXPRESS WORLDWIDE EU UDOCUMENTS N

Notes:

Usage

Once configured, steps for usage are as follows:

  1. Create a new Sales Order for any customer,
  2. Add stock items and a payment line to the Sales Order, Save.
  3. Open the Sales Order in the [ Sales Invoice Manager ] and move to the Shipping stage.
  4. Green select the Sales Order in the shipping stage, click confirm shipment
  5. Set the date for delivery, move the sales order into the lower grid.
  6. Click ok.
  7. 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.
  8. 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.
  9. A label and any other documents will be returned and printed/saved based on your configuration.
  10. A dialog will ask if you wish to move the invoice to the next stage.
  11. 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:
    1. Green select the sales invoice and click Confirm Shipment,
    2. 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/expressRateBook The 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.


See Also


Did you find this article helpful?