Automatizzare la stampa di etichette con gli script di campo Python

2026-10-23 pdf labels barcodes label merge browser based graphical layout editor google sheets addin microsoft excel addon electronic shelf labels esl barcode3 labels label editor

Automazione della stampa di etichette con script Python sui campi

L’etichetta è quasi sempre corretta. La data è obsoleta, il numero di serie ha perso gli zeri iniziali e il totale necessita di una cifra di controllo prima che il codice a barre sia scansionabile. Così qualcuno apre il modello dell’etichetta nel designer, modifica tre campi, preme stampa e poi rifà esattamente la stessa cosa la mattina dopo.

Quella modifica non appartiene a un modello. Appartiene al codice che viene eseguito al momento della stampa. RSJ LPSNG consente di collegare un blocco di script Python direttamente a un campo dell’etichetta, così la trasformazione avviene all’interno del modello — nessuna fase di pre-elaborazione, nessun rituale “prima sistema il CSV” tra il tuo ERP e la stampante.

Questo articolo riguarda l’automazione a livello di campo: cos’è uno script di campo, come configurarlo una volta sola, come pilotarlo tramite l’API del servizio web e come evitare che comprometta silenziosamente la tua linea di produzione.

Due argomenti adiacenti sono trattati altrove: i contenuti che cambiano per ordine sono in Building Order-Specific Labeling on Top of a Label Printing API, e le etichette basate su dati da fogli di calcolo sono in How to Create Labels from Excel Data Files and Lookup Tables. Qui restiamo sul campo.

Perché automatizzare la stampa di etichette con script Python sui campi?

Gli script di campo vengono eseguiti all’interno del modello dell’etichetta. Il blocco Python è collegato a un campo e ha accesso al valore corrente di quel campo, che può modificare prima che l’etichetta venga renderizzata. Questa singola scelta di progettazione cambia la pipeline:

Nessuna pre-elaborazione esterna. Non serve uno script che riscriva i dati di input prima dell’invio. I dati entrano così come sono; l’etichetta corregge ciò che va corretto.
Coerenza tra i client. Lo script viaggia con l’etichetta. Che il job provenga dalla UI web, dall’API del servizio web o da LPSNG Player, lo stesso campo riceve lo stesso trattamento.
La logica è verificabile. Vive accanto al campo che influenza, non in un cron job sul portatile di qualcuno.

I compiti che giustificano tutto questo sono noiosi e ripetitivi:

Compito	Approccio manuale	Script di campo
Timestamp di stampa	Digitare la data odierna nel campo	Formattare il valore al momento del rendering
Numeri di serie	Aggiungere zeri a mano, saltarne uno, ristampare	Normalizzare a una larghezza fissa
Cifre di controllo	Calcolare in un foglio di calcolo	Calcolare dal valore del campo
Etichette derivate	Copiare un valore da un altro campo	Fare riferimento al campo sorgente

Nessuno di questi è difficile. È proprio questo il punto: sono troppo piccoli per meritare un servizio e troppo frequenti per continuare a farli a mano.

Configurazione una tantum: preparare l’etichetta e lo script

La configurazione è un’operazione una tantum per campo. Serve il label studio, non un ambiente Python locale.

Apri l’etichetta che vuoi automatizzare nel label studio LPSNG e seleziona il campo. Scegli un campo mappato a un elemento di testo o codice a barre.
Collega un blocco di script Python a quel campo tramite l’API degli script di campo. Lo script è memorizzato e gestito dalla piattaforma insieme all’etichetta — non c’è alcun interprete da installare sul client di stampa.
Usa il contesto dello script. Il blocco vede il valore corrente del campo e ne restituisce uno modificato prima della stampa. Le variabili di contesto esatte sono definite nel riferimento dell’API Python — leggilo una volta, poi copia il pattern.
Salva l’etichetta. Da questo momento, ogni job che renderizza questa etichetta esegue lo script.

Un blocco minimale che normalizza un numero di serie:

# Field: serial
# Runs before rendering. Input: the value passed in the print job.
raw = str(value).strip()

if raw.isdigit():
    value = f"SN-{int(raw):06d}"
else:
    value = raw.upper()

E uno che appone l’ora di stampa invece di fidarsi dei dati:

# Field: printed_at
from datetime import datetime

value = datetime.now().strftime("%Y-%m-%d %H:%M")

Il valore di fare questo in una piattaforma gestita anziché nel proprio codice è che lo script fa parte dell’etichetta: è versionato con essa, riutilizzato tra i job e non può andare fuori sincronia con il modello.

