Script de Impressão RUB (ZPL / Térmico)

O Script de Impressão RUB é o motor de template e execução de expressões do RuB para geração de etiquetas térmicas baseadas em comandos (como ZPL, EPL ou texto plano). Ele interpreta arquivos de layout (.etq), substituindo variáveis dinâmicas, avaliando diretivas condicionais, executando funções matemáticas e de formatação antes do envio ao writer de saída.

Para criação de cartazes promocionais gráficos, cartazetes e relatórios em folha A4/A3/A5 utilizando HTML5 e CSS, consulte o guia especializado em Modelos HTML e Relatórios.

graph TD
    A[Dados da Solicitação: Produto / Local / Conjunto] --> B[Script de Impressão RUB]
    T[Template de Comandos: .etq / ZPL / EPL] --> B
    B --> C{Processamento do Script}
    C -->|1. Interpolação de Variáveis| D["Substituição @VAR@ e ${VAR}"]
    C -->|2. Avaliação Condicional| E["Blocos #IF / #ELSIF / #ELSE"]
    C -->|3. Execução de Funções| F["Funções $INT, $FORMATN, etc."]
    D --> G[Fluxo de Comandos ZPL / EPL]
    E --> G
    F --> G
    G --> H[Writer de Saída: Impressora Térmica / TXT / Banco]

Sintaxe fundamental

O motor reconhece quatro tipos principais de elementos no arquivo de layout:

  1. Interpolação de variáveis: substituição direta do valor de uma variável no texto.
  2. Diretivas de controle: comandos de fluxo de execução iniciados por # no início da linha (#IF, #ELSIF, #ELSE, #END, #SET, #CALL).
  3. Funções embutidas: chamadas a funções do motor iniciadas por $ e terminadas por $, na sintaxe $NOME_FUNCAO(arg1, arg2, ...)$.
  4. Comentários: linhas iniciadas por #// são completamente ignoradas durante a renderização.

Interpolação de variáveis

O Script de Impressão RUB aceita três formatos equivalentes para interpolar variáveis:

  • @NOME@
  • @{NOME}
  • ${NOME}

Exemplo básico

^XA
^FO50,50^A0N,30,30^FDProduto: @SKU@^FS
^FO50,90^A0N,30,30^FDDescricao: ${DESCPRODUTO}^FS
^FO50,130^A0N,40,40^FDPreco: R$ @PRECO@^FS
^XZ

Se os dados da solicitação contiverem chaves literais no formato @CAMPO@ ou ${CAMPO}, esses valores terão precedência e sobrescreverão variáveis internas de mesmo nome.

Diretivas e estruturas de controle

As diretivas são interpretadas linha a linha quando posicionadas na primeira coluna (# no início da linha).

Declaração e atribuição de variáveis (#SET)

A diretiva #SET permite criar novas variáveis ou alterar o valor de variáveis existentes durante o processamento do template:

#SET DESCONTO_CALCULADO = NUM(PRECO_DE) - NUM(PRECO_POR)
#SET EXIBIR_PROMO = NUM(DESCONTO_CALCULADO) > 0

Chamada de expressões (#CALL)

Executa uma expressão ou função sem imprimir seu retorno diretamente na saída:

#CALL SET(VARIAVEL_AUXILIAR, "VALOR")

Comentários (#//)

Permite documentar o arquivo de layout sem que o comentário seja enviado para a impressora:

#// Layout de Etiqueta Promocional de Gondola - Revisao 2
#// Autor: Equipe de TI / Automacao Comercial
^XA
^FO50,50^A0N,30,30^FD@DESCPRODUTO@^FS
^XZ

Estrutura condicional e encadeamento de #IF

O motor suporta decisões condicionais completas através de #IF, #ELSIF, #ELSE e #END.

Diagrama de fluxo condicional

graph TD
    A[Início do Bloco #IF] --> B{Expressão #IF é verdadeira?}
    B -->|Sim| C[Renderiza Bloco 1]
    B -->|Não| D{#ELSIF é verdadeiro?}
    D -->|Sim| E[Renderiza Bloco 2]
    D -->|Não| F[Renderiza Bloco #ELSE]
    C --> G[Fim do Bloco #END]
    E --> G
    F --> G

Operadores suportados nas expressões

TipoOperadoresDescrição
Comparação==, !=, <, >, <=, >=Igualdade, diferença (!=), menor, maior, menor ou igual, maior ou igual.
Lógicos&&, ||, !E lógico, OU lógico (||), Negação lógica (!).
Aritméticos+, -, *, /, ^Soma, subtração, multiplicação, divisão, exponenciação.
Agrupamento( ... )Parênteses para precedência de operações.

Exemplo de encadeamento completo

^XA
^FO50,50^A0N,30,30^FD@DESCPRODUTO@^FS

#IF PRECO_PROMOCIONAL != "" && NUM(PRECO_PROMOCIONAL) > 0
#// Caso 1: Produto com promocao ativa
^FO50,90^A0N,25,25^FDDE: R$ @PRECO@^FS
^FO50,120^A0N,45,45^FDPOR: R$ @PRECO_PROMOCIONAL@^FS
^FO50,175^A0N,20,20^FDECONOMIZE: R$ $FORMATN("#,##0.00", NUM(PRECO) - NUM(PRECO_PROMOCIONAL))$^FS
#ELSIF EMB6_VALUE != "" && NUM(EMB6_VALUE) > 0
#// Caso 2: Sem promocao, mas possui preco de atacado (caixa com 6)
^FO50,90^A0N,40,40^FDUN: R$ @EMB1_VALUE@^FS
^FO50,135^A0N,30,30^FDLEVE 6+ POR: R$ @EMB6_VALUE@ CADA^FS
#ELSE
#// Caso 3: Preco regular padrao
^FO50,90^A0N,50,50^FDR$ @PRECO@^FS
#END

^XZ

Aninhamento de #IF (IF dentro de IF)

É possível aninhar blocos condicionais para regras de negócio com múltiplos níveis de decisão:

^XA
#IF PESO_VARIAVEL == true
    ^FO50,50^A0N,30,30^FD@DESCPRODUTO@ (KG)^FS
    #IF NUM(PRECO) > 100.00
        ^FO50,90^A0N,25,25^FDAviso: Produto de Alto Valor^FS
    #END
#ELSE
    ^FO50,50^A0N,30,30^FD@DESCPRODUTO@ (UN)^FS
#END
^XZ

Funções embutidas do motor

Todas as funções do motor são invocadas utilizando a sintaxe $NOME_FUNCAO(arg1, arg2, ...)$. Elas podem ser utilizadas diretamente no corpo do layout para gerar texto formatado ou no interior de diretivas condicionais (#IF, #ELSIF, #SET).

1. $CAT(...) — Concatenação de Textos

Concatena múltiplos argumentos (textos literais, variáveis e retornos de outras funções) em uma única cadeia de texto contínua.

  • Assinatura: $CAT(arg1, arg2, arg3, ...)$
  • Parâmetros: Quantidade arbitrária de textos, variáveis ou expressões.

Exemplo no template ZPL:

^FO50,50^A0N,25,25^FD$CAT("Ref: ", @SKU@, " | Forn: ", @FORNECEDOR_NOME@, " (", @FORNECEDOR_CODIGO@, ")")$^FS

Resultado gerado:

^FO50,50^A0N,25,25^FDRef: 102030 | Forn: INDÚSTRIA ALIMENTÍCIA S.A. (504)^FS

2. $OR(...) — Primeiro Valor Válido

Avalia os argumentos sequencialmente da esquerda para a direita e retorna o primeiro valor que não seja nulo, vazio ou resultado de erro.

  • Assinatura: $OR(valor1, valor2, ...)
  • Parâmetros: Dois ou mais valores/variáveis para resolução em cascata.

Exemplo no template ZPL:

#// Exibe o preco promocional se existir; senao exibe o preco regular
^FO50,100^A0N,40,40^FDR$ $OR(@PRECO_PROMOCIONAL@, @PRECO@)$^FS

Resultado gerado:

  • Se PRECO_PROMOCIONAL estiver preenchido com 12,90: ^FO50,100^A0N,40,40^FDR$ 12,90^FS
  • Se PRECO_PROMOCIONAL estiver vazio e PRECO for 15,90: ^FO50,100^A0N,40,40^FDR$ 15,90^FS

3. $NVL(...) — Coalescência de Nulos / Valor Padrão

Avalia uma variável ou expressão e, caso seja nula ou vazia, retorna o valor padrão alternativo informado no argumento seguinte. Suporta referências com ${VAR}.

  • Assinatura: $NVL(expressaoOuVariavel, valorPadrao)

Exemplo no template ZPL:

^FO50,80^A0N,22,22^FDComplemento: $NVL("${COMPLEMENTO}", "NENHUM")$^FS

Resultado gerado:

  • Se COMPLEMENTO for vazio: ^FO50,80^A0N,22,22^FDComplemento: NENHUM^FS
  • Se COMPLEMENTO contiver SABOR MORANGO: ^FO50,80^A0N,22,22^FDComplemento: SABOR MORANGO^FS

4. $NUM(...) — Conversão de Texto Formatado para Número

Converte uma representação textual de valor formatado (com separador decimal , e de milhar .) em um tipo numérico nativo. É essencial para realizar cálculos matemáticos e comparações numéricas (>, <, etc.) em diretivas #IF.

  • Assinatura: $NUM(valorFormatado)

Exemplo no template ZPL:

#// Compara numericamente o preco promocional com o preco regular
#IF NUM(PRECO_PROMOCIONAL) > 0 && NUM(PRECO_PROMOCIONAL) < NUM(PRECO)
^FO50,120^A0N,25,25^FDOFERTA ESPECIAL!^FS
#END

Resultado gerado:

Converte internamente strings como "1.450,90" para o valor 1450.90, permitindo avaliações aritméticas e comparações precisas.

5. $INT(...) — Extração da Parte Inteira

Retorna exclusivamente os dígitos inteiros de um número ou valor de preço, descartando as casas decimais sem arredondar.

  • Assinatura: $INT(valorNumericoOuString)

Exemplo no template ZPL:

#// Imprime o valor em reais em tamanho grande
^FO50,100^A0N,80,70^FD$INT(PRECO)$^FS

Resultado gerado:

  • Para PRECO = 49,90: ^FO50,100^A0N,80,70^FD49^FS

6. $DEC(...) — Extração da Parte Fracionária / Centavos

Retorna a parte decimal (centavos) de um número, formatada com a quantidade especificada de dígitos (padrão: 2 casas decimais).

  • Assinatura: $DEC(valorNumerico, [casasDecimais])
  • Parâmetros: valorNumerico (obrigatório) e casasDecimais (opcional, padrão 2).

Exemplo no template ZPL:

#// Imprime a virgula e os centavos menores e elevados
^FO160,105^A0N,35,35^FD,$DEC(PRECO, 2)$^FS

Resultado gerado:

  • Para PRECO = 49,90: ^FO160,105^A0N,35,35^FD,90^FS
  • Para PRECO = 5,00: ^FO160,105^A0N,35,35^FD,00^FS

7. $FORMATN(...) — Formatação Numérica Customizada

Formata um número conforme a máscara padrão do Java (DecimalFormat), aplicando os separadores decimais (EtiquetaSeparador) e de milhares (EtiquetaSeparadorMilhar) configurados no RuB.

  • Assinatura: $FORMATN(mascara, valorNumerico)
  • Exemplos de máscaras: #,##0.00, 0.000, #,##0.

Exemplo no template ZPL:

#// Calcula e formata a economia da promocao
^FO50,150^A0N,22,22^FDEconomize: R$ $FORMATN("#,##0.00", NUM(PRECO) - NUM(PRECO_PROMOCIONAL))$^FS

Resultado gerado:

  • Se PRECO = 100,00 e PRECO_PROMOCIONAL = 75,50: ^FO50,150^A0N,22,22^FDEconomize: R$ 24,50^FS

8. $FORMATDATE(...) — Conversão e Formatação de Datas

Converte uma data textual de um formato de origem (formatoOrigem) para um novo padrão de exibição (formatoDestino), utilizando a convenção SimpleDateFormat (ex: yyyy-MM-dd, dd/MM/yyyy).

  • Assinatura: $FORMATDATE(formatoDestino, formatoOrigem, dataString)

Exemplo no template ZPL:

^FO50,180^A0N,20,20^FDValidade: $FORMATDATE("dd/MM/yyyy", "yyyy-MM-dd", @DATA_VALIDADE@)$^FS

Resultado gerado:

  • Se DATA_VALIDADE for 2026-12-31: ^FO50,180^A0N,20,20^FDValidade: 31/12/2026^FS

Exemplos práticos avançados com protótipos de saída

Abaixo estão exemplos completos de templates ZPL combinando variáveis, condicionais, funções e propriedades extras, acompanhados do protótipo visual de como a etiqueta impressa é renderizada na gôndola.

Exemplo 1: Etiqueta de gôndola com preço fracionado (Inteiro grande e Decimal pequeno)

Em layouts de varejo, é comum imprimir a parte inteira do preço em tamanho grande e os centavos em tamanho menor:

Template ZPL com Script de Impressão RUB:

^XA
^FO40,30^A0N,28,28^FD@DESCPRODUTO@^FS
^FO40,65^A0N,20,20^FDCod: @SKU@ | Forn: @FORNECEDOR_NOME@^FS
#// Preco fracionado: R$ + Inteiro grande + Centavos elevado
^FO40,110^A0N,30,30^FDR$^FS
^FO85,90^A0N,75,70^FD$INT(PRECO)$^FS
^FO220,95^A0N,35,35^FD,$DEC(PRECO, 2)$^FS
#// Codigo de barras
^FO40,180^BY2^BCN,50,Y,N,N^FD@MENOR_EMB_CODIGO_1@^FS
^XZ

Protótipo visual da etiqueta impressa:

+-----------------------------------------------------------+
| SABÃO EM PÓ BRILHO TOTAL 1KG                              |
| Cod: 45892 | Forn: INDÚSTRIA QUÍMICA NACIONAL             |
|                                                           |
| R$  24 ,99                                                |
|                                                           |
| |||||| |||||||||||||| |||||||||||| |||||||                |
| 7891000123456                                             |
+-----------------------------------------------------------+

Exemplo 2: Etiqueta de produto com propriedade extra e preço atacado

Uso de propriedades dinâmicas (PROP_MARCA, PROP_VOLTAGEM) e embalagem ordenada (EMB_2O):

Template ZPL:

^XA
^FO40,30^A0N,30,30^FD@DESCPRODUTO@^FS
#IF PROP_MARCA != ""
^FO40,65^A0N,22,22^FDMarca: @PROP_MARCA@^FS
#END
#IF PROP_VOLTAGEM != ""
^FO250,65^A0N,22,22^FDVoltagem: @PROP_VOLTAGEM@^FS
#END

#// Preco unitario da 1a menor embalagem
^FO40,105^A0N,25,25^FDUNIDADE:^FS
^FO40,135^A0N,45,45^FDR$ @EMB_1O_VALUE@^FS

#// Se existir 2a embalagem (ex: fardo/caixa), exibe preco diferenciado
#IF EMB_2O_VALUE != "" && NUM(EMB_2O_VALUE) > 0
^FO250,105^A0N,22,22^FD@EMB_2O_DESC@ (@EMB_2O_QTD@ UN):^FS
^FO250,130^A0N,35,35^FDR$ @EMB_2O_TOTAL@^FS
^FO250,170^A0N,20,20^FD(R$ @EMB_2O_VALUE@ cada)^FS
#END

^FO40,210^BY2^BCN,45,Y,N,N^FD@EMB_1O_CODIGO_1@^FS
^XZ

Protótipo visual da etiqueta impressa:

+-----------------------------------------------------------+
| REFRIGERANTE COLA LATA 350ML                              |
| Marca: COCA-COLA       Voltagem: BIVOLT                   |
|                                                           |
| UNIDADE:               FARDO C/ 12 (12 UN):               |
| R$ 4,50                R$ 48,00                           |
|                        (R$ 4,00 cada)                     |
|                                                           |
| |||||| |||||||||||||| |||||||||||| |||||||                |
| 7894900011517                                             |
+-----------------------------------------------------------+

Exemplo 3: Etiqueta de identificação de Local

Template ZPL utilizando as variáveis exclusivas do contexto de local:

Template ZPL:

^XA
^FO50,40^A0N,40,40^FDENDERECO: @CODIGO@^FS
^FO50,90^A0N,25,25^FD@DESCRICAO@^FS
#IF LOCAL_CLASSE_PRODUTO != ""
^FO50,125^A0N,20,20^FDSetor: @LOCAL_CLASSE_PRODUTO@^FS
#END
^FO50,165^BY3^BCN,80,Y,N,N^FD@BARCODE@^FS
^XZ

Protótipo visual da etiqueta impressa:

+-----------------------------------------------------------+
| ENDEREÇO: A-01-04-02                                      |
| CORREDOR A - PRATELEIRA 4 - NIVEL 2                       |
| Setor: BEBIDAS / REFRIGERANTES                            |
|                                                           |
| |||||||||||| |||||||||||||||||||| |||||||||||||           |
| A-01-04-02                                                |
+-----------------------------------------------------------+

Exemplo 4: Etiqueta de Conjunto (Kit de Produtos)

Template para identificação de kit promocional agrupado:

Template ZPL:

^XA
^FO40,30^A0N,32,32^FDKIT PROMOCIONAL #@CODIGO_CONJUNTO@^FS
^FO40,70^A0N,22,22^FDLoja: @LOJA@ (ID: @ID_LOJA@)^FS
^FO40,100^A0N,22,22^FDTotal de Itens: @TOTAL_PRODUTOS_CONJUNTO@ produtos^FS
^FO40,140^BY2^BCN,60,Y,N,N^FD@CODIGO_CONJUNTO@^FS
^FO40,220^A0N,18,18^FDEmitido em: @DTH_ATUAL@^FS
^XZ

Protótipo visual da etiqueta impressa:

+-----------------------------------------------------------+
| KIT PROMOCIONAL #KIT-CHURRASCO-01                         |
| Loja: HIPERMERCADO CENTRAL (ID: 101)                      |
| Total de Itens: 4 produtos                                |
|                                                           |
| |||||||||||| |||||||||||||||||||| |||||||||||||           |
| KIT-CHURRASCO-01                                          |
| Emitido em: 24/08/2026 18:30:00                           |
+-----------------------------------------------------------+

Configurações do motor de script

As seguintes configurações em ConfigEtiqueta influenciam diretamente a formatação numérica no motor:

PropriedadePadrãoDescrição
ConfigEtiqueta.PRECO_ETIQUETA_SEPARADOR,Caractere usado como separador decimal ao formatar preços e saídas de $FORMATN.
ConfigEtiqueta.PRECO_ETIQUETA_SEPARADOR_MILHAR.Caractere usado como separador de milhares. Se vazio, o agrupamento de milhar é desativado.