ZPL render API: ZPL u PNG i PDF preko HTTP

Jedan krajnji tačka renduje ZPL u PNG ili PDF. Kompatibilna je sa Labelary-evim v1 API: iste putanje, zaglavlja i greške.

Generiši oznaku

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

Sa POST, pošaljite ZPL kao sirovu telo zahteva, ili kao multipart form polje nazvano file.

API ključevi

Bez ključa dobijate 3 oznake dnevno po IP adresi, što je dovoljno da probate. Sa ključem sa vašeg kontrolnog panela, pošaljite ga u X-API-Key header-u i primenjuju se ograničenja plana vašeg radnog prostora.

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

Primeri

Svaka šalje label.zpl, čuva label.pdf i prikazuje poruku o grešci API-a ako nešto nije u redu. Za PNG, zatražite image/png i dodajte indeks etikete (/0/) u 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"

Zaglavlja zahteva

Ograničenja

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

Odgovori i greške

Uspešni odgovori sadrže X-Total-Count, broj oznaka koje ZPL proizvodi, ^PQ kopija uključeno. Greške su običan tekst koji počinje sa ERROR:.

Šta motor crta, ignorira ili još ne podržava je na the compatibility page; kolika je brzina renderovanja, mereno na produkcionom serveru, na the benchmarks page.

Šabloni: popunite sačuvani dizajn sa vašim podacima

Dizajnirajte oznaku sa {{variables}} mestima, sačuvajte je, i kopirajte njen ID sa vašeg kontrolnog panela: d123 za dizajn, l45 za sačuvanu oznaku. Tada vaš sistem šalje samo podatke, uz API ključ.

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

Koristite {"data": {...}} za jednu oznaku ili {"rows": [...]} za do 50. Accept daje PDF ili PNG, ili text/plain popunjeni ZPL za slanje na štampač. Vrednosti su obeležene, tako da vaši podaci nikada ne mogu započeti ZPL komandu.

Štampajte na lokalnoj štampači

Sa print agent koji radi pored printera, POST /v1/print-jobs redovno šalje ZPL za njega, a POST /v1/templates/{id}/print popunjava sačuvani dizajn. Obe zahtevaju ime printer i vraćaju ID posla; GET /v1/print-jobs/{id} vam javlja da li je odštampano.

Pitanja

Koliko košta API?

Bez ključa možete isprobati sa 3 etikete dnevno. Besplatan ključ omogućava 20 etiketa dnevno, a paid plans počinju od 29$ mesečno za 100.000 etiketa.

Da li je kompatibilan sa Labelary?

Da: isti putevi, zaglavlja i greške. Promenite naziv hosta i pošaljite svoj ključ, kako migration guide pokazuje.

Da li čuvate moje etikete?

Ne sa API ključem: oznaka se renderuje i vraća. privacy page ima detalje i rokove.

Može li AI asistent to koristiti?

Da, kroz MCP server: Claude, Cursor i drugi asistenti mogu renderovati oznake s njim.

OpenAPI i Markdown

Isti ugovor je objavljen kao OpenAPI 3.1 i kao Markdown, za generatore koda i asistente za kodiranje.

Vodiči korak po korak: Python, Node.js, PHP, C#. Premestite se sa Labelary: migration guide.