Comment imprimer des étiquettes depuis une API de service web : un guide pas à pas pour développeurs

Votre application sait déjà ce que l’étiquette doit afficher — le numéro de commande, l’UGS, la valeur du code-barres, le bordereau de colisage. La partie pénible n’a jamais été les données. C’est la sortie : les pilotes, les langages d’imprimante, les spouleurs, et cette imprimante d’entrepôt qui s’obstine à rendre votre police deux points trop grande.

Ce guide pas à pas contourne entièrement cette pile. Vous allez apprendre à imprimer des étiquettes depuis une API de service web : enregistrez votre système externe une fois, concevez l’étiquette une fois dans un navigateur, puis soumettez des tâches d’impression — ou récupérez des PDF et PNG rendus — depuis votre propre code. Pas de pilote d’imprimante, pas de SDK, pas de commandes d’imprimante brutes.

Ce que vous allez construire : imprimer des étiquettes depuis une API de service web

Il y a deux résultats que vous voudrez généralement obtenir, et la bonne nouvelle est qu’ils partagent la même forme de requête :

• Soumettre une tâche d’impression. Votre application envoie une référence d’étiquette plus une charge utile de données. La tâche entre dans une file d’attente et est envoyée à l’imprimante configurée.
• Rendre une étiquette unique. La même étiquette et les mêmes données reviennent sous forme de PDF ou de PNG — pour les aperçus dans votre interface, les pièces jointes d’e-mails, les validations ou une archive d’audit.

Next Generation Label Printing System (LPSNG) expose exactement cela sous forme d’API de service web gérée. Vous appelez un point de terminaison ; le service prend en charge la pile d’impression. La même surface d’API couvre également l’impression directe (directement vers un appareil, en contournant la file d’attente) et les mises à jour d’étiquettes électroniques de gondole, de sorte que l’intégration que vous construisez aujourd’hui continue de fonctionner lorsque vos besoins évoluent.

Voici le parcours que nous allons suivre :

1. Enregistrer le système externe avec OAuth2.
2. Concevoir l’étiquette une fois dans le studio d’étiquettes.
3. Soumettre une tâche d’impression depuis votre application.
4. Rendre une étiquette unique en PDF ou PNG.
5. Vérifier que la tâche est bien arrivée sur le papier.

Les chemins exacts des points de terminaison et les noms des paramètres se trouvent dans la documentation Web Service Interface et External Application Integration — cet article vous donne la forme et l’ordre des opérations, et la documentation vous donne les détails au niveau de l’octet.

Prérequis avant d’appeler l’API

Avant la première requête, préparez les éléments suivants :

• Un compte ou une édition LPSNG qui inclut l’interface de service web. La Cloud Solution, l’Embedded Edition sur un ordinateur monocarte et les Enterprise Features multi-utilisateurs portent tous la même fonctionnalité de base décrite dans Use Cases — interface web, studio d’étiquettes, file d’attente des tâches, génération de PDF et interface de service web.
• Une mise en page d’étiquette qui existe déjà dans le studio d’étiquettes, avec des champs mappés aux données que vous comptez envoyer. L’API référence la mise en page par identifiant ; elle ne construit pas les mises en page à la volée.
• Des identifiants OAuth2 issus du flux d’enregistrement utilisé pour connecter des systèmes externes.
• N’importe quel client HTTP compatible HTTPS. Python, Node, Go, curl — le protocole s’en moque.
• Facultatif : une imprimante de test, ou le LPSNG Player si vous voulez un chemin de rendu local avant de connecter un appareil.

Étape 1 : Enregistrer votre système externe avec OAuth2

LPSNG utilise un protocole d’enregistrement OAuth2 simplifié qui connecte des systèmes externes avec une seule URL. C’est la partie que la plupart des intégrations ratent lorsqu’elles la réalisent elles-mêmes : gérer à la main le rafraîchissement des jetons et l’authentification des appareils contre un protocole d’impression brut représente des semaines de travail qui n’ont rien à voir avec les étiquettes.

Le flux géré se fait en une étape :

# 1. Open the registration URL that LPSNG generates for your external system.
#    You complete the consent step once, in a browser.
open "$REGISTRATION_URL"

