Deutsche Post の INTERNETMARKE を ZPL で: 本物の郵便料金を API から購入し、Zebra で印刷する

切手もひとつのラベルです

ショップ、修理受付、物流チームは、毎日のように単発の郵便物を送ります。請求書を同梱したマニュアル、返品伝票、書留郵便などです。最後の物理的な工程が郵便料金であり、通常は料金計器、印刷済み切手を入れた引き出し、あるいは券売機まで歩くことを意味します。

INTERNETMARKE 連携は、お客様自身の DHL デベロッパー認証情報と、お客様自身の Portokasse を使って、正規に料金が支払われた本物の切手を購入し、2 つの形式で返します。

• PDF - 公式の切手ドキュメント、43 × 89 mm、自動回転付き。
• ZPL - 同じ切手を 203 dpi (711 × 344 px) でラスタライズしたもの。Zebra ですぐに印刷できます。

zplCloud は郵便料金を再販しません。購入のたびに、その時点の PPL 価格でお客様の Portokasse から引き落とされます。上乗せも、端数処理も、事前の買い置きもありません。

一度だけのセットアップ

Integrations → DHL Internetmarke:

1. 認証情報 - DHL デベロッパーポータルの API キーとシークレット、および Portokasse のログイン情報 (メールアドレスとパスワード、最大 22 文字)。REST アプリケーションは、Portokasse のフロントエンドの My data → Business applications で一度承認しておく必要があります。これを省くと、すべての呼び出しが 401 genericUserAuthenticationError を返します。認証情報に問題はなく、アプリが有効になっていないだけです。

2. 差出人 - 1 つ以上の差出人住所を登録し、1 つを既定に設定します。

3. 商品 - 購入する手紙商品。

商品	価格
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 は認証情報を検証し、現在の Portokasse の残高を表示します。API シークレットと Portokasse のパスワードはサーバー側に保存され、ブラウザーに送り返されることはありません。

2 つの API と、選ぶべきもの

エントリーポイントは 2 つあります。処理内容は同じですが認証方式が異なり、この 2 つの取り違えは最もよくある連携ミスです。

	Session API	Public API
パス	/api/integrations/dhl/…	/v1/integrations/dhl/…
認証	ログイン済みセッション (同一オリジン)	API キー
用途	プラットフォームの UI、同一オリジンの呼び出し	自社のバックエンド、スクリプト、ERP

切手を購入する (Public 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 は省略できます。省略した場合は既定の差出人が使われます。レスポンスには ZPL、寸法、記録用の DHL 識別子、そして新しい残高が含まれます。

{
  "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" を指定すると、代わりに元の切手 PDF が base64 で返ります。

購入する前に、何を購入できるかを確認します。

GET /v1/integrations/dhl/status    # balance + product catalog
GET /v1/integrations/dhl/stamps    # your transactions incl. voucher IDs

バッチ処理の前には status を読んでください。Portokasse が空の状態で購入すると DHL 側で失敗し、後からログに残るのは、その失敗した試行です。

Print View: 梱包台に API クライアントは不要です

出荷カウンターでは、机ごとに連携を組み込みたくはありません。DHL Print View はラベルデザインをまったく必要としません。切手そのものがラベルだからです。専用の URL を持ちます。

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

モバイルファーストで、PWA としてインストールでき、検索フィールド、差出人のドロップダウン、宛先フォーム、プリンター選択を備えています。

受注データベースをつなぐ

ネットワーク内のマシンで CLI エージェントを実行します。SQL Server の接続文字列はその中にとどまります。

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

ベースクエリを指定して、データソース でデータソース (種類は SQL Server、サーバーは ORDERS) を作成します。

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

続いて、Print View エディターの DHL で列をマッピングします。注文 ID の列 (既定は orderId) が入力値との照合先になり、宛先フィールド には氏名、番地、郵便番号、市区町村を割り当てます。氏名は複数の列を組み合わせられます: vorname+nachname。

担当者の操作

10042 と入力 → Lookup → エージェントがクエリを実行して宛先フィールドが埋まる → 差出人とプリンターを選ぶ → Buy & print:

1. お客様の Portokasse を通じて切手が購入され、

2. PDF が 203 dpi で ZPL に変換され、

3. その ZPL が選択したプリンター (Weblink または CLI プロキシのプリンター) に送られます。

成功メッセージは、プリンターがジョブを受け付けた後にのみ 表示されます。プリンターに到達できない場合、その操作は黙って成功扱いにはならず、エラーとして報告されます。切手の代金はすでに支払われているため、実際に出力されたかどうかを知る必要があるからです。

内部の仕組み

ホストに依存しない .NET 10 のプラグイン (com.zplcloud.plugin.dhl) が、公式 API の api-eu.dhl.com/post/de/shipping/im/v1 と通信します。クライアントクレデンシャルによる OAuth2 に Portokasse のログインを組み合わせ、トークンの有効期間は 24 h、サーバー側で 12 h キャッシュされます。その後、ショッピングカート → 商品、価格、住所を指定したチェックアウト → PDF のダウンロードと進み、画面上でもラベル上でも切手が読める向きになるよう 90° の回転も行います。

取引ログ

購入はすべて記録されます。セッション API、公開 API キー、Print View のいずれから行われた場合も同じです。Integrations → DHL → Logs (/platform/integrations/dhl/logs) で確認できます。

• 誰が要求したか、つまりアカウント、API キー (説明付き)、または Print View のスラッグ、そしてどの差出人が使われたか
• 商品、費用、voucherId、shopOrderId、および購入後の残高
• 宛先住所の全体とタイムスタンプ。失敗は赤で表示されます
• 操作: PDF のダウンロード、ZPL のダウンロード、または ZPL の再送信 (プリンターへ)

会社の管理者は会社全体を、それ以外のユーザーは自分の分を参照できます。絞り込みが可能で、XLSX 形式でエクスポートできます。同じデータは GET /v1/integrations/dhl/stamps からプログラムでも取得できます。

ログからの再印刷では、2 枚目の切手を購入 しません。すでに支払い済みのバウチャーを再送するだけです。ラベルが詰まったときには、これが正しい対応です。もう一度購入すると € 0.95 が余分にかかり、有効なバウチャーが 2 枚出回ってしまいます。

はじめかた

1. DHL のデベロッパーキーとシークレット、および Portokasse のアカウントを用意し、アプリケーションを一度承認します。

2. 連携を設定し、差出人を追加し、商品を選び、Check を押します。

3. format: "zpl" で切手を 1 枚購入します。あるいは DHL Print View を作成し、CLI エージェント経由で受注データベースに接続します。

関連

• zplcloud CLI - エージェント、SQL データソース、サービスのインストール
• クラウド連携 / 接続
• 料金