Como Conectar Tags ESL a Itens via API

O planograma foi atualizado. Os preços estão corretos no ERP, corretos no template da etiqueta de gôndola, corretos no cadastro de produtos. E, ainda assim, três horas depois, um corredor continua exibindo o preço antigo — porque a etiqueta eletrônica de gôndola presa àquela posição de prateleira ainda está vinculada ao item que costumava ficar ali. Alguém precisa percorrer o corredor com um coletor, escanear a tag, escanear o item, e repetir isso algumas centenas de vezes.

Essa etapa de vinculação manual é a última peça da etiquetagem de gôndola que resiste à automação. Mas não precisa ser assim. Com a ESL Binding API do Next Generation Label Printing System (LPSNG), você pode associar tags ESL a itens de forma programática, enviar dados de itens para os displays através de uma interface JSON neutra em relação a fornecedor, e só pegar um scanner quando algo realmente deu errado.

Este artigo percorre a automação de ponta a ponta: a configuração inicial única, o pipeline que faz a vinculação, o que monitorar e como mantê-la confiável.

Configuração Inicial Única: Preparando Seu Ambiente ESL

Você faz isso uma vez por loja, estação base ou unidade MDE (mobile data entry). Tudo depois disso é um job agendado.

1. Registre seu sistema externo

O LPSNG usa um protocolo de registro OAuth2 simplificado: você conecta um sistema externo — uma estação base ESL, uma unidade MDE portátil, um serviço de middleware — com uma única URL. O LPSNG gerencia a troca de tokens por trás desse registro, então você não precisa implementar um cliente OAuth2 do zero.

Na prática, isso significa que sua configuração de integração contém uma URL de registro e uma credencial, não uma máquina de estados de renovação de token:

# lpSng-integration.yaml
esl:
  registration_url: "https://lpsng.rsj.de/..."   # from your LPSNG registration
  client_id: "${LPSNG_CLIENT_ID}"
  client_secret: "${LPSNG_CLIENT_SECRET}"        # keep in a secret store, not in git
  store_id: "store-0417"

Armazene esses valores em um gerenciador de segredos. O registro é a única etapa em que um erro é caro de desfazer.

2. Certifique-se de que o hardware está acessível

Suas tags ESL precisam estar instaladas e ao alcance da estação base ou gateway antes que qualquer chamada de API possa ter sucesso. Se você usa hardware ESL da CATIC, siga as instruções de instalação da CATIC — posicionamento de antena e endereçamento de tags são as duas coisas que mais frequentemente causam “a API funcionou, mas nada mudou na prateleira”.

3. Confirme seu caminho de atualização de display

O conteúdo do display é atualizado através da interface de arquivo JSON neutra em relação a fornecedor (ESLSEND). Essa é a parte que vale a pena considerar arquiteturalmente: o payload é JSON, não um formato binário proprietário, então sua integração não fica soldada a um único fornecedor de tags. Abordamos as implicações em O Que uma Interface ESL Neutra em Relação a Fornecedor Significa para Desenvolvedores.

4. Aponte o LPSNG para seus dados de itens

A etapa de vinculação precisa de algo para vincular a. O LPSNG pode usar arquivos Excel como arquivos de dados e consulta, um add-on do Google Sheets para equipes que vivem em planilhas, ou seu ERP como fonte upstream. A lógica de vinculação em si não se importa — ela precisa de uma chave estável (SKU ou EAN) e dos campos que você quer no display.

Se você quiser o caminho difícil, pode criar manualmente arquivos JSON ESLSEND e executar a troca de tokens OAuth2 por conta própria. O fluxo gerenciado do LPSNG existe para que você não precise fazer isso.

O Pipeline Automatizado: Vinculando Tags a Itens

Aqui está o fluxo, passo a passo.

Passo 1 — Dispare o processo de vinculação

A ESL Binding API é um web service criado especificamente para unidades MDE que não têm interface web: um coletor pode chamá-la, um cron job pode chamá-la, um webhook pode chamá-la. Uma execução de vinculação começa com uma requisição HTTP.

curl -X POST "$LPSNG_BASE/binding/jobs" \
  -H "Authorization: Bearer $LPSNG_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "store_id": "store-0417",
        "source": "erp-sync-2026-10-18",
        "mode": "reconcile"
      }'

