ZPL rendering API: ZPL sa PNG at PDF sa pamamagitan ng HTTP

Isang endpoint ang nagrerepresenta ng ZPL sa PNG o PDF. Ito ay tugma sa v1 API ng Labelary: parehong mga landas, header at error.

Mag-render ng isang 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}/

Sa POST, ipadala ang ZPL bilang raw na nilalaman ng kahilingan, o bilang isang multipart form field na may pangalang file.

API mga susi

Walang key, nakakakuha ka ng 3 label araw-araw bawat IP address, sapat na upang subukan ito. Sa isang key mula sa iyong dashboard, ipadala ito sa X-API-Key header at ang mga limitasyon ng plano ng iyong workspace ay nalalapat.

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

Mga Halimbawa

Ang bawat isa ay nagpapadala ng label.zpl, nag-save ng label.pdf at nagpapakita ng mensahe ng error ng API kung may mali. Para sa PNG, humingi ng image/png at idagdag ang index ng label (/0/) sa 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"

Mga header ng kahilingan

Mga Limitasyon

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

Mga tugon at error

Ang matagumpay na mga tugon ay nagdadala ng X-Total-Count, ang bilang ng mga label na produces ng ZPL, na kasama ang ^PQ na kopya. Ang mga error ay plain text na nagsisimula sa ERROR:.

Ano ang iginuhit ng engine, hindi pinansin o hindi pa sinusuportahan ay nasa the compatibility page; kung gaano kabilis ito nagre-render, sukat mula sa production server, sa the benchmarks page.

Mga template: punan ang isang na-save na disenyo ng iyong data

Idisenyo ang isang label na may {{variables}} na placeholders, i-save ito, at kopyahin ang ID nito mula sa iyong dashboard: d123 para sa isang disenyo, l45 para sa isang nai-save na label. Pagkatapos ay ipinapadala ng iyong sistema ang data lamang, gamit ang isang API key.

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

Gamitin ang {"data": {...}} para sa isang label o {"rows": [...]} para sa hanggang 50. Ang Accept ay nagbibigay ng PDF o PNG, o ang text/plain ang pinunong ZPL na ipadala sa printer. Ang mga halaga ay naka-escape, kaya ang iyong data ay hindi kailanman makakapagsimula ng isang ZPL command.

I-print sa isang lokal na printer

Sa print agent na tumatakbo sa tabi ng printer, ang POST /v1/print-jobs ay nag-queue ng ZPL para dito at ang POST /v1/templates/{id}/print ay nagpapuno ng naka-save na disenyo. Pareho silang kumukuha ng pangalan ng printer at bumabalik ng job ID; ang GET /v1/print-jobs/{id} ay nagsasabi sa iyo kung ito ay nag-print.

Mga Tanong

Magkano ang halaga ng API?

Nang walang susi, maaari mo itong subukan sa 3 label sa isang araw. Ang libreng susi ay nagpapahintulot ng 20 label sa isang araw, at ang paid plans ay nagsisimula sa $29 sa isang buwan para sa 100,000 label.

Ito ba ay tugma sa Labelary?

Oo: ang parehong mga landas, header at error. Palitan ang hostname at ipadala ang iyong key, tulad ng ipinapakita ng migration guide.

Ipinapanatili mo ba ang aking mga label?

Hindi gamit ang API key: ang label ay nai-render at ibinabalik. Ang privacy page ay may mga detalye at mga deadline.

Maaari bang gamitin ito ng isang AI assistant?

Oo, sa pamamagitan ng MCP server: ang Claude, Cursor at iba pang mga katulong ay maaaring mag-render ng mga label gamit ito.

OpenAPI at Markdown

Ang parehong kontrata ay inilathala bilang OpenAPI 3.1 at bilang Markdown, para sa mga tagabuo ng code at mga katulong sa pag-code.

Mga gabay na hakbang-hakbang: Python, Node.js, PHP, C#. Paglipat mula sa Labelary: migration guide.