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

Geração de Etiquetas de Código de Barras em Python: Um Guia Passo a Passo

Se você já tentou gerar uma etiqueta de código de barras a partir de um script Python, conhece o caminho habitual: escolher uma biblioteca de código de barras, renderizar uma imagem, construir o layout da etiqueta por conta própria e depois descobrir como se comunicar com uma impressora térmica. Este guia adota uma abordagem diferente e gerenciada. Você usará o Next Generation Label Printing System (LPSNG) como mecanismo de renderização e impressão, e o acionará a partir do Python com requisições HTTP simples.

Ao final, você terá um script Python que:

Autentica-se na API do serviço web LPSNG
Consulta um layout de etiqueta
Envia dados dinâmicos de itens, incluindo o conteúdo do código de barras
Aplica personalizações de campos baseadas em Python
Renderiza a etiqueta como PDF ou PNG
Envia-a para uma impressora ou salva-a localmente

Isso é ideal para desenvolvedores que precisam de geração de etiquetas orientada a dados em fluxos de trabalho de armazém, logística, varejo ou fulfillment — sem construir e manter um pipeline personalizado de renderização de etiquetas.

Pré-requisitos

Antes de começar, certifique-se de ter:

Python 3.x instalado na sua máquina.
Uma conta LPSNG — seja a edição em nuvem ou uma edição embarcada — com acesso à API do serviço web.
Um layout de etiqueta criado no estúdio de etiquetas LPSNG, ou um layout de exemplo que você possa usar para testes. O layout deve conter pelo menos um campo de código de barras.
Credenciais de cliente OAuth2 para autenticação na API. Consulte o guia OAuth2 para o fluxo de registro simplificado.
Familiaridade básica com Python e APIs REST. O serviço web LPSNG é RESTful e retorna JSON, portanto, conhecimento padrão de HTTP é suficiente.

Você não precisa instalar fontes de código de barras, drivers ZPL/EPL ou SDKs específicos de impressora. O LPSNG cuida desses detalhes por trás do seu serviço web.

Passo a Passo: Gerando Etiquetas de Código de Barras com Python

O fluxo de trabalho é direto: autenticar, identificar o layout, preparar os dados, opcionalmente personalizar campos com um bloco de script Python, renderizar a etiqueta e imprimir ou salvar.

Passo 1: Configure seu ambiente Python

Crie um diretório de projeto e instale a biblioteca requests. A API do LPSNG é RESTful, então você só precisa de um cliente HTTP padrão.

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

Crie um arquivo chamado generate_label.py. No topo, defina a URL base do LPSNG e as credenciais. Substitua os valores de exemplo pelos detalhes reais da sua instância.

import requests
import json
from pathlib import Path

# Substitua pela URL da sua instância LPSNG, ex.: https://sua-instancia.lpsng.rsj.de
LPSNG_BASE_URL = "https://sua-instancia.lpsng.rsj.de"

# Substitua pelas credenciais do seu registro OAuth2
CLIENT_ID = "seu-client-id"
CLIENT_SECRET = "seu-client-secret"

Passo 2: Obtenha um token de acesso OAuth2

O LPSNG usa um protocolo de registro OAuth2 simplificado. Depois que sua aplicação externa estiver registrada, você troca suas credenciais de cliente por um token de acesso.

O exemplo abaixo mantém o endpoint de token como uma variável, para que você possa apontá-lo para a URL exata da documentação da API do Serviço Web da sua instância.

def get_access_token():
    # Use o endpoint de token listado no guia OAuth2 do 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"]

Em código de produção, armazene o token em cache e atualize-o antes que expire. Para este passo a passo, você pode solicitar um novo token a cada execução.

Passo 3: Recupere o ID do seu layout de etiqueta

Cada layout de etiqueta no LPSNG tem um ID. Você pode copiá-lo da interface web do LPSNG abrindo as propriedades do layout, ou pode consultá-lo por meio da API.

O caminho pela interface web é o mais simples para um primeiro teste. Abra seu layout de etiqueta no estúdio de etiquetas e copie o ID do layout da URL ou das configurações do layout.

Se quiser automatizar a consulta de layout a partir do Python, use o mesmo padrão REST. O endpoint exato pode variar conforme a instância, então preencha-o a partir da sua referência de API:

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

    # Substitua /layouts pelo endpoint de listagem documentado para sua instância.
    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 não encontrado: {layout_name}")

