ZappLabel REST API

Integre conversão térmica nativa (ZPL) de alta velocidade diretamente na infraestrutura do seu ERP, WMS ou plataforma de e-commerce. A API processa páginas, fatia quadrantes e aplica algoritmos Hex-Compressive em tempo real.

💡 As URLs são amigáveis: você pode omitir a extensão .php nos endpoints (ex: /convert ou /render).

O endpoint base para todas as chamadas é: https://api.zapplabel.test/api/v1

Autenticação & Limites de Taxa

ZappLabel é autenticado via Chaves de API. Você pode gerar e revogar chaves ilimitadas dentro do seu Dashboard. Inclua sua Chave de API no cabeçalho `Authorization` como um token Bearer.

docs_auth_rate_limit_warning

HTTP HEADERS

Authorization: Bearer zpk_live_a1b2c3d4e5f6g7h8i9j0
Accept: application/json
Content-Type: multipart/form-data

POST POST /convert.php

Envia um ou múltiplos arquivos (PDF, PNG, JPG) de etiquetas e devolve o código ZPL purificado e processado. O Content-Type deve obrigatoriamente ser multipart/form-data.

Parâmetro	Tipo	Descrição
`document`	Arquivo (PDF/IMG)	Required. Obrigatório. O arquivo de etiqueta que você deseja converter. Máx 10MB.
`widthCm`	Integer	Largura em centímetros (cm). Padrão: `10`.
`heightCm`	Integer	Altura em centímetros (cm). Padrão: `15`.
`cropMode`	String	Opções: `none`, `ml`, `shopee`, `custom` (Pro+). Padrão é `none`. Extrai etiquetas menores de folhas A4 dinamicamente.
`cropRows` & `cropCols`	Integer	Apenas necessário se `cropMode=custom`. Define a matriz de etiquetas na folha A4.
`blackLimit`	Integer	Limite de contraste (1-100). Valores mais altos deixam a impressão mais escura. Padrão `50`.
`compressHex`	Boolean	Produz ZPL altamente condensado via mapas hexadecimais. Recurso Pro+. Padrão `true`.

cURL

curl -X POST https://api.zapplabel.test/api/v1/convert \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -F "document=@/path/to/invoice_shopee.pdf" \
 -F "widthCm=10" \
 -F "heightCm=15" \
 -F "cropMode=shopee" \
 -F "compressHex=true"

PHP

<?php
$apiKey = 'YOUR_API_KEY';
$filePath = '/path/to/invoice_shopee.pdf';

$ch = curl_init('https://api.zapplabel.test/api/v1/convert');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
 "Authorization: Bearer " . $apiKey
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, [
 'document' => new CURLFile($filePath),
 'widthCm' => 10,
 'heightCm' => 15,
 'cropMode' => 'shopee',
 'compressHex' => true
]);

$response = curl_exec($ch);
curl_close($ch);

echo $response;

JavaScript

// Node.js with node-fetch or browser with fetch
const apiKey = 'YOUR_API_KEY';
const formData = new FormData();
formData.append('document', file); // file from  or Blob
formData.append('widthCm', 10);
formData.append('heightCm', 15);
formData.append('cropMode', 'shopee');
formData.append('compressHex', true);

 fetch('https://api.zapplabel.test/api/v1/convert', {
 method: 'POST',
 headers: {
 'Authorization': `Bearer ${apiKey}`
 },
 body: formData
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));

Python

import requests

api_key = 'YOUR_API_KEY'
url = 'https://api.zapplabel.test/api/v1/convert'
file_path = '/path/to/invoice_shopee.pdf'

with open(file_path, 'rb') as f:
 files = {'document': f}
 data = {
 'widthCm': 10,
 'heightCm': 15,
 'cropMode': 'shopee',
 'compressHex': True
 }
 headers = {'Authorization': f'Bearer {api_key}'}
 
 response = requests.post(url, files=files, data=data, headers=headers)
 print(response.json())

Exemplo de Resposta (200 OK):

JSON

{
  "message": "Conversão realizada com sucesso",
  "pagesConverted": 4,
  "zpl": "^XA^FX...^FS^XZ\n^XA^FX...^FS^XZ",
  "previews": ["data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ..."]
}

POST POST /render

O endpoint de emulação Server-Side nativo do ZappLabel. Recebe códigos estritos em ZPL (ASCII) e renderiza visualmente o resultado vetorial para imagens Base64 (PNG), permitindo que você exiba etiquetas já prontas em sua própria tela. O Content-Type deve ser explícito string ou raw body.

Parâmetro	Tipo	Descrição
`body`	String (Raw)	Obrigatório. Uma string formatada contendo código válido da Zebra, encapsulada dentro de limites `^XA` e `^XZ`. Múltiplos limites forçam paginação automática (Lote).

cURL

curl -X POST https://api.zapplabel.test/api/v1/render \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: text/plain" \
 -d '^XA^FO50,50^A0N,36,20^FDTexto de Exemplo^FS^XZ'

PHP

<?php
$apiKey = 'YOUR_API_KEY';
$zpl = '^XA^FO50,50^A0N,36,20^FDTexto de Exemplo^FS^XZ';

$ch = curl_init('https://api.zapplabel.test/api/v1/render');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
 "Authorization: Bearer " . $apiKey,
 "Content-Type: text/plain"
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, $zpl);

$response = curl_exec($ch);
curl_close($ch);

echo $response;

JavaScript

const apiKey = 'YOUR_API_KEY';
const zpl = '^XA^FO50,50^A0N,36,20^FDTexto de Exemplo^FS^XZ';

 fetch('https://api.zapplabel.test/api/v1/render', {
 method: 'POST',
 headers: {
 'Authorization': `Bearer ${apiKey}`,
 'Content-Type': 'text/plain'
 },
 body: zpl
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));

Python

import requests

api_key = 'YOUR_API_KEY'
url = 'https://api.zapplabel.test/api/v1/render'
zpl = '^XA^FO50,50^A0N,36,20^FDTexto de Exemplo^FS^XZ'

headers = {
 'Authorization': f'Bearer {api_key}',
 'Content-Type': 'text/plain'
}

response = requests.post(url, headers=headers, data=zpl)
print(response.json())

Exemplo de Resposta (200 OK):

JSON

{
  "message": "Renderização ZPL concluída com sucesso.",
  "pagesRendered": 1,
  "images": [
      "data:image/png;base64,iVBORw0KGgoAAAANSUhX..."
  ]
}

Uso & Limites

Verifique seu uso da API e limites do plano via dashboard ou endpoints da API (em breve).

Códigos de Erro

Códigos de erro comuns e guia de solução de problemas serão documentados aqui.