zplCloud Blog

Deutsche Post INTERNETMARKE als ZPL: echtes Porto per API kaufen und auf dem Zebra drucken

Deine DHL-Zugangsdaten, deine Portokasse, dein Drucker. Empfänger per POST hinein, 203-dpi-Marke als ZPL oder PDF zurück.

September 14, 2026 4 Min. Lesezeit zplCloud Team

Eine Briefmarke ist auch nur ein Etikett

Shops, Reparaturannahmen und Logistikteams verschicken täglich Einzelbriefe: eine Anleitung mit Rechnung, ein Retourenschein, ein Einschreiben. Der letzte physische Schritt ist das Porto - und das heißt üblicherweise Frankiermaschine, eine Schublade voll vorgedruckter Marken oder der Weg zum Automaten.

Die INTERNETMARKE-Integration kauft die echte, rechtsgültig frankierte Marke über deine eigenen DHL-Entwickler-Zugangsdaten gegen deine eigene Portokasse und gibt sie in zwei Formaten zurück:

PDF - das offizielle Markendokument, 43 × 89 mm, automatisch gedreht.
ZPL - dieselbe Marke, mit 203 dpi gerastert (711 × 344 px), fertig für den Zebra.

zplCloud handelt nicht mit Porto. Jeder Kauf belastet deine Portokasse zum aktuellen PPL-Preis; kein Aufschlag, keine Rundung, kein vorgekaufter Bestand.

Einmalige Einrichtung

Integrations → DHL Internetmarke:

1. Zugangsdaten - API-Key und Secret aus dem DHL-Entwicklerportal, dazu dein Portokasse-Login (E-Mail und Passwort, max. 22 Zeichen). Die REST-Anwendung muss einmal im Portokasse-Frontend unter Meine Daten → Geschäftsanwendungen freigegeben werden. Ohne diesen Schritt antwortet jeder Aufruf mit 401 genericUserAuthenticationError - die Zugangsdaten stimmen, nur die Anwendung ist nicht freigeschaltet.

2. Absender - eine oder mehrere Absenderadressen, eine davon als Standard markieren.

3. Produkt - das Briefprodukt, das gekauft werden soll.

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

Check prüft die Zugangsdaten und zeigt den aktuellen Portokasse-Saldo. API-Secret und Portokasse-Passwort liegen serverseitig und werden nie an den Browser zurückgegeben.

Zwei APIs - und welche du brauchst

Es gibt zwei Einstiegspunkte. Sie tun dasselbe, authentifizieren aber unterschiedlich; sie zu verwechseln ist der häufigste Integrationsfehler:

	Session-API	Öffentliche API
Pfad	`/api/integrations/dhl/…`	`/v1/integrations/dhl/…`
Auth	angemeldete Session (same-origin)	API-Key
Wofür	Plattform-UI, Same-Origin-Aufrufe	eigenes Backend, Skripte, ERP

Marke kaufen (öffentliche API):

curl -X POST https://api.zplcloud.com/v1/integrations/dhl/stamp \
  -H "X-Api-Key: sk_zplcloud_…" -H "Content-Type: application/json" \
  -d '{
        "format": "zpl",
        "receiver": { "name": "Max Mustermann",
                      "addressLine1": "Musterstrasse 12b",
                      "postalCode": "12345", "city": "Musterstadt",
                      "country": "DEU" }
      }'

senderId ist optional - ohne Angabe wird der Standardabsender genommen. Die Antwort enthält das ZPL, die Geometrie, die DHL-Kennungen für deine Ablage und den neuen Saldo:

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

format: "pdf" liefert stattdessen das Original-PDF als Base64.

Vor dem Kauf prüfen, was kaufbar ist:

GET /v1/integrations/dhl/status    # Saldo + Produktkatalog
GET /v1/integrations/dhl/stamps    # eigene Transaktionen inkl. Voucher-IDs

Lies status vor einem Stapel. Ein Kauf gegen eine leere Portokasse scheitert bei DHL - und der gescheiterte Versuch ist das, was du danach im Log findest.