# 2. Store the credentials LPSNG hands back for that registered system.
export LPSNG_CLIENT_ID="<client-id>"
export LPSNG_CLIENT_SECRET="<client-secret>"

# 3. Exchange them for a token your API calls will use.
#    Exact parameter names: see https://lpsng.rsj.de/en/oauth2.md

Deux choses à noter :

• Le consentement est une étape unique. Après l’enregistrement, votre application utilise les identifiants obtenus à chaque appel d’API ultérieur — vous n’envoyez pas un humain à travers un flux navigateur pour chaque tâche d’impression.
• C’est le même modèle que celui utilisé pour les stations de base ESL. Si vous connectez plus tard des étiquettes de gondole, vous reconnaîtrez immédiatement le schéma. Les détails se trouvent dans la documentation ESL et ESL Interface.

Stockez le jeton comme vous stockeriez n’importe quel autre secret : variable d’environnement ou gestionnaire de secrets, jamais dans le dépôt.

Étape 2 : Concevoir l’étiquette une fois dans le studio d’étiquettes

Ouvrez l’interface web et construisez la mise en page comme vous construiriez un document : blocs de texte, images, codes-barres et espaces réservés de champs là où les données de l’API viendront se loger.

Quelques décisions qui paient plus tard :

• Utilisez des symbologies de codes-barres prises en charge. LPSNG rend nativement les formats 1D et 2D — la page Barcode Formats liste ce qui est disponible. Si vous choisissez un format pris en charge, l’API le rend sans aucun travail supplémentaire de votre côté.
• Attachez des blocs de script Python aux champs lorsque vous avez besoin de logique. L’Field Script API permet à un bloc de script d’accéder à la valeur d’un champ et de la modifier avant l’impression — pratique pour formater des dates, tronquer de longs noms de fournisseurs ou dériver une clé de contrôle.

# Example: a script block attached to a field, formatting a raw value
# before it reaches the printer. See https://lpsng.rsj.de/api.html
value = str(value).strip().upper()

if len(value) > 30:
    value = value[:27] + "..."

• Enregistrez la mise en page et notez son identifiant. C’est cet identifiant que votre appel d’API référence — traitez-le comme une valeur de configuration, pas comme une chaîne magique enfouie dans le code.
• Gardez la mise en page séparée des données. La mise en page définit l’apparence d’une étiquette ; la requête définit ce qu’elle dit. C’est cette séparation qui permet à une seule mise en page de servir des milliers de tâches.

Étape 3 : Soumettre une tâche d’impression depuis votre application

Passons maintenant à l’appel lui-même. La forme est toujours la même : s’authentifier, référencer l’étiquette, transmettre la charge utile de données pour les champs.

import os
import requests

BASE  = os.environ["LPSNG_BASE_URL"]        # your LPSNG instance
TOKEN = os.environ["LPSNG_ACCESS_TOKEN"]    # from the OAuth2 registration

job = {
    "label": "shipping-label-4x6",   # identifier from the label studio
    "printer": "warehouse-01",       # a printer configured in LPSNG
    "data": {
        "order_no":  "SO-10432",
        "customer":  "Nordwind Handel GmbH",
        "sku":       "HND-2200-BLK",
        "qty":       "12",
        "barcode":   "SO-10432-HND-2200-BLK",
    },
}

resp = requests.post(
    f"{BASE}/<print-job-endpoint>",   # exact path: see the Web Service Interface docs
    json=job,
    headers={"Authorization": f"Bearer {TOKEN}"},
    timeout=30,
)
resp.raise_for_status()
print(resp.json())   # job identifier + status

Côté serveur, la tâche entre dans la file d’attente et est envoyée à l’imprimante configurée. Votre application ne maintient pas de connexion ouverte vers un appareil, et elle n’a pas besoin de savoir si cette imprimante parle ZPL, EPL ou autre chose.

Variantes à connaître :

• Impression directe. Lorsque vous voulez que l’étiquette aille directement vers un appareil plutôt que d’attendre son tour dans la file d’attente, l’interface expose un chemin d’impression directe.
• Traitement par lots. Chaque appel est une référence d’étiquette plus des données, donc boucler sur des lignes de commande n’est qu’une boucle dans votre code — une tâche par ligne, dans l’ordre dont votre poste de colisage a besoin.

