Overview
Client-mode REST API connectors for the DHL API Developer Portal: Shipment Tracking Unified (every DHL division) with Tracking Push subscriptions, Location Finder service points, DHL Express MyDHL API (rates, landed cost, shipments and labels, pickups, tracking, proof of delivery, paperless trade uploads) and Post & Parcel Germany (Parcel DE Shipping, Pickup and Returns with OAuth); purchases marked; companion server connector for DHL Tracking Push webhooks. This is one of the templates in the DHL API Developer Portal REST API app (dhl-api-developer-portal). Deploy it alongside the other connectors of that app when they depend on each other (for example a token connector plus an API connector).
Not yet verified against the live vendor API: No own DHL credentials on the factory box (no DHL_* / MYDHL_* variables): no developer.dhl.com app key with the Tracking / Location Finder / Push / Parcel DE products, no MyDHL API username + password, no DHL Express account or Parcel DE billing number. Static, mock, negative-control and no / fake-credential public probes ran; DHL’s public pre-defined test keys gave live 200s for TrackShipment (mocked data), Location Finder and the Parcel DE sandbox token + hello, but those demo keys have no shipping product (Parcel DE ValidateShipments 401 no apiproduct match; MyDHL rejects the portal demo key), so no authenticated GET + POST round trip of the shipping APIs and no broker MQTT round trip.
Auth
Per product: DhlApi + DhlLocationFinder header DHL-API-Key (developer.dhl.com app key); MyDhlExpress HTTP Basic MyDHL username:password (from DHL Express, not the portal key) + x-version 3.3.3 + Message-Reference; DhlParcelDeAuth OAuth 2.0 password grant (form grant_type=password, username, password = GKP system user, client_id = API key, client_secret = API secret; reply access_token Bearer, expires_in 1799, no refresh token); DhlParcelDe Authorization: Bearer only (bearer + dhl-api-key together -> 401). Every event sends User-Agent: Coreflux-Broker. Auth headers used by the template:Authorization: Basic {value.json.basic}.
Template parameters
| Placeholder | Type | Description | Required |
|---|---|---|---|
RouteName | string | Name of the My Dhl Express connector | no |
BaseUrl | string | My Dhl Express base URL without trailing slash (e.g. https://express.api.dhl.com) | yes |
BASE_ADDRESS default: https://express.api.dhl.com.
Events
| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
|---|---|---|---|---|---|
ExpressGetRates | GET | /mydhlapi/rates?{value.json.query} | fleet/dhl/express-rate/get | fleet/dhl/express-rate/get/response | basic, message_ref, query |
ExpressGetRatesMultiPiece | POST | /mydhlapi/rates | fleet/dhl/express-rate-multi/get | fleet/dhl/express-rate-multi/get/response | basic, body, message_ref |
ExpressGetProducts | GET | /mydhlapi/products?{value.json.query} | fleet/dhl/express-product/get | fleet/dhl/express-product/get/response | basic, message_ref, query |
ExpressValidateAddress | GET | /mydhlapi/address-validate?{value.json.query} | fleet/dhl/express-address/validate | fleet/dhl/express-address/validate/response | basic, message_ref, query |
ExpressGetLandedCost | POST | /mydhlapi/landed-cost | fleet/dhl/express-landed-cost/get | fleet/dhl/express-landed-cost/get/response | basic, body, message_ref |
ExpressValidateShipment | POST | /mydhlapi/shipments?validateDataOnly=true | fleet/dhl/express-shipment/validate | fleet/dhl/express-shipment/validate/response | basic, body, message_ref |
ExpressCreateShipment | POST | /mydhlapi/shipments | fleet/dhl/express-shipment/create | fleet/dhl/express-shipment/create/response | basic, body, message_ref |
ExpressAddShipmentPiece | PATCH | /mydhlapi/shipments/{value.json.id}/add-piece | fleet/dhl/express-shipment-piece/create | fleet/dhl/express-shipment-piece/create/response | basic, body, id, message_ref |
ExpressTrackShipment | GET | /mydhlapi/shipments/{value.json.id}/tracking?{value.json.query} | fleet/dhl/express-tracking/get | fleet/dhl/express-tracking/get/response | basic, id, message_ref, query |
ExpressTrackShipments | GET | /mydhlapi/tracking?{value.json.query} | fleet/dhl/express-tracking-multi/get | fleet/dhl/express-tracking-multi/get/response | basic, message_ref, query |
ExpressGetProofOfDelivery | GET | /mydhlapi/shipments/{value.json.id}/proof-of-delivery?{value.json.query} | fleet/dhl/express-proof-of-delivery/get | fleet/dhl/express-proof-of-delivery/get/response | basic, id, message_ref, query |
ExpressGetShipmentImage | GET | /mydhlapi/shipments/{value.json.id}/get-image?{value.json.query} | fleet/dhl/express-shipment-image/get | fleet/dhl/express-shipment-image/get/response | basic, id, message_ref, query |
ExpressUploadShipmentImage | PATCH | /mydhlapi/shipments/{value.json.id}/upload-image | fleet/dhl/express-shipment-image/upload | fleet/dhl/express-shipment-image/upload/response | basic, body, id |
ExpressUploadShipmentInvoiceData | PATCH | /mydhlapi/shipments/{value.json.id}/upload-invoice-data | fleet/dhl/express-shipment-invoice/upload | fleet/dhl/express-shipment-invoice/upload/response | basic, body, id, message_ref |
ExpressUploadInvoiceData | POST | /mydhlapi/invoices/upload-invoice-data | fleet/dhl/express-invoice/upload | fleet/dhl/express-invoice/upload/response | basic, body, message_ref |
ExpressCreatePickup | POST | /mydhlapi/pickups | fleet/dhl/express-pickup/create | fleet/dhl/express-pickup/create/response | basic, body, message_ref |
ExpressUpdatePickup | PATCH | /mydhlapi/pickups/{value.json.id} | fleet/dhl/express-pickup/update | fleet/dhl/express-pickup/update/response | basic, body, id, message_ref |
ExpressCancelPickup | DELETE | /mydhlapi/pickups/{value.json.id}?{value.json.query} | fleet/dhl/express-pickup/cancel | fleet/dhl/express-pickup/cancel/response | basic, id, message_ref, query |
ExpressAllocateIdentifiers | GET | /mydhlapi/identifiers?{value.json.query} | fleet/dhl/express-identifier/create | fleet/dhl/express-identifier/create/response | basic, message_ref, query |
ExpressFindServicePoints | GET | /mydhlapi/servicepoints?{value.json.query} | fleet/dhl/express-service-point/search | fleet/dhl/express-service-point/search/response | basic, query |
ExpressGetReferenceData | GET | /mydhlapi/reference-data?{value.json.query} | fleet/dhl/express-reference-data/get | fleet/dhl/express-reference-data/get/response | basic, message_ref, query |
ExpressEarlyShipmentScreening | POST | /mydhlapi/early-shipment-screening | fleet/dhl/express-screening/create | fleet/dhl/express-screening/create/response | basic, body, message_ref |
Deploy
Get the template card (JSON withtemplate and metadata) from the broker, then deploy the connector:
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-routeCode MY_DHL_EXPRESS"
BASE_ADDRESS already filled in:
DEFINE ROUTE MyDhlExpress WITH TYPE REST_API
ADD REST_API_CONFIG
WITH BASE_ADDRESS "https://express.api.dhl.com"
WITH ENABLE_CLIENT "true"
WITH USE_SSL "true"
WITH REQUEST_TIMEOUT '60'
WITH DEFAULT_CONTENT_TYPE "application/json"
ADD EVENT ExpressGetRates
WITH SOURCE_TOPIC "fleet/dhl/express-rate/get"
WITH DESTINATION_TOPIC "fleet/dhl/express-rate/get/response"
WITH METHOD "GET"
WITH ENDPOINT "/mydhlapi/rates?{value.json.query}"
WITH HEADERS
ADD "Accept" "application/json"
ADD "User-Agent" "Coreflux-Broker"
ADD "Authorization" "Basic {value.json.basic}"
ADD "x-version" "3.3.3"
ADD "Message-Reference" "{value.json.message_ref}"
ADD EVENT ExpressGetRatesMultiPiece
WITH SOURCE_TOPIC "fleet/dhl/express-rate-multi/get"
WITH DESTINATION_TOPIC "fleet/dhl/express-rate-multi/get/response"
WITH METHOD "POST"
WITH ENDPOINT "/mydhlapi/rates"
WITH HEADERS
ADD "Accept" "application/json"
ADD "User-Agent" "Coreflux-Broker"
ADD "Authorization" "Basic {value.json.basic}"
ADD "x-version" "3.3.3"
ADD "Message-Reference" "{value.json.message_ref}"
ADD "Content-Type" "application/json"
WITH BODY "{value.json.body}"
ADD EVENT ExpressGetProducts
WITH SOURCE_TOPIC "fleet/dhl/express-product/get"
WITH DESTINATION_TOPIC "fleet/dhl/express-product/get/response"
WITH METHOD "GET"
WITH ENDPOINT "/mydhlapi/products?{value.json.query}"
WITH HEADERS
ADD "Accept" "application/json"
ADD "User-Agent" "Coreflux-Broker"
ADD "Authorization" "Basic {value.json.basic}"
ADD "x-version" "3.3.3"
ADD "Message-Reference" "{value.json.message_ref}"
ADD EVENT ExpressValidateAddress
WITH SOURCE_TOPIC "fleet/dhl/express-address/validate"
WITH DESTINATION_TOPIC "fleet/dhl/express-address/validate/response"
WITH METHOD "GET"
WITH ENDPOINT "/mydhlapi/address-validate?{value.json.query}"
WITH HEADERS
ADD "Accept" "application/json"
ADD "User-Agent" "Coreflux-Broker"
ADD "Authorization" "Basic {value.json.basic}"
ADD "x-version" "3.3.3"
ADD "Message-Reference" "{value.json.message_ref}"
ADD EVENT ExpressGetLandedCost
WITH SOURCE_TOPIC "fleet/dhl/express-landed-cost/get"
WITH DESTINATION_TOPIC "fleet/dhl/express-landed-cost/get/response"
WITH METHOD "POST"
WITH ENDPOINT "/mydhlapi/landed-cost"
WITH HEADERS
ADD "Accept" "application/json"
ADD "User-Agent" "Coreflux-Broker"
ADD "Authorization" "Basic {value.json.basic}"
ADD "x-version" "3.3.3"
ADD "Message-Reference" "{value.json.message_ref}"
ADD "Content-Type" "application/json"
WITH BODY "{value.json.body}"
ADD EVENT ExpressValidateShipment
WITH SOURCE_TOPIC "fleet/dhl/express-shipment/validate"
WITH DESTINATION_TOPIC "fleet/dhl/express-shipment/validate/response"
WITH METHOD "POST"
WITH ENDPOINT "/mydhlapi/shipments?validateDataOnly=true"
WITH HEADERS
ADD "Accept" "application/json"
ADD "User-Agent" "Coreflux-Broker"
ADD "Authorization" "Basic {value.json.basic}"
ADD "x-version" "3.3.3"
ADD "Message-Reference" "{value.json.message_ref}"
ADD "Content-Type" "application/json"
WITH BODY "{value.json.body}"
ADD EVENT ExpressCreateShipment
WITH SOURCE_TOPIC "fleet/dhl/express-shipment/create"
WITH DESTINATION_TOPIC "fleet/dhl/express-shipment/create/response"
WITH METHOD "POST"
WITH ENDPOINT "/mydhlapi/shipments"
WITH HEADERS
ADD "Accept" "application/json"
ADD "User-Agent" "Coreflux-Broker"
ADD "Authorization" "Basic {value.json.basic}"
ADD "x-version" "3.3.3"
ADD "Message-Reference" "{value.json.message_ref}"
ADD "Content-Type" "application/json"
WITH BODY "{value.json.body}"
ADD EVENT ExpressAddShipmentPiece
WITH SOURCE_TOPIC "fleet/dhl/express-shipment-piece/create"
WITH DESTINATION_TOPIC "fleet/dhl/express-shipment-piece/create/response"
WITH METHOD "PATCH"
WITH ENDPOINT "/mydhlapi/shipments/{value.json.id}/add-piece"
WITH HEADERS
ADD "Accept" "application/json"
ADD "User-Agent" "Coreflux-Broker"
ADD "Authorization" "Basic {value.json.basic}"
ADD "x-version" "3.3.3"
ADD "Message-Reference" "{value.json.message_ref}"
ADD "Content-Type" "application/json"
WITH BODY "{value.json.body}"
ADD EVENT ExpressTrackShipment
WITH SOURCE_TOPIC "fleet/dhl/express-tracking/get"
WITH DESTINATION_TOPIC "fleet/dhl/express-tracking/get/response"
WITH METHOD "GET"
WITH ENDPOINT "/mydhlapi/shipments/{value.json.id}/tracking?{value.json.query}"
WITH HEADERS
ADD "Accept" "application/json"
ADD "User-Agent" "Coreflux-Broker"
ADD "Authorization" "Basic {value.json.basic}"
ADD "x-version" "3.3.3"
ADD "Message-Reference" "{value.json.message_ref}"
ADD EVENT ExpressTrackShipments
WITH SOURCE_TOPIC "fleet/dhl/express-tracking-multi/get"
WITH DESTINATION_TOPIC "fleet/dhl/express-tracking-multi/get/response"
WITH METHOD "GET"
WITH ENDPOINT "/mydhlapi/tracking?{value.json.query}"
WITH HEADERS
ADD "Accept" "application/json"
ADD "User-Agent" "Coreflux-Broker"
ADD "Authorization" "Basic {value.json.basic}"
ADD "x-version" "3.3.3"
ADD "Message-Reference" "{value.json.message_ref}"
ADD EVENT ExpressGetProofOfDelivery
WITH SOURCE_TOPIC "fleet/dhl/express-proof-of-delivery/get"
WITH DESTINATION_TOPIC "fleet/dhl/express-proof-of-delivery/get/response"
WITH METHOD "GET"
WITH ENDPOINT "/mydhlapi/shipments/{value.json.id}/proof-of-delivery?{value.json.query}"
WITH HEADERS
ADD "Accept" "application/json"
ADD "User-Agent" "Coreflux-Broker"
ADD "Authorization" "Basic {value.json.basic}"
ADD "x-version" "3.3.3"
ADD "Message-Reference" "{value.json.message_ref}"
ADD EVENT ExpressGetShipmentImage
WITH SOURCE_TOPIC "fleet/dhl/express-shipment-image/get"
WITH DESTINATION_TOPIC "fleet/dhl/express-shipment-image/get/response"
WITH METHOD "GET"
WITH ENDPOINT "/mydhlapi/shipments/{value.json.id}/get-image?{value.json.query}"
WITH HEADERS
ADD "Accept" "application/json"
ADD "User-Agent" "Coreflux-Broker"
ADD "Authorization" "Basic {value.json.basic}"
ADD "x-version" "3.3.3"
ADD "Message-Reference" "{value.json.message_ref}"
ADD EVENT ExpressUploadShipmentImage
WITH SOURCE_TOPIC "fleet/dhl/express-shipment-image/upload"
WITH DESTINATION_TOPIC "fleet/dhl/express-shipment-image/upload/response"
WITH METHOD "PATCH"
WITH ENDPOINT "/mydhlapi/shipments/{value.json.id}/upload-image"
WITH HEADERS
ADD "Accept" "application/json"
ADD "User-Agent" "Coreflux-Broker"
ADD "Authorization" "Basic {value.json.basic}"
ADD "x-version" "3.3.3"
ADD "Content-Type" "application/json"
WITH BODY "{value.json.body}"
ADD EVENT ExpressUploadShipmentInvoiceData
WITH SOURCE_TOPIC "fleet/dhl/express-shipment-invoice/upload"
WITH DESTINATION_TOPIC "fleet/dhl/express-shipment-invoice/upload/response"
WITH METHOD "PATCH"
WITH ENDPOINT "/mydhlapi/shipments/{value.json.id}/upload-invoice-data"
WITH HEADERS
ADD "Accept" "application/json"
ADD "User-Agent" "Coreflux-Broker"
ADD "Authorization" "Basic {value.json.basic}"
ADD "x-version" "3.3.3"
ADD "Message-Reference" "{value.json.message_ref}"
ADD "Content-Type" "application/json"
WITH BODY "{value.json.body}"
ADD EVENT ExpressUploadInvoiceData
WITH SOURCE_TOPIC "fleet/dhl/express-invoice/upload"
WITH DESTINATION_TOPIC "fleet/dhl/express-invoice/upload/response"
WITH METHOD "POST"
WITH ENDPOINT "/mydhlapi/invoices/upload-invoice-data"
WITH HEADERS
ADD "Accept" "application/json"
ADD "User-Agent" "Coreflux-Broker"
ADD "Authorization" "Basic {value.json.basic}"
ADD "x-version" "3.3.3"
ADD "Message-Reference" "{value.json.message_ref}"
ADD "Content-Type" "application/json"
WITH BODY "{value.json.body}"
ADD EVENT ExpressCreatePickup
WITH SOURCE_TOPIC "fleet/dhl/express-pickup/create"
WITH DESTINATION_TOPIC "fleet/dhl/express-pickup/create/response"
WITH METHOD "POST"
WITH ENDPOINT "/mydhlapi/pickups"
WITH HEADERS
ADD "Accept" "application/json"
ADD "User-Agent" "Coreflux-Broker"
ADD "Authorization" "Basic {value.json.basic}"
ADD "x-version" "3.3.3"
ADD "Message-Reference" "{value.json.message_ref}"
ADD "Content-Type" "application/json"
WITH BODY "{value.json.body}"
ADD EVENT ExpressUpdatePickup
WITH SOURCE_TOPIC "fleet/dhl/express-pickup/update"
WITH DESTINATION_TOPIC "fleet/dhl/express-pickup/update/response"
WITH METHOD "PATCH"
WITH ENDPOINT "/mydhlapi/pickups/{value.json.id}"
WITH HEADERS
ADD "Accept" "application/json"
ADD "User-Agent" "Coreflux-Broker"
ADD "Authorization" "Basic {value.json.basic}"
ADD "x-version" "3.3.3"
ADD "Message-Reference" "{value.json.message_ref}"
ADD "Content-Type" "application/json"
WITH BODY "{value.json.body}"
ADD EVENT ExpressCancelPickup
WITH SOURCE_TOPIC "fleet/dhl/express-pickup/cancel"
WITH DESTINATION_TOPIC "fleet/dhl/express-pickup/cancel/response"
WITH METHOD "DELETE"
WITH ENDPOINT "/mydhlapi/pickups/{value.json.id}?{value.json.query}"
WITH HEADERS
ADD "Accept" "application/json"
ADD "User-Agent" "Coreflux-Broker"
ADD "Authorization" "Basic {value.json.basic}"
ADD "x-version" "3.3.3"
ADD "Message-Reference" "{value.json.message_ref}"
ADD EVENT ExpressAllocateIdentifiers
WITH SOURCE_TOPIC "fleet/dhl/express-identifier/create"
WITH DESTINATION_TOPIC "fleet/dhl/express-identifier/create/response"
WITH METHOD "GET"
WITH ENDPOINT "/mydhlapi/identifiers?{value.json.query}"
WITH HEADERS
ADD "Accept" "application/json"
ADD "User-Agent" "Coreflux-Broker"
ADD "Authorization" "Basic {value.json.basic}"
ADD "x-version" "3.3.3"
ADD "Message-Reference" "{value.json.message_ref}"
ADD EVENT ExpressFindServicePoints
WITH SOURCE_TOPIC "fleet/dhl/express-service-point/search"
WITH DESTINATION_TOPIC "fleet/dhl/express-service-point/search/response"
WITH METHOD "GET"
WITH ENDPOINT "/mydhlapi/servicepoints?{value.json.query}"
WITH HEADERS
ADD "Accept" "application/json"
ADD "User-Agent" "Coreflux-Broker"
ADD "Authorization" "Basic {value.json.basic}"
ADD EVENT ExpressGetReferenceData
WITH SOURCE_TOPIC "fleet/dhl/express-reference-data/get"
WITH DESTINATION_TOPIC "fleet/dhl/express-reference-data/get/response"
WITH METHOD "GET"
WITH ENDPOINT "/mydhlapi/reference-data?{value.json.query}"
WITH HEADERS
ADD "Accept" "application/json"
ADD "User-Agent" "Coreflux-Broker"
ADD "Authorization" "Basic {value.json.basic}"
ADD "x-version" "3.3.3"
ADD "Message-Reference" "{value.json.message_ref}"
ADD EVENT ExpressEarlyShipmentScreening
WITH SOURCE_TOPIC "fleet/dhl/express-screening/create"
WITH DESTINATION_TOPIC "fleet/dhl/express-screening/create/response"
WITH METHOD "POST"
WITH ENDPOINT "/mydhlapi/early-shipment-screening"
WITH HEADERS
ADD "Accept" "application/json"
ADD "User-Agent" "Coreflux-Broker"
ADD "Authorization" "Basic {value.json.basic}"
ADD "Message-Reference" "{value.json.message_ref}"
ADD "Content-Type" "application/json"
WITH BODY "{value.json.body}"
-addRoute (do not include ADD METADATA).
Usage example
CallExpressGetRates by publishing a JSON payload to its request topic, and read the reply on the response topic:
mosquitto_sub -t 'fleet/dhl/express-rate/get/response' &
mosquitto_pub -t 'fleet/dhl/express-rate/get' -m '{"basic": "<basic>", "message_ref": "<message_ref>", "query": "<query>"}'