Generazione di etichette con codici a barre in Python: una guida passo passo

Se hai mai provato a generare un’etichetta con codice a barre da uno script Python, conosci il percorso abituale: scegli una libreria per codici a barre, renderizza un’immagine, costruisci da solo il layout dell’etichetta e poi scopri come comunicare con una stampante termica. Questa guida adotta un approccio diverso e gestito. Utilizzerai il Next Generation Label Printing System (LPSNG) come motore di rendering e stampa, pilotandolo da Python con semplici richieste HTTP.

Alla fine, avrai uno script Python che:

• Si autentica presso l’API del servizio web LPSNG
• Individua un layout di etichetta
• Invia dati dinamici sugli articoli, incluso il contenuto del codice a barre
• Applica personalizzazioni dei campi basate su Python
• Renderizza l’etichetta come PDF o PNG
• La invia a una stampante o la salva localmente

È la soluzione ideale per gli sviluppatori che necessitano di generazione di etichette basata sui dati in flussi di lavoro di magazzino, logistica, vendita al dettaglio o evasione ordini, senza dover costruire e mantenere una pipeline personalizzata di rendering delle etichette.

Prerequisiti

Prima di iniziare, assicurati di avere:

• Python 3.x installato sulla tua macchina.
• Un account LPSNG — edizione cloud o edizione embedded — con accesso all’API del servizio web.
• Un layout di etichetta creato nel label studio di LPSNG, oppure un layout di esempio da usare per i test. Il layout deve contenere almeno un campo codice a barre.
• Credenziali client OAuth2 per l’autenticazione API. Consulta la guida OAuth2 per il flusso di registrazione semplificato.
• Familiarità di base con Python e le API REST. Il servizio web LPSNG è RESTful e restituisce JSON, quindi è sufficiente una conoscenza standard di HTTP.

Non è necessario installare font per codici a barre, driver ZPL/EPL o SDK specifici per stampanti. LPSNG gestisce questi dettagli dietro il suo servizio web.

Passo dopo passo: generare etichette con codici a barre con Python

Il flusso di lavoro è semplice: autenticarsi, identificare il layout, preparare i dati, personalizzare facoltativamente i campi con un blocco di script Python, renderizzare l’etichetta e stamparla o salvarla.

Passo 1: configurare l’ambiente Python

Crea una directory di progetto e installa la libreria requests. L’API LPSNG è RESTful, quindi ti serve solo un client HTTP standard.

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

Crea un file chiamato generate_label.py. In alto, definisci l’URL di base di LPSNG e le credenziali. Sostituisci i segnaposto con i dettagli reali della tua istanza.

import requests
import json
from pathlib import Path

# Sostituisci con l'URL della tua istanza LPSNG, ad es. https://your-instance.lpsng.rsj.de
LPSNG_BASE_URL = "https://your-instance.lpsng.rsj.de"

# Sostituisci con le credenziali della tua registrazione OAuth2
CLIENT_ID = "your-client-id"
CLIENT_SECRET = "your-client-secret"

Passo 2: ottenere un token di accesso OAuth2

LPSNG utilizza un protocollo di registrazione OAuth2 semplificato. Una volta registrata la tua applicazione esterna, scambi le credenziali client con un token di accesso.

L’esempio seguente mantiene l’endpoint del token come variabile, così puoi puntarlo all’URL esatto indicato nella documentazione della Web Service API per la tua istanza.

def get_access_token():
    # Usa l'endpoint del token indicato nella guida OAuth2 di 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"]

Nel codice di produzione, memorizza il token nella cache e aggiornalo prima della scadenza. Per questa guida, puoi richiedere un nuovo token ogni volta.

Passo 3: recuperare l’ID del layout dell’etichetta

Ogni layout di etichetta in LPSNG ha un ID. Puoi copiarlo dall’interfaccia web di LPSNG aprendo le proprietà del layout, oppure puoi interrogarlo tramite l’API.

Il percorso tramite interfaccia web è il più semplice per un primo test. Apri il layout dell’etichetta nel label studio e copia l’ID del layout dall’URL o dalle impostazioni del layout.

Se vuoi automatizzare la ricerca del layout da Python, usa lo stesso schema REST. L’endpoint esatto può variare in base all’istanza, quindi compilalo in base al tuo riferimento API:

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

    # Sostituisci /layouts con l'endpoint di elenco documentato per la tua istanza.
    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"Layout non trovato: {layout_name}")

