API vykresľovania ZPL: ZPL na PNG a PDF cez HTTP

Jeden koncový bod renderuje ZPL do PNG alebo PDF. Je kompatibilný s Labelary's v1 API: rovnaké cesty, hlavičky a chyby.

Vykresliť štítok

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

S pomocou POST pošlite ZPL ako surové telo požiadavky alebo ako multipart form field s názvom file.

API kľúče

Bez kľúča dostanete 3 nálepky denne na IP adresu, čo je dosť na vyskúšanie. S kľúčom z vašej palubnej dosky ho pošlite v hlavičke X-API-Key a limity plánu vášho pracovného priestoru sa uplatnia.

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

Príklady

Každý z nich pošle label.zpl, uloží label.pdf a zobrazí chybovú správu API, ak je niečo v neporiadku. Pre PNG požiadajte o image/png a pridajte index štítka (/0/) do 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"

Hlavičky žiadosti

Obmedzenia

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

Odpovede a chyby

Úspešné odpovede obsahujú X-Total-Count, počet etikiet, ktoré ZPL produkuje, vrátane ^PQ kópií. Chyby sú obyčajný text, ktorý začína s ERROR:.

To, čo motor vykresľuje, ignoruje alebo ešte nepodporuje, je na the compatibility page; akou rýchlosťou to vykresľuje, merané na produkčnom serveri, na the benchmarks page.

Šablóny: vyplňte uložený dizajn vašimi údajmi

Navrhnite etiketu s {{variables}} zástupnými symbolmi, uložte ju a skopírujte jej ID z vášho panela: d123 pre dizajn, l45 pre uloženú etiketu. Potom váš systém odošle len údaje s API kľúčom.

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

Použite {"data": {...}} pre jeden štítok alebo {"rows": [...]} pre až 50. Accept poskytuje PDF alebo PNG, alebo text/plain vyplnené ZPL na odoslanie do tlačiarne. Hodnoty sú unikátne, takže vaše údaje nikdy nemôžu začať ZPL príkazom.

Tlačte na lokálnej tlačiarni

S print agent bežiacim vedľa tlačiarne, POST /v1/print-jobs radí ZPL a POST /v1/templates/{id}/print vyplní uložený dizajn. Obe prijímajú názov printer a vracajú ID úlohy; GET /v1/print-jobs/{id} vám povie, či to vytlačilo.

Otázky

Koľko stojí API?

Bez kľúča to môžete vyskúšať s 3 štítkami za deň. Bezplatný kľúč povoľuje 20 štítkov za deň a paid plans začínajú na 29 dolároch za mesiac pre 100 000 štítkov.

Je to kompatibilné s Labelary?

Áno: rovnaké cesty, hlavičky a chyby. Zmeňte názov hostiteľa a pošlite svoj kľúč, ako ukazuje migration guide.

Uchovávate moje štítky?

Nie s API kľúčom: štítok je vykreslený a vrátený. privacy page obsahuje podrobnosti a termíny.

Môže to AI asistent používať?

Áno, cez MCP server: Claude, Cursor a iní asistenti môžu s ním renderovať nálepky.

OpenAPI a Markdown

Tá istá zmluva je zverejnená ako OpenAPI 3.1 a ako Markdown, pre generátory kódu a asistenty programovania.

Príručky krok za krokom: Python, Node.js, PHP, C#. Migrácia z Labelary: migration guide.