Franqueamento DHL Internetmarke: o selo como etiqueta ZPL

Um selo é só mais uma etiqueta

Lojas, bancadas de reparo e equipes logísticas enviam cartas individuais todos os dias: um manual com uma fatura, um formulário de devolução, uma carta registrada. O último passo físico é o franqueamento - o que geralmente significa uma máquina de franquear, uma gaveta de selos pré-impressos, ou uma caminhada até a máquina.

A integração INTERNETMARKE compra o selo real, legalmente franqueado, através das suas próprias credenciais de desenvolvedor DHL contra a sua própria Portokasse, e o devolve em dois formatos:

• PDF - o documento oficial do selo, 43 × 89 mm, rotação automática.
• ZPL - o mesmo selo rasterizado a 203 dpi (711 × 344 px), pronto para uma Zebra.

O zplCloud não revende franqueamento. Cada compra debita sua Portokasse ao preço PPL vigente; sem margem, sem arredondamento e sem estoque pré-comprado.

Configuração única

Integrações → DHL Internetmarke:

1. Credenciais - chave de API e segredo do portal de desenvolvedores DHL, além do seu login Portokasse (e-mail e senha, máx. 22 caracteres). O aplicativo REST deve ser aprovado uma vez no frontend da Portokasse em Meus dados → Aplicativos comerciais. Pule isso e toda chamada retorna 401 genericUserAuthenticationError - as credenciais estão corretas, o app simplesmente não está habilitado.

2. Remetentes - um ou mais endereços de remetente; marque um como padrão.

3. Produto - o produto de carta a comprar.

Verificar valida as credenciais e mostra o saldo atual da Portokasse. O segredo da API e a senha da Portokasse são armazenados no servidor e nunca são enviados de volta ao navegador.

Duas APIs, e qual você quer

Há dois pontos de entrada. Eles fazem a mesma coisa, mas autenticam de forma diferente, e confundi-los é o erro de integração mais comum:

Comprar um selo (API pública):

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 é opcional - o remetente padrão é usado se você o omitir. A resposta traz o ZPL, a geometria, os identificadores DHL para seus registros e o novo 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" retorna o PDF original do selo como base64.

Antes de comprar, verifique o que pode comprar:

GET /v1/integrations/dhl/status    # saldo + catálogo de produtos
GET /v1/integrations/dhl/stamps    # suas transações com os IDs de voucher

Leia status antes de um lote. Uma compra contra uma Portokasse vazia falha na DHL, e é a tentativa falha que você encontrará no log depois.

Print Views: sem cliente de API na bancada de embalagem

Para um balcão de expedição você não quer uma integração em cada mesa. Uma Print View DHL não precisa de nenhum design de etiqueta - o selo é a etiqueta. Ela tem sua própria URL:

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

Mobile-first, instalável como PWA, com campo de busca, menu suspenso de remetente, formulário de destinatário e seleção de impressora.

Conectando o banco de pedidos

Execute o agente CLI em uma máquina da sua rede. A string de conexão SQL Server fica lá:

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

Crie a fonte de dados (Fontes de dados, tipo SQL Server, servidor ORDERS) com uma consulta base:

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

Depois mapeie as colunas no editor de Print View sob DHL: a coluna de ID do pedido (padrão orderId) é contra a qual o valor digitado é comparado, e os campos do destinatário recebem nome, rua, CEP e cidade. O nome pode combinar colunas: vorname+nachname.

O que o operador faz

Digite 10042 → Buscar → o agente executa a consulta e os campos do destinatário se preenchem → escolha remetente e impressora → Comprar e imprimir:

1. o selo é comprado através da sua Portokasse,

2. o PDF é convertido para ZPL a 203 dpi,

3. o ZPL vai para a impressora selecionada (Weblink ou uma impressora proxy CLI).

A mensagem de sucesso aparece somente depois que a impressora aceitou o trabalho. Se a impressora estiver inacessível, a operação é relatada como erro em vez de ter sucesso silencioso - você já pagou por esse selo, então precisa saber se ele saiu.