Tutorial da API de Vinculação ESL: Conecte Etiquetas a Itens

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

Tutorial da API de Vinculação de ESL: Conecte Etiquetas a Itens

Você tem uma etiqueta eletrônica de prateleira (ESL) na mão e um item no seu catálogo. Você precisa que essa etiqueta mostre o preço correto, o nome do produto e dados adicionais sem passar por um fluxo de trabalho proprietário com dispositivo portátil. Este tutorial mostra como usar a API de Vinculação de ESL no Next Generation Label Printing System (LPSNG) para conectar uma etiqueta ESL a um item por meio de uma simples chamada HTTPS.

Ao final, você será capaz de vincular programaticamente uma etiqueta a partir de um sistema externo, como uma unidade de entrada de dados móvel (MDE), verificar a vinculação e desvincular ou revincular uma etiqueta quando ela for movida para um item diferente.

Pré-requisitos

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

Uma conta LPSNG com acesso à API de Vinculação de ESL. A API de vinculação faz parte da funcionalidade principal do LPSNG e está disponível em todas as edições.
Hardware ESL compatível que suporte a interface de vinculação, por exemplo, dispositivos ESL CATIC.
Uma estação base ESL alimentada com as etiquetas que você deseja vincular dentro do alcance.
Familiaridade básica com APIs REST e JSON.
A URL base do seu serviço web LPSNG, conforme mostrado na configuração da sua conta.
Credenciais de cliente OAuth2 para autenticação. Se você ainda não registrou um sistema externo, siga primeiro a documentação OAuth2.

Você não precisa falar diretamente com um protocolo de estação base específico do fornecedor. O caminho difícil seria fazer engenharia reversa da comunicação de baixo nível usada pelo seu hardware ESL. O caminho suportado é deixar o serviço gerenciado LPSNG lidar com essa tradução enquanto você usa uma única API HTTPS.

Passo a Passo: Vinculando uma Etiqueta ESL a um Item

Passo 1: Obter um Token de Acesso OAuth2

O LPSNG usa um protocolo de registro OAuth2 simplificado para sistemas externos. Depois que sua integração estiver registrada, você solicita um token de acesso do endpoint de token do seu tenant e o inclui em cada chamada de API.

O endpoint exato e o fluxo de registro dependem da sua conta. Na maioria das configurações, uma solicitação de credenciais de cliente se parece com isto:

curl -s -X POST "https://<SUA-BASE-LPSNG>/oauth2/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -u "<CLIENT_ID>:<CLIENT_SECRET>" \
  -d "grant_type=client_credentials"

Uma resposta bem-sucedida inclui um token bearer:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Use esse valor access_token no cabeçalho Authorization para a solicitação de vinculação. Consulte o guia OAuth2 se o seu tenant usar um formato de solicitação de token diferente.

Passo 2: Identificar o Item e a Etiqueta

Você precisa de dois identificadores antes de poder vincular qualquer coisa:

Identificador do item: Geralmente o SKU, EAN ou número de material interno que já existe na sua fonte de dados LPSNG.
Identificador da etiqueta: O ID exclusivo da etiqueta ESL. Geralmente está impresso na própria etiqueta ou é capturado ao escanear a etiqueta com uma unidade MDE.

Por exemplo, um item pode ser identificado como EAN-4001234567890, e uma etiqueta pode ser identificada como CATIC-001234. Mantenha ambos os valores à mão para o payload JSON.

Passo 3: Construir a Solicitação de Vinculação

Uma solicitação de vinculação é um objeto JSON enviado ao endpoint de vinculação. Os campos obrigatórios são o identificador do item e o identificador da etiqueta. Dependendo do layout da sua etiqueta e da configuração ESL, você também pode enviar campos opcionais como price ou um objeto labelData.

{
  "itemId": "EAN-4001234567890",
  "tagId": "CATIC-001234",
  "price": "19.90",
  "labelData": {
    "name": "Leite de Aveia Orgânico 1L",
    "unit": "L"
  }
}

