Drucker- & Agent-API: Zebra-Drucker, Kontingent

Alle Endpunkte dieser Seite sind GET-Requests auf https://api.zplcloud.com, benötigen einen API-Key (X-API-Key oder Basic Auth) und akzeptieren die Webhook-Parameter webhookId und webhookResult. Sie zählen keine Renders und werden nie durch das Kontingent begrenzt. Firma meint immer die Firma des API-Keys; Keys ohne Firma erhalten stattdessen die persönlichen Einträge des Key-Besitzers (scope: "personal"). Die JSON-Antworten unten sind Beispieldaten.

Drucker des API-Keys

GET /v1/printers liefert nur die Drucker, die an den aufrufenden API-Key gebunden sind:

Weblink-Cloud-Drucker, deren Zertifikat für diesen Key ausgestellt wurde - der beim Drucker hinterlegte Key ist der aufrufende Key.
Remote-Drucker, deren Agent sich mit diesem Key verbindet - der Agent-Name des Druckers gehört zu einem Agent, der mit diesem Key online ist oder für den eine Konfiguration zu diesem Key gespeichert ist. Remote-Drucker ohne Agent erscheinen nicht.
Virtuelle Drucker sind an keinen Key gebunden; sie stehen in GET /v1/company/printers.

Praktisch, wenn ein Key je Standort oder je Anwendung nur „seine“ Drucker sehen soll. Zuerst kommen Weblink-Drucker (online zuerst, jüngste Verbindung zuerst), danach Remote-Drucker nach Name.

curl https://api.zplcloud.com/v1/printers -H "X-API-Key: sk_zplcloud_YOUR_KEY"

{
  "scope": "apiKey",
  "apiKey": "sk_zplcloud_…9f3a",
  "count": 2,
  "printers": [
    {
      "target": "wl:17",
      "type": "weblink",
      "id": 17,
      "name": "Packtisch 1",
      "serial": "D4J223104587",
      "model": "ZT411",
      "hostname": "ZT411-PACK1",
      "online": true,
      "blocked": false,
      "firmware": "V92.21.39Z",
      "linkOsVersion": "7.0",
      "lastConnectUtc": "2026-09-11T08:02:13.52",
      "lastKeepAliveUtc": "2026-09-11T10:14:58.107",
      "apiKeyBound": true,
      "apiKey": null,
      "owner": null
    },
    {
      "target": "rp:5",
      "type": "remote",
      "id": 5,
      "name": "Versand ZD421",
      "online": true,
      "host": "192.168.10.41",
      "port": 9100,
      "usb": false,
      "agent": "warehouse-pi",
      "agentOnline": true,
      "agentVersion": "1.8.2",
      "owner": null,
      "createdUtc": "2026-06-02T13:40:11.803"
    }
  ]
}

Feld	Bedeutung
`scope`	Immer `apiKey`.
`apiKey`	Der aufrufende Key, maskiert (Präfix und letzte 4 Zeichen).
`count`	Anzahl der Einträge in `printers`.
`printers`	Drucker-Einträge - Felder siehe Drucker-Eintrag. `apiKey` und `owner` sind hier immer `null`.

Webhook-Event: api.printers.listed, summary { scope, count, weblink, remote }.

Drucker der Firma

GET /v1/company/printers liefert alle Drucker, die die Firma des Keys nutzen kann - unabhängig davon, mit welchem Key sie eingerichtet wurden.

scope	Wann	Inhalt
`company`	Der API-Key gehört zu einer Firma.	Für die Firma sichtbare Weblink-Drucker, alle Remote- und virtuellen Drucker der Firma.
`personal`	Der API-Key hat keine Firma.	Drucker der E-Mail des Key-Besitzers; `company` ist `null`.

type	Drucker	target
`weblink`	Zebra-Drucker, per Weblink mit zplCloud verbunden.	`wl:{id}` (die Seriennummer funktioniert ebenfalls)
`remote`	LAN- oder USB-Drucker, erreichbar über einen zplCloud-CLI-Agent.	`rp:{id}`
`virtual`	Virtueller Testdrucker (PNG mit Wasserzeichen) - nur gelistet, wo virtuelle Drucker verfügbar sind.	`vp:{id}`