Il riutilizzo è il vero guadagno. Una volta che uno script è corretto, collega lo stesso blocco a ogni campo che necessita della stessa trasformazione — tra etichette, tra stampanti. Dieci modelli di etichetta che stampano tutti i numeri di serie allo stesso modo sono dieci modelli che falliscono tutti allo stesso modo, e un unico punto in cui correggerli.

Costruire la pipeline automatizzata: dai dati alla stampa

Con lo script collegato, la pipeline è: autenticarsi, inviare un job di stampa, lasciare che l’etichetta faccia il lavoro.

Autenticarsi una volta sola

L’interfaccia del servizio web di LPSNG utilizza OAuth2 con un protocollo di registrazione semplificato che collega un sistema esterno tramite un singolo URL. Esegui la registrazione una volta, conserva il token nel tuo secret store e tienilo fuori dal repository:

export LPSNG_BASE_URL="https://lpsng.rsj.de"   # host of your edition
export LPSNG_TOKEN="<token from the OAuth2 registration>"

Inviare un job

L’API del servizio web accetta job di stampa, renderizza singole etichette come PDF o PNG e supporta la stampa diretta. I percorsi esatti degli endpoint e lo schema del payload provengono dalla documentazione dell’interfaccia del servizio web — lo snippet seguente mostra la forma della chiamata, non sostituisce il riferimento:

import os
import requests

BASE = os.environ["LPSNG_BASE_URL"]
TOKEN = os.environ["LPSNG_TOKEN"]

job = {
    # Payload keys are illustrative — use the schema from the
    # web service interface documentation.
    "label": "shipping-label",
    "printer": "warehouse-zebra-01",
    "data": {
        "order_id": "A-10442",
        "serial": "42",          # the field script turns this into SN-000042
        "printed_at": "",        # left empty on purpose
    },
}

resp = requests.post(
    f"{BASE}/<print-endpoint-from-the-docs>",
    headers={"Authorization": f"Bearer {TOKEN}"},
    json=job,
    timeout=30,
)
resp.raise_for_status()
print(resp.json())   # the response gives you the reference to poll

Nota ciò che il chiamante non fa: non formatta il numero di serie e non compila printed_at. Ora è compito dell’etichetta.

Il caso interessante: calcolare un valore

La trasformazione che si ripaga più rapidamente è una cifra di controllo, perché una cifra errata significa che uno scanner rifiuta l’etichetta alla stazione di imballaggio. Lo script la calcola dal valore passato dal job:

# Field: ean
# Compute the mod-10 check digit for a 12-digit payload.
digits = [int(c) for c in str(value) if c.isdigit()]

if len(digits) == 12:
    checksum = (10 - (sum(digits[::2]) + 3 * sum(digits[1::2])) % 10) % 10
    value = "".join(map(str, digits)) + str(checksum)
else:
    # Defensive: don't render an invalid barcode silently.
    value = "INVALID"

Poiché lo script modifica il valore del campo prima che il codice a barre venga renderizzato, il contenuto del codice a barre riflette il risultato calcolato. Non serve una fase separata di generazione del codice a barre.

Il modo difficile, per contrasto

L’alternativa è calcolare questi valori a monte: un preprocessore che legge i dati dell’ordine, riscrive ogni campo e solo allora chiama l’API. Funziona, finché il preprocessore e il modello dell’etichetta non sono in disaccordo — uno aggiunge zeri fino a sei cifre, l’altro fino a otto — e nessuno se ne accorge finché un pallet non viene spedito con numeri di serie illeggibili. Mantenere la logica all’interno del modello significa avere esattamente una definizione di “corretto” per campo.

Se devi eseguire la stessa logica dell’etichetta in un contesto senza browser, LPSNG Player è un motore di stampa da riga di comando standalone che riceve un pacchetto più i dati e produce PDF, PNG, JSON, una stampa diretta o un aggiornamento ESL. Stessa etichetta, stessi script, contesto di esecuzione diverso.

Monitoraggio e gestione degli errori nella stampa automatizzata

Una pipeline automatizzata che fallisce in silenzio è peggiore di una manuale, perché nessuno sta guardando l’etichetta.

Tieni d’occhio la coda. La UI web ha una coda dei job e l’API del servizio web consente di verificare lo stato dei job. Esegui il polling del riferimento ottenuto dall’invio, con backoff, e lancia un avviso quando un job resta nello stesso stato troppo a lungo:

import time

def wait_for_job(session, base, job_ref, timeout=120, interval=5):
    deadline = time.monotonic() + timeout
    while time.monotonic() < deadline:
        status = session.get(
            f"{base}/<job-status-endpoint-from-the-docs>/{job_ref}",
            timeout=15,
        ).json()
        if status.get("state") in ("done", "failed"):
            return status
        time.sleep(interval)
    raise TimeoutError(f"job {job_ref} did not finish in {timeout}s")

