DHL Internetmarke Integration: Stamps as ZPL

User plugins

Under Integrations (/platform/integrations) a plugin is configured once per account with the user's own credentials. Configured plugins are available in Print Views and, with an API key, in REST calls. Registered plugin IDs: dhl. Storage: userplugins.configJson per e-mail + plugin.

The DHL plugin (com.zplcloud.plugin.dhl, .NET 10, PDFsharp) calls the Deutsche Post API api-eu.dhl.com/post/de/shipping/im/v1: token via client_credentials + Portokasse login (24 h), shopping cart, checkout as PDF, 90° rotation and optional right trim. Every stamp is a real purchase at the current PPL price; no markup, no stamp stock.

Functions

Stamp as PDF (address-zone layout, 43 × 89 mm, auto-rotated) or as ZPL (1:1 conversion at 203 dpi, Pdf2ZplConverter, contain).
Sender list with default sender; product choice (Standardbrief … Großbrief, with/without Einschreiben).
Balance and product catalog check (/status).
REST purchase (POST /api/integrations/dhl/buy) with voucherId, shopOrderId and new balance.
DHL-only Print Views: order ID → datasource lookup → purchase → print to Weblink, CLI agent or watch folder.
Transaction log with PDF reprint, ZPL download and re-send.

Requirements

Item	Detail
DHL Developer Portal	`client_id` and `client_secret` of your REST application.
Portokasse	Username (e-mail) and password (max. 22 characters).
One-time approval	Approve the REST application in the Portokasse under My data → Business applications; otherwise the API answers `401 genericUserAuthenticationError`.
Funds	Each stamp debits the Portokasse at the current PPL price.

Setup

/platform/integrations → DHL Internetmarke → Configure: client ID, client secret, Portokasse user and password.
Add at least one sender (name/company, street + no., ZIP, city); mark one as default (otherwise the first is used).
Choose the product (default 1002 "Standardbrief + Einschreiben Einwurf").
Save, then Check: balance, version and product catalog are shown.

Client secret and password are never returned to the browser; leave them empty when editing to keep the stored values.

Products and prices

Product	Price
Standardbrief	€ 0.95
Kompaktbrief	€ 1.10
Großbrief	€ 1.80
Maxibrief	€ 2.90
Standardbrief + Einschreiben Einwurf (product 1002, default)	€ 3.30
Standardbrief + Einschreiben	€ 3.60
Kompaktbrief + Einschreiben Einwurf	€ 3.45
Großbrief + Einschreiben Einwurf	€ 4.15

Prices follow the current DHL PPL; the API validates the price against the catalog before checkout. The chosen product applies to the API and to DHL-only Print Views. Page format 296 (43 × 89 mm without margin), voucher layout AddressZone.

REST API (account)

Route	Function
GET\|PUT\|DELETE /api/integrations/{plugin}/config	Read / write / remove plugin configuration.
GET /api/integrations/dhl/status	`walletBalanceCents`, `productId`, product catalog.
POST /api/integrations/dhl/product	Set the product.
POST /api/integrations/dhl/buy	Purchase; body see below.

GET /api/integrations/dhl/status

{
  "ok": true,
  "walletBalanceCents": 12550,
  "productId": 1002,
  "products": [ { "id": 1, "name": "Standardbrief", "priceCents": 95 }, ... ]
}

POST /api/integrations/dhl/buy
{
  "senderId": "3f1a2c9b",          // optional, default sender otherwise
  "format": "zpl",                  // pdf | zpl
  "receiver": {
    "name": "Max Mustermann",
    "additionalName": "",           // optional
    "addressLine1": "Musterstrasse 12b",
    "addressLine2": "",             // optional
    "postalCode": "12345",
    "city": "Musterstadt",
    "country": "DEU"
  }
}

{
  "ok": true,
  "format": "zpl",
  "zpl": "^XA^FO...^XZ",
  "widthMm": 89, "heightMm": 43,
  "widthPx": 711, "heightPx": 344,
  "walletBalanceCents": 12220,
  "voucherId": "VH-4f2a9c...",
  "shopOrderId": "1000023456"
}

Send the ZPL to any Zebra: zplcloud send, Weblink printer or the platform. shopOrderId and voucherId serve as receipt references.

DHL-only Print Views

View type dhlOnly in the Print Views editor: no design, the stamp is the label. URL https://print.zplcloud.com/d/dhl/{slug} (/pv/{id} redirects). Access, mobile layout and PWA as for all views.

Editor fields: dhlOnly switch; dhlFieldMap with orderIdColumn (default orderId), optional label/placeholder, map.receiverName|receiverStreet|receiverPostalCode|receiverCity (columns can be combined: vorname+nachname); datasourceId (data hub); printerId / allowedPrinters.

https://print.zplcloud.com/d/dhl/versand-marken

Datasource example (SQL Server through the CLI agent; the connection string stays on the agent host, the query runs with pushdown and parameters):

zplcloud proxy --agent "Lager" \
  --sql ORDERS="Server=127.0.0.1;Database=erp;User Id=zplcloud;Password=...;Encrypt=True;TrustServerCertificate=True"

-- datasource "Lager-Artikel": SQL Server, server ORDERS
SELECT orderId, nachname, vorname, strasse, plz, ort
FROM auftraege
WHERE orderId LIKE @p0

Flow on the page: enter ID → POST /d/dhl/{slug}/dhl/lookup fills the mapped receiver fields → choose sender and printer → POST /d/dhl/{slug}/dhl/print: purchase via the user's integration, PDF → ZPL (203 dpi), send to the printer (Weblink, CLI agent or watch folder). "✓ Stamp bought & sent" is shown only after the printer accepted the data; a failed send is reported as an error. Missing data → 400; demo accounts cannot print.

Transaction log

Table plugintransactions records every purchase: source (user / apikey with description / printview slug), e-mail + company snapshot, status ok/error, product, costs, voucherId, shopOrderId, balance after, full recipient address, DHL response JSON, PDF blob, optional ZPL.

UI: /platform/integrations/dhl/logs (Integrations → DHL → Logs): grid with filter row, XLSX export, totals today / month / all; row actions PDF (reprint), ZPL, Send ZPL (Weblink, agent or watch folder).
Visibility: own transactions; company transactions for company admins; supervisor all.
Endpoints: GET/POST /api/integrations/dhl/logs*.

Public API (api.zplcloud.com, API key)

Route	Function
POST /v1/integrations/dhl/stamp	Purchase (same body as `/buy`); response includes `voucherId`.
GET /v1/integrations/dhl/stamps	Own transactions incl. voucher IDs.
GET /v1/integrations/dhl/status	Balance and product catalog.

Security

Client secret and Portokasse password are stored server-side only and never returned.
Price validation against the current PPL catalog before checkout.
Datasource credentials stay in your LAN; only result rows reach the platform.
Incomplete receiver or lookup data → 400; demo accounts cannot print.