Pular para o conteúdo principal

Etiquetas

Tela de gerenciamento de modelos de etiquetas ZPL da empresa. Permite cadastrar, editar, visualizar e excluir layouts ZPL que serão consumidos por Gerar Ativos, Impressão e demais fluxos que utilizam etiquetas.

Tela de Etiquetas

Como acessar​

  • Rota: /etiquetas
  • Permissão necessária: etiquetas

Tela Principal - Listagem de Etiquetas​

Tela Etiquetas - Listagem Principal

A tela de listagem mostra todas as etiquetas ZPL cadastradas para a empresa. Nesta tela você pode visualizar a tabela com colunas: Nome, Dimensões (L x A), Campos e Ações. O botão "Criar Nova Etiqueta" abre o formulário completo, e o menu de ações (três pontos) permite Preview, Editar ou Excluir cada etiqueta.

O que você pode fazer​

  • Listar todas as etiquetas ZPL cadastradas para a empresa do usuário logado.
  • Criar uma nova etiqueta com nome, dimensões (largura x altura), código ZPL e campos dinâmicos.
  • Adicionar elementos visuais (texto, linhas, retângulos, círculos), códigos de barras (Code128, Code39, EAN13, EAN8 etc.), códigos 2D (QR Code, Data Matrix, PDF417) e bloco RFID/EPC ao ZPL via botões.
  • Definir campos personalizados (@nome_campo) que serão preenchidos no momento da geração de ativos.
  • Visualizar prévia da etiqueta renderizada (PopupPreviewEtiqueta).
  • Editar e excluir etiquetas existentes.
  • Copiar o ZPL para a área de transferência.

Seções da tela de listagem​

  • Tabela de etiquetas: mostra nome, dimensões (L x A), campos dinâmicos e ações.
  • Botão Criar Nova Etiqueta: abre formulário full-screen para criação.
  • Menu de ações (três pontos): Preview, Editar, Excluir por etiqueta.

Tela de Criação/Edição - Modal Criar Nova Etiqueta​

Tela Etiquetas - Criar Nova Etiqueta

Fluxo de criação/edição de etiqueta​

1. Configurações básicas (Seção superior)​

  • Nome da Etiqueta: identificador legível (obrigatório).
  • Largura (mm): largura da etiqueta em milímetros.
  • Altura (mm): altura da etiqueta em milímetros.

2. Campos dinâmicos (Seção esquerda-superior)​

  • Campo de texto para nomear novo campo (ex: descricao, codigo_barras).
  • Botão Adicionar para incluir o campo na lista.
  • Visualização em chips dos campos adicionados com ícone de deletar em cada um.
  • Campos built-in reconhecidos automaticamente: @epc, @lote, @num_serie.
  • Exemplo na imagem: chips descricao e codigo_barras já adicionados.

3. Upload de imagem (Seção direita-superior)​

  • Botão Carregar imagem para converter imagem em bloco ZPL.
  • Slider para ajustar tamanho da imagem (0-200%).
  • Botão Enviar para converter na API (POST /zpl/convert).
  • Exibição do ZPL gerado com opção de Copiar (ícone clipboard) ou Expandir (ícone zoom).

4. Elementos da etiqueta (Seção esquerda-inferior)​

  • Elementos de Texto: Texto Estático.
  • Códigos de Barras: Code 128, Code 39, EAN-13, EAN-8, Code 93, UPC-A, UPC-E, Interleaved 2/5, Codabar, PDF417.
  • Códigos 2D: QR Code, Data Matrix.
  • Elementos Gráficos: Linha, Retângulo, Círculo (múltiplos permitidos).
  • RFID: Bloco RFID/EPC (apenas um).
  • Na imagem: botões de exemplo mostram "TEXTO ESTÁTICO", "CODE 128", "CODE 39", "EAN-13", "EAN-8".

5. Código ZPL (Seção central-inferior)​

  • Área com preview do código ZPL gerado em tempo real.
  • Ícone de copiar para transferir para clipboard.
  • Ícone de expandir para visualizar código completo em modal.
  • Validação em tempo real de mapeamento entre campos dinâmicos e referências no ZPL.
  • Na imagem: código ZPL mostra referências aos campos @descricao e @codigo_barras.

6. Preview da etiqueta (Seção direita-inferior)​

  • Painel lateral com renderização visual da etiqueta conforme edição.
  • Atualiza à medida que elementos são adicionados/removidos.
  • Na imagem: mostra "Nome da Etiqueta" e "Produto: @descricao" como preview.

Campos e validações​

  • Nome: obrigatório, texto livre.
  • Largura/Altura: obrigatórios, números positivos em milímetros.
  • Campos dinâmicos: devem ser nomeados e aparecer no ZPL com prefixo @ (ex: @descricao, @codigo_barras).
    • Ao adicionar um campo, ele vira um chip que pode ser removido individualmente.
    • O campo aparece automaticamente no ZPL quando você adiciona um elemento que o referencia.
  • Mapeamento de campos: todos os @campo no ZPL devem estar listados em "Campos Adicionados", exceto built-ins (@epc, @lote, @num_serie).
    • Se houver descomposição (campo no ZPL mas não adicionado), o botão Salvar fica desabilitado.
  • Elementos: podem ser adicionados múltiplas vezes (exceto RFID, que é único por etiqueta).
  • Imagem: opcional, é convertida em bloco ZPL através do endpoint /zpl/convert.
  • ZPL: validado automaticamente quanto à sintaxe Zebra Print Language.

Como usar​

  1. Clique em Criar Nova Etiqueta no topo direito.
  2. Informe nome, largura e altura em milímetros.
  3. Adicione campos dinâmicos (ex: @descricao, @codigo_barras) usando o formulário.
  4. Clique em Adicionar após cada campo.
  5. (Opcional) Faça upload de imagem, ajuste tamanho e envie para gerar ZPL automático.
  6. Clique nos botões de elementos para inserir componentes na etiqueta (texto, código de barras, QR, etc.).
  7. Valide que o ZPL gerado contém referências corretas aos campos.
  8. Clique em Salvar para confirmar.
  9. Para editar ou excluir, abra o menu (ícone três pontos) na linha da tabela.

Regras e comportamentos​

  • A página é protegida por permissão etiquetas.
  • Ao abrir formulário de criação, um ZPL template inicial é carregado automaticamente.
  • Campos dinâmicos devem respeitar a convenção @nome_sem_espacos.
  • A flag epcConfig é derivada automaticamente da presença de @epc no ZPL.
  • Ao editar uma etiqueta, todos os dados (ZPL, campos, dimensões) são carregados no formulário.
  • Remover um elemento do ZPL requer clique no ícone de deletar ou limpeza manual do código.
  • O botão Salvar fica desabilitado enquanto houver campos não mapeados no ZPL.
  • Todas as etiquetas criadas são vinculadas à empresa do usuário logado.

Estados de retorno esperados​

  • Listagem vazia: "Nenhuma etiqueta cadastrada" — o usuário pode criar a primeira.
  • Criação com sucesso: toast "Etiqueta criada com sucesso!" e retorno à listagem.
  • Edição com sucesso: toast "Etiqueta editada com sucesso!" e atualização da linha na tabela.
  • Exclusão com sucesso: toast "Etiqueta excluída com sucesso!" e remoção da linha.
  • Mapeamento inválido: botão Salvar desabilitado com mensagem de validação.
  • Preview: modal com renderização visual da etiqueta conforme código ZPL.
  • Erro de operação: toast "Erro ao [criar/editar/excluir] etiqueta" com detalhe técnico no console.