curl https://api.zplcloud.com/v1/company/printers -H "X-API-Key: sk_zplcloud_YOUR_KEY"

{
  "scope": "company",
  "company": "example-logistics",
  "count": 3,
  "printers": [
    {
      "target": "wl:17",
      "type": "weblink",
      "id": 17,
      "name": "Packtisch 1",
      "serial": "D4J223104587",
      "model": "ZT411",
      "hostname": "ZT411-PACK1",
      "online": true,
      "blocked": false,
      "firmware": "V92.21.39Z",
      "linkOsVersion": "7.0",
      "lastConnectUtc": "2026-09-11T08:02:13.52",
      "lastKeepAliveUtc": "2026-09-11T10:14:58.107",
      "apiKeyBound": false,
      "apiKey": "sk_zplcloud_…c71b",
      "owner": "ops@example.com"
    },
    {
      "target": "rp:5",
      "type": "remote",
      "id": 5,
      "name": "Versand ZD421",
      "online": false,
      "host": "192.168.10.41",
      "port": 9100,
      "usb": false,
      "agent": "warehouse-pi",
      "agentOnline": false,
      "agentVersion": null,
      "owner": "ops@example.com",
      "createdUtc": "2026-06-02T13:40:11.803"
    },
    {
      "target": "vp:3",
      "type": "virtual",
      "id": 3,
      "name": "Test 100x150",
      "online": true,
      "widthMm": 100,
      "heightMm": 150,
      "dpi": 203,
      "owner": "dev@example.com",
      "createdUtc": "2026-08-19T09:05:44.61"
    }
  ]
}

Feld	Bedeutung
`scope`	`company` oder `personal`.
`company`	Firma des API-Keys; `null` bei `personal`.
`count`	Anzahl der Einträge in `printers`.
`printers`	Erst Weblink-, dann Remote-, dann virtuelle Drucker.

Webhook-Event: api.company.printers.listed, summary { scope, count, weblink, remote, virtual }.

Drucker-Eintrag

Feld	Typ	Bedeutung
`target`	alle	Drucker-Ziel für Batch-Jobs: `wl:{id}`, `rp:{id}`, `vp:{id}`.
`type`	alle	`weblink`, `remote` oder `virtual`.
`id`	alle	ID innerhalb des Typs.
`name`	alle	Anzeigename. Weblink: Anzeigename, sonst Hostname, sonst Seriennummer.
`online`	alle	Weblink: Drucker verbunden. Remote: sein Agent ist online. Virtuell: immer `true`.
`owner`	alle	E-Mail des Benutzers, der den Drucker eingerichtet hat. Nur in der Firmenliste.
`serial`, `model`, `hostname`	weblink	Vom Drucker gemeldete Gerätedaten.
`firmware`, `linkOsVersion`	weblink	Firmware- und Link-OS-Version.
`blocked`	weblink	Drucker in zplCloud gesperrt.
`lastConnectUtc`, `lastKeepAliveUtc`	weblink	Letzte Weblink-Verbindung und letztes Keep-Alive (UTC).
`apiKeyBound`	weblink	`true`, wenn der Drucker an den aufrufenden Key gebunden ist.
`apiKey`	weblink	Maskierter Key, an den der Drucker gebunden ist. Nur in der Firmenliste.
`host`, `port`, `usb`	remote	Adresse, an die der Agent druckt (TCP, meist Port 9100), oder USB.
`agent`, `agentOnline`, `agentVersion`	remote	Agent-Name, ob er online ist, zplCloud-CLI-Version (`null`, solange offline).
`widthMm`, `heightMm`, `dpi`	virtual	Labelgröße und Auflösung.
`createdUtc`	remote, virtual	Angelegt (UTC).

target in Batch-Jobs verwenden