O caminho e os parâmetros exatos estão na documentação da interface de web service; a parte importante é que uma execução de vinculação é um job que você submete, não uma sessão que você acompanha.

Passo 2 — Deixe o LPSNG mapear itens para IDs de tags

Este é o passo que substitui o scanner. O LPSNG pega identificadores de itens (SKU, EAN) da sua fonte de dados e os associa a IDs de tags ESL, usando a relação tag-para-posição-de-prateleira já conhecida pelo sistema. Seu código nunca precisa saber qual tag física está pendurada sobre qual prateleira.

Se você está conduzindo a reconciliação por conta própria, o loop é pequeno:

import os, requests

BASE = os.environ["LPSNG_BASE"]
HEADERS = {"Authorization": f"Bearer {os.environ['LPSNG_TOKEN']}"}

def reconcile(store_id: str, items: list[dict]):
    """items: [{"sku": "...", "ean": "...", "price": "...", "name": "..."}]"""
    resp = requests.post(
        f"{BASE}/binding/jobs",
        headers=HEADERS,
        json={"store_id": store_id, "items": items, "mode": "reconcile"},
        timeout=30,
    )
    resp.raise_for_status()
    return resp.json()["job_id"]

Passo 3 — Envie dados de itens para os displays

Uma vez que uma tag está vinculada, o LPSNG atualiza o display ESL com os valores específicos do item que você fornece — preço, nome, código de barras, o que o layout usar — através da interface JSON ESLSEND. Um payload mínimo se parece mais ou menos com isto (veja a documentação da interface ESL para o schema completo):

{
  "esl_id": "TAG-0042-1188",
  "item": {
    "sku": "SKU-88213",
    "ean": "4012345678901",
    "name": "Organic Coffee 500g",
    "price": "8.49"
  }
}

Como o formato é neutro em relação a fornecedor, trocar o hardware de tags depois é uma questão de implantação, não uma reescrita.

Passo 4 — Imprima as etiquetas que ainda precisam ser impressas

Algumas coisas continuam físicas: cartazes promocionais de gôndola, faixas de gôndola, etiquetas de caixa. Essas podem ser renderizadas a partir dos mesmos dados de itens, porque a API de web service do LPSNG pode submeter jobs de impressão e renderizar etiquetas individuais como PDF ou PNG, e o Player standalone pode emitir PDF, PNG, JSON, jobs de impressão ou atualizações ESL a partir da mesma entrada de pacote mais dados. Uma fonte de dados, dois canais de saída.

Tudo isso como um fluxo de trabalho agendado

Uma reconciliação noturna geralmente é suficiente:

# crontab: every night at 02:15, after the ERP export lands
15 2 * * * /usr/local/bin/python /opt/esl/sync.py --store store-0417 >> /var/log/esl-sync.log 2>&1

# sync.py (sketch)
items = load_from_erp()          # or read the Excel/Sheets export
job_id = reconcile("store-0417", items)
wait_for_job(job_id)             # poll LPSNG for job status
handle_failures(job_id)          # retry or flag

Cron está bom. Um webhook do seu ERP é melhor — ele vincula tags no momento em que os preços mudam, em vez de horas depois.

Monitoramento e Tratamento de Falhas

Automação que você não consegue ver é automação em que você não pode confiar.

• Acompanhe jobs na fila de jobs. A fila de jobs do LPSNG faz parte da funcionalidade principal em todas as edições. Execuções de vinculação e atualizações de display aparecem lá, e jobs com falha são registrados para revisão.
• Repita, não entre em pânico. Se uma tag está inacessível, a API retorna um erro. Configure lógica de retry para falhas transitórias (uma tag temporariamente fora de alcance) e sinalize o resto para um humano.
• Monitore a saúde das tags. Status de bateria e sinal são visíveis através da interface ESL. Fazer polling disso é como você encontra a tag que vai morrer na próxima semana em vez da que já morreu.
• Configure alertas do seu lado. Faça polling do web service do LPSNG para status de jobs e envie falhas para o que você já usa para alertas. Você não precisa de uma segunda stack de monitoramento.
• Mantenha um fallback manual. Se uma tag permanecer inacessível, vincule-a manualmente na interface web do LPSNG quando ela voltar a ficar online. A mesma plataforma gerencia tanto o caminho automatizado quanto o manual, então não há split-brain entre os dois.

Uma verificação de status simples:

curl -s "$LPSNG_BASE/jobs/$JOB_ID" \
  -H "Authorization: Bearer $LPSNG_TOKEN" | jq '{status, failed: [.results[] | select(.status=="failed")]}'

Boas Práticas para Automação ESL Confiável

• Mantenha os identificadores limpos. Sua chave do ERP e sua chave ESL devem ser a mesma string, gerada em um único lugar. A maioria dos tickets de “falha na vinculação” são, na verdade, tickets de “o SKU mudou de formato”.
• Fique na interface JSON. Payloads neutros em relação a fornecedor tornam a troca de hardware uma tarefa de implantação. Também significa que a mesma estrutura de payload funciona entre lojas.
• Teste em staging primeiro. Uma execução de vinculação contra uma loja de teste captura erros de mapeamento antes que eles atinjam 400 tags em um corredor real.
• Rotacione credenciais. Armazene credenciais OAuth2 e refresh tokens em um gerenciador de segredos, documente quem é o responsável por elas, e rotacione em um cronograma.
• Considere implantação em edge. Para lojas com conectividade instável, a Embedded Edition executa o LPSNG completo em um computador de placa única como um Raspberry Pi, então os jobs de vinculação executam localmente e sincronizam quando o link está ativo.
• Verifique códigos de barras antes de enviá-los. Um EAN errado em um display é pior que um preço desatualizado — veja Como Verificar Códigos de Barras Antes de Imprimir Etiquetas.

FAQ

Preciso escrever código para conectar tags ESL a itens?

Não necessariamente. O LPSNG fornece uma API de web service e um fluxo de trabalho gerenciado que pode ser disparado via requisições HTTP simples. Para automação completa, porém, você provavelmente escreverá scripts que chamam a ESL Binding API. A interface JSON neutra em relação a fornecedor (ESLSEND) torna simples integrar com seus sistemas existentes.

Posso usar a ESL Binding API com qualquer hardware ESL?

A ESL Binding API foi projetada para ser neutra em relação a fornecedor, usando uma interface de arquivo JSON (ESLSEND) para atualizar displays ESL. Ela pode funcionar com vários hardwares ESL, desde que suportem o formato JSON. O LPSNG também fornece instruções de instalação específicas para hardware ESL da CATIC.

Como o LPSNG lida com autenticação para sistemas externos?

O LPSNG usa um protocolo de registro OAuth2 simplificado. Você conecta seu sistema externo (como uma unidade MDE) com uma única URL, e o LPSNG gerencia a troca de tokens. Isso evita implementar OAuth2 do zero em cada integração.

O que acontece se uma tag ESL ficar offline durante uma atualização?

Se uma tag estiver inacessível, a API retorna um erro. A fila de jobs do LPSNG registra a falha, e você pode configurar lógica de retry ou receber alertas. Para atualizações críticas, você pode vincular a tag manualmente usando a interface web do LPSNG quando ela voltar a ficar online.

Conclusão: Automatize Uma Vez, Beneficie-se Continuamente

Conectar tags ESL a itens via API remove a etapa de percorrer corredores do seu processo. Você submete um job de vinculação, o LPSNG associa seus identificadores de itens a IDs de tags, e os displays são atualizados através de uma interface JSON que não te prende a um único fornecedor de hardware. Os preços permanecem precisos entre mudanças de planograma em vez de se desviarem até que alguém perceba.

O caminho prático é o gerenciado: registre cada loja com uma única URL, deixe o Next Generation Label Printing System cuidar da troca de tokens e do rastreamento de jobs, e mantenha seu próprio código na parte que é realmente sua — decidir quais itens vão para onde.

Comece lendo a documentação da interface ESL e a referência da ESL Binding API. Depois faça um protótipo contra a edição em nuvem, ou baixe a Embedded Edition se você quiser o job de vinculação rodando dentro da loja desde o primeiro dia.

Posts relacionados

• O Que uma Interface ESL Neutra em Relação a Fornecedor Significa para Desenvolvedores
• Preços de Software de Impressão de Etiquetas em Nuvem: O Que Procurar
• Como Verificar Códigos de Barras Antes de Imprimir Etiquetas