API רנדר ZPL: ZPL ל-PNG ו-PDF מעל HTTP

נקודת קצה אחת ממריצה 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}/

בהגדרת POST, שלח את ה-ZPL כגוף הבקשה הגולמית, או כשדה טופס multipart בשם file.

מפתחות API

בלי מפתח, אתה מקבל 3 תיוגים ביום על כל כתובת 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

דוגמאות

כל אחד שולח label.zpl, שומר label.pdf ומציג את הודעת השגיאה של ה-API אם משהו לא בסדר. עבור PNG, בקש image/png והוסף את האינדקס של התווית (/0/) ל-URL.

• cURL
• Python
• Node.js
• PHP
• C#
• Java
• Go
• Ruby
• PowerShell

curl https://api.openzpl.com/v1/printers/8dpmm/labels/4x6/ \
  -H "Accept: application/pdf" \
  --data-binary @label.zpl --fail-with-body -o label.pdf

import requests  # pip install requests

with open("label.zpl", "rb") as f:
    res = requests.post(
        "https://api.openzpl.com/v1/printers/8dpmm/labels/4x6/",
        data=f.read(),
        headers={"Accept": "application/pdf"},
        timeout=30,
    )
if not res.ok:
    raise SystemExit(res.text)
with open("label.pdf", "wb") as f:
    f.write(res.content)

// Node.js 18+; save as label.mjs
import { readFile, writeFile } from "node:fs/promises";

const res = await fetch("https://api.openzpl.com/v1/printers/8dpmm/labels/4x6/", {
  method: "POST",
  headers: { Accept: "application/pdf" },
  body: await readFile("label.zpl"),
});
if (!res.ok) throw new Error(await res.text());
await writeFile("label.pdf", Buffer.from(await res.arrayBuffer()));

<?php
$ch = curl_init("https://api.openzpl.com/v1/printers/8dpmm/labels/4x6/");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => file_get_contents("label.zpl"),
    CURLOPT_HTTPHEADER => ["Accept: application/pdf"],
    CURLOPT_RETURNTRANSFER => true,
]);
$pdf = curl_exec($ch);
if (curl_getinfo($ch, CURLINFO_RESPONSE_CODE) !== 200) {
    exit($pdf);
}
file_put_contents("label.pdf", $pdf);

using var http = new HttpClient();
var req = new HttpRequestMessage(HttpMethod.Post,
    "https://api.openzpl.com/v1/printers/8dpmm/labels/4x6/")
{
    Content = new StringContent(File.ReadAllText("label.zpl")),
};
req.Headers.Add("Accept", "application/pdf");

var res = await http.SendAsync(req);
if (!res.IsSuccessStatusCode)
    throw new Exception(await res.Content.ReadAsStringAsync());
File.WriteAllBytes("label.pdf", await res.Content.ReadAsByteArrayAsync());

// Java 11+
import java.net.URI;
import java.net.http.*;
import java.nio.file.Path;

public class Label {
    public static void main(String[] args) throws Exception {
        var req = HttpRequest.newBuilder(
                URI.create("https://api.openzpl.com/v1/printers/8dpmm/labels/4x6/"))
            .header("Accept", "application/pdf")
            .POST(HttpRequest.BodyPublishers.ofFile(Path.of("label.zpl")))
            .build();
        var res = HttpClient.newHttpClient()
            .send(req, HttpResponse.BodyHandlers.ofByteArray());
        if (res.statusCode() != 200)
            throw new RuntimeException(new String(res.body()));
        java.nio.file.Files.write(Path.of("label.pdf"), res.body());
    }
}

package main

import (
	"io"
	"log"
	"net/http"
	"os"
)

func main() {
	zpl, err := os.Open("label.zpl")
	if err != nil {
		log.Fatal(err)
	}
	req, _ := http.NewRequest("POST", "https://api.openzpl.com/v1/printers/8dpmm/labels/4x6/", zpl)
	req.Header.Set("Accept", "application/pdf")
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		log.Fatal(err)
	}
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)
	if res.StatusCode != 200 {
		log.Fatal(string(body))
	}
	os.WriteFile("label.pdf", body, 0o644)
}

require "net/http"