target unverändert als printer an POST /v1/batch/design/{designId} übergeben. Der Job löst das Ziel vor dem Rendern im Bereich des Key-Besitzers auf - ein falsches Ziel scheitert sofort mit 400 oder 404 - und druckt in Blöcken zu 100 Labels: wl: über die Weblink-Verbindung, rp: über den Agent (er muss online sein), vp: in den Verlauf des virtuellen Druckers.

curl -X POST "https://api.zplcloud.com/v1/batch/design/shipping-label.42?webhookId=12" \
  -H "X-API-Key: sk_zplcloud_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"records":[{"sku":"A-1001"},{"sku":"A-1002"}],"output":"none","printer":"rp:5","async":true}'

Details zu Batch-Jobs: Rendering.

Agents des API-Keys

GET /v1/agents listet die zplCloud-CLI-Agents (zplcloud proxy), die sich mit diesem Key verbinden: alle aktiven Verbindungen plus Agents, die offline sind, aber eine Konfiguration zu diesem Key gespeichert haben. Einträge werden nach Agent-Name zusammengeführt - mehrere Verbindungen unter demselben Namen zählen in connections, die jüngste liefert Version, Betriebssystem und Host.

curl https://api.zplcloud.com/v1/agents -H "X-API-Key: sk_zplcloud_YOUR_KEY"

{
  "scope": "apiKey",
  "apiKey": "sk_zplcloud_…9f3a",
  "count": 2,
  "online": 1,
  "agents": [
    {
      "name": "office-win",
      "online": false,
      "connections": 0,
      "version": null,
      "os": null,
      "hostname": null,
      "ips": [],
      "connectedAt": null,
      "lastSeenUtc": null,
      "lastHealthCheckUtc": null,
      "configVersion": 2,
      "configUpdatedUtc": "2026-07-14T15:30:00",
      "printers": 1,
      "apiKey": null,
      "owner": null
    },
    {
      "name": "warehouse-pi",
      "online": true,
      "connections": 1,
      "version": "1.8.2",
      "os": "Linux 6.6 arm64",
      "hostname": "raspberrypi",
      "ips": ["192.168.10.20"],
      "connectedAt": "2026-09-10T22:03:41.2210473Z",
      "lastSeenUtc": "2026-09-11T10:14:30.0071210Z",
      "lastHealthCheckUtc": "2026-09-11T10:14:30.0071210Z",
      "configVersion": 4,
      "configUpdatedUtc": "2026-08-28T09:12:05.4",
      "printers": 3,
      "apiKey": null,
      "owner": null
    }
  ]
}

Feld	Bedeutung
`scope`, `apiKey`	Immer `apiKey`; der aufrufende Key, maskiert.
`count`, `online`	Anzahl der Agents und wie viele davon online sind.
`agents[].name`	Agent-Name (alphabetisch sortiert).
`online`, `connections`	Mindestens eine aktive Verbindung; Anzahl aktiver Verbindungen unter diesem Namen.
`version`, `os`, `hostname`, `ips`	zplCloud-CLI-Version und Hostdaten der jüngsten Verbindung; `null` bzw. leer, solange offline.
`connectedAt`, `lastSeenUtc`, `lastHealthCheckUtc`	Verbindungsbeginn, letztes Lebenszeichen, letzter Health-Check (UTC); `null`, solange offline.
`configVersion`, `configUpdatedUtc`	Version und letzte Änderung der gespeicherten Agent-Konfiguration; `null` ohne Konfiguration.
`printers`	Anzahl der Remote-Drucker im Konto, die diesem Agent-Namen zugeordnet sind.
`apiKey`, `owner`	Hier immer `null`; in der Firmenliste befüllt.

Webhook-Event: api.agents.listed, summary { scope, count, online }.

Agents der Firma

GET /v1/company/agents listet alle Agents der Firma des Keys über alle API-Keys hinweg - aktive Verbindungen und Offline-Agents mit gespeicherter Konfiguration. Keys ohne Firma erhalten die persönlichen Agents des Key-Besitzers (scope: "personal"). Die Einträge haben dieselben Felder wie bei GET /v1/agents, zusätzlich befüllt sind apiKey (maskierter Key, mit dem sich der Agent verbindet) und owner (E-Mail).

curl https://api.zplcloud.com/v1/company/agents -H "X-API-Key: sk_zplcloud_YOUR_KEY"

{
  "scope": "company",
  "company": "example-logistics",
  "count": 1,
  "online": 1,
  "agents": [
    {
      "name": "warehouse-pi",
      "online": true,
      "connections": 1,
      "version": "1.8.2",
      "os": "Linux 6.6 arm64",
      "hostname": "raspberrypi",
      "ips": ["192.168.10.20"],
      "connectedAt": "2026-09-10T22:03:41.2210473Z",
      "lastSeenUtc": "2026-09-11T10:14:30.0071210Z",
      "lastHealthCheckUtc": "2026-09-11T10:14:30.0071210Z",
      "configVersion": 4,
      "configUpdatedUtc": "2026-08-28T09:12:05.4",
      "printers": 3,
      "apiKey": "sk_zplcloud_…9f3a",
      "owner": "ops@example.com"
    }
  ]
}

Feld	Bedeutung
`scope`	`company` oder `personal`.
`company`	Firma des API-Keys; `null` bei `personal`.
`count`, `online`	Anzahl der Agents und wie viele davon online sind.
`agents[].apiKey`	Maskierter API-Key der jüngsten Verbindung, sonst der gespeicherten Konfiguration.
`agents[].owner`	E-Mail des Key-Besitzers.

Webhook-Event: api.company.agents.listed, summary { scope, count, online }.

Label-Kontingent

GET /v1/quota liefert das aktuelle Label-Kontingent des Key-Besitzers - dieselben Zahlen, die die Plattform unter Billing zeigt. Wie Labels gezählt werden: Label-Kontingent und Render-Zählung.

curl https://api.zplcloud.com/v1/quota -H "X-API-Key: sk_zplcloud_YOUR_KEY"

{
  "plan": "starter",
  "status": "active",
  "billing": "monthly",
  "labels": {
    "limit": 15000,
    "used": 4211,
    "remaining": 10789,
    "percentUsed": 28.1,
    "includedInPlan": 10000,
    "purchasedTopUps": 5000
  },
  "period": {
    "start": "2026-09-01",
    "end": "2026-09-30",
    "resetsUtc": "2026-10-01T00:00:00Z"
  },
  "subscription": {
    "currentPeriodEnd": "2026-10-14T09:31:22",
    "cancelAt": null
  },
  "counting": "Labels are counted per account (the API key owner) per calendar month in UTC. Design renders (ZPL, PDF, PNG) and batch jobs return 429 when the limit is reached; ZPL tools and label enrichment are counted but never blocked."
}

Feld	Bedeutung
`plan`	`free` (Developer), `starter` oder `pro`. Ohne aktives Abo: `free`. Batch-Jobs und Label-Anreicherung verlangen `pro`, andere Tarife erhalten dort `403`.
`status`	Abo-Status, z. B. `none`, `active`, `past_due`, `canceled`.
`billing`	`monthly` oder `annual`.
`labels.limit`	Monatliches Limit: `includedInPlan + purchasedTopUps`.
`labels.used`	Im laufenden Kalendermonat gezählte Labels (Plattform und API). Neue API-Renders sind sofort enthalten.
`labels.remaining`	`limit - used`, nie unter 0.
`labels.percentUsed`	`used / limit` in Prozent, eine Nachkommastelle.
`labels.includedInPlan`	Im Tarif enthaltene Labels: 100, 10.000 oder 100.000.
`labels.purchasedTopUps`	Labels aus allen gekauften Render-Top-ups.
`period.start`, `period.end`	Erster und letzter Tag des laufenden Kalendermonats (UTC).
`period.resetsUtc`	Ab wann `used` wieder bei 0 beginnt: der 1. des Folgemonats, 00:00 UTC.
`subscription.currentPeriodEnd`	Ende des laufenden Abrechnungszeitraums; `null` ohne Abo.
`subscription.cancelAt`	Gesetzt, wenn das Abo zum Periodenende gekündigt ist.
`counting`	Die Zählregel in einem Satz.