Pour les points de terminaison exacts, les noms des paramètres et les champs de réponse, utilisez les références Web Service Interface et External Application Integration.

Étape 4 : Rendre une étiquette unique en PDF ou PNG

Le rendu l’emporte sur l’impression lorsqu’un humain doit d’abord regarder l’étiquette, ou lorsque vous avez besoin d’une trace de son existence :

• Aperçus dans votre propre interface avant que quelqu’un ne valide un tirage.
• Pièces jointes d’e-mails pour les fournisseurs ou les clients.
• Étapes de validation où un relecteur approuve le visuel.
• Archives d’audit qui subsistent indépendamment d’une imprimante.

L’appel ressemble à la tâche d’impression, sauf qu’il renvoie des octets au lieu de mettre du travail en file d’attente :

# PDF for archiving or attaching
curl -sS -X POST "$LPSNG_BASE_URL/<render-endpoint>" \
  -H "Authorization: Bearer $LPSNG_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"label":"shipping-label-4x6","format":"pdf",
       "data":{"order_no":"SO-10432","sku":"HND-2200-BLK"}}' \
  -o label-SO-10432.pdf

# PNG for a preview thumbnail — same layout, same data, same output geometry
curl -sS -X POST "$LPSNG_BASE_URL/<render-endpoint>" \
  -H "Authorization: Bearer $LPSNG_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"label":"shipping-label-4x6","format":"png",
       "data":{"order_no":"SO-10432","sku":"HND-2200-BLK"}}' \
  -o label-SO-10432.png

Comme les deux chemins utilisent la même mise en page et les mêmes données, ce que vous prévisualisez est ce que vous imprimez. C’est tout l’intérêt de le faire dans un seul système plutôt que de raccorder une bibliothèque PDF à un pilote d’imprimante.

Deux notes pratiques :

• Rendu hors ligne ou embarqué. Le LPSNG Player est un moteur d’impression en ligne de commande autonome qui prend un paquet et des données en entrée et produit un PDF, un PNG, du JSON, une sortie d’impression ou une mise à jour ESL. C’est le bon outil lorsque vous avez besoin d’une sortie sans aller-retour vers un serveur.
• Mettez en cache agressivement. Les étiquettes répétées — la même étiquette de gondole, le même identifiant de palette — n’ont pas besoin d’un nouveau rendu à chaque fois. Stockez le PDF indexé sur la mise en page + le hachage des données et évitez l’appel d’API.

Étape 5 : Vérifier que la tâche d’impression a fonctionné

Un HTTP 200 signifie que la tâche a été acceptée. Cela ne signifie pas qu’une étiquette est sortie d’une imprimante. Vérifiez dans cet ordre :

1. Consultez la file d’attente des tâches dans l’interface web. Confirmez que la tâche a été acceptée et terminée, et qu’elle est allée à l’imprimante que vous attendiez.
2. Comparez le rendu à la réalité. Placez le PDF ou le PNG à côté de l’étiquette physique. C’est là que les problèmes de mise à l’échelle et les problèmes de zone de silence des codes-barres apparaissent, et ils sont bien moins coûteux à détecter maintenant que chez un client.
3. Scannez le code-barres. Un lecteur est le seul test honnête pour savoir si les données font l’aller-retour — vérifiez que la valeur scannée correspond à ce que votre application a envoyé, caractère par caractère.
4. Journalisez la réponse et l’identifiant de la tâche. Stockez les deux avec votre enregistrement interne de commande ou d’expédition. Quand quelqu’un demande « est-ce que ce colis est parti avec une étiquette ? », vous voulez une réponse venant d’une base de données, pas une supposition.
5. Si vous utilisez ESL, vérifiez aussi l’affichage. Un affichage de gondole mis à jour est un second signal indépendant que les mêmes données ont atteint le service. L’ESL Interface et l’ESL Binding API couvrent ce côté.

Dépannage des problèmes courants

Échecs d’authentification. Si les appels commencent à renvoyer des erreurs d’authentification, le jeton a probablement été révoqué ou l’enregistrement du système externe a changé. Relancez l’enregistrement OAuth2 — c’est un flux en une étape par conception, donc la récupération est peu coûteuse. Voir la page OAuth2.

Champs vides ou manquants sur l’étiquette. Presque toujours une incohérence de clés : les clés de votre charge utile data doivent correspondre exactement aux noms des champs de la mise en page, y compris la casse. Rendez l’étiquette en PNG et inspectez-la avant de blâmer l’imprimante.

Sortie de code-barres incorrecte. Vérifiez deux choses : que le format que vous avez choisi figure dans la liste prise en charge des Barcode Formats, et que le type de données correspond à ce que la symbologie attend. Les formats purement numériques rendront volontiers du charabia à partir d’une chaîne contenant des lettres.

L’imprimante ne reçoit pas les tâches. La tâche ne peut être envoyée qu’à une imprimante configurée et en ligne dans LPSNG. Si la file d’attente montre la tâche en attente, c’est la cible qui pose problème, pas votre requête.

Le rendu semble différent de l’impression. Comparez le DPI et la taille d’étiquette entre la mise en page et le support physique. Une mise en page conçue pour une taille et envoyée à un support de taille différente sera mise à l’échelle d’une manière qui casse la lisibilité des codes-barres.

FAQ

Ai-je besoin d’un pilote d’imprimante ou d’un SDK sur mon serveur pour imprimer des étiquettes depuis l’API de service web ?

Non. Next Generation Label Printing System prend en charge la pile d’impression pour vous : vous soumettez une tâche ou demandez un rendu via l’API de service web, et le service géré s’occupe du reste. Le LPSNG Player est disponible si vous avez besoin d’un moteur en ligne de commande autonome pour une sortie locale.

Quelle est la différence entre soumettre une tâche d’impression et rendre une étiquette unique ?

Soumettre une tâche d’impression envoie l’étiquette à l’imprimante configurée via la file d’attente des tâches. Le rendu renvoie l’étiquette sous forme de PDF ou de PNG afin que vous puissiez la prévisualiser, l’archiver ou la joindre sans imprimer. Les deux utilisent la même mise en page et les mêmes données, donc la sortie est cohérente.

Comment fonctionne l’enregistrement OAuth2 pour les systèmes externes ?

LPSNG utilise un protocole d’enregistrement OAuth2 simplifié qui connecte des systèmes externes avec une seule URL. Vous complétez l’étape de consentement une fois, et les identifiants obtenus sont utilisés pour les appels d’API ultérieurs. Le même modèle est utilisé pour les stations de base ESL, donc le schéma est cohérent d’une intégration à l’autre.

La même API peut-elle aussi mettre à jour des étiquettes électroniques de gondole ?

Oui. LPSNG inclut une interface JSON neutre vis-à-vis des fournisseurs (ESLSEND) et une API de liaison pour les étiquettes ESL, de sorte que vous pouvez gérer à la fois les étiquettes imprimées et les étiquettes électroniques de gondole depuis la même intégration. Pour un aperçu plus approfondi, consultez nos articles compagnons sur l’ESL Binding API et les API d’intégration des étiquettes électroniques de gondole.

Conclusion

Le schéma est assez court pour être gardé en tête : enregistrez-vous une fois avec OAuth2, concevez l’étiquette une fois dans le studio d’étiquettes, puis soumettez une tâche ou récupérez un rendu depuis votre application. Tout ce qui était autrefois un problème propre à l’imprimante — pilotes, langages de commande, mise à l’échelle des polices, bibliothèques de codes-barres — est géré derrière une seule surface d’API qui couvre les tâches d’impression, l’impression directe, le rendu PDF et PNG, et les mises à jour ESL.

Next Generation Label Printing System est le service géré qui fait de tout cela l’intégration entière plutôt qu’une de ses parties. Commencez par la documentation Web Service Interface pour les points de terminaison exacts, concevez votre première mise en page dans le studio d’étiquettes, et envoyez une tâche de test à une seule imprimante avant d’automatiser le reste. Si vous pesez encore vos options, notre comparatif d’alternatives à Zebra Designer est une lecture suivante raisonnable.

Articles similaires

• Alternative à Zebra Designer : logiciels d’impression d’étiquettes à comparer
• ESL Binding API : documentation et exemples
• Comprendre les API d’intégration des étiquettes électroniques de gondole