Taxmod DHL

DHL tracking for the Taxonomy Modeller (WordPress plugin), over DHL's Shipment Tracking – Unified API.

Status 0.0.10: API key in the common «Access» part of the modeller's «DHL» tab (sealed in the modeller's vault), server switch sandbox / production, «Test connection», a read-only probe that tracks one number and lists its events, and the filter taxmod_dhl_tracking for other modules. New in 0.0.2: Internetmarke access (app secret + Portokasse login, sealed) and a probe «Check Portokasse» that shows the balance and the print formats, label printers first — step 1 towards printing letter postage on the 62 mm label printer. It buys nothing. Deutsche Post letters with a matrix code (e.g. the Maxibrief of an eBay label) are found without a hint; DHL answers them as service svb with an internal id, so the result keeps the number asked for (0.0.6). The probe «Track» takes an optional service hint and recipient postcode. Tracking tested against DHL production on 2026-10-27; Internetmarke not yet tested against the Post. Nothing is written to the model.

Idea in short

• The eBay shipping page (and later every source) knows tracking numbers but not where the parcel is.
• This module asks DHL per tracking number and turns DHL's statusCode into a stage: announced (label only), shipped, delivered, problem.
• One place holds the DHL key and the daily quota; other modules only ask the filter.
• Addresses DHL sends are not stored, only the place of an event.

Setup

1. Sign in at developer.dhl.com, create an app with Shipment Tracking – Unified. Start with the sandbox: it is granted at once and proves that the web server can reach DHL at all.

2. Enter the app's API key on Taxonomy Modeller → Configuration → DHL, server «Sandbox», save, «Test connection». If the test says the web server cannot reach DHL, the host blocks outgoing calls and production access is pointless. Or define the key in wp-config.php, which takes precedence. Never post it in a chat:

   define('TAXDHL_API_KEY', '…');
   define('TAXDHL_ENVIRONMENT', 'production'); // or 'sandbox'

3. Request production access for the app, switch the server to «Production», test again, then «Track» one real number.

Internetmarke (letter postage, optional)

The Internetmarke API sells Deutsche Post letter postage from a Portokasse and returns each stamp as PNG or PDF, so a label can be laid out pixel-exact for a label printer. Access = client id and secret of the DHL app (with the API «Post DE Internetmarke») plus the Portokasse login; production needs a one-time approval per Portokasse. For tests, register a second Portokasse and ask it-csp@deutschepost.de to turn it into a developer Portokasse (stamps print «Muster», no charge).

Mails

With Taxmod Mail, this module also reads DHL's parcel notices («Ihre … Sendung ist unterwegs», «… wurde zugestellt»). They name no order, only the tracking number, so the modeller hands them to the order carrying that number, whatever shop it came from. Without such an order a notice brings nothing. Label mails («Online Frankierung») are still read by Taxmod Mail.

For other modules

$state = apply_filters('taxmod_dhl_tracking', null, $trackingNumber);             // last loaded answer, no call to DHL
$state = apply_filters('taxmod_dhl_tracking', null, $trackingNumber, 'refresh');  // asks DHL now and keeps the answer
// null when nothing was loaded yet, or (refresh) no key, budget used up or DHL failed; otherwise
// ['tracking_number', 'known', 'stage' => 'announced|shipped|delivered|problem', 'status_code', 'status', 'at', 'shipped_at', 'estimated',
//  'events' => [['at', 'status_code', 'status', 'description', 'place'], …] newest first (empty if not scanned), 'checked_at' => Unix time DHL was asked]
// A number DHL has not scanned yet: 'known' => false, 'stage' => 'announced' (like eBay's «tracking number entered», 0.0.7).

DHL is only called on refresh (0.0.9: the shipping page refreshes on a click on the number or «Refresh»); calls keep DHL's gap of 5 seconds (a refresh of n numbers takes about 5·n seconds), a 404 never overwrites a known answer, the last 500 answers are kept, and all calls of a day stay under 200 (the app's quota is 250).

Development

composer install, then vendor/bin/phpunit (core suite, no WordPress). The fixture is the example of DHL's OpenAPI file 1.5.8.

License

Copyright (C) 2026 Stefan Fambach (SteFam), https://www.fambach.net — PolyForm Noncommercial 1.0.0. Commercial use needs the owner's prior consent.

Authors

• Stefan Fambach (SteFam) – idea and concept, review and testing – https://www.fambach.net
• Claude (Anthropic AI) – implementation, via Claude Code

AI disclosure

This project is built with AI assistance. Stefan Fambach had the idea, wrote the concept and reviews and tests every change; the implementation (code and documentation) is written largely by Claude (Anthropic) via Claude Code.