Génération d’étiquettes à code-barres en Python : un guide étape par étape

Si vous avez déjà essayé de générer une étiquette à code-barres à partir d’un script Python, vous connaissez le chemin habituel : choisir une bibliothèque de codes-barres, rendre une image, construire vous-même la mise en page de l’étiquette, puis trouver comment communiquer avec une imprimante thermique. Ce guide adopte une approche différente et gérée. Vous utiliserez le système d’impression d’étiquettes de nouvelle génération (LPSNG) comme moteur de rendu et d’impression, et vous le piloterez depuis Python avec de simples requêtes HTTP.

À la fin de ce guide, vous disposerez d’un script Python qui :

• s’authentifie auprès de l’API du service web LPSNG ;
• recherche une mise en page d’étiquette ;
• envoie des données d’article dynamiques, y compris le contenu du code-barres ;
• applique des personnalisations de champs basées sur Python ;
• rend l’étiquette en PDF ou en PNG ;
• l’envoie à une imprimante ou l’enregistre localement.

C’est idéal pour les développeurs qui ont besoin d’une génération d’étiquettes pilotée par les données dans des flux de travail d’entrepôt, de logistique, de vente au détail ou d’exécution de commandes — sans construire ni maintenir un pipeline de rendu d’étiquettes personnalisé.

Prérequis

Avant de commencer, assurez-vous de disposer des éléments suivants :

• Python 3.x installé sur votre machine.
• Un compte LPSNG — soit l’édition cloud, soit une édition embarquée — avec accès à l’API du service web.
• Une mise en page d’étiquette créée dans le studio d’étiquettes LPSNG, ou un exemple de mise en page que vous pouvez utiliser pour vos tests. La mise en page doit contenir au moins un champ de code-barres.
• Des identifiants client OAuth2 pour l’authentification à l’API. Consultez le guide OAuth2 pour le flux d’enregistrement simplifié.
• Une familiarité de base avec Python et les API REST. Le service web LPSNG est RESTful et renvoie du JSON, donc des connaissances HTTP standard suffisent.

Vous n’avez pas besoin d’installer des polices de codes-barres, des pilotes ZPL/EPL ou des SDK spécifiques à une imprimante. LPSNG gère ces détails en coulisses via son service web.

Étape par étape : générer des étiquettes à code-barres avec Python

Le flux de travail est simple : s’authentifier, identifier la mise en page, préparer les données, personnaliser éventuellement les champs avec un bloc de script Python, rendre l’étiquette, puis l’imprimer ou l’enregistrer.

Étape 1 : Configurer votre environnement Python

Créez un répertoire de projet et installez la bibliothèque requests. L’API LPSNG est RESTful, vous n’avez donc besoin que d’un client HTTP standard.

mkdir lpsng-python-labeling
cd lpsng-python-labeling
python -m venv venv
source venv/bin/activate  # ou venv\Scripts\activate sous Windows
pip install requests

Créez un fichier nommé generate_label.py. En haut du fichier, définissez votre URL de base LPSNG et vos identifiants. Remplacez les valeurs d’exemple par les détails réels de votre instance.

import requests
import json
from pathlib import Path

# Remplacez par l'URL de votre instance LPSNG, par ex. https://votre-instance.lpsng.rsj.de
LPSNG_BASE_URL = "https://votre-instance.lpsng.rsj.de"

# Remplacez par les identifiants issus de votre enregistrement OAuth2
CLIENT_ID = "votre-client-id"
CLIENT_SECRET = "votre-client-secret"

Étape 2 : Obtenir un jeton d’accès OAuth2

LPSNG utilise un protocole d’enregistrement OAuth2 simplifié. Une fois votre application externe enregistrée, vous échangez vos identifiants client contre un jeton d’accès.

L’exemple ci-dessous conserve l’URL du point de terminaison de jeton sous forme de variable, afin que vous puissiez la faire pointer vers l’URL exacte indiquée dans la documentation de l’API du service web de votre instance.