Nem todas as implantações usam price e labelData. Se suas etiquetas forem totalmente orientadas pelos dados mestres do item no LPSNG, você pode enviar apenas itemId e tagId. Verifique o layout da sua etiqueta para ver quais campos adicionais a etiqueta deve exibir.

Passo 4: Enviar uma Solicitação POST ao Endpoint de Vinculação

Para este tutorial, usamos /api/esl/bind como endpoint de vinculação. Sua instalação LPSNG pode expor o mesmo caminho ou um caminho específico do tenant, então confirme o endpoint exato na documentação da API de Vinculação de ESL para o seu ambiente.

Salve o payload em um arquivo para que o comando curl permaneça legível:

{
  "itemId": "EAN-4001234567890",
  "tagId": "CATIC-001234",
  "price": "19.90",
  "labelData": {
    "name": "Leite de Aveia Orgânico 1L",
    "unit": "L"
  }
}

Em seguida, envie a solicitação:

curl -s -X POST "https://<SUA-BASE-LPSNG>/api/esl/bind" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  --data @binding-payload.json

O LPSNG recebe a solicitação, resolve os dados do item na sua fonte de dados e instrui a estação base ESL a atualizar a etiqueta.

Passo 5: Tratar a Resposta

Uma vinculação bem-sucedida normalmente retorna uma resposta 200 OK com um objeto de status:

{
  "status": "bound",
  "tagId": "CATIC-001234",
  "itemId": "EAN-4001234567890",
  "updatedAt": "2026-09-21T10:15:00Z"
}

Respostas de erro comuns incluem:

400 para dados inválidos, como um corpo JSON malformado ou um campo obrigatório ausente.
401 para falha de autenticação, por exemplo, um token de acesso expirado ou ausente.

Inspecione o corpo da resposta para obter uma mensagem de erro que explique qual campo falhou. Se a API retornar outro status 4xx, verifique se a etiqueta ou o item é desconhecido ou se a etiqueta já está vinculada em outro lugar.

Passo 6: Verificar a Vinculação Consultando o Status da Etiqueta

Se sua implantação expuser um endpoint de status de etiqueta, você pode consultar a vinculação atual. O endpoint exato pode variar; o seguinte é um exemplo de formato:

curl -s "https://<SUA-BASE-LPSNG>/api/esl/status/CATIC-001234" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Uma resposta semelhante a esta confirma que a etiqueta está vinculada ao item esperado:

{
  "tagId": "CATIC-001234",
  "boundItemId": "EAN-4001234567890",
  "lastSeen": "2026-09-21T10:15:00Z"
}

Se o seu tenant não expuser um endpoint de status, use o painel de gerenciamento de ESL no LPSNG para ver o status da etiqueta.

Passo 7: Opcional — Desvincular ou Revincular uma Etiqueta

Quando um item se move para um novo local ou uma etiqueta é reutilizada, você precisa desvincular ou revincular. O método exato depende do seu endpoint de vinculação LPSNG.

Uma solicitação comum de desvinculação usa DELETE:

curl -s -X DELETE "https://<SUA-BASE-LPSNG>/api/esl/bind/CATIC-001234" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Para revincular a mesma etiqueta a um item diferente, envie uma solicitação PUT:

curl -s -X PUT "https://<SUA-BASE-LPSNG>/api/esl/bind/CATIC-001234" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"itemId":"EAN-4001234567891"}'

Consulte a documentação da API de Vinculação de ESL para o comportamento exato de desvinculação e revinculação na sua instalação.

Verificando a Vinculação

Depois que a chamada da API retornar sucesso, confirme a vinculação de mais de uma maneira:

