Affrancatura DHL Internetmarke: il francobollo come etichetta ZPL

Un francobollo è solo un'altra etichetta

Negozi, banchi di riparazione e team logistici spediscono lettere singole ogni giorno: un manuale con una fattura, un modulo di reso, una raccomandata. L'ultimo passo fisico è l'affrancatura - che di solito significa una macchina affrancatrice, un cassetto di francobolli pre-stampati, o una passeggiata fino alla macchina.

L'integrazione INTERNETMARKE acquista il vero francobollo, legalmente affrancato, tramite le tue credenziali sviluppatore DHL contro la tua Portokasse, e lo restituisce in due formati:

• PDF - il documento ufficiale del francobollo, 43 × 89 mm, rotazione automatica.
• ZPL - lo stesso francobollo rasterizzato a 203 dpi (711 × 344 px), pronto per una Zebra.

zplCloud non rivende affrancature. Ogni acquisto addebita la tua Portokasse al prezzo PPL corrente; nessun ricarico, nessun arrotondamento, nessuno stock pre-acquistato.

Configurazione una tantum

Integrazioni → DHL Internetmarke:

1. Credenziali - chiave API e segreto del portale sviluppatori DHL, più il tuo accesso Portokasse (email e password, max 22 caratteri). L'applicazione REST deve essere approvata una volta nel frontend Portokasse sotto I miei dati → Applicazioni aziendali. Se salti questo passaggio, ogni chiamata restituisce 401 genericUserAuthenticationError - le credenziali sono corrette, l'app semplicemente non è abilitata.

2. Mittenti - uno o più indirizzi mittente; segna uno come predefinito.

3. Prodotto - il prodotto di lettera da acquistare.

Verifica valida le credenziali e mostra il saldo corrente della Portokasse. Il segreto API e la password Portokasse sono memorizzati lato server e non vengono mai rispediti al browser.

Due API, e quale vuoi

Ci sono due punti di ingresso. Fanno la stessa cosa ma si autenticano diversamente, e confonderli è l'errore di integrazione più comune:

Compra un francobollo (API pubblica):

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 è opzionale - se lo ometti viene usato il mittente predefinito. La risposta contiene lo ZPL, la geometria, gli identificativi DHL per i tuoi archivi e il nuovo 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" restituisce il PDF originale del francobollo in base64.

Prima di comprare, verifica cosa puoi comprare:

GET /v1/integrations/dhl/status    # saldo + catalogo prodotti
GET /v1/integrations/dhl/stamps    # le tue transazioni con gli ID dei voucher

Leggi status prima di un batch. Un acquisto contro una Portokasse vuota fallisce da DHL, ed è il tentativo fallito quello che troverai nel log dopo.

Print Views: nessun client API sul banco di imballaggio

Per un banco di spedizioni non vuoi un'integrazione su ogni scrivania. Una Print View DHL non ha bisogno di alcun design di etichetta - il francobollo è l'etichetta. Ha la sua URL:

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

Mobile-first, installabile come PWA, con campo di ricerca, menu a tendina mittente, modulo destinatario e selezione stampante.

Collegare il database degli ordini

Esegui l'agente CLI su una macchina nella tua rete. La stringa di connessione SQL Server resta lì:

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

Crea la sorgente dati (Origini dati, tipo SQL Server, server ORDERS) con una query di base:

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

Poi mappa le colonne nell'editor Print View sotto DHL: la colonna ID ordine (default orderId) è quella contro cui viene confrontato il valore digitato, e i campi destinatario prendono nome, via, CAP e città. Il nome può combinare colonne: vorname+nachname.

Cosa fa l'operatore

Digita 10042 → Cerca → l'agente esegue la query e i campi del destinatario si riempiono → scegli mittente e stampante → Compra e stampa:

1. il francobollo viene acquistato tramite la tua Portokasse,

2. il PDF viene convertito in ZPL a 203 dpi,

3. lo ZPL va alla stampante selezionata (Weblink o una stampante proxy CLI).

Il messaggio di successo appare solo dopo che la stampante ha accettato il lavoro. Se la stampante non è raggiungibile, l'operazione viene segnalata come errore invece di riuscire in silenzio - hai già pagato quel francobollo, quindi devi sapere se è uscito.