Lompati ke konten

Dokumen API

Satu titik akhir merender ZPL ke PNG atau PDF. Ini kompatibel dengan API v1 Labelary: jalur, header, dan kesalahan yang sama.

Render sebuah 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}/
dpmmKepadatan cetak: 6dpmm, 8dpmm, 12dpmm, 24dpmm.
width, heightUkuran label dalam inci, misalnya 4x6 atau 2.25x1.25. Maksimal 15 inci masing-masing.
indexLabel mana yang akan dirender, mulai dari 0. Biarkan kosong untuk keluaran PDF agar mendapatkan setiap label, satu per halaman.
zplUntuk GET, ZPL yang telah di-URL-encode. Encode # sebagai %23. Gunakan POST untuk yang panjang.

Dengan POST, kirim ZPL sebagai tubuh permintaan mentah, atau sebagai field formulir multipart bernama file.

Kunci API

Tanpa kunci Anda mendapatkan batas gratis per alamat IP. Dengan kunci dari dasbor Anda, kirimkan di header X-API-Key dan batas rencana ruang kerja Anda berlaku.

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

Contoh

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

Header permintaan

KepalaNilaiDefault
Acceptimage/png, application/pdfPNG
X-QualityGrayscale (8-bit, tepi halus) atau Bitonal (1-bit, file lebih kecil)Grayscale
X-Rotation0, 90, 180, 270, searah jarum jam0
X-API-KeyKunci ruang kerja Anda, opsional—

Batas

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

Respon dan kesalahan

Respon yang berhasil membawa X-Total-Count, jumlah label yang dihasilkan ZPL, ^PQ salinan termasuk. Kesalahan adalah teks biasa yang dimulai dengan ERROR:.

StatusMakna
400Parameter tidak valid, label terlalu besar, atau indeks di luar jangkauan.
401Kunci API tidak dikenal atau telah dicabut.
406Header Accept meminta format output yang belum tersedia.
413Badan lebih dari 1 MB, atau ZPL menghasilkan lebih dari 50 label.
429Terlalu banyak permintaan atau label untuk rencana Anda. Tunggu jumlah detik di Retry-After.
503Label memerlukan waktu lebih dari 10 detik untuk dirender, atau layanan sedang penuh. Coba lagi, atau turunkan kepadatan atau ukuran.

Apa yang digambar oleh mesin, diabaikan atau belum didukung ada di the compatibility page; seberapa cepat ia merender, diukur di server produksi, di the benchmarks page.

OpenAPI dan Markdown

Kontrak yang sama diterbitkan sebagai OpenAPI 3.1 dan Markdown, untuk generator kode dan asisten pemrograman.

Panduan langkah demi langkah: Python, Node.js, PHP, C#. Pindah dari Labelary: migration guide.

Umpan balik