DHL Internetmarke 邮资：邮票即 ZPL 标签

邮票不过是一枚标签

商店、维修台和物流团队每天都要寄出单封信件：一份带发票的手册、一张退货单、一封挂号信。最后一个物理步骤是邮资——通常意味着一台邮资机、一抽屉预印邮票，或者走到机器前。

INTERNETMARKE 集成通过你自己的 DHL 开发者凭证、对你自己 Portokasse（邮资账户）扣款购买真实、合法邮资的邮票，并以两种格式返回：

• PDF - 官方邮票文档，43 × 89 mm，自动旋转。
• ZPL - 同一邮票按 203 dpi 栅格化（711 × 344 px），可直接用于 Zebra。

zplCloud 不转售邮资。每次购买按当前 PPL 价格从你的 Portokasse 扣款；没有加价、没有四舍五入、没有预购库存。

一次性设置

集成 → DHL Internetmarke：

1. 凭证 - DHL 开发者门户 API 密钥和密钥，加上你的 Portokasse 登录（电子邮件和密码，最多 22 个字符）。REST 应用必须在 Portokasse 前端的我的数据 → 商业应用下批准一次。跳过这一步，每次调用都会返回 401 genericUserAuthenticationError——凭证没问题，只是应用没有启用。

2. 发件人 - 一个或多个发件人地址；将其中一个标记为默认。

3. 产品 - 要购买的信件产品。

检查验证凭证并显示当前 Portokasse 余额。API 密钥和 Portokasse 密码存储在服务器端，绝不回传给浏览器。

两个 API，选哪个

有两个入口点。它们做同样的事，但认证方式不同，混淆它们是集成中最常见的错误：

购买邮票（公共 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    # 余额 + 产品目录
GET /v1/integrations/dhl/stamps    # 你的交易记录，含 voucher ID

在批次前读取 status。对空 Portokasse 的购买会在 DHL 端失败，之后你在日志里看到的正是这次失败的尝试。

Print Views：打包台上无需 API 客户端

对于发货柜台，你不希望每张桌子上都装一个集成。DHL Print View 完全不需要设计标签——邮票就是标签。它有自己独立的 URL：

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

移动优先、可作为 PWA 安装，带查找字段、发件人下拉框、收件人表单和打印机选择。

接入订单数据库

在网络中的一台机器上运行 CLI agent。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 → 查找 → agent 执行查询，收件人字段自动填充 → 选择发件人和打印机 → 购买并打印：

1. 邮票通过你的 Portokasse 购买，

2. PDF 按 203 dpi 转换为 ZPL，

3. ZPL 发送到所选打印机（Weblink 或 CLI 代理打印机）。

成功消息只在打印机接受作业后出现。如果打印机不可达，操作会被报告为错误，而不是静默成功——你已经为那枚邮票付了钱，所以你需要知道它是否打印出来。