Verifique fisicamente o display ESL — a etiqueta agora deve mostrar o preço e o nome do item. Se o display ainda estiver em branco ou mostrando dados antigos, aguarde alguns segundos e verifique novamente.
Consulte o status da etiqueta através da interface ESL se sua implantação fornecer uma. A resposta de status deve mostrar o boundItemId esperado.
Abra o painel de gerenciamento de ESL no LPSNG e localize a etiqueta. Seu status deve mudar de não vinculada ou item anterior para o novo item.
Teste com um item diferente e revincule a mesma etiqueta. Se o display atualizar corretamente, sua integração está funcionando de ponta a ponta.

Solução de Problemas Comuns

Erros de autenticação

Verifique novamente seu ID de cliente e segredo OAuth2. Os tokens de acesso expiram, então renove o token se receber uma resposta 401 após um período de tempo.

Etiqueta não encontrada

Certifique-se de que o ID da etiqueta está exatamente correto, incluindo quaisquer prefixos ou zeros à esquerda. Confirme também que a etiqueta está ligada e dentro do alcance da estação base ESL. Uma etiqueta que não reportou recentemente pode não estar disponível para vinculação.

Item não encontrado

Verifique se o identificador do item existe na sua fonte de dados LPSNG. A API de vinculação resolve contra os mesmos dados que suas etiquetas usam, então um erro de digitação no EAN ou SKU impedirá a vinculação.

Conflito de vinculação

A etiqueta pode já estar vinculada a outro item. Desvincule a etiqueta primeiro e, em seguida, envie uma nova solicitação de vinculação. Algumas instalações rejeitam uma revinculação direta sem uma etapa explícita de desvinculação.

Problemas de rede

Se a solicitação expirar, verifique a conectividade entre seu cliente, o serviço web LPSNG e a estação base ESL. A estação base deve ser acessível a partir do LPSNG, não diretamente do seu cliente.

FAQ

O que é a API de Vinculação de ESL?

A API de Vinculação de ESL é um serviço web fornecido pelo Next Generation Label Printing System (LPSNG) que permite que sistemas externos, como unidades de entrada de dados móveis, vinculem etiquetas eletrônicas de prateleira a itens específicos. Ela usa uma simples solicitação JSON sobre HTTPS.

Posso vincular várias etiquetas a um item?

Normalmente, uma etiqueta é vinculada a um item. No entanto, dependendo do seu hardware ESL e da configuração do LPSNG, você pode vincular várias etiquetas ao mesmo item para redundância ou diferentes locais de exibição. Consulte a documentação do seu hardware.

Como desvinculo uma etiqueta?

Para desvincular uma etiqueta, você pode enviar uma solicitação ao endpoint de vinculação com um identificador de item vazio ou nulo, ou usar um método dedicado de desvinculação, se disponível. Consulte a documentação da API para o endpoint e payload exatos.

A API de vinculação está disponível em todas as edições do LPSNG?

Sim, a API de Vinculação de ESL faz parte da funcionalidade principal do LPSNG e está disponível em todas as edições, incluindo a solução em nuvem e a edição embarcada. No entanto, você precisa de hardware ESL compatível para usá-la.

Conclusão

O fluxo de trabalho de vinculação é um pequeno ciclo: autenticar, coletar os IDs do item e da etiqueta, enviar a solicitação de vinculação e verificar o display. Uma vez que esse ciclo funcione, você pode chamá-lo de uma unidade MDE, de um processo de fulfillment ou de qualquer outro sistema externo que precise atribuir etiquetas ESL a itens.

A API de Vinculação de ESL é apenas uma parte da solução ESL mais ampla do LPSNG. O LPSNG também fornece a Interface ESL neutra em relação ao fornecedor para atualizar displays, o guia OAuth2 para autenticação e o LPSNG Player para fluxos de trabalho de saída ESL por linha de comando.

Se você está integrando hardware ESL pela primeira vez, comece com a documentação da API de Vinculação de ESL e teste com uma etiqueta reserva antes de passar para produção.

Posts relacionados

Tutorial da API de Vinculação ESL: Conecte Etiquetas a Itens