ZPL renderelő API: ZPL PNG és PDF formátumba HTTP-n keresztül

Egy végpont rendereli a ZPL-t PNG vagy PDF formátumban. Kompatibilis a Labelary v1 API-jával: azonos útvonalak, fejlécek és hibák.

Címke létrehozása

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-tal küldje a ZPL-t nyers kérés törzsként, vagy mint egy több részes űrlapmezőt, amelynek neve file.

API kulcsok

Kulcs nélkül IP-címenként naponta 3 címkét kaphat, ami elegendő a kipróbálásra. Egy kulccsal a műszerfaláról küldje el a X-API-Key fejlécben, és a munkaterve korlátai érvényesek.

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

Példák

Mindegyik label.zpl fájlt küld, elmenti a label.pdf fájlt, és megjeleníti az API hibáját, ha valami nem jó. Egy PNG-hoz kérj image/png és add hozzá a címke indexét (/0/) az URL-hez.

• 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"

Kérés fejléc

Korlátok

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

Válaszok és hibák

A sikeres válaszok tartalmazzák a X-Total-Count -t, a ZPL által előállított címkék számát, ^PQ példányt beleértve. A hibák sima szövegek, amelyek ERROR: -el kezdődnek.

Ami a motor által rajzolódik, figyelmen kívül hagyva, vagy amit még nem támogat, az a the compatibility page; hogy mennyire gyorsan renderel, azt a gyártási szerveren, a the benchmarks page alatt mérjük.

Sablonok: töltse ki a mentett tervet az adatával

Tervezzen egy címkét {{variables}} helyőrzőkkel, mentse el, és másolja ki az ID-ját a vezérlőpultjáról: d123 a tervhez, l45 a mentett címkéhez. Ezután a rendszere csak az adatokat küldi el, egy API kulccsal.

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

Használja a {"data": {...}} értéket egy címkéhez, vagy a {"rows": [...]} értéket legfeljebb 50-hez. A Accept PDF-et vagy PNG-t ad, a text/plain pedig a kinyomtatásra szánt kitöltött ZPL-t. Az értékek leképezve vannak, így az adatai soha nem indíthatnak el ZPL parancsot.

Nyomtasson egy helyi nyomtatón

A print agent a nyomtató mellett fut, a POST /v1/print-jobs ZPL-t sorba állít hozzá, a POST /v1/templates/{id}/print pedig kitölt egy mentett tervet. Mindkettő megköveteli a printer nevet és visszaad egy munkamenet ID-t; a GET /v1/print-jobs/{id} megmondja, hogy nyomtatott-e.

Kérdések

Mennyibe kerül az API?

Kulcs nélkül napi 3 címkével kipróbálhatod. Egy ingyenes kulcs napi 20 címkét engedélyez, és az paid plans 29 $-tól indul havi 100,000 címkéért.

Kompatibilis a Labelary-val?

Igen: ugyanazok az útvonalak, fejléc és hibák. Változtassa meg a hosztnevet, és küldje el a kulcsát, ahogyan a migration guide mutatja.

Megőrzi a címkéimet?

Nem API kulccsal: a címke renderelve van és vissza van küldve. A privacy page tartalmazza a részleteket és az időkereteket.

Használhatja egy AI asszisztens?

Igen, a MCP server segítségével: Claude, Cursor és más asszisztensek képesek vele címkéket renderelni.

OpenAPI és Markdown

Ugyanaz a szerződés OpenAPI 3.1 és Markdown formájában van közzétéve, kód-generátorok és kódolási asszisztensek számára.

Lépésről lépésre útmutatók: Python, Node.js, PHP, C#. Átköltözés a Labelary-ból: migration guide.