L’interfaccia pubblicata documenta l’invio dei job, il rendering di singole etichette, la stampa diretta e lo stato — non descrive webhook, quindi il polling è il pattern su cui basarsi. Se hai bisogno di notifiche push, consideralo una lacuna da risolvere dalla tua parte.

Fallisci in modo difensivo all’interno dello script. Decidi cosa deve fare un input errato prima che accada. Uno script che renderizza INVALID in un campo codice a barre ti fa un favore rispetto a uno che solleva un’eccezione e fa cadere l’intero job — o a uno che solleva un’eccezione, la fa inghiottire e stampa il valore non formattato. Consulta la documentazione dell’API degli script di campo per sapere come la piattaforma segnala un blocco in errore, e scrivi i tuoi script in modo che la modalità di errore sia quella che hai scelto.

Prova a secco con l’output renderizzato. L’API del servizio web può renderizzare una singola etichetta come PDF o PNG. Renderizza prima di stampare. È lo smoke test più economico che hai: fornisci allo script un input noto, guarda l’output e solo allora punta la pipeline verso la stampante.

Best practice per gli script Python sui campi

Una trasformazione per script. Un blocco che formatta una data e cerca il nome di un cliente e ricalcola un totale è un blocco che nessuno debuggerà alle 2 di notte.
Sii idempotente. Le ristampe accadono — un’etichetta inceppata, un cartone rifiutato, un operatore che preme stampa due volte. Se SN-000042 passa di nuovo attraverso lo script, deve uscire come SN-000042, non come SN-SN-000042. Verifica se il valore ha già la forma attesa prima di trasformarlo.
Versiona gli script fuori da LPSNG. Tieni le definizioni delle etichette e i loro blocchi di script in Git con una breve nota sul perché esiste ciascuno. La piattaforma li memorizza e li esegue; non sostituisce la code review.
Non codificare mai i dati in modo fisso. Nessun numero cliente fisso, nessuna data fissa, nessuna logica di diramazione specifica della stampante. Tutto dovrebbe provenire dal valore del campo o dai dati passati nel job di stampa.
Mantienilo leggero. Evita operazioni di lunga durata. Gli script di campo vengono eseguiti nel percorso di stampa, e uno script lento è un’etichetta lenta.
Testa con stranezze reali. Stringhe vuote, zeri iniziali, valori già formattati, valori troppo lunghi. È qui che gli script di campo si rompono.

FAQ

Gli script Python sui campi possono accedere ad API o database esterni?

L’API degli script di campo è progettata per accedere e modificare i valori dei campi nel contesto dell’etichetta. Per i dati esterni, in genere li passeresti nei dati del job di stampa. Consulta la documentazione LPSNG per eventuali limitazioni sulle chiamate esterne.

Quale versione di Python e quali librerie sono disponibili negli script di campo?

L’ambiente Python esatto è specificato nella documentazione dell’API degli script di campo di LPSNG. Si consiglia di usare le funzionalità della libreria standard e di mantenere gli script leggeri.

Come funzionano gli script di campo con i codici a barre?

Gli script possono modificare il valore del campo prima che il codice a barre venga renderizzato, consentendoti di calcolare cifre di controllo, formattare dati o applicare trasformazioni che influenzano il contenuto del codice a barre.

C’è un limite al tempo di esecuzione degli script?

Gli script di campo dovrebbero essere efficienti. Sebbene i limiti specifici non siano dettagliati nelle informazioni fornite, è buona pratica evitare operazioni di lunga durata. Fai riferimento alla documentazione LPSNG per eventuali vincoli.

Conclusione

Il pattern è semplice, ed è per questo che regge: collega la trasformazione al campo una volta, autenticati una volta, invia job per sempre. La modifica manuale scompare, e la definizione di un’etichetta corretta vive in un unico posto — il modello — invece che in chiunque si trovasse alla stampante quella mattina.

Inizia con un campo. Scegli quello che il tuo team modifica più spesso, scrivi dieci righe di Python, renderizza un PDF e confrontalo con un’etichetta di riferimento. Poi passa al successivo.

Next Generation Label Printing System è la piattaforma gestita che esegue questi script — il label studio, l’interfaccia del servizio web OAuth2, la coda dei job e il Player — senza un ambiente Python locale da mantenere. Puoi vedere il quadro completo su lpsng.rsj.de.

Post correlati

Automatizzare la stampa di etichette con gli script di campo Python