ZPL-renderöint API: ZPL PNG:ksi ja PDF:ksi HTTP:n yli

Yksi päätepiste renderöi ZPL:n PNG:ksi tai PDF:ksi. Se on yhteensopiva Labelaryn v1 API:n kanssa: samat polut, otsakkeet ja virheet.

Muuta tunniste

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:n kanssa lähetä ZPL raakana pyyntö-ruumiina tai monimutkaisena lomakekenttänä nimeltä file.

API-avaimet

Ilman avainta saat 3 etikettiä päivässä IP-osoitetta kohti, riittävästi kokeilua varten. Avain ohjauspaneelista, lähetä se X-API-Key otsikossa, ja työtilasi suunnitelman rajoitukset tulevat voimaan.

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

Esimerkit

Jokainen lähettää label.zpl, tallentaa label.pdf ja näyttää API:n virheilmoituksen, jos jokin menee pieleen. PNG:tä varten pyydä image/png ja lisää etiketin indeksi (/0/) URL-osoitteeseen.

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

Pyyntöotsikot

Rajat

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

Vastaukset ja virheet

Onnistuneet vastaukset sisältävät X-Total-Count, ZPL: n tuottamien etikettien määrän, ^PQ kopiota mukaan lukien. Virheet ovat tavanomaista tekstiä, joka alkaa ERROR:.

Mitä moottori piirtää, jättää huomiotta tai ei tue vielä, on the compatibility page; kuinka nopeasti se renderöi, mitattuna tuotantopalvelimella, the benchmarks page.

Mallipohjat: täytä tallennettu malli omilla tiedoillasi

Suunnittele etiketti {{variables}} paikkamerkeillä, tallenna se, ja kopioi sen ID hallintapaneelista: d123 suunnittelulle, l45 tallennetulle tarralle. Sitten järjestelmäsi lähettää vain tiedot API-avaimen kanssa.

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

Käytä {"data": {...}} yhtä etikettiä varten tai {"rows": [...]} enintään 50:lle. Accept tuottaa PDF:n tai PNG:n, tai text/plain täytetyn ZPL:n lähetettäväksi tulostimelle. Arvot on pakotettu, joten tietosi eivät koskaan voi aloittaa ZPL-komentoa.

Tulosta paikalliselle tulostimelle

Kun print agent toimii tulostimen vieressä, POST /v1/print-jobs jonottaa ZPL:n sille ja POST /v1/templates/{id}/print täyttää tallennetun muotoilun. Molemmat ottavat vastaan printer nimen ja palauttavat työn ID:n; GET /v1/print-jobs/{id} kertoo, tulostettinko se.

Kysymykset

Kuinka paljon API maksaa?

Ilman avainta voit kokeilla sitä 3 etikettiä päivässä. Ilmainen avain sallii 20 etikettiä päivässä, ja paid plans alkaa 29 dollarista kuukaudessa 100 000 etiketille.

Onko se yhteensopiva Labelaryn kanssa?

Kyllä: samat polut, otsikot ja virheet. Vaihda isäntänimi ja lähetä avaimesi, kuten migration guide näyttää.

Säilytättekö minun etiketit?

Ei API-avaimen kanssa: etiketti renderöidään ja palautetaan. privacy page sisältää yksityiskohdat ja määräajat.

Voiko AI-avustaja käyttää sitä?

Kyllä, MCP server:n kautta: Claude, Cursor ja muut avustajat voivat renderöidä etikettejä sen avulla.

OpenAPI ja Markdown

Sama sopimus on julkaistu muodossa OpenAPI 3.1 ja Markdown, koodigeneraattoreita ja koodausavustajia varten.

Askelsuunnitelmat: Python, Node.js, PHP, C#. Siirtyminen Labelarysta: migration guide.