Per uno script rapido, un ID layout hardcoded va benissimo:

LAYOUT_ID = "your-layout-id"

Passo 4: preparare il payload dei dati con il contenuto del codice a barre

L’API del servizio web invia processi di stampa e renderizza singole etichette. Il payload contiene in genere un insieme di valori dei campi per il layout, incluso il valore che deve essere codificato nel codice a barre.

Ecco un payload di esempio per un’etichetta articolo con un codice a barre Code 128:

label_data = {
    "product_name": "Rotolo etichette termiche 100x150",
    "sku": "THR-100-150",
    "barcode": "4012345678901",
    "quantity": 12,
    "batch": "B20260831-04",
}

I nomi dei campi nel payload devono corrispondere ai nomi dei campi definiti nel label studio di LPSNG. Se il layout ha un campo codice a barre chiamato barcode, LPSNG codifica il valore inviato per quel campo nel formato di codice a barre configurato nel layout.

Passo 5: personalizzare i campi con la Python Field Script API

LPSNG include una Python Field Script API che consente di associare piccoli blocchi di script Python ai campi dell’etichetta. Questi script vengono eseguiti prima della stampa e possono accedere o modificare i valori dei campi.

Ad esempio, supponi che i dati del tuo magazzino contengano a volte codici a barre in minuscolo o spazi finali e che tu voglia normalizzare il valore prima che raggiunga il codice a barre. Nel label studio di LPSNG, associa al campo codice a barre un blocco di script simile a questo:

# Associato al campo codice a barre in LPSNG Label Studio.
# Lo script viene eseguito prima della stampa e può accedere al valore corrente.
if "barcode" in context:
    value = str(context["barcode"]).strip().upper()

Il punto di ingresso esatto e gli oggetti disponibili sono documentati nel riferimento API Python. Usa quel riferimento per verificare la firma esatta dell’hook per la tua versione di LPSNG. L’idea chiave è che gli script Python a livello di campo mantengono la logica di formattazione vicina all’etichetta, mentre la tua applicazione Python esterna resta concentrata sulla preparazione dei dati e sulle chiamate API.

Passo 6: chiamare l’endpoint del servizio web per renderizzare l’etichetta

Ora chiama LPSNG per renderizzare l’etichetta come PDF o PNG. L’API del servizio web può renderizzare singole etichette, quindi non è necessario eseguire un renderer locale.

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

    # Usa l'endpoint di rendering dalla documentazione della Web Service API di 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

Per l’output PNG, passa "png" come formato. La risposta API contiene il contenuto binario del file, che puoi salvare direttamente.

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

Path("label.pdf").write_bytes(pdf_bytes)
print("Etichetta renderizzata: label.pdf")

Passo 7: inviare l’etichetta generata a una stampante o salvarla localmente

Se la tua istanza LPSNG è collegata alle stampanti, puoi inviare un processo di stampa tramite la stessa API del servizio web invece di scaricare il file. La struttura esatta della richiesta è documentata nella Web Service Interface.

Una tipica chiamata di stampa diretta segue lo stesso schema REST:

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

    # Usa l'endpoint di stampa documentato per la tua istanza 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()

Sostituisci "printer" con il nome o l’ID della stampante configurato nel tuo ambiente LPSNG. Se preferisci conservare il file localmente, salta questo passaggio e usa l’output PDF o PNG del Passo 6.

Verifica dell’output dell’etichetta

Non dare per scontato che il codice a barre sia corretto solo perché il PDF o il PNG si è aperto senza errori. Esegui questi controlli:

• Apri visivamente il file generato. Conferma che i campi di testo siano compilati, che il codice a barre sia visibile e che il layout corrisponda al design del label studio.
• Scansiona il codice a barre con un’app scanner. Punta uno scanner di codici a barre basato su smartphone verso il codice a barre stampato o visualizzato sullo schermo. Verifica che i dati codificati corrispondano al valore inviato nel payload.
• Controlla le personalizzazioni dei campi. Se hai aggiunto uno script di campo Python che converte in maiuscolo o rimuove gli spazi dal valore del codice a barre, invia dati di test in minuscolo o con spazi e conferma che l’output sia cambiato come previsto.
• Testa con più set di dati. Esegui lo script con SKU, quantità e valori di codice a barre diversi per assicurarti che nessun campo sia hardcoded o disallineato.

Se l’output è un PDF, stampalo una volta sulla stampante termica di destinazione per confermare le dimensioni dell’etichetta e la densità di stampa.

