Converter PDF para ZPL

Esta API converte documentos PDF em ZPL que impressoras Zebra conseguem imprimir. Ela suporta PDFs de várias páginas e pode recortar, rotacionar e escalar cada página antes da conversão.

Usos típicos incluem imprimir etiquetas de envio de transportadoras, romaneios e outros PDFs que não foram desenhados como ZPL.

Uso da API

Endpoint: POST https://html-to-zpl.p.rapidapi.com/pdf2zpl

Defina a chave da API do Rapid API no cabeçalho X-RapidAPI-Key.

Envie os parâmetros no corpo do POST como JSON (Content-Type: application/json) ou como campos de formulário (Content-Type: application/x-www-form-urlencoded). A resposta é ZPL bruto.

Parâmetros obrigatórios

Parâmetro	Descrição	Exemplo
width	Largura da etiqueta, na unidade definida por unit (polegadas por padrão).	4
height	Altura da etiqueta, na unidade definida por unit (polegadas por padrão).	6
pdfBase64	O arquivo PDF, codificado como uma única string base64 (sem prefixo de data-URL e sem quebras de linha).	Baixar amostra

Seleção de páginas, escala e rotação

Parâmetro	Obrigatório	Descrição	Exemplo
pages	opcional	Quais páginas converter. Aceita: um único número de página (1 é a primeira página) uma lista separada por vírgulas (1,3,5) all para todas as páginas O padrão é 1. Cada página convertida vira a sua própria etiqueta ZPL na resposta.	all
scale	opcional	Como a página PDF (já recortada, se houver recorte) é ajustada à etiqueta: none (padrão) — sem redimensionar. O gráfico ZPL tem o tamanho da página PDF depois do recorte. contain — cabe a página inteira na etiqueta, preserva a proporção e adiciona margens se necessário. cover — preenche a etiqueta, preserva a proporção. As bordas que ultrapassam a etiqueta são cortadas. fill — estica até a etiqueta. A proporção não é preservada. fitToWidth — corresponde à largura da etiqueta, preserva a proporção. fitToHeight — corresponde à altura da etiqueta, preserva a proporção.	contain
rotate	opcional	Rotaciona o resultado. Um de 0 (padrão), 90 (direita), 180, 270 (esquerda).	90
unit	opcional	Unidade de width, height e dos parâmetros de recorte. Um de: in (padrão) — polegadas mm — milímetros dots — pontos da impressora no dpi solicitado	in

cover pode cortar bordas como efeito colateral do enquadramento. Isso é diferente dos parâmetros de recorte abaixo, que removem de propósito as margens da página PDF antes da escala.

Recortar páginas PDF

Use cropLeft, cropRight, cropTop e cropBottom para cortar uma margem de cada lado da página PDF. Lados omitidos valem 0. Os valores são números não negativos na mesma unit de width e height (polegadas por padrão).

O recorte vale só para PDF. O caminho de conversão HTML ignora esses parâmetros.

Quando recortar

• PDFs de etiqueta de envio com espaço em branco extra ou um cabeçalho acima da etiqueta 4×6
• Páginas com margens não imprimíveis que você não quer no adesivo
• Documentos carta ou A4 em que só a região interna deve ser impressa

Parâmetro	Obrigatório	Descrição	Exemplo
cropLeft	opcional	Quantidade a remover da borda esquerda da página PDF.	0.25
cropRight	opcional	Quantidade a remover da borda direita.	0.25
cropTop	opcional	Quantidade a remover da borda superior.	0.5
cropBottom	opcional	Quantidade a remover da borda inferior.	0.25

Ordem das operações

1. A página PDF selecionada é rasterizada no dpi solicitado.
2. Cada lado de recorte é cortado desse raster. O recorte usa a orientação original da página, não o resultado rotacionado.
3. scale ajusta o que restou em width × height.
4. rotate é aplicado por último.

Como o recorte roda antes da escala:

• scale=contain (o caso típico) — o conteúdo restante é ampliado para preencher a etiqueta. Use isso quando você removeu espaço em branco e ainda quer um adesivo 4×6 (ou outro tamanho) completo.
• scale=none (padrão da API) — o gráfico ZPL encolhe na mesma medida do recorte. Uma página 4×6 recortada em 0,25″ de cada lado vira uma etiqueta 3,5×5,5.

Mantenha a largura e a altura restantes positivas. Recortar mais do que o tamanho da página produz um resultado vazio ou inválido.

dica

Experimente o recorte na demonstração online de PDF para ZPL. Carregue a etiqueta de envio de amostra, escolha uma predefinição como ¼″ e compare a pré-visualização com e sem recorte.

Exemplo JSON — recortar um quarto de polegada de cada lado e encaixar o restante em uma etiqueta 4×6:

{
  "width": 4,
  "height": 6,
  "scale": "contain",
  "cropLeft": 0.25,
  "cropRight": 0.25,
  "cropTop": 0.25,
  "cropBottom": 0.25,
  "pdfBase64": "JVBERi0xLjcK..."
}

Só o topo de uma página (por exemplo um cabeçalho de 1″):

{
  "width": 4,
  "height": 6,
  "scale": "contain",
  "cropTop": 1,
  "pdfBase64": "JVBERi0xLjcK..."
}

Configurações de qualidade de impressão

Parâmetro	Obrigatório	Descrição	Exemplo
darkness	opcional	Inteiro de 0 a 30. Define a escuridão da impressora, o mesmo ajuste da interface web ou do driver Zebra.	15
dpi	opcional	Resolução da impressora: 203 (padrão) — 203 dpi / 8 dpmm, usado pela maioria das impressoras Zebra 300 — 300 dpi / 12 dpmm 600 — 600 dpi / 24 dpmm	203
speed	opcional	Velocidade de impressão em polegadas por segundo, inteiro de 2 a 12. Equivale à taxa de impressão na interface web ou no driver Zebra.	2

dica

Reduzir a velocidade de impressão melhora a qualidade, especialmente para fontes pequenas e códigos de barras.

Exemplo de linha de comando (curl)

Baixe uma amostra de PDF de etiqueta de envio 4×6″:

wget https://www.htmltozpl.com/img/sample-label.pdf

Codifique-o em base64. No Linux, -w0 omite quebras de linha. No macOS, o base64 já não quebra a linha por padrão:

base64 -w0 sample-label.pdf > sample-label.base64

Você deve ter agora um arquivo sample-label.base64 com uma única string ASCII longa. Você pode baixar nossa referência para comparar.

Envie esse arquivo para a API como JSON. $(cat sample-label.base64) insere a string base64 no campo pdfBase64. Substitua API_KEY pela sua chave do Rapid API.

curl --request POST \
	 --url https://html-to-zpl.p.rapidapi.com/pdf2zpl \
	 --header 'content-type: application/json' \
	 --header 'x-rapidapi-host: html-to-zpl.p.rapidapi.com' \
	 --header 'x-rapidapi-key: API_KEY' \
	 --data "{
	 	\"width\": 4,
	 	\"height\": 6,
	 	\"pdfBase64\": \"$(cat sample-label.base64)\"
	 }" \
> sample-label.zpl

Com recorte — remover 0,25″ de cada lado e então escalar o conteúdo restante de volta para a etiqueta 4×6:

curl --request POST \
	 --url https://html-to-zpl.p.rapidapi.com/pdf2zpl \
	 --header 'content-type: application/json' \
	 --header 'x-rapidapi-host: html-to-zpl.p.rapidapi.com' \
	 --header 'x-rapidapi-key: API_KEY' \
	 --data "{
	 	\"width\": 4,
	 	\"height\": 6,
	 	\"scale\": \"contain\",
	 	\"cropLeft\": 0.25,
	 	\"cropRight\": 0.25,
	 	\"cropTop\": 0.25,
	 	\"cropBottom\": 0.25,
	 	\"pdfBase64\": \"$(cat sample-label.base64)\"
	 }" \
> sample-label-cropped.zpl

Se a solicitação for bem-sucedida, sample-label.zpl contém ZPL que você pode enviar a uma impressora de rede com netcat no macOS ou Linux:

nc -N 192.168.1.234 9100 < sample-label.zpl

No Windows, use o PowerShell:

$client = New-Object System.Net.Sockets.TcpClient("192.168.1.234", 9100)
$stream = $client.GetStream()
$bytes = [System.IO.File]::ReadAllBytes("sample-label.zpl")
$stream.Write($bytes, 0, $bytes.Length)
$stream.Close()
$client.Close()

Esta é a etiqueta resultante impressa em uma Zebra GK420t:

Configuração do Postman

Consulte as seguintes capturas de tela para detalhes de configuração do Postman: