Overslaan naar inhoud

API-documentatie

Eén eindpunt rendert ZPL naar PNG of PDF. Het is compatibel met Labelary's v1 API: dezelfde paden, headers en fouten.

Render een label

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}/
dpmmAfdrukdichtheid: 6dpmm, 8dpmm, 12dpmm, 24dpmm.
width, heightEtiketgrootte in inches, bijvoorbeeld 4x6 of 2.25x1.25. Tot 15 inches elk.
indexWelke label te renderen, beginnend bij 0. Laat het weg bij PDF-uitvoer om elke label te krijgen, één per pagina.
zplVoor GET, de URL-gecodeerde ZPL. Encodeer # als %23. Gebruik POST voor lange gegevens.

Met POST, stuur de ZPL als de ruwe aanvraagbody, of als een multipart formulierveld genaamd file.

API-sleutels

Zonder een sleutel krijg je de gratis limieten per IP-adres. Met een sleutel van je dashboard, stuur deze in de X-API-Key header en de limieten van het plan van je werkruimte zijn van toepassing.

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

Voorbeelden

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

Verzoek headers

KoptekstWaardenStandaard
Acceptimage/png, application/pdfPNG
X-QualityGrayscale (8-bit, smooth edges) or Bitonal (1-bit, smaller files)Grayscale
X-Rotation0, 90, 180, 270, met de klok mee0
X-API-KeyUw werkruimte sleutel, optioneel—

Beperkingen

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

Antwoorden en fouten

Succesvolle reacties bevatten X-Total-Count, het aantal labels dat de ZPL produceert, ^PQ kopieën inbegrepen. Fouten zijn platte tekst die begint met ERROR:.

StatusBetekenis
400Een parameter is ongeldig, het label is te groot, of de index is buiten bereik.
401De API-sleutel is onbekend of ingetrokken.
406De Accept header vraagt om een uitvoerformaat dat nog niet beschikbaar is.
413De body is groter dan 1 MB of de ZPL produceert meer dan 50 labels.
429Te veel verzoeken of labels voor uw plan. Wacht het aantal seconden in Retry-After.
503Het label duurde langer dan 10 seconden om te renderen, of de service is vol. Probeer het opnieuw, of verlaag de densiteit of de grootte.

Wat de engine tekent, negeert of nog niet ondersteunt, staat op the compatibility page; hoe snel het wordt gerenderd, gemeten op de productie-server, op the benchmarks page.

OpenAPI en Markdown

Hetzelfde contract is gepubliceerd als OpenAPI 3.1 en als Markdown, voor codegeneratoren en coderingsassistenten.

Stapsgewijze handleidingen: Python, Node.js, PHP, C#. Overstappen van Labelary: migration guide.

Feedback