وثائق API

نقطة نهاية واحدة تحول ZPL إلى PNG أو PDF. إنها متوافقة مع واجهة برمجة التطبيقات 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}/

باستخدام 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

أمثلة

• cURL
• Python
• Node.js
• PHP

# 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));

رؤوس الطلب

Limits

• 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:.

OpenAPI and Markdown

The same contract is published as OpenAPI 3.1 and as Markdown, for code generators and coding assistants.

Step-by-step guides: Python, Node.js, PHP, C#. Moving from Labelary: migration guide.