Print Views: kein API-Client am Packtisch

Für einen Versandtresen willst du keine Integration auf jedem Rechner. Eine DHL-Print-View braucht gar kein Label-Design - die Marke ist das Etikett. Sie bekommt eine eigene URL:

https://print.zplcloud.com/d/dhl/{slug}

Mobile-first, als PWA installierbar, mit Suchfeld, Absender-Auswahl, Empfängerformular und Druckerauswahl.

Auftragsdatenbank anbinden

Den CLI-Agent auf einer Maschine im Netz starten. Der SQL-Server-Connection-String bleibt dort:

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

Datenquelle anlegen (Datenquellen, Typ SQL Server, Server ORDERS) mit einer Basis-Query:

SELECT orderId, nachname, vorname, strasse, plz, ort
FROM auftraege
WHERE orderId LIKE @p0

Danach im Print-View-Editor unter DHL die Spalten zuordnen: Die Order-ID-Spalte (Default orderId) ist das, wogegen der eingetippte Wert gematcht wird, die Empfängerfelder nehmen Name, Straße, PLZ und Ort. Der Name darf Spalten kombinieren: vorname+nachname.

Was die Bedienung macht

10042 eintippen → Lookup → der Agent führt die Query aus, die Empfängerfelder füllen sich → Absender und Drucker wählen → Kaufen & drucken:

1. Die Marke wird über deine Portokasse gekauft,

2. das PDF wird mit 203 dpi nach ZPL konvertiert,

3. das ZPL geht an den gewählten Drucker (Weblink oder CLI-Proxy-Drucker).

Die Erfolgsmeldung erscheint erst, wenn der Drucker den Job angenommen hat. Ist der Drucker nicht erreichbar, wird das als Fehler gemeldet statt still als Erfolg - du hast diese Marke bereits bezahlt, also musst du wissen, ob sie herausgekommen ist.

Unter der Haube

Ein host-agnostisches .NET-10-Plugin (com.zplcloud.plugin.dhl) spricht mit der offiziellen API unter api-eu.dhl.com/post/de/shipping/im/v1: OAuth2 mit Client Credentials plus Portokasse-Login, Token 24 h gültig und serverseitig 12 h gecacht, dann Warenkorb → Checkout mit Produkt, Preis und Adressen → PDF-Download, inklusive der 90°-Drehung, die die Marke auf dem Bildschirm und auf dem Etikett lesbar macht.

Das Transaktionslog

Jeder Kauf wird protokolliert - egal ob aus der Session-API, mit einem öffentlichen API-Key oder aus einer Print View. Unter Integrations → DHL → Logs (/platform/integrations/dhl/logs):

wer den Kauf ausgelöst hat - Konto, API-Key (mit Beschreibung) oder Print-View-Slug - und welcher Absender verwendet wurde
Produkt, Kosten, voucherId, shopOrderId und der Saldo danach
die vollständige Empfängeradresse und der Zeitpunkt; Fehler in Rot
Aktionen: PDF laden, ZPL laden oder das ZPL erneut an einen Drucker senden

Firmen-Admins sehen die ganze Firma, alle anderen ihre eigenen Vorgänge. Filterbar, mit XLSX-Export. Dieselben Daten gibt es programmatisch unter GET /v1/integrations/dhl/stamps.

Ein Nachdruck aus dem Log kauft keine zweite Marke - er schickt den bereits bezahlten Voucher erneut. Genau das will man bei einem Papierstau; ein zweiter Kauf würde weitere 0,95 € kosten und zwei gültige Voucher in Umlauf bringen.

Loslegen

1. DHL-Entwickler-Key/-Secret und Portokasse-Konto besorgen, die Anwendung einmal freigeben.

2. Integration konfigurieren, Absender anlegen, Produkt wählen, Check drücken.

3. Eine Marke mit format: "zpl" kaufen - oder eine DHL-Print-View bauen und die Auftragsdatenbank über den CLI-Agent anbinden.