def get_access_token():
    # Utilisez le point de terminaison de jeton indiqué dans le guide OAuth2 LPSNG.
    token_url = f"{LPSNG_BASE_URL}/oauth2/token"

    response = requests.post(
        token_url,
        data={
            "grant_type": "client_credentials",
            "client_id": CLIENT_ID,
            "client_secret": CLIENT_SECRET,
        },
        timeout=30,
    )
    response.raise_for_status()
    return response.json()["access_token"]

En production, mettez le jeton en cache et actualisez-le avant son expiration. Pour ce tutoriel, vous pouvez demander un nouveau jeton à chaque fois.

Étape 3 : Récupérer l’ID de votre mise en page d’étiquette

Chaque mise en page d’étiquette dans LPSNG possède un ID. Vous pouvez le copier depuis l’interface web LPSNG en ouvrant les propriétés de la mise en page, ou vous pouvez l’interroger via l’API.

Le chemin via l’interface web est le plus simple pour un premier test. Ouvrez votre mise en page d’étiquette dans le studio d’étiquettes et copiez l’ID de la mise en page depuis l’URL ou les paramètres de la mise en page.

Si vous souhaitez automatiser la recherche de mise en page depuis Python, utilisez le même modèle REST. Le point de terminaison exact peut varier selon l’instance, alors complétez-le à partir de votre référence d’API :

def find_layout_id(token, layout_name):
    headers = {"Authorization": f"Bearer {token}"}

    # Remplacez /layouts par le point de terminaison de liste documenté pour votre instance.
    response = requests.get(
        f"{LPSNG_BASE_URL}/layouts",
        headers=headers,
        timeout=30,
    )
    response.raise_for_status()

    for layout in response.json():
        if layout.get("name") == layout_name:
            return layout["id"]

    raise ValueError(f"Mise en page introuvable : {layout_name}")

Pour un script rapide, un ID de mise en page codé en dur convient parfaitement :

LAYOUT_ID = "votre-id-de-mise-en-page"

Étape 4 : Préparer la charge utile de données avec le contenu du code-barres

L’API du service web soumet des travaux d’impression et rend des étiquettes individuelles. Votre charge utile contient généralement un ensemble de valeurs de champs pour la mise en page, y compris la valeur qui doit être encodée dans le code-barres.

Voici un exemple de charge utile pour une étiquette d’article avec un code-barres Code 128 :

label_data = {
    "product_name": "Rouleau d'étiquettes thermiques 100x150",
    "sku": "THR-100-150",
    "barcode": "4012345678901",
    "quantity": 12,
    "batch": "B20260831-04",
}

Les noms de champs de votre charge utile doivent correspondre aux noms de champs que vous avez définis dans le studio d’étiquettes LPSNG. Si votre mise en page comporte un champ de code-barres nommé barcode, LPSNG encode la valeur que vous envoyez pour ce champ dans le format de code-barres configuré dans la mise en page.

Étape 5 : Personnaliser les champs avec l’API Python Field Script

LPSNG inclut une API Python Field Script qui vous permet d’attacher de petits blocs de script Python aux champs d’étiquette. Ces scripts s’exécutent avant l’impression et peuvent accéder aux valeurs des champs ou les modifier.

Par exemple, supposons que vos données d’entrepôt contiennent parfois des codes-barres en minuscules ou des espaces de fin, et que vous souhaitiez normaliser la valeur avant qu’elle n’atteigne le code-barres. Dans le studio d’étiquettes LPSNG, attachez un bloc de script au champ de code-barres qui ressemble à ceci :

# Attaché au champ de code-barres dans LPSNG Label Studio.
# Le script s'exécute avant l'impression et peut accéder à la valeur actuelle.
if "barcode" in context:
    value = str(context["barcode"]).strip().upper()

Le point d’entrée exact et les objets disponibles sont documentés dans la référence de l’API Python. Utilisez cette référence pour vérifier la signature exacte du hook pour votre version de LPSNG. L’idée clé est que les scripts Python au niveau des champs gardent la logique de formatage proche de l’étiquette, tandis que votre application Python externe reste concentrée sur la préparation des données et les appels d’API.

Étape 6 : Appeler le point de terminaison du service web pour rendre l’étiquette

