Automatizzare la stampa di etichette con codici a barre tramite l’API LPSNG

Se il tuo team esporta ancora i dati degli ordini, apre un modello di etichetta, incolla gli SKU e fa clic su Stampa una volta per pacco, il collo di bottiglia non è la stampante. È il passaggio manuale intermedio tra i dati e l’etichetta. L’API Web Service LPSNG elimina quel passaggio: invii i lavori di stampa in modo programmatico, generi singole etichette come PDF o PNG per l’anteprima e invii i lavori direttamente a stampanti termiche o standard.

Questa guida copre gli aspetti pratici: la configurazione una tantum di OAuth2, una pipeline automatizzata di base, la gestione degli errori e le pratiche che mantengono affidabile un sistema di automazione delle etichette man mano che il volume cresce.

Configurazione una tantum: collegare la tua applicazione a LPSNG

Prima di poter inviare una singola etichetta, devi collegare la tua applicazione a LPSNG. LPSNG utilizza un protocollo di registrazione OAuth2 semplificato per i sistemi esterni. Invece di una lunga procedura manuale di registrazione dell’app sviluppatore, la connessione viene configurata con un unico URL di registrazione.

Il flusso funziona così:

1. Avvia la registrazione OAuth2 tra la tua applicazione e LPSNG.
2. Approva la connessione.
3. Conserva le credenziali restituite nel tuo ambiente di integrazione.
4. Utilizza tali credenziali per richiedere i token bearer per le chiamate API.

Lo stesso modello di registrazione a URL singolo viene utilizzato per i sistemi esterni come le stazioni base ESL, quindi una volta che il tuo team lo ha configurato una volta, il pattern è replicabile in altre integrazioni.

Il punto in cui puntare l’API dipende dalla tua distribuzione. Sia l’edizione cloud multiutente ospitata sia l’edizione embedded espongono l’interfaccia del servizio web. Se hai bisogno di un percorso da riga di comando offline o ad alto volume, il LPSNG Player è un motore di stampa autonomo che accetta input di pacchi e dati e produce output PDF, PNG, JSON, stampa o ESL.

Per i non sviluppatori o i processi basati su fogli di calcolo, il componente aggiuntivo per Google Sheets e l’interfaccia Excel sono utili percorsi senza codice. Se stai automatizzando da un foglio di calcolo anziché dal codice, consulta Come stampare etichette da Google Sheets con LPSNG prima di creare un client API personalizzato.

Tieni le credenziali di integrazione fuori dal controllo del codice sorgente:

# .env — conserva nel tuo gestore di segreti o nell'archivio segreti CI/CD
LPSNG_BASE_URL=https://<your-lpsng-instance>
LPSNG_CLIENT_ID=<from-oauth2-registration>
LPSNG_CLIENT_SECRET=<from-oauth2-registration>

Costruire la pipeline automatizzata: dai dati all’etichetta stampata

Il ciclo principale è semplice: il tuo sistema di ordini, inventario o spedizioni contiene dei record. Impacchetti quei record in un payload di lavoro e lo invii all’API Web Service LPSNG. LPSNG genera le etichette utilizzando i modelli che hai progettato e il risultato è un lavoro di stampa su una stampante configurata oppure un file generato.

Questo ti offre tre pattern utili:

• Stampa diretta: invia il lavoro e lascia che LPSNG lo invii alla stampante di destinazione.
• Genera per approvazione: genera una singola etichetta come PDF o PNG per anteprima, allegato e-mail o archiviazione.
• Stampa e archivia: combina entrambi i percorsi in modo che l’etichetta fisica venga stampata e una prova PNG/PDF venga archiviata nel tuo sistema.

Un’integrazione Python minima può apparire così. I percorsi degli endpoint e i campi del payload sono intenzionalmente concettuali qui — utilizza la guida all’API Web Service per le forme esatte delle richieste.

import os
import requests

LPSNG_BASE_URL = os.environ["LPSNG_BASE_URL"]

def get_token():
    # Scambia le credenziali di registrazione OAuth2 con un token bearer.
    # Consulta la guida OAuth2 per i campi esatti di richiesta e risposta.
    ...

def render_label_preview(template_id: str, record: dict, output_format: str = "png"):
    token = get_token()
    response = requests.post(
        f"{LPSNG_BASE_URL}/<render-endpoint>",  # percorso esatto nella guida API Web Service
        headers={"Authorization": f"Bearer {token}"},
        json={
            "template_id": template_id,
            "data": record,
            "format": output_format,
        },
        timeout=30,
    )
    response.raise_for_status()
    return response.content

def submit_print_job(template_id: str, records: list[dict]):
    token = get_token()
    response = requests.post(
        f"{LPSNG_BASE_URL}/<jobs-endpoint>",
        headers={"Authorization": f"Bearer {token}"},
        json={
            "template_id": template_id,
            "records": records,
        },
        timeout=30,
    )
    response.raise_for_status()
    return response.json()

Il payload del lavoro deve contenere solo i dati variabili di cui il modello di etichetta ha bisogno. Mantieni il modello responsabile del layout, della formattazione del codice a barre e dei contenuti statici.

Per il contenuto dinamico delle etichette, LPSNG include un’API Python Field Script. Puoi allegare blocchi di script Python ai campi dell’etichetta in modo che possano accedere e modificare i valori dei campi prima della stampa. Questo è utile per la formattazione, la pulizia dei dati di input o l’applicazione di logica condizionale direttamente nell’etichetta invece di costruire tutta quella logica nella tua applicazione.

# Script di campo concettuale allegato a un campo codice a barre o testo.
if record.get("country_code") == "DE":
    value = value.strip().upper()