uri = URI("https://api.openzpl.com/v1/printers/8dpmm/labels/4x6/")
res = Net::HTTP.post(uri, File.binread("label.zpl"), "Accept" => "application/pdf")
abort res.body unless res.is_a?(Net::HTTPSuccess)
File.binwrite("label.pdf", res.body)

Invoke-WebRequest -Method Post `
  -Uri "https://api.openzpl.com/v1/printers/8dpmm/labels/4x6/" `
  -Headers @{ Accept = "application/pdf" } `
  -InFile "label.zpl" -OutFile "label.pdf"

כותרות הבקשה

מגבלות

• Without a key: 3 requests per second and 3 labels per UTC day, per IP address. With a free key from the dashboard: 20 labels per UTC day.
• Labels, not requests, count against the allowance (per UTC day on Free, per UTC calendar month on paid plans): 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 (Pro $29/month: 10 requests/s and 100,000 labels/month, Business $99/month: 20 requests/s and 1,000,000 labels/month): subscriptions, monthly or yearly, from the dashboard's Billing page (card, through Stripe), and you can cancel at any time. The workspace's API keys move to the plan's limits as soon as the payment is approved.
• Over a limit the API answers 429 with Retry-After (seconds) and a body that names the limit, e.g. ERROR: Daily limit reached: 20 labels per UTC day on this plan (^PQ copies and PDF pages count).

תשובות ושגיאות

תשובות מצליחות נושאות X-Total-Count, מספר התוויות שה-ZPL מייצר, כולל ^PQ עותקים. שגיאות הן טקסט רגיל שמתחיל ב-ERROR:.

מה שהמנוע מצייר, מתעלם ממנו או לא תומך בו עדיין נמצא ב-the compatibility page; כמה מהר זה מהיר, נמדד על השרת הייצורי, על the benchmarks page.

תבניות: מלא עיצוב נשמר בנתוניך

עצב תווית עם {{variables}} תפסים, שמור אותה, והעתק את ה-ID שלה מהלוח המחוונים שלך: d123 עבור עיצוב, l45 עבור תווית שמורה. אז המערכת שלך שולחת רק את הנתונים, עם מפתח API.

curl https://api.openzpl.com/v1/templates/d123 \
  -H "X-API-Key: oz_live_…" -H "Accept: application/pdf" \
  -d '{"rows": [{"sku": "A-100"}, {"sku": "A-101"}]}' > labels.pdf

השתמש ב-{"data": {...}} עבור תווית אחת או {"rows": [...]} עבור עד 50. Accept נותן PDF או PNG, או text/plain את ה-ZPL המלא שנשלח למדפסת. הערכים נברחו, כך שדאטה שלך לעולם לא יכולה להתחיל פקודת ZPL.

הדפס על מדפסת מקומית

עם ה-print agent רץ ליד המדפסת, POST /v1/print-jobs מתכנן ZPL בשבילה ו-POST /v1/templates/{id}/print ממלא עיצוב שנשמר. שניהם לוקחים שם printer ומחזירים מזהה משימה; GET /v1/print-jobs/{id} אומר לך אם הוא הדפיס.

שאלות

כמה עולה ה-API?

ללא מפתח אתה יכול לנסות את זה עם 3 תוויות ביום. מפתח חינם מאפשר 20 תוויות ביום, ו-paid plans מתחילים מ-$29 בחודש עבור 100,000 תוויות.

האם זה תואם ל-Labelary?

כן: אותם נתיבים, כותרות ושגיאות. שנה את שם המארח ושלח את המפתח שלך, כפי שמראה ה-migration guide.

האם אתם שומרים את התוויות שלי?

לא עם מפתח API: התגית מנוגנת ומוחזרת. ה-privacy page מכיל את הפרטים ואת המועדים.

האם עוזר בינה מלאכותית יכול להשתמש בזה?

כן, דרך ה-MCP server: Claude, Cursor ועוזרים אחרים יכולים לרנדר תיוגים עם זה.

OpenAPI ו-Markdown

אותו החוזה מפורסם כ-OpenAPI 3.1 וכ-Markdown, עבור יצרני קוד ועוזרי קידוד.

מדריכים שלב אחר שלב: Python, Node.js, PHP, C#. מעבר מ-Labelary: migration guide.