Impressão de Etiquetas (QZ Tray)
O idworks imprime etiquetas térmicas (ZPL), cupons e documentos enviando os dados direto para a impressora do seu computador por meio do QZ Tray — um aplicativo gratuito que faz a ponte entre o navegador e a impressora. Por segurança, o navegador não imprime sozinho numa impressora local; é o QZ Tray, rodando na máquina, que recebe o conteúdo do idworks e repassa para o equipamento. Por isso, sem o QZ Tray aberto a impressão não funciona — e é daí que vêm quase todas as falhas ("não imprime", "falha na conexão"). Este artigo mostra como instalar, configurar a impressora por tipo de documento, testar e resolver os erros mais comuns.
Índice
- O que é o QZ Tray e por que preciso dele?
- Pré-requisitos: instalar a impressora e o QZ Tray
- Como configurar as impressoras no idworks
- Onde a impressão pelo QZ Tray é usada
- Erros mais comuns e como resolver
- A etiqueta não imprime automaticamente
- Erro status 500 ao imprimir (não é o QZ Tray)
- Saem 2 ou 3 etiquetas (cópia a mais)
- Erro de token ao tirar etiqueta do marketplace
- Perguntas frequentes
O que é o QZ Tray e por que preciso dele?
O QZ Tray é um pequeno aplicativo que roda no seu computador (fica com um ícone na bandeja do sistema, ao lado do relógio) e recebe do idworks o que precisa ser impresso, repassando para a impressora instalada na máquina. Ele precisa estar instalado e aberto sempre que você for imprimir. O idworks se comunica com ele de forma assinada/autenticada — você não precisa liberar nenhum site "não confiável"; basta o QZ Tray estar rodando.
Pré-requisitos: instalar a impressora e o QZ Tray
- Instale a impressora no computador (no Windows) e imprima uma página de teste pelo próprio Windows para confirmar que o equipamento está funcionando.
- Baixe e instale o QZ Tray: copie e cole no seu navegador o endereço https://qz.io/download/, baixe a versão do seu sistema operacional e instale normalmente.
- Abra o QZ Tray. Ele fica rodando em segundo plano (ícone na bandeja). Deixe-o aberto sempre que for imprimir — se ele fechar, a impressão para.
Dica: configure o QZ Tray para iniciar junto com o Windows, assim ele já sobe quando o computador liga e ninguém esquece de abri-lo.
Como configurar as impressoras no idworks
📍 Onde: menu Configurações → Configuração de Impressoras.
O idworks separa a impressora por tipo de documento, na janela Configuração de Impressoras. Os tipos são:
- Impressora A4 — documentos em folha.
- Impressora de Etiquetas
- Impressora ZPL — etiquetas térmicas em ZPL.
- Impressora Térmica — cupons.
- Outras
Você informa a impressora digitando o nome dela em cada tipo — e o nome precisa ser exatamente o mesmo que aparece no Windows.
Passo a passo:
- Descubra o nome exato da impressora no Windows: em Configurações → Bluetooth e dispositivos → Impressoras e scanners (ou Painel de Controle → Dispositivos e Impressoras). Anote o nome exatamente como está escrito.
- Com o QZ Tray aberto, em Configurações → Configuração de Impressoras, digite esse nome no campo do tipo de documento correspondente (ex.: Impressora de Etiquetas, Impressora ZPL).
- Salve a configuração.
⚠️ O nome digitado precisa bater exatamente com o do Windows — maiúsculas/minúsculas, espaços e acentos. Um nome errado ou desatualizado gera, na hora de imprimir, o erro "Nenhuma impressora definida foi encontrada, verifique o nome digitado".
A configuração fica salva no navegador daquele computador, não na sua conta. Se você trocar de computador ou de navegador, precisa refazer a configuração nele. Em operações com várias estações (vários caixas, WMS), configure a impressora em cada máquina.
Onde a impressão pelo QZ Tray é usada
O QZ Tray atende as telas que imprimem etiqueta ou cupom, entre elas:
- Pedidos — etiqueta de envio (ZPL) e etiqueta de devolução.
- Logística → Packing — etiquetas de expedição.
- PDV (Frente de Caixa) — cupom de venda, comprovante TEF e ajuste de caixa.
- Produtos (SKUs) — etiqueta do produto.
Erros mais comuns e como resolver
As mensagens abaixo são as que o idworks mostra na tela ao tentar imprimir. Elas indicam exatamente onde está o problema:
| Mensagem | O que significa | Como resolver |
|---|---|---|
| "Falha na conexão com o QZ Tray. Certifique-se de que ele está aberto e acessível." | O QZ Tray não está rodando (fechado, não iniciou, ou foi encerrado). | Abra o QZ Tray (ícone na bandeja) e tente imprimir de novo. É a causa nº 1 de "não imprime". |
| "Nenhuma impressora padrão foi encontrada." | Nenhuma impressora foi selecionada no idworks e o Windows não tem impressora padrão definida. | Selecione a impressora na Configuração de Impressoras, ou defina uma impressora padrão no Windows. |
| "Nenhuma impressora definida foi encontrada, verifique o nome digitado." | O nome digitado não corresponde a nenhuma impressora do Windows (erro de digitação, ou a impressora mudou de nome — trocou de PC, reinstalou o driver, renomeou). | Confira o nome exato da impressora no Windows e digite igual no campo do idworks (maiúsculas, espaços e acentos). |
| "Erro ao enviar dados para a impressora." | O QZ Tray conectou, mas a impressora recusou o trabalho (offline, sem papel, driver travado). | Confira se a impressora está ligada, com papel e sem erro; imprima um teste pelo Windows; reinstale o driver se necessário. |
A etiqueta não imprime automaticamente
Se a impressão parou de sair sozinha (ou você precisa insistir a cada pedido), quase sempre é o QZ Tray fechado — ele encerra ao reiniciar o computador. Deixe-o aberto (e configurado para iniciar com o Windows). Se mesmo aberto não sair, confira em Configuração de Impressoras se o nome da impressora continua igual ao do Windows.
Erro status 500 ao imprimir (não é o QZ Tray)
O QZ Tray só produz as quatro mensagens da tabela acima. Um erro 500 ao gerar a etiqueta é um erro do servidor montando o documento (ou buscando a etiqueta na integração do marketplace) — não é a impressão local. Nesse caso, reprocesse o pedido/etiqueta; se persistir, é caso de suporte. Mexer no QZ Tray não resolve um erro 500.
Saem 2 ou 3 etiquetas (cópia a mais)
A quantidade de vias impressas não é definida no QZ Tray — é uma parametrização do idworks. Ajuste o número de cópias em Parametrizações.
Erro de token ao tirar etiqueta do marketplace
Quando o erro cita token e um marketplace (Magalu, Mercado Livre, Shopee), a etiqueta não voltou da integração do marketplace — também não é o QZ Tray. Consulte o artigo de erros do canal correspondente, por exemplo Mercado Livre — erros.
Perguntas frequentes
- Preciso deixar o QZ Tray sempre aberto? Sim. Sem ele aberto, a impressão não funciona. Configure-o para iniciar junto com o Windows.
- Configurei num computador e no outro não imprime. A configuração fica no navegador de cada máquina. Refaça a Configuração de Impressoras no outro computador.
- Troquei a impressora ou o nome dela mudou. Abra a Configuração de Impressoras e atualize o nome para o novo (igual ao do Windows).
- Como desenho o layout da etiqueta? O modelo (ZPL/Canvas) é feito na tela de Etiquetas; a impressão em si é o que este artigo cobre.