Franqueo DHL Internetmarke: el sello como etiqueta ZPL

Un sello es solo otra etiqueta

Las tiendas, los servicios técnicos y los equipos de logística envían cartas individuales cada día: un manual con una factura, un formulario de devolución, una carta certificada. El último paso físico es el franqueo, que normalmente significa una máquina franqueadora, un cajón de sellos preimpresos o un paseo hasta la máquina.

La integración INTERNETMARKE compra el sello real, legalmente franqueado, a través de tus propias credenciales de desarrollador de DHL contra tu propia Portokasse, y lo entrega en dos formatos:

• PDF - el documento oficial del sello, 43 × 89 mm, con rotación automática.
• ZPL - el mismo sello rasterizado a 203 dpi (711 × 344 px), listo para una Zebra.

zplCloud no revende franqueo. Cada compra se carga en tu Portokasse al precio PPL vigente; sin recargos, sin redondeos y sin existencias compradas por adelantado.

Configuración única

Integraciones → DHL Internetmarke:

1. Credenciales - clave API y secreto del Portal de desarrolladores de DHL, además del acceso a tu Portokasse (correo electrónico y contraseña, máx. 22 caracteres). La aplicación REST debe aprobarse una vez en el frontend de Portokasse en Mis datos → Aplicaciones comerciales. Si te lo saltas, cada llamada devuelve 401 genericUserAuthenticationError: las credenciales son correctas, la aplicación simplemente no está habilitada.

2. Remitentes - una o más direcciones de remitente; marca una como predeterminada.

3. Producto - el producto de carta a comprar.

Comprobar valida las credenciales y muestra el saldo actual de Portokasse. El secreto de la API y la contraseña de Portokasse se almacenan en el servidor y nunca se envían de vuelta al navegador.

Dos API, y cuál quieres

Hay dos puntos de entrada. Hacen lo mismo pero autentican de forma distinta, y confundirlos es el error de integración más común:

Comprar un sello (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 es opcional: se usa el remitente predeterminado cuando lo omites. La respuesta incluye el ZPL, la geometría, los identificadores de DHL para tus registros y el nuevo 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" devuelve el PDF original del sello como base64.

Antes de comprar, comprueba qué puedes comprar:

GET /v1/integrations/dhl/status    # saldo + catálogo de productos
GET /v1/integrations/dhl/stamps    # tus transacciones, incluidos los ID de los comprobantes

Lee status antes de un lote. Una compra contra una Portokasse vacía falla en DHL, y el intento fallido es lo que encontrarás en el registro después.

Print Views: sin cliente API en la mesa de empaquetado

Para un mostrador de envíos no quieres una integración en cada escritorio. Una Print View de DHL no necesita ningún diseño de etiqueta: el sello es la etiqueta. Tiene su propia URL:

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

Mobile-first, instalable como PWA, con un campo de búsqueda, menú desplegable de remitente, formulario de destinatario y selección de impresora.

Conectando la base de datos de pedidos

Ejecuta el agente CLI en una máquina de tu red. La cadena de conexión de SQL Server se queda allí:

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

Crea la fuente de datos (Fuentes de datos, tipo SQL Server, servidor ORDERS) con una consulta base:

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

Luego asigna las columnas en el editor de Print View en DHL: la columna de ID de pedido (por defecto orderId) es contra la que se compara el valor tecleado, y los campos de destinatario toman nombre, calle, CP y ciudad. El nombre puede combinar columnas: vorname+nachname.

Lo que hace el operador

Teclea 10042 → Buscar → el agente ejecuta la consulta y los campos del destinatario se rellenan → elige remitente e impresora → Comprar e imprimir:

1. el sello se compra a través de tu Portokasse,

2. el PDF se convierte a ZPL a 203 dpi,

3. el ZPL va a la impresora seleccionada (Weblink o una impresora proxy de la CLI).

El mensaje de éxito aparece solo después de que la impresora haya aceptado el trabajo. Si la impresora no está accesible, la operación se informa como un error en lugar de tener éxito silenciosamente: ya has pagado por ese sello, así que necesitas saber si ha salido.