Para um script rápido, um ID de layout fixo no código é suficiente:

LAYOUT_ID = "seu-id-de-layout"

Passo 4: Prepare o payload de dados com o conteúdo do código de barras

A API do serviço web envia trabalhos de impressão e renderiza etiquetas individuais. Seu payload normalmente contém um conjunto de valores de campo para o layout, incluindo o valor que deve ser codificado no código de barras.

Aqui está um exemplo de payload para uma etiqueta de item com um código de barras Code 128:

label_data = {
    "product_name": "Rolo de Etiqueta Térmica 100x150",
    "sku": "THR-100-150",
    "barcode": "4012345678901",
    "quantity": 12,
    "batch": "B20260831-04",
}

Os nomes dos campos no seu payload devem corresponder aos nomes dos campos que você definiu no estúdio de etiquetas LPSNG. Se o seu layout tiver um campo de código de barras chamado barcode, o LPSNG codifica o valor que você enviar para esse campo no formato de código de barras configurado no layout.

Passo 5: Personalize campos com a API de Script de Campo Python

O LPSNG inclui uma API de Script de Campo Python que permite anexar pequenos blocos de script Python a campos de etiqueta. Esses scripts são executados antes da impressão e podem acessar ou modificar valores de campo.

Por exemplo, suponha que os dados do seu armazém às vezes contenham códigos de barras em letras minúsculas ou espaços no final, e você queira normalizar o valor antes que ele chegue ao código de barras. No estúdio de etiquetas LPSNG, anexe um bloco de script ao campo de código de barras que se pareça com isto:

# Anexado ao campo de código de barras no LPSNG Label Studio.
# O script é executado antes da impressão e pode acessar o valor atual.
if "barcode" in context:
    value = str(context["barcode"]).strip().upper()

O ponto de entrada exato e os objetos disponíveis estão documentados na referência da API Python. Use essa referência para verificar a assinatura exata do hook para sua versão do LPSNG. A ideia principal é que os scripts Python em nível de campo mantêm a lógica de formatação próxima à etiqueta, enquanto sua aplicação Python externa permanece focada na preparação de dados e nas chamadas de API.

Passo 6: Chame o endpoint do serviço web para renderizar a etiqueta

Agora chame o LPSNG para renderizar a etiqueta como PDF ou PNG. A API do serviço web pode renderizar etiquetas individuais, então você não precisa executar um renderizador local.

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

    # Use o endpoint de renderização da documentação da API do Serviço 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

Para saída em PNG, passe "png" como formato. A resposta da API contém o conteúdo binário do arquivo, que você pode salvar diretamente.

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

Path("label.pdf").write_bytes(pdf_bytes)
print("Etiqueta renderizada: label.pdf")

Passo 7: Envie a etiqueta gerada para uma impressora ou salve-a localmente

Se sua instância LPSNG estiver conectada a impressoras, você pode enviar um trabalho de impressão pela mesma API do serviço web em vez de baixar o arquivo. O formato exato da requisição está documentado na Interface do Serviço Web.

Uma chamada típica de impressão direta segue o mesmo padrão REST:

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

    # Use o endpoint de impressão documentado para sua instância 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()

Substitua "printer" pelo nome ou ID da impressora configurada no seu ambiente LPSNG. Se preferir manter o arquivo localmente, pule esta etapa e use a saída em PDF ou PNG do Passo 6.

Verificando a Saída da Sua Etiqueta

Não presuma que o código de barras está correto só porque o PDF ou PNG abriu sem erros. Execute estas verificações:

Abra o arquivo gerado visualmente. Confirme que os campos de texto estão preenchidos, que o código de barras está visível e que o layout corresponde ao design do seu estúdio de etiquetas.
Escaneie o código de barras com um aplicativo de scanner. Aponte um leitor de código de barras baseado em celular para a etiqueta impressa ou exibida na tela. Verifique se os dados codificados correspondem ao valor que você enviou no payload.
Verifique as personalizações de campo. Se você adicionou um script de campo Python que converte para maiúsculas ou remove espaços do valor do código de barras, envie dados de teste em minúsculas ou com espaços e confirme se a saída mudou conforme o esperado.
Teste com vários conjuntos de dados. Execute o script com SKUs, quantidades e valores de código de barras diferentes para garantir que nenhum campo esteja fixo no código ou desalinhado.

Se a saída for um PDF, imprima-o uma vez na impressora térmica de destino para confirmar as dimensões da etiqueta e a densidade de impressão.

Solução de Problemas Comuns

Erros de autenticação

Verifique novamente suas credenciais de cliente OAuth2 e o endpoint de token. Se o token expirou, solicite um novo. Confirme se o cliente ainda está registrado na sua conta LPSNG e se a conta tem acesso à API.

Layout de etiqueta não encontrado

Verifique o ID do layout e as permissões de usuário associadas ao seu cliente OAuth2. O cliente pode ter acesso à API, mas não ao layout específico. Verifique o nome do layout exatamente, incluindo maiúsculas/minúsculas e espaços em branco.

Código de barras não renderiza

Certifique-se de que o formato do código de barras é suportado pelo LPSNG e que o valor no campo de código de barras é válido para esse formato. Por exemplo, um campo Code 128 deve receber dados válidos para Code 128. Consulte a documentação de Formatos de Código de Barras para a lista completa de formatos 1D e 2D suportados.

Verifique também se o campo de código de barras no seu layout está realmente mapeado para a chave do payload que você está enviando. Uma incompatibilidade entre nomes de campos é uma causa comum de códigos de barras vazios.

Erros de script de campo

Se o seu script de campo Python gerar um erro, a resposta da API geralmente contém uma mensagem de erro. Leia-a com atenção; ela frequentemente aponta para o número da linha ou o tipo de exceção no bloco de script. Use a referência da API Python para confirmar quais objetos estão disponíveis no contexto do script.

Problemas de impressão

Se a etiqueta renderizar, mas não imprimir, confirme a conectividade da impressora e a configuração do driver no seu ambiente LPSNG. Verifique se o nome da impressora na sua chamada de impressão corresponde ao nome configurado no LPSNG e se a impressora está online.

FAQ

Posso gerar etiquetas de código de barras em Python sem usar o serviço web LPSNG?

Sim, você poderia usar bibliotecas puras como python-barcode ou reportlab, mas precisaria lidar com o design da etiqueta, a comunicação com a impressora e os padrões de código de barras por conta própria. O LPSNG fornece um serviço gerenciado com uma API Python que simplifica todo o processo, incluindo personalização de campos e impressão direta.

Quais formatos de código de barras são suportados pelo LPSNG?

O LPSNG suporta uma ampla variedade de formatos de código de barras 1D e 2D. Consulte a documentação de Formatos de Código de Barras para a lista completa, incluindo Code 128, QR Code, Data Matrix e mais.

Preciso instalar pacotes Python especiais para usar a API do LPSNG?

Apenas bibliotecas de cliente HTTP padrão como requests são necessárias. A API é RESTful e retorna respostas JSON, o que facilita a integração com qualquer ambiente Python.

Posso usar a API Python para atualizar etiquetas eletrônicas de prateleira (ESL) também?

Sim, o LPSNG oferece uma interface ESL e API de vinculação que pode ser acessada via Python. Consulte a documentação ESL para detalhes sobre como atualizar displays ESL programaticamente.

Conclusão

A geração de etiquetas de código de barras em Python se torna muito mais simples quando você deixa um serviço gerenciado cuidar da renderização, dos padrões de código de barras e dos detalhes de impressão. Com o LPSNG, sua aplicação Python só precisa autenticar, enviar dados de campo e chamar um endpoint REST. O design da etiqueta permanece no estúdio de etiquetas, enquanto os scripts de campo Python lidam com a formatação em nível de campo.

Essa abordagem se encaixa perfeitamente em fluxos de trabalho de automação maiores. Se você está avaliando software de etiquetas como desenvolvedor, consulte Melhor Software de Design de Etiquetas para Desenvolvedores: Por que o LPSNG se Destaca. Se o seu projeto de etiquetagem se estende a etiquetas eletrônicas de prateleira, continue com Integração ESL para Varejo: Um Guia Completo. E se a maior parte dos seus dados de origem vive em planilhas, não perca Automatize a Impressão de Etiquetas a partir do Excel: Economize Tempo e Reduza Erros.

Pronto para criar sua primeira etiqueta de código de barras gerada em Python? Pegue suas credenciais OAuth2, escolha um layout e execute o script com um item real. O Next Generation Label Printing System cuida do trabalho pesado — você escreve a integração.

Posts relacionados