Initial Setup Wizard
The Setup Wizard guides you step by step through the basic configuration of the DHL Parcel DE Connector. It is ideal for initial setup or when you want to configure the DHL connection from scratch.
Opening the Page
- Open the DHL Dashboard β Click Setup Wizard in the navigation bar.
- Or: Open the search (Alt+Q) and search for "DHL Setup Wizard".
- Or: When first opening the DHL Dashboard, a notification with a link to the wizard appears automatically.
Prerequisites
Before starting the wizard, have the following information ready:
- DHL Business Customer Account (contract number)
- API Key (DHL Developer Portal β App "DHL Parcel DE Shipping")
- Username & Password (for Basic Auth) or Client ID & Secret (for OAuth2)
- Shipper Address (company name, street, postal code, city, country)
Obtaining API Credentials
Register at the DHL Developer Portal and create an app of type "DHL Parcel DE Shipping (Post & Parcel Germany)". Your API credentials are available there under your app details.
Wizard Steps
Step 1: Welcome
The welcome page shows an overview of prerequisites. Ensure you have all necessary credentials ready.
Click Next to continue.
Step 2: Authentication
Configure the API credentials for the DHL Shipping API here.
| Field | Description |
|---|---|
| Auth Type | Authentication method: Basic Auth (standard/legacy) or OAuth2 (ROPC) |
| API Key | DHL API Key (dhl-api-key header) β click to enter |
| Username / Client ID | Basic Auth username or OAuth2 Client ID β click to enter |
| Password / Client Secret | Basic Auth password or OAuth2 Client Secret β click to enter |
| Sandbox Mode | Enables the DHL sandbox environment for testing (no real labels) |
| API Base URL | DHL API URL (set automatically, change only if needed) |
Credential Entry
All sensitive fields (API Key, Username, Password) open a secure input dialog when clicked. Already stored values are only displayed as "Configured" / "Not configured" β never in plain text.
Sandbox Mode
Enable sandbox mode for testing. In sandbox mode, no real shipping labels are created. Only disable the mode when you are ready for production.
Step 3: Connection Test
Test the connection to the DHL API to ensure your credentials are correct.
- Click Test Connection.
- The result is displayed:
- Green (Successful): Connection successful β you can proceed.
- Red (Error): Connection failed β check your credentials in Step 2.
Optional Step
The connection test is recommended but not mandatory. You can proceed to the next step without testing.
Step 4: Shipper Address
Enter the shipper address that will be printed on all DHL labels.
| Field | Description |
|---|---|
| Shipper Name | Company name (line 1) |
| Shipper Name 2 | Additional name (line 2, optional) |
| Shipper Street | Street name |
| Shipper House No. | House number |
| Shipper Post Code | Postal code |
| Shipper City | City |
| Shipper Country Code | Country code (ISO, e.g., DE) |
| Shipper Contact Name | Contact person |
| Shipper Email | Email address |
| Shipper Phone | Phone number |
Automatically Load from Company Data
Click Load from Company to automatically populate the shipper address from BC company information (Company Information):
- Company name β Shipper Name
- Address β Street + House No.
- Post Code β Post Code
- City β City
- Country β Country Code
- Phone β Phone
- Email β Email
Time Saver
If your BC company information is already correctly maintained, simply click "Load from Company" and review the imported values. In most cases, you only need to add the contact person.
Step 5: Defaults
Set defaults that will be used as standard values for every label creation.
| Field | Description | Recommendation |
|---|---|---|
| Default Weight (g) | Default package weight in grams if no weight is provided | 1000 (= 1 kg) |
| Label Print Format | Default print format for labels | Depends on printer (A4, 100x70mm, etc.) |
| Doc Format | Document format (PDF or ZPL2) | PDF for standard printers, ZPL2 for thermal printers |
| Def. GoGreen Plus | Enable GoGreen Plus by default | As desired |
| Include Return Label | Automatically create return label with every label | Depends on business model |
Step 6: Summary & Finish
The final page shows a configuration status summary:
| Checkpoint | Status | Meaning |
|---|---|---|
| Credentials | β Configured / β Incomplete | API credentials complete |
| Connection Test | β Successful / β Not tested | Connection test passed |
| Shipper Address | β Configured / β Incomplete | Shipper address complete |
Click Finish to complete the setup and save the configuration.
Incomplete Configuration
Even if individual checkpoints show "Incomplete" or "Not tested", you can complete the wizard. You can add the missing settings at any time via the DHL Setup Card.
After the Wizard
After completing the Setup Wizard, we recommend:
- Create a Profile: Set up at least one DHL profile for your standard shipping configuration.
- Define Shipping Rules: Set up automatic rules (e.g., insurance above amount X).
- Enable Tracking: Configure the separate Tracking API Key for automatic shipment tracking.
- Test Shipment: Create a test label (in sandbox mode) and verify the result.
Frequently Asked Questions
Can I run the wizard again?
Yes. The wizard can be restarted at any time via the Dashboard or search. Existing values are preserved β you can selectively adjust individual steps.
What happens to my existing settings?
The wizard only overwrites fields that you actively change. Already configured values remain intact if you pass a step unchanged.
Connection test fails β what to do?
- Check the API Key (most common error: key from the wrong app in the Developer Portal).
- Check Username/Password (for Basic Auth: the GKP credentials, not the portal credentials).
- Check Sandbox Mode: In sandbox mode, different credentials apply than in production.
- See also: Troubleshooting.