Como Imprimir Etiquetas a Partir de uma API de Serviço Web: Um Guia para Desenvolvedores
Sua aplicação já sabe o que a etiqueta deve conter — o número do pedido, o SKU, o valor do código de barras, a lista de embalagem. A parte chata nunca foram os dados. É a saída: drivers, linguagens de impressora, spoolers e uma impressora de armazém que insiste em renderizar sua fonte dois pontos maior.
Este guia ignora toda essa pilha. Você vai aprender como imprimir etiquetas a partir de uma API de serviço web: registre seu sistema externo uma vez, projete a etiqueta uma vez no navegador e então envie trabalhos de impressão — ou obtenha PDFs e PNGs renderizados — a partir do seu próprio código. Sem driver de impressora, sem SDK, sem comandos brutos de impressora.
O Que Você Vai Construir: Imprimindo Etiquetas a Partir de uma API de Serviço Web
Há dois resultados que você normalmente vai querer, e a boa notícia é que eles compartilham o mesmo formato de requisição:
- Enviar um trabalho de impressão. Sua aplicação envia uma referência de etiqueta mais um payload de dados. O trabalho entra em uma fila e é despachado para a impressora configurada.
- Renderizar uma única etiqueta. A mesma etiqueta e os mesmos dados retornam como PDF ou PNG — para pré-visualizações na sua interface, anexos de e-mail, aprovações ou um arquivo de auditoria.
O Next Generation Label Printing System (LPSNG) expõe exatamente isso como uma API de serviço web gerenciada. Você chama um endpoint; o serviço é dono da pilha de impressão. A mesma superfície de API também cobre impressão direta (direto para um dispositivo, ignorando a fila) e atualizações de etiquetas eletrônicas de prateleira, então a integração que você constrói hoje continua funcionando quando seus requisitos crescerem.
Aqui está o caminho que vamos seguir:
- Registrar o sistema externo com OAuth2.
- Projetar a etiqueta uma vez no label studio.
- Enviar um trabalho de impressão a partir da sua aplicação.
- Renderizar uma única etiqueta como PDF ou PNG.
- Verificar se o trabalho realmente chegou ao papel.
Os caminhos exatos dos endpoints e nomes de parâmetros estão na documentação do Web Service Interface e do External Application Integration — este artigo dá o formato e a ordem das operações, e a documentação dá os detalhes no nível do byte.
Pré-requisitos Antes de Chamar a API
Antes da primeira requisição, prepare o seguinte:
- Uma conta ou edição do LPSNG que inclua a interface de serviço web. A Cloud Solution, a Embedded Edition em um computador de placa única e os Enterprise Features multiusuário todos carregam a mesma funcionalidade central descrita em Use Cases — interface web, label studio, fila de trabalhos, geração de PDF e a interface de serviço web.
- Um layout de etiqueta que já existe no label studio, com campos mapeados para os dados que você pretende enviar. A API referencia o layout por identificador; ela não constrói layouts em tempo real.
- Credenciais OAuth2 do fluxo de registro usado para conectar sistemas externos.
- Qualquer cliente HTTP compatível com HTTPS. Python, Node, Go, curl — o protocolo não se importa.
- Opcional: uma impressora de teste, ou o LPSNG Player se você quiser um caminho de renderização local antes de conectar um dispositivo.
Passo 1: Registre Seu Sistema Externo com OAuth2
O LPSNG usa um protocolo de registro OAuth2 simplificado que conecta sistemas externos com uma única URL. Esta é a parte que a maioria das integrações erra quando faz por conta própria: implementar manualmente a renovação de token e a autenticação de dispositivo contra um protocolo bruto de impressão são semanas de trabalho que não têm nada a ver com etiquetas.
O fluxo gerenciado é um único passo:
# 1. Open the registration URL that LPSNG generates for your external system.
# You complete the consent step once, in a browser.
open "$REGISTRATION_URL"
# 2. Store the credentials LPSNG hands back for that registered system.
export LPSNG_CLIENT_ID="<client-id>"
export LPSNG_CLIENT_SECRET="<client-secret>"
# 3. Exchange them for a token your API calls will use.
# Exact parameter names: see https://lpsng.rsj.de/en/oauth2.md
Duas coisas que vale a pena notar:
- O consentimento é um passo único. Após o registro, sua aplicação usa as credenciais resultantes em cada chamada de API subsequente — você não está enviando um humano por um fluxo de navegador a cada trabalho de impressão.
- É o mesmo modelo usado para estações base de ESL. Se você conectar etiquetas de prateleira depois, vai reconhecer o padrão imediatamente. Os detalhes estão na documentação do ESL e do ESL Interface.
Armazene o token como você armazenaria qualquer outro segredo: variável de ambiente ou gerenciador de segredos, nunca no repositório.
Passo 2: Projete a Etiqueta Uma Vez no Label Studio
Abra a interface web e construa o layout como você construiria um documento: blocos de texto, imagens, códigos de barras e placeholders de campos onde os dados da API vão chegar.
Algumas decisões que compensam depois:
- Use simbologias de código de barras suportadas. O LPSNG renderiza formatos 1D e 2D nativamente — a página Barcode Formats lista o que está disponível. Se você escolher um formato suportado, a API o renderiza sem nenhum trabalho extra do seu lado.
- Anexe blocos de script Python a campos quando precisar de lógica. A Field Script API permite que um bloco de script acesse e modifique o valor de um campo antes da impressão — útil para formatar datas, truncar nomes longos de fornecedores ou derivar um dígito verificador.
# Example: a script block attached to a field, formatting a raw value
# before it reaches the printer. See https://lpsng.rsj.de/api.html
value = str(value).strip().upper()
if len(value) > 30:
value = value[:27] + "..."
- Salve o layout e anote seu identificador. Esse identificador é o que sua chamada de API referencia — trate-o como um valor de configuração, não como uma string mágica enterrada no código.
- Mantenha o layout separado dos dados. O layout define como uma etiqueta se parece; a requisição define o que ela diz. Essa separação é o que permite que um layout sirva milhares de trabalhos.
Passo 3: Envie um Trabalho de Impressão a Partir da Sua Aplicação
Agora a chamada em si. O formato é sempre o mesmo: autenticar, referenciar a etiqueta, passar o payload de dados para os campos.
import os
import requests
BASE = os.environ["LPSNG_BASE_URL"] # your LPSNG instance
TOKEN = os.environ["LPSNG_ACCESS_TOKEN"] # from the OAuth2 registration
job = {
"label": "shipping-label-4x6", # identifier from the label studio
"printer": "warehouse-01", # a printer configured in LPSNG
"data": {
"order_no": "SO-10432",
"customer": "Nordwind Handel GmbH",
"sku": "HND-2200-BLK",
"qty": "12",
"barcode": "SO-10432-HND-2200-BLK",
},
}
resp = requests.post(
f"{BASE}/<print-job-endpoint>", # exact path: see the Web Service Interface docs
json=job,
headers={"Authorization": f"Bearer {TOKEN}"},
timeout=30,
)
resp.raise_for_status()
print(resp.json()) # job identifier + status
No lado do servidor, o trabalho entra na fila e é despachado para a impressora configurada. Sua aplicação não mantém uma conexão aberta com um dispositivo, e não precisa saber se aquela impressora fala ZPL, EPL ou outra coisa.
Variantes que vale a pena conhecer:
- Impressão direta. Quando você quer que a etiqueta vá direto para um dispositivo em vez de esperar sua vez na fila, a interface expõe um caminho de impressão direta.
- Lote. Cada chamada é uma referência de etiqueta mais dados, então iterar sobre linhas de pedido é apenas um loop no seu código — um trabalho por linha, na ordem que sua estação de embalagem precisa.
Para endpoints exatos, nomes de parâmetros e campos de resposta, use as referências do Web Service Interface e do External Application Integration.
Passo 4: Renderize uma Única Etiqueta como PDF ou PNG
Renderizar supera imprimir quando um humano precisa olhar a etiqueta primeiro, ou quando você precisa de um registro de que ela existiu:
- Pré-visualizações dentro da sua própria interface antes que alguém confirme uma execução.
- Anexos de e-mail para fornecedores ou clientes.
- Etapas de aprovação onde um revisor aprova a arte.
- Arquivos de auditoria que sobrevivem independentemente de uma impressora.
A chamada se parece com o trabalho de impressão, exceto que retorna bytes em vez de enfileirar trabalho:
# PDF for archiving or attaching
curl -sS -X POST "$LPSNG_BASE_URL/<render-endpoint>" \
-H "Authorization: Bearer $LPSNG_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"label":"shipping-label-4x6","format":"pdf",
"data":{"order_no":"SO-10432","sku":"HND-2200-BLK"}}' \
-o label-SO-10432.pdf
# PNG for a preview thumbnail — same layout, same data, same output geometry
curl -sS -X POST "$LPSNG_BASE_URL/<render-endpoint>" \
-H "Authorization: Bearer $LPSNG_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"label":"shipping-label-4x6","format":"png",
"data":{"order_no":"SO-10432","sku":"HND-2200-BLK"}}' \
-o label-SO-10432.png
Como ambos os caminhos usam o mesmo layout e os mesmos dados, o que você pré-visualiza é o que você imprime. Esse é o ponto central de fazer isso em um único sistema em vez de costurar uma biblioteca de PDF a um driver de impressora.
Duas notas práticas:
- Renderização offline ou embarcada. O LPSNG Player é um motor de impressão de linha de comando autônomo que recebe um pacote e dados e produz PDF, PNG, JSON, saída de impressão ou uma atualização de ESL. É a ferramenta certa quando você precisa de saída sem uma ida e volta ao servidor.
- Faça cache agressivamente. Etiquetas repetidas — a mesma etiqueta de prateleira, o mesmo ID de palete — não precisam de uma nova renderização toda vez. Armazene o PDF com chave baseada em layout + hash dos dados e pule a chamada de API.
Passo 5: Verifique se o Trabalho de Impressão Funcionou
Um HTTP 200 significa que o trabalho foi aceito. Não significa que uma etiqueta saiu de uma impressora. Verifique nesta ordem:
- Confira a fila de trabalhos na interface web. Confirme que o trabalho foi aceito e concluído, e que foi para a impressora que você esperava.
- Compare a renderização com a realidade. Coloque o PDF ou PNG ao lado da etiqueta física. É aqui que problemas de escala e de zona de silêncio de código de barras aparecem, e são muito mais baratos de detectar agora do que no site de um cliente.
- Escaneie o código de barras. Um leitor é o único teste honesto de se os dados fazem o ciclo completo — verifique se o valor escaneado corresponde ao que sua aplicação enviou, caractere por caractere.
- Registre a resposta e o identificador do trabalho. Armazene ambos junto ao seu registro interno de pedido ou remessa. Quando alguém perguntar “isso foi enviado com uma etiqueta?”, você quer uma resposta de um banco de dados, não um palpite.
- Se você usa ESL, confira o display também. Um display de prateleira atualizado é um segundo sinal independente de que os mesmos dados chegaram ao serviço. O ESL Interface e a ESL Binding API cobrem esse lado.
Solução de Problemas Comuns
Falhas de autenticação. Se as chamadas começarem a retornar erros de autenticação, o token provavelmente foi revogado ou o registro do sistema externo mudou. Execute novamente o registro OAuth2 — é um fluxo de um único passo por design, então a recuperação é barata. Veja a página OAuth2.
Campos em branco ou ausentes na etiqueta. Quase sempre é uma incompatibilidade de chave: as chaves no seu payload data devem corresponder exatamente aos nomes dos campos no layout, incluindo maiúsculas e minúsculas. Renderize a etiqueta como PNG e inspecione-a antes de culpar a impressora.
Saída de código de barras errada. Verifique duas coisas: se o formato que você escolheu está na lista de Barcode Formats suportados, e se o tipo de dado corresponde ao que a simbologia espera. Formatos apenas numéricos vão renderizar lixo alegremente a partir de uma string com letras.
Impressora não recebendo trabalhos. O trabalho só pode ser despachado para uma impressora que está configurada e online no LPSNG. Se a fila mostra o trabalho parado lá, o alvo é o problema, não sua requisição.
A renderização parece diferente da impressão. Compare DPI e tamanho da etiqueta entre o layout e a mídia física. Um layout projetado para um tamanho e enviado para um estoque de tamanho diferente vai escalar de formas que quebram a legibilidade do código de barras.
FAQ
Preciso de um driver de impressora ou SDK no meu servidor para imprimir etiquetas a partir da API de serviço web?
Não. O Next Generation Label Printing System cuida da pilha de impressão para você: você envia um trabalho ou solicita uma renderização através da API de serviço web, e o serviço gerenciado cuida do resto. O LPSNG Player está disponível se você precisar de um motor de linha de comando autônomo para saída local.
Qual é a diferença entre enviar um trabalho de impressão e renderizar uma única etiqueta?
Enviar um trabalho de impressão envia a etiqueta para a impressora configurada através da fila de trabalhos. Renderizar retorna a etiqueta como PDF ou PNG para que você possa pré-visualizar, arquivar ou anexar sem imprimir. Ambos usam o mesmo layout e os mesmos dados, então a saída é consistente.
Como funciona o registro OAuth2 para sistemas externos?
O LPSNG usa um protocolo de registro OAuth2 simplificado que conecta sistemas externos com uma única URL. Você completa o passo de consentimento uma vez, e as credenciais resultantes são usadas para chamadas de API subsequentes. O mesmo modelo é usado para estações base de ESL, então o padrão é consistente entre integrações.
A mesma API também pode atualizar etiquetas eletrônicas de prateleira?
Sim. O LPSNG inclui uma interface JSON neutra em relação a fornecedor (ESLSEND) e uma API de binding para tags ESL, então você pode gerenciar tanto etiquetas impressas quanto etiquetas eletrônicas de prateleira a partir da mesma integração. Para um olhar mais aprofundado, veja nossos artigos complementares sobre a ESL Binding API e APIs de integração de etiquetas eletrônicas de prateleira.
Conclusão
O padrão é curto o suficiente para caber na sua cabeça: registre uma vez com OAuth2, projete a etiqueta uma vez no label studio e então envie um trabalho ou obtenha uma renderização a partir da sua aplicação. Tudo que costumava ser um problema específico de impressora — drivers, linguagens de comando, escala de fontes, bibliotecas de código de barras — é tratado por trás de uma única superfície de API que cobre trabalhos de impressão, impressão direta, renderização de PDF e PNG e atualizações de ESL.
O Next Generation Label Printing System é o serviço gerenciado que faz disso a integração inteira em vez de apenas uma parte dela. Comece com a documentação do Web Service Interface para os endpoints exatos, projete seu primeiro layout no label studio e envie um trabalho de teste para uma única impressora antes de automatizar o resto. Se você ainda está avaliando suas opções, nossa comparação com alternativas ao Zebra Designer é uma próxima leitura razoável.
Posts relacionados
- Alternativa ao Zebra Designer: Software de Impressão de Etiquetas para Comparar
- ESL Binding API: Documentação e Exemplos
- Entendendo as APIs de Integração de Etiquetas Eletrônicas de Prateleira