Kontingent richtig lesen

Vor einem Design-Render (ZPL, PDF, PNG) oder Batch-Job: Der Aufruf geht durch, wenn die Anzahl der Labels höchstens labels.remaining beträgt; sonst gibt es 429, bevor gerendert wird.
used kann limit übersteigen (remaining bleibt dann 0), weil ZPL-Tools und Label-Anreicherung nie blockiert werden.
Zählzeitraum ≠ Abrechnungszeitraum: Der Label-Zähler folgt dem Kalendermonat (period), nicht subscription.currentPeriodEnd.
Gepufferte Zählung: Limit und Verbrauch werden je Konto 60 Sekunden zwischengespeichert; Renders auf api.zplcloud.com zählen sofort im Speicher mit und werden alle 5 Sekunden in die Datenbank geschrieben. GET /v1/quota zeigt neue API-Renders deshalb sofort und Labels aus der Plattform spätestens nach 60 Sekunden; Billing in der Plattform kann einige Sekunden hinterherhinken.
Tarif: plan zeigt vor dem Aufruf, ob Batch-Jobs und Label-Anreicherung verfügbar sind (pro).
Monitoring: Ein zeitgesteuertes GET /v1/quota?webhookId=12 schickt api.quota.checked mit summary { plan, limit, used, remaining } an den Webhook.

Webhooks

GET /v1/webhooks listet die hinterlegten Webhooks des Key-Besitzers - firmenweit, bei Keys ohne Firma die persönlichen - die neuesten zuerst. id ist der Wert für webhookId. Secrets werden nie zurückgegeben; sie stehen in der Plattform unter Webhooks, wo jeder Webhook auch seine ID als ID n zeigt.

curl https://api.zplcloud.com/v1/webhooks -H "X-API-Key: sk_zplcloud_YOUR_KEY"

{
  "count": 2,
  "webhooks": [
    {
      "id": 12,
      "url": "https://erp.example.com/hooks/zplcloud",
      "status": "active",
      "events": ["label.rendered", "export.completed"],
      "lastDeliveryUtc": "2026-09-11T10:15:03.117",
      "lastHttpStatus": 204,
      "consecutiveFailures": 0,
      "createdUtc": "2026-08-02T07:45:19.5"
    },
    {
      "id": 7,
      "url": "https://hooks.example.org/labels",
      "status": "disabled",
      "events": ["print.status_changed"],
      "lastDeliveryUtc": "2026-07-30T16:02:41.9",
      "lastHttpStatus": 500,
      "consecutiveFailures": 4,
      "createdUtc": "2026-05-19T12:00:00"
    }
  ],
  "usage": "Pass id as ?webhookId=<id> on the design rendering (PDF, PNG), /v1/tools, /v1/enrich, /v1/batch, printer, agent, quota and webhook endpoints to be called when the request has finished; add &webhookResult=true to receive the result as well. Deliveries are signed with X-ZplCloud-Signature (HMAC-SHA256 of the body with the webhook secret)."
}

Feld	Bedeutung
`count`	Anzahl der Webhooks.
`webhooks[].id`	Wert für `webhookId`.
`url`	Empfänger-URL.
`status`	`active` oder `disabled`. Nur aktive Webhooks werden als `webhookId` akzeptiert (sonst 400).
`events`	Abonnierte Plattform-Events - für API-Callbacks ohne Bedeutung.
`lastDeliveryUtc`, `lastHttpStatus`	Letzter Zustellversuch und Statuscode des Empfängers; `null` vor der ersten Zustellung.
`consecutiveFailures`	Fehlgeschlagene Versuche seit der letzten erfolgreichen Zustellung.
`createdUtc`	Angelegt (UTC).
`usage`	Kurzer Hinweis zur Verwendung der Webhook-Parameter.

Webhook-Event: api.webhooks.listed, summary { count }. Payload, Signatur und Wiederholungen: Webhook-Callback.