Risoluzione dei problemi comuni

Errori di autenticazione

Ricontrolla le credenziali client OAuth2 e l’endpoint del token. Se il token è scaduto, richiedine uno nuovo. Conferma che il client sia ancora registrato nel tuo account LPSNG e che l’account abbia accesso all’API.

Layout dell’etichetta non trovato

Verifica l’ID del layout e i permessi utente associati al tuo client OAuth2. Il client potrebbe avere accesso all’API ma non allo specifico layout. Controlla il nome del layout esattamente, inclusi maiuscole e spazi.

Il codice a barre non viene renderizzato

Assicurati che il formato del codice a barre sia supportato da LPSNG e che il valore nel campo codice a barre sia valido per quel formato. Ad esempio, un campo Code 128 deve ricevere dati validi per Code 128. Consulta la documentazione sui Formati dei codici a barre per l’elenco completo dei formati 1D e 2D supportati.

Controlla inoltre che il campo codice a barre nel layout sia effettivamente mappato alla chiave del payload che stai inviando. Una mancata corrispondenza tra i nomi dei campi è una causa comune di codici a barre vuoti.

Errori negli script di campo

Se il tuo script di campo Python genera un errore, la risposta API di solito contiene un messaggio di errore. Leggilo attentamente; spesso indica il numero di riga o il tipo di eccezione nel blocco di script. Usa il riferimento API Python per confermare quali oggetti sono disponibili nel contesto dello script.

Problemi di stampa

Se l’etichetta viene renderizzata ma non stampata, conferma la connettività della stampante e la configurazione del driver nel tuo ambiente LPSNG. Controlla che il nome della stampante nella chiamata di stampa corrisponda al nome configurato in LPSNG e che la stampante sia online.

FAQ

Posso generare etichette con codici a barre in Python senza usare il servizio web LPSNG?

Sì, potresti usare librerie grezze come python-barcode o reportlab, ma dovresti gestire da solo il design delle etichette, la comunicazione con la stampante e gli standard dei codici a barre. LPSNG fornisce un servizio gestito con un’API Python che semplifica l’intero processo, inclusa la personalizzazione dei campi e la stampa diretta.

Quali formati di codici a barre sono supportati da LPSNG?

LPSNG supporta un’ampia gamma di formati di codici a barre 1D e 2D. Consulta la documentazione sui formati dei codici a barre per l’elenco completo, inclusi Code 128, QR Code, Data Matrix e altri.

Devo installare pacchetti Python speciali per usare l’API LPSNG?

Sono necessarie solo librerie client HTTP standard come requests. L’API è RESTful e restituisce risposte JSON, il che la rende facile da integrare con qualsiasi ambiente Python.

Posso usare l’API Python anche per aggiornare le etichette elettroniche da scaffale (ESL)?

Sì, LPSNG offre un’interfaccia ESL e un’API di binding accessibile tramite Python. Consulta la documentazione ESL per i dettagli sull’aggiornamento programmatico dei display ESL.

Conclusione

La generazione di etichette con codici a barre in Python diventa molto più semplice quando si lascia che un servizio gestito si occupi del rendering, degli standard dei codici a barre e dei dettagli di stampa. Con LPSNG, la tua applicazione Python deve solo autenticarsi, inviare i dati dei campi e chiamare un endpoint REST. Il design dell’etichetta resta nel label studio, mentre gli script di campo Python gestiscono la formattazione a livello di campo.

Questo approccio si inserisce perfettamente in flussi di lavoro di automazione più ampi. Se stai valutando un software per etichette come sviluppatore, consulta Best Label Design Software for Developers: Why LPSNG Stands Out. Se il tuo progetto di etichettatura si estende alle etichette elettroniche da scaffale, prosegui con ESL Integration for Retail: A Complete Guide. E se la maggior parte dei tuoi dati di origine vive in fogli di calcolo, non perdere Automate Label Printing from Excel: Save Time and Reduce Errors.

Pronto a creare la tua prima etichetta con codice a barre generata da Python? Prendi le tue credenziali OAuth2, scegli un layout ed esegui lo script con un articolo reale. Il Next Generation Label Printing System si occupa del lavoro pesante: a te resta scrivere l’integrazione.

Post correlati

• Best Label Design Software for Developers: Why LPSNG Stands Out
• ESL Integration for Retail: A Complete Guide
• Automate Label Printing from Excel: Save Time and Reduce Errors