Affranchissement DHL Internetmarke : le timbre comme étiquette ZPL

Un timbre n'est qu'une autre étiquette

Les boutiques, les ateliers de réparation et les équipes logistiques envoient des lettres individuelles chaque jour : un manuel avec une facture, un bordereau de retour, une lettre recommandée. La dernière étape physique est l'affranchissement - ce qui signifie généralement une machine à affranchir, un tiroir de timbres pré-imprimés, ou une marche jusqu'à la machine.

L'intégration INTERNETMARKE achète le vrai timbre, légalement affranchi, via vos propres identifiants de développeur DHL contre votre propre Portokasse, et le restitue en deux formats :

• PDF - le document officiel du timbre, 43 × 89 mm, rotation automatique.
• ZPL - le même timbre pixellisé en 203 dpi (711 × 344 px), prêt pour une Zebra.

zplCloud ne revend pas d'affranchissement. Chaque achat débite votre Portokasse au prix PPL en vigueur ; pas de marge, pas d'arrondi, pas de stock pré-acheté.

Configuration unique

Intégrations → DHL Internetmarke :

1. Identifiants - clé API et secret du portail développeur DHL, plus votre accès Portokasse (e-mail et mot de passe, max. 22 caractères). L'application REST doit être approuvée une fois dans l'interface Portokasse sous Mes données → Applications métier. Si vous sautez cette étape, chaque appel renvoie 401 genericUserAuthenticationError - les identifiants sont corrects, l'application n'est simplement pas activée.

2. Expéditeurs - une ou plusieurs adresses d'expéditeur ; marquez-en une par défaut.

3. Produit - le produit de lettre à acheter.

Vérifier valide les identifiants et affiche le solde actuel de la Portokasse. Le secret API et le mot de passe Portokasse sont stockés côté serveur et ne sont jamais renvoyés au navigateur.

Deux API, et laquelle choisir

Il y a deux points d'entrée. Ils font la même chose mais s'authentifient différemment, et les confondre est l'erreur d'intégration la plus courante :

Acheter un timbre (API publique) :

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 est facultatif - l'expéditeur par défaut est utilisé si vous l'omettez. La réponse contient le ZPL, la géométrie, les identifiants DHL pour vos archives et le nouveau solde :

{
  "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" renvoie le PDF original du timbre en base64.

Avant d'acheter, vérifiez ce que vous pouvez acheter :

GET /v1/integrations/dhl/status    # solde + catalogue produits
GET /v1/integrations/dhl/stamps    # vos transactions avec les ID de justificatifs

Lisez status avant un lot. Un achat contre une Portokasse vide échoue chez DHL, et c'est la tentative échouée que vous trouverez dans le journal ensuite.

Print Views : pas de client API sur la table d'emballage

Pour un guichet d'expédition, vous ne voulez pas d'intégration sur chaque bureau. Une Print View DHL n'a besoin d'aucun design d'étiquette - le timbre est l'étiquette. Elle a sa propre URL :

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

Mobile-first, installable en PWA, avec un champ de recherche, une liste d'expéditeurs, un formulaire de destinataire et une sélection d'imprimante.

Brancher la base de données de commandes

Exécutez l'agent CLI sur une machine de votre réseau. La chaîne de connexion SQL Server reste là :

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

Créez la source de données (Sources de données, type SQL Server, serveur ORDERS) avec une requête de base :

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

Puis mappez les colonnes dans l'éditeur de Print View sous DHL : la colonne d'ID de commande (par défaut orderId) est celle contre laquelle la valeur saisie est comparée, et les champs du destinataire prennent nom, rue, CP et ville. Le nom peut combiner des colonnes : vorname+nachname.

Ce que fait l'opérateur

Saisissez 10042 → Rechercher → l'agent exécute la requête et les champs du destinataire se remplissent → choisissez l'expéditeur et l'imprimante → Acheter et imprimer :

1. le timbre est acheté via votre Portokasse,

2. le PDF est converti en ZPL à 203 dpi,

3. le ZPL va à l'imprimante sélectionnée (Weblink ou une imprimante proxy CLI).

Le message de succès n'apparaît qu'après que l'imprimante a accepté le travail. Si l'imprimante est injoignable, l'opération est signalée comme une erreur plutôt que de réussir en silence - vous avez déjà payé ce timbre, vous devez donc savoir s'il est sorti.