DHL-Internetmarke-Integration: Porto als ZPL

User-Plugins

Unter Integrations (/platform/integrations) wird ein Plugin einmal je Konto mit den eigenen Zugangsdaten konfiguriert. Konfigurierte Plugins stehen in Print Views und, mit API-Key, in REST-Aufrufen zur Verfügung. Registrierte Plugin-IDs: dhl. Ablage: userplugins.configJson je E-Mail + Plugin.

Das DHL-Plugin (com.zplcloud.plugin.dhl, .NET 10, PDFsharp) ruft die Deutsche-Post-API api-eu.dhl.com/post/de/shipping/im/v1 auf: Token per client_credentials + Portokasse-Login (24 h), Warenkorb, Checkout als PDF, 90°-Drehung und optionaler Beschnitt rechts. Jede Marke ist ein echter Kauf zum aktuellen PPL-Preis; kein Aufschlag, kein Markenvorrat.

Funktionen

Marke als PDF (Adresszonen-Layout, 43 × 89 mm, automatisch gedreht) oder als ZPL (1:1-Konvertierung bei 203 dpi, Pdf2ZplConverter, contain).
Absenderliste mit Standard-Absender; Produktwahl (Standardbrief … Großbrief, mit/ohne Einschreiben).
Saldo- und Produktkatalog-Prüfung (/status).
REST-Kauf (POST /api/integrations/dhl/buy) mit voucherId, shopOrderId und neuem Saldo.
DHL-only Print Views: Auftrags-ID → Datenquellen-Lookup → Kauf → Druck an Weblink, CLI-Agent oder Watch-Ordner.
Transaktionslog mit PDF-Reprint, ZPL-Download und erneutem Senden.

Voraussetzungen

Punkt	Detail
DHL Developer Portal	`client_id` und `client_secret` der REST-Anwendung.
Portokasse	Benutzername (E-Mail) und Passwort (max. 22 Zeichen).
Einmalige Freigabe	REST-Anwendung in der Portokasse unter Meine Daten → Geschäftsanwendungen freigeben; sonst antwortet die API mit `401 genericUserAuthenticationError`.
Guthaben	Jede Marke belastet die Portokasse zum aktuellen PPL-Preis.

Einrichtung

/platform/integrations → DHL Internetmarke → Konfigurieren: Client-ID, Client-Secret, Portokasse-Benutzer und -Passwort.
Mindestens einen Absender anlegen (Name/Firma, Straße + Nr., PLZ, Ort); einen als Standard markieren (sonst wird der erste genutzt).
Produkt wählen (Standard 1002 „Standardbrief + Einschreiben Einwurf“).
Speichern, dann Prüfen: Saldo, Version und Produktkatalog werden angezeigt.

Client-Secret und Passwort werden nie an den Browser zurückgegeben; beim Bearbeiten leer lassen, um die gespeicherten Werte zu behalten.

Produkte und Preise

Produkt	Preis
Standardbrief	0,95 €
Kompaktbrief	1,10 €
Großbrief	1,80 €
Maxibrief	2,90 €
Standardbrief + Einschreiben Einwurf (Produkt 1002, Standard)	3,30 €
Standardbrief + Einschreiben	3,60 €
Kompaktbrief + Einschreiben Einwurf	3,45 €
Großbrief + Einschreiben Einwurf	4,15 €

Preise folgen der aktuellen DHL-PPL; die API prüft den Preis vor dem Checkout gegen den Katalog. Das gewählte Produkt gilt für API und DHL-only Print Views. Seitenformat 296 (43 × 89 mm ohne Rand), Voucher-Layout AddressZone.

REST-API (Konto)

Route	Funktion
GET\|PUT\|DELETE /api/integrations/{plugin}/config	Plugin-Konfiguration lesen / schreiben / entfernen.
GET /api/integrations/dhl/status	`walletBalanceCents`, `productId`, Produktkatalog.
POST /api/integrations/dhl/product	Produkt setzen.
POST /api/integrations/dhl/buy	Kauf; Body siehe unten.

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, sonst Standard-Absender
  "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"
}

Das ZPL an jeden Zebra senden: zplcloud send, Weblink-Drucker oder Plattform. shopOrderId und voucherId dienen als Belegreferenz.

DHL-only Print Views

View-Art dhlOnly im Print-Views-Editor: kein Design, die Marke ist das Label. URL https://print.zplcloud.com/d/dhl/{slug} (/pv/{id} leitet weiter). Zugriff, Mobile-Layout und PWA wie bei allen Views.

Editor-Felder: Schalter dhlOnly; dhlFieldMap mit orderIdColumn (Standard orderId), optional label/placeholder, map.receiverName|receiverStreet|receiverPostalCode|receiverCity (Spalten kombinierbar: vorname+nachname); datasourceId (Datenhub); printerId / allowedPrinters.

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

Datenquellen-Beispiel (SQL Server über den CLI-Agenten; der Connection-String bleibt auf dem Agent-Host, die Abfrage läuft mit Pushdown und Parametern):

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

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

Ablauf auf der Seite: ID eingeben → POST /d/dhl/{slug}/dhl/lookup füllt die gemappten Empfängerfelder → Absender und Drucker wählen → POST /d/dhl/{slug}/dhl/print: Kauf über die User-Integration, PDF → ZPL (203 dpi), Versand an den Drucker (Weblink, CLI-Agent oder Watch-Ordner). „✓ Briefmarke gekauft & gesendet“ erscheint erst, wenn der Drucker die Daten angenommen hat; ein fehlgeschlagener Versand wird als Fehler gemeldet. Fehlende Daten → 400; Demo-Konten dürfen nicht drucken.

Transaktionslog

Tabelle plugintransactions protokolliert jeden Kauf: Quelle (user / apikey mit Beschreibung / printview-Slug), E-Mail + Company-Snapshot, Status ok/error, Produkt, Kosten, voucherId, shopOrderId, Saldo danach, vollständige Empfängeradresse, DHL-Response-JSON, PDF-Blob, optional ZPL.

UI: /platform/integrations/dhl/logs (Integrations → DHL → Logs): Grid mit Filterzeile, XLSX-Export, Summen heute / Monat / gesamt; Zeilenaktionen PDF (Reprint), ZPL, Send ZPL (Weblink, Agent oder Watch-Ordner).
Sichtbarkeit: eigene Transaktionen; Firmen-Transaktionen für Company-Admins; Supervisor alles.
Endpunkte: GET/POST /api/integrations/dhl/logs*.

Public API (api.zplcloud.com, API-Key)

Route	Funktion
POST /v1/integrations/dhl/stamp	Kauf (gleicher Body wie `/buy`); Antwort enthält `voucherId`.
GET /v1/integrations/dhl/stamps	Eigene Transaktionen inkl. Voucher-IDs.
GET /v1/integrations/dhl/status	Saldo und Produktkatalog.

Sicherheit

Client-Secret und Portokasse-Passwort werden nur serverseitig gespeichert und nie zurückgegeben.
Preisprüfung gegen den aktuellen PPL-Katalog vor dem Checkout.
Datenquellen-Zugangsdaten bleiben im eigenen LAN; nur Ergebniszeilen erreichen die Plattform.
Unvollständige Empfänger- oder Lookup-Daten → 400; Demo-Konten dürfen nicht drucken.