La stessa mentalità di automazione si estende oltre le etichette cartacee. Per le etichette elettroniche da scaffale, LPSNG fornisce un’interfaccia file JSON neutrale rispetto al fornitore chiamata ESLSEND e un’API ESL Binding. Se il tuo progetto include etichette di prezzo digitali, consulta Cosa sono le etichette elettroniche da scaffale e come funzionano? per il contesto più ampio.

Monitoraggio e gestione degli errori

Una pipeline di automazione affidabile non tratta un lavoro inviato come un lavoro stampato. Dopo aver inviato una richiesta di stampa, traccia il lavoro finché non raggiunge uno stato terminale.

L’interfaccia web LPSNG include una coda dei lavori, che offre agli operatori un punto di supervisione manuale. Tale coda è utile per individuare i lavori non riusciti, verificare perché un’etichetta non è stata stampata e ristampare senza inviare nuovamente i dati originali.

Nel tuo codice di integrazione, crea un piccolo polling dello stato:

import time

def wait_until_terminal(job_reference: str, timeout: int = 120):
    deadline = time.time() + timeout
    while time.time() < deadline:
        state = get_job_state(job_reference)  # dall'API o dalla coda dei lavori
        if state in ("printed", "completed", "failed"):
            return state
        time.sleep(2)
    raise TimeoutError(
        f"Il lavoro {job_reference} non ha raggiunto uno stato terminale in {timeout}s"
    )

Per i tentativi, sii prudente dopo i timeout di rete. Un timeout non ti dice se il lavoro è stato accettato. Prima di inviare nuovamente, interroga la coda dei lavori per il tuo tentativo precedente. Se puoi allegare un riferimento lavoro generato dal client, mantienilo stabile tra i tentativi in modo che un invio duplicato sia rilevabile.

In produzione, registra almeno questi campi:

• riferimento del lavoro o ID restituito dall’API
• ID del modello
• identificatori del record, come numero d’ordine o SKU
• stampante o percorso di output
• stato HTTP e corpo dell’errore

Quindi genera avvisi sui lavori non riusciti anziché solo sugli errori a livello di servizio. Un’etichetta che fallisce silenziosamente è peggiore di un servizio che segnala un’eccezione.

Best practice per l’automazione delle etichette

• Progetta i modelli attorno a segnaposto di dati variabili. Più mantieni layout, tipo di codice a barre e branding statico nel modello, meno codice applicativo dovrai modificare in seguito.
• Utilizza l’API Python Field Script per le trasformazioni a livello di etichetta. La formattazione di un codice a barre, la rifilatura dell’input o la modifica condizionale del testo appartengono allo script dell’etichetta quando sono specifiche dell’etichetta.
• Utilizza l’interfaccia Excel per tabelle di ricerca e validazione dei dati. Se la tua applicazione dipende già da fogli di calcolo per dati di prodotto, mappatura o validazione, LPSNG può utilizzare file Excel come file di dati e file di ricerca.
• Considera l’edizione Embedded per ambienti on-premise o a bassa latenza. Fornisce LPSNG completo su un computer a scheda singola come un Raspberry Pi, utile quando le etichette devono essere stampate anche se la connettività cloud viene interrotta.
• Valuta la soluzione White Label per build OEM o rivenditori. Se la stampa di etichette è incorporata in un prodotto più ampio, l’edizione white label è progettata per produttori di stampanti, produttori di carta e integratori di sistema.

All’interno dello studio etichette del Next Generation Label Printing System, i modelli riutilizzabili sono la chiave per la manutenibilità a lungo termine. Una buona regola pratica: se due etichette differiscono solo nei dati, dovrebbero essere un unico modello.

FAQ

Quale metodo di autenticazione utilizza l’API LPSNG?

LPSNG utilizza OAuth2 con un protocollo di registrazione semplificato. Registri la tua applicazione tramite un unico URL e ricevi le credenziali per autenticare le chiamate API.

Posso generare anteprime delle etichette senza stampare?

Sì, l’API Web Service può generare singole etichette come file PDF o PNG. Tali file possono essere utilizzati per anteprime, allegati e-mail o archiviazione.

L’API supporta tutti i formati di codici a barre?

LPSNG supporta un’ampia gamma di formati di codici a barre 1D e 2D. Consulta la documentazione sui formati di codici a barre per l’elenco completo.

Esiste un’opzione offline o on-premise per l’automazione?

Sì, LPSNG Player è un motore di stampa a riga di comando autonomo che può essere eseguito localmente, e l’edizione Embedded fornisce un’installazione LPSNG completa su un computer a scheda singola come un Raspberry Pi.

Conclusione: inizia ad automatizzare oggi

La stampa di etichette guidata da API elimina la copia, l’incolla e i clic manuali che causano evasione lenta e spedizioni etichettate in modo errato. Con l’API Web Service LPSNG, gli stessi dati che alimentano il tuo sistema di ordini o inventario possono produrre etichette stampate, anteprime PDF e aggiornamenti delle etichette elettroniche da scaffale senza una persona in mezzo.

Inizia in piccolo: scegli un tipo di etichetta, collega un’applicazione ed eseguila in parallelo con il processo esistente finché non ti fidi dell’output. Il Next Generation Label Printing System gestito ti offre l’edizione cloud e il player autonomo per valutare il flusso di lavoro senza costruire prima un’intera sala stampa.

Per i dettagli di implementazione, inizia con la documentazione dell’API Web Service e la guida OAuth2.

Post correlati

• Cosa sono le etichette elettroniche da scaffale e come funzionano?
• Come stampare etichette da Google Sheets con LPSNG
• Prezzi LPSNG: quale edizione fa per te?