Appelez maintenant LPSNG pour rendre l’étiquette en PDF ou en PNG. L’API du service web peut rendre des étiquettes individuelles, vous n’avez donc pas besoin d’exécuter un moteur de rendu local.

def render_label(token, layout_id, data, output_format="pdf"):
    headers = {
        "Authorization": f"Bearer {token}",
        "Content-Type": "application/json",
    }

    # Utilisez le point de terminaison de rendu de la documentation de l'API du service web LPSNG.
    render_url = f"{LPSNG_BASE_URL}/render"

    response = requests.post(
        render_url,
        headers=headers,
        json={
            "layout_id": layout_id,
            "data": data,
            "format": output_format,
        },
        timeout=60,
    )
    response.raise_for_status()
    return response.content

Pour une sortie PNG, passez "png" comme format. La réponse de l’API contient le contenu binaire du fichier, que vous pouvez enregistrer directement.

token = get_access_token()
pdf_bytes = render_label(token, LAYOUT_ID, label_data, "pdf")

Path("label.pdf").write_bytes(pdf_bytes)
print("Étiquette rendue : label.pdf")

Étape 7 : Envoyer l’étiquette générée à une imprimante ou l’enregistrer localement

Si votre instance LPSNG est connectée à des imprimantes, vous pouvez soumettre un travail d’impression via la même API de service web au lieu de télécharger le fichier. La forme exacte de la requête est documentée dans l’interface du service web.

Un appel d’impression directe typique suit le même modèle REST :

def send_to_printer(token, layout_id, data, printer_name):
    headers = {
        "Authorization": f"Bearer {token}",
        "Content-Type": "application/json",
    }

    # Utilisez le point de terminaison d'impression documenté pour votre instance LPSNG.
    print_url = f"{LPSNG_BASE_URL}/print"

    response = requests.post(
        print_url,
        headers=headers,
        json={
            "layout_id": layout_id,
            "data": data,
            "printer": printer_name,
        },
        timeout=60,
    )
    response.raise_for_status()
    return response.json()

Remplacez "printer" par le nom ou l’ID de l’imprimante configuré dans votre environnement LPSNG. Si vous préférez conserver le fichier localement, ignorez cette étape et utilisez la sortie PDF ou PNG de l’étape 6.

Vérifier la sortie de votre étiquette

Ne partez pas du principe que le code-barres est correct simplement parce que le PDF ou le PNG s’est ouvert sans erreur. Effectuez ces vérifications :

• Ouvrez visuellement le fichier généré. Confirmez que les champs de texte sont remplis, que le code-barres est visible et que la mise en page correspond à votre conception dans le studio d’étiquettes.
• Scannez le code-barres avec une application de scanner. Pointez un scanner de codes-barres basé sur téléphone vers l’étiquette imprimée ou affichée à l’écran. Vérifiez que les données encodées correspondent à la valeur que vous avez envoyée dans la charge utile.
• Vérifiez les personnalisations de champs. Si vous avez ajouté un script de champ Python qui met en majuscules ou supprime les espaces de la valeur du code-barres, envoyez des données de test en minuscules ou avec des espaces et confirmez que la sortie a changé comme prévu.
• Testez avec plusieurs jeux de données. Exécutez le script avec différents SKU, quantités et valeurs de codes-barres pour vous assurer qu’aucun champ n’est codé en dur ou mal aligné.

Si votre sortie est un PDF, imprimez-le une fois sur l’imprimante thermique cible pour confirmer les dimensions de l’étiquette et la densité d’impression.

Résolution des problèmes courants

Erreurs d’authentification

Vérifiez vos identifiants client OAuth2 et le point de terminaison de jeton. Si le jeton a expiré, demandez-en un nouveau. Confirmez que le client est toujours enregistré dans votre compte LPSNG et que le compte dispose d’un accès à l’API.

Mise en page d’étiquette introuvable

Vérifiez l’ID de la mise en page et les autorisations utilisateur associées à votre client OAuth2. Le client peut avoir accès à l’API mais pas à la mise en page spécifique. Vérifiez le nom exact de la mise en page, y compris la casse et les espaces.

Le code-barres ne s’affiche pas

Assurez-vous que le format de code-barres est pris en charge par LPSNG et que la valeur du champ de code-barres est valide pour ce format. Par exemple, un champ Code 128 doit recevoir des données valides pour le Code 128. Consultez la documentation sur les formats de codes-barres pour la liste complète des formats 1D et 2D pris en charge.

Vérifiez également que le champ de code-barres de votre mise en page est réellement mappé à la clé de charge utile que vous envoyez. Une discordance entre les noms de champs est une cause fréquente de codes-barres vides.

Erreurs de script de champ

Si votre script de champ Python génère une erreur, la réponse de l’API contient généralement un message d’erreur. Lisez-le attentivement ; il indique souvent le numéro de ligne ou le type d’exception dans le bloc de script. Utilisez la référence de l’API Python pour confirmer quels objets sont disponibles dans le contexte du script.

Problèmes d’impression

Si l’étiquette se rend mais ne s’imprime pas, confirmez la connectivité de l’imprimante et la configuration du pilote dans votre environnement LPSNG. Vérifiez que le nom de l’imprimante dans votre appel d’impression correspond au nom configuré dans LPSNG et que l’imprimante est en ligne.

FAQ

Puis-je générer des étiquettes à code-barres en Python sans utiliser le service web LPSNG ?

Oui, vous pourriez utiliser des bibliothèques brutes comme python-barcode ou reportlab, mais vous devriez gérer vous-même la conception des étiquettes, la communication avec l’imprimante et les normes de codes-barres. LPSNG fournit un service géré avec une API Python qui simplifie l’ensemble du processus, y compris la personnalisation des champs et l’impression directe.

Quels formats de codes-barres sont pris en charge par LPSNG ?

LPSNG prend en charge une large gamme de formats de codes-barres 1D et 2D. Consultez la documentation sur les formats de codes-barres pour la liste complète, y compris Code 128, QR Code, Data Matrix et plus encore.

Dois-je installer des paquets Python spéciaux pour utiliser l’API LPSNG ?

Seules des bibliothèques client HTTP standard comme requests sont nécessaires. L’API est RESTful et renvoie des réponses JSON, ce qui facilite l’intégration avec n’importe quel environnement Python.

Puis-je également utiliser l’API Python pour mettre à jour des étiquettes électroniques de gondole (ESL) ?

Oui, LPSNG propose une interface ESL et une API de liaison accessibles via Python. Consultez la documentation ESL pour plus de détails sur la mise à jour programmatique des affichages ESL.

Conclusion

La génération d’étiquettes à code-barres en Python devient beaucoup plus simple lorsque vous laissez un service géré prendre en charge le rendu, les normes de codes-barres et les détails d’impression. Avec LPSNG, votre application Python n’a qu’à s’authentifier, envoyer les données de champs et appeler un point de terminaison REST. La conception de l’étiquette reste dans le studio d’étiquettes, tandis que les scripts de champs Python gèrent le formatage au niveau des champs.

Cette approche s’intègre parfaitement dans des flux de travail d’automatisation plus larges. Si vous évaluez un logiciel d’étiquettes en tant que développeur, consultez Meilleur logiciel de conception d’étiquettes pour les développeurs : pourquoi LPSNG se démarque. Si votre projet d’étiquetage s’étend aux étiquettes électroniques de gondole, poursuivez avec Intégration ESL pour le commerce de détail : un guide complet. Et si la plupart de vos données sources se trouvent dans des feuilles de calcul, ne manquez pas Automatiser l’impression d’étiquettes depuis Excel : gagner du temps et réduire les erreurs.

Prêt à créer votre première étiquette à code-barres générée en Python ? Récupérez vos identifiants OAuth2, choisissez une mise en page et exécutez le script avec un article réel. Le système d’impression d’étiquettes de nouvelle génération s’occupe du gros du travail — vous écrivez l’intégration.

Articles connexes

• Meilleur logiciel de conception d’étiquettes pour les développeurs : pourquoi LPSNG se démarque
• Intégration ESL pour le commerce de détail : un guide complet
• Automatiser l’impression d’étiquettes depuis Excel : gagner du temps et réduire les erreurs