Documentazione API

Un endpoint converte ZPL in PNG o PDF. È compatibile con l'API v1 di Labelary: stessi percorsi, intestazioni ed errori.

Renderizza un'etichetta

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}/

Con POST, invia il ZPL come corpo della richiesta raw, o come campo di modulo multipart denominato file.

Chiavi API

Senza una chiave si ottengono i limiti gratuiti per indirizzo IP. Con una chiave dal tuo pannello, inviala nell'intestazione X-API-Key e si applicano i limiti del piano del tuo workspace.

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

Esempi

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

Intestazioni della richiesta

Limiti

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

Risposte ed errori

Le risposte riuscite riportano X-Total-Count, il numero di etichette che il ZPL produce, ^PQ copie incluse. Gli errori sono testo semplice che inizia con ERROR:.

OpenAPI e Markdown

Lo stesso contratto è pubblicato come OpenAPI 3.1 e come Markdown, per generatori di codice e assistenti di codifica.

Guide passo-passo: Python, Node.js, PHP, C#. Migrare da Labelary: migration guide.