Перейти к контенту

документация API

Одну конечную точку для рендеринга ZPL в PNG или PDF. Она совместима с API v1 от Labelary: те же пути, заголовки и ошибки.

Рендеринг ярлыка

GET  https://api.openzpl.com/v1/printers/{dpmm}/labels/{width}x{height}/{index}/{zpl}
POST https://api.openzpl.com/v1/printers/{dpmm}/labels/{width}x{height}/{index}
POST https://api.openzpl.com/v1/printers/{dpmm}/labels/{width}x{height}/
dpmmПлотность печати: 6dpmm, 8dpmm, 12dpmm, 24dpmm.
width, heightРазмер метки в дюймах, например 4x6 или 2.25x1.25. До 15 дюймов каждая.
indexКакой ярлык отобразить, начиная с 0. Опустите это для PDF-вывода, чтобы получить каждый ярлык, по одному на странице.
zplДля GET, URL-кодированный ZPL. Кодируйте # как %23. Используйте POST для всего длинного.

С помощью POST отправьте ZPL как необработанное содержимое запроса или как поле многокомпонентной формы с именем file.

Ключи API

Без ключа вы получите бесплатные лимиты на IP-адрес. С ключом из вашей панели управления отправьте его в заголовке X-API-Key, и применятся лимиты вашего тарифного плана рабочего пространства.

curl https://api.openzpl.com/v1/printers/8dpmm/labels/4x6/0/ \
  -H "X-API-Key: oz_live_…" --data-binary @label.zpl > label.png

Примеры

# PNG from a short ZPL string
curl --get https://api.openzpl.com/v1/printers/8dpmm/labels/4x6/0/ \
  --data-urlencode "^xa^cfa,50^fo100,100^fdHello World^fs^xz" > label.png

# PDF with every label in a file
curl https://api.openzpl.com/v1/printers/8dpmm/labels/4x6/ \
  -H "Accept: application/pdf" --form file=@labels.zpl > labels.pdf
import requests

zpl = "^xa^cfa,50^fo100,100^fdHello World^fs^xz"
res = requests.post("https://api.openzpl.com/v1/printers/8dpmm/labels/4x6/0/", data=zpl)
res.raise_for_status()
open("label.png", "wb").write(res.content)
const zpl = "^xa^cfa,50^fo100,100^fdHello World^fs^xz";
const res = await fetch("https://api.openzpl.com/v1/printers/8dpmm/labels/4x6/0/", {
  method: "POST",
  headers: { Accept: "application/pdf" },
  body: zpl,
});
await require("fs/promises").writeFile("label.pdf", Buffer.from(await res.arrayBuffer()));
$zpl = "^xa^cfa,50^fo100,100^fdHello World^fs^xz";
$ch = curl_init("https://api.openzpl.com/v1/printers/8dpmm/labels/4x6/0/");
curl_setopt_array($ch, [CURLOPT_POST => true, CURLOPT_POSTFIELDS => $zpl, CURLOPT_RETURNTRANSFER => true]);
file_put_contents("label.png", curl_exec($ch));

Заголовки запроса

ЗаголовокЗначенияПо умолчанию
Acceptimage/png, application/pdfPNG
X-QualityGrayscale (8-бит, гладкие края) или Bitonal (1-бит, меньшие файлы)Grayscale
X-Rotation0, 90, 180, 270, по часовой стрелке0
X-API-KeyКлюч вашего рабочего пространства, необязательный—

Ограничения

  • Free, no sign-up and no key: 3 requests per second and 5,000 labels per UTC day, per IP address.
  • Labels, not requests, count against the daily allowance: every label rendered, ^PQ copies and PDF pages included. A 10-label PDF is 1 request and 10 labels.
  • Every request: up to 50 labels, a 1 MB body, 15 inches per side, and 10 seconds of render time.
  • Paid plans (Starter $9/month: 10 requests/s and 25,000 labels/day, Pro $29/month: 10 requests/s and 100,000 labels/day, Business $99/month: 20 requests/s and 500,000 labels/day) are announced but billing isn't live yet. API keys work today; a workspace stays on the Free plan until billing opens.
  • Over a limit the API answers 429 with Retry-After (seconds) and a body that names the limit, e.g. ERROR: Daily limit reached: 5000 labels per UTC day on this plan (^PQ copies and PDF pages count).

Ответы и ошибки

Успешные ответы содержат X-Total-Count, количество ярлыков, которые генерирует ZPL, включая ^PQ копий. Ошибки - это простой текст, который начинается с ERROR:.

СтатусЗначение
400Параметр недействителен, ярлык слишком большой или индекс вне диапазона.
401Ключ API неизвестен или был отозван.
406Заголовок Accept запрашивает выходной формат, который еще недоступен.
413Размер тела превышает 1 МБ, или ZPL производит более 50 ярлыков.
429Слишком много запросов или ярлыков для вашего плана. Подождите количество секунд в Retry-After.
503Создание ярлыка заняло более 10 секунд, или служба загружена. Повторите попытку или уменьшите плотность или размер.

Что движок рисует, игнорирует или еще не поддерживает, находится на the compatibility page; как быстро он рендерит, измеряется на производственном сервере, на the benchmarks page.

OpenAPI и Markdown

Тот же контракт опубликован как OpenAPI 3.1 и как Markdown, для генераторов кода и помощников по кодированию.

Пошаговые руководства: Python, Node.js, PHP, C#. Переход с Labelary: migration guide.

Обратная связь