Formate, valide e transforme dados de etiquetas com Python antes da impressão

Uma etiqueta de preço que imprime 35.00 em vez de 3.50 não é um problema de design. É um problema de dados — e é o tipo de problema que sobrevive a toda revisão visual porque a etiqueta parece correta.

Este artigo trata da camada que a maioria dos fluxos de trabalho de etiquetas ignora: o que acontece com o valor de um campo entre “a planilha tem um valor” e “a impressora o coloca no papel”.

A freelancer que quase enviou uma etiqueta de preço errada

Imagine uma desenvolvedora solo — chamemo-la de Mara — que assume um pequeno cliente do varejo: uma loja, quarenta SKUs, uma planilha que a própria dona mantém. Mara cria um modelo de etiqueta, conecta a planilha como fonte de dados, imprime uma folha de teste, e a primeira etiqueta mostra um pacote de café de 250 g a 35.00.

A planilha dizia 3,50. Vírgula decimal. O design da etiqueta esperava um ponto, e ninguém percebeu até a prova voltar da dona da loja.

O resto da coluna não é melhor:

• Preços como 3.5, 3,50, € 3.50, e algumas células vazias.
• SKUs que o Excel silenciosamente transformou em números, comendo os zeros à esquerda que um código de barras precisa.
• Datas de validade em três formatos ao longo de quarenta linhas.
• Códigos de fornecedor com um prefixo SUP- que a dona quer remover para uma etiqueta mais limpa.

O primeiro instinto de Mara é o padrão: escrever um script de exportação que limpa o CSV e então alimentar a ferramenta de impressão com o arquivo limpo. Isso funciona — até a dona da loja editar a planilha na semana seguinte, e o script de exportação ficar no laptop de Mara, sem documentação, e ninguém lembrar de executá-lo.

Então a verdadeira pergunta é esta: como você limpa e molda os valores dos campos antes que cheguem à impressora, sem criar e manter um segundo pipeline de dados?

A resposta no RSJ LPSNG é a Python Field Script API: blocos de script que são anexados a campos individuais da etiqueta e que acessam e modificam os valores dos campos antes da impressão. O script viaja com a etiqueta em vez de viver ao lado dela.

Para deixar o escopo claro: não se trata de projetar a etiqueta. Se você quer o lado do layout — posicionar texto, códigos de barras e imagens no editor do navegador — isso está coberto em How to Design Barcode Labels in a Browser Layout Editor. Este artigo trata dos valores que fluem para dentro desse layout.

Por que o controle de dados no nível do campo importa para desenvolvedores e usuários finais

A maioria dos defeitos de etiquetas são defeitos de dados vestidos de design. Decimais errados, datas não formatadas, zeros à esquerda ausentes em códigos de barras, um nome de produto truncado que não cabe mais — o layout está fazendo exatamente o que lhe foi dito. A entrada estava errada.

O controle no nível do campo importa para dois públicos muito diferentes, pelo mesmo motivo subjacente.

Para desenvolvedores, ele elimina toda uma classe de infraestrutura paralela. Você não escreve nem mantém um script externo de pré-processamento, um job agendado que reescreve arquivos CSV, ou código de cola entre a fonte de dados e o motor de impressão. Formatação e validação vivem na definição da etiqueta, que é o artefato que realmente precisa delas.

Para usuários finais e pequenas equipes, ele produz saída consistente sem exigir que ninguém entenda os dados de origem. A dona da loja continua preenchendo sua planilha como sempre fez. A etiqueta decide como um preço é exibido.

A Python Field Script API é a camada intermediária entre esses dois mundos:

• Ela roda no campo, não no arquivo.
• Ela pode ler e modificar o valor antes da impressão.
• Ela vive dentro da mesma plataforma que renderiza a etiqueta, então não há divergência de versão entre “o limpador” e “o modelo”.

A referência da API está em lpsng.rsj.de/api.html.

Um guia prático: formatar, validar e transformar em três passagens

Trate cada script de campo como três passagens sobre o valor, nesta ordem: formate-o, comprove-o, depois derive a partir dele. Os trechos abaixo são Python ilustrativo — a parte importante é a forma da lógica, não os nomes exatos dos helpers.

Passagem 1: Formatar

Normalize o valor bruto para exatamente o que o design da etiqueta espera. Preços para um padrão decimal fixo, datas para um formato de exibição, texto para a caixa em torno da qual o layout foi projetado.

import re

CURRENCY = re.compile(r"[^\d,.\-]")

def format_price(raw):
    """'€ 3,50' -> '3.50'; returns None when nothing usable is left."""
    if raw is None:
        return None
    cleaned = CURRENCY.sub("", str(raw)).strip()
    if not cleaned:
        return None
    if "," in cleaned and "." in cleaned:
        cleaned = cleaned.replace(".", "").replace(",", ".")   # 1.234,56
    elif "," in cleaned:
        cleaned = cleaned.replace(",", ".")                    # 3,50
    return f"{float(cleaned):.2f}"

from datetime import datetime

DATE_FORMATS = ("%Y-%m-%d", "%d.%m.%Y", "%d/%m/%Y")

def format_date(raw, out="%d.%m.%Y"):
    text = str(raw or "").strip()
    for fmt in DATE_FORMATS:
        try:
            return datetime.strptime(text, fmt).strftime(out)
        except ValueError:
            continue
    return None   # unparseable beats guessed

def label_case(raw, style="upper"):
    text = " ".join(str(raw or "").split())   # collapse stray whitespace
    return text.upper() if style == "upper" else text.title()

Observe os retornos None deliberados. Um valor não formatável deve falhar de forma visível na próxima passagem, não se tornar um 0.00 de aparência plausível.

Passagem 2: Validar

A validação é o que impede que um preço errado chegue silenciosamente à impressora. Verifique se os campos dos quais você depende existem e estão bem formados, e faça cada mensagem específica o suficiente para localizar o registro.

def validate_record(record):
    """Return a list of 'field: reason' strings. Empty list means OK."""
    errors = []

    sku = (record.get("sku") or "").strip()
    if not sku:
        errors.append("sku: missing")
    elif len(sku) < 8:
        errors.append(f"sku: shorter than 8 characters ({sku!r})")

    price = record.get("price")
    if price is None:
        errors.append("price: not parseable")
    elif not (0.01 <= price <= 9999.99):
        errors.append(f"price: out of range ({price!r})")

    if record.get("best_before") is None:
        errors.append("best_before: unparseable date")

    return errors

Uma mensagem como price: not parseable ('0,00') diz ao operador qual campo olhar e qual valor causou o problema. Uma mensagem como invalid data diz a ele para ligar para você.

price: not parseable ('0,00')
sku: shorter than 8 characters ('4711')
best_before: unparseable date (row: Espresso 250g)

Passagem 3: Transformar

Somente depois que o valor estiver formatado e validado você deve derivar valores de exibição a partir dele — um código de produto combinado, um prefixo de fornecedor removido, um nome curto para um campo estreito.

def product_code(record, prefix="SUP-"):
    supplier = (record.get("supplier_code") or "").strip()
    if supplier.startswith(prefix):
        supplier = supplier[len(prefix):]
    sku = (record.get("sku") or "").strip()
    return f"{supplier}-{sku}".strip("-")

Onde o script vive no fluxo de trabalho

No RSJ LPSNG você anexa o bloco de script a um campo da etiqueta no layout. A plataforma o executa como parte do job normal de impressão ou renderização — a mesma execução que também lida com saída em PDF ou PNG e impressão direta pela interface de web service. Não há processo auxiliar para iniciar nem problema de ordenação para raciocinar.

Isso importa para a entrega. A regra de formatação faz parte da definição da etiqueta, então ela se move com o modelo em vez de ficar na máquina de quem a escreveu.

O jeito difícil vs. o jeito gerenciado

O jeito difícil é o que Mara quase escolheu: um script separado que reescreve arquivos CSV ou Excel antes de serem alimentados a uma ferramenta de impressão. Ele tem sua própria história de implantação, seus próprios modos de falha, e sua própria suposição silenciosa de que todos lembram de executá-lo antes de imprimir.

O jeito gerenciado coloca o bloco de script Python no próprio campo no RSJ LPSNG. Formatação e validação viajam com a etiqueta. A mesma etiqueta pode ser renderizada como PDF ou PNG, ou enviada para impressão direta pela interface de web service, e a lógica do campo é a mesma em todos os casos porque pertence à etiqueta, não a uma etapa externa.

Checklist para o seu primeiro script de campo

• Comece com um campo e uma regra. Formate o preço, renderize um PDF de amostra e inspecione-o. Só então passe ao próximo campo.
• Torne as falhas localizáveis. Toda mensagem de validação deve nomear o campo e mostrar o valor problemático.
• Teste com entrada deliberadamente bagunçada. Células vazias, espaços extras, formatos de data mistos, um preço negativo, um preço de 0.00, um SKU com comprimento errado.
• Decida entre transformação e consulta. Arquivos Excel podem servir tanto como arquivos de dados quanto como arquivos de consulta, então um nome de fornecedor pode pertencer a uma planilha de referência em vez de ser derivado no script. O lado da fonte de dados está coberto em How to Print Barcoded Labels from Excel.
• Renderize antes de executar. Uma prova em PDF de três registros bagunçados custa um minuto; uma reimpressão de quarenta etiquetas de prateleira erradas custa uma manhã.

O que evitar

Não enterre regras de negócio no layout. Mantenha formatação e validação no script de campo e mantenha decisões de design no editor de layout. Misturá-los significa que um ajuste de design pode silenciosamente mudar um formato de preço.

Não force silenciosamente dados ruins para um valor plausível. Uma etiqueta que imprime com confiança o preço errado é pior que um job que falha ruidosamente. Retorne None e deixe a validação capturá-lo.

Não duplique a mesma transformação em muitos campos. Se seis campos precisam do mesmo formato de preço, uma abordagem compartilhada é melhor que seis blocos copiados e colados que divergem. Inconsistência entre campos na mesma etiqueta é uma das fontes mais comuns de erros.

Não adivinhe em entradas ambíguas. 03/04/2026 é 4 de março ou 3 de abril. Fixe o formato na origem; um script que adivinha estará errado para alguém.

Não trate o script como substituto de testes. Renderize etiquetas de amostra e olhe para elas. Scripts de campo reduzem o número de surpresas, mas não eliminam a necessidade de verificar.

Perguntas frequentes

Onde os blocos de script Python rodam no RSJ LPSNG?

Os blocos de script Python são anexados a campos da etiqueta e acessam e modificam os valores dos campos antes da impressão, como parte da definição da etiqueta na plataforma.

Preciso construir um pipeline separado de limpeza de dados?

Não. O script de campo cuida de formatação, validação e transformação dentro da própria etiqueta, então você não precisa de um script auxiliar reescrevendo seus arquivos de dados antes que cheguem ao motor de impressão.

Ainda posso enviar jobs programaticamente?

Sim. A interface de web service permite enviar jobs de impressão e renderizar etiquetas individuais como PDF ou PNG, e o modelo OAuth2 cobre a conexão de sistemas externos com uma única URL de registro.

A mesma lógica de campo se aplica a PDF, PNG e impressão direta?

Renderização de PDF/PNG e impressão direta são caminhos de saída documentados da interface de web service, e a lógica de campo pertence à definição da etiqueta que esses caminhos usam. Etiquetas eletrônicas de prateleira são uma trilha separada com sua própria interface JSON neutra em relação a fornecedor (ESLSEND) — consulte a documentação da interface ESL em vez de assumir que o caminho de impressão se aplica sem alterações.

Não desenvolvedores podem usar uma etiqueta que contém scripts de campo?

Sim. Uma vez que o script está anexado ao campo, imprimir a etiqueta não exige escrever ou ler Python. Quem executa o job seleciona os dados e imprime; a formatação e a validação acontecem como parte da etiqueta.

Isso substitui o editor de layout?

Não. O editor de layout cuida do design; os scripts de campo Python cuidam dos dados que fluem para cada campo. Eles são partes complementares da mesma etiqueta.

Conclusão

A correção de Mara não foi um script de exportação melhor. Foi mover a regra para onde o valor é realmente usado: um campo de preço que formata uma vírgula decimal em 3.50, recusa-se a imprimir uma célula vazia, e remove um prefixo de fornecedor na saída. A dona da loja manteve sua planilha. As etiquetas pararam de estar erradas.

O Next Generation Label Printing System é construído exatamente em torno dessa divisão — design no editor de layout, controle de dados em scripts de campo, e uma interface de web service para quando você quiser conduzir jobs programaticamente. Comece com um campo, uma regra e um PDF renderizado. Depois entregue.

Posts relacionados

• What Is Label Merge and How Does It Work?
• How to Design Barcode Labels in a Browser Layout Editor
• Best Label Printing Software for Developers: Buying Guide