Zebra ZC350 REST API

Warum eine REST API für den Zebra ZC350?

Der Zebra ZC350 ist ein hervorragender Kartendrucker, aber seine Standard-Ansteuerung ist es nicht. Wer den Drucker in einen eigenen Workflow integrieren will, steht in der Praxis vor drei operationellen Hürden: einer Windows-Arbeitsstation pro Drucker, einem USB-Kabel zwischen Arbeitsstation und Hardware sowie einem Hersteller-Treiberstack (CardStudio plus Silex SX Virtual Link), den man pro Arbeitsstation installieren und pflegen muss. Für eine einzelne Rezeption vielleicht akzeptabel; für ein Corporate- oder Multi-Site-Setup ein operativer Albtraum.

ConoCard bietet eine Alternative auf der richtigen Ebene: einen HTTP-Server, der den Drucker über IP ansteuert. Ein POST-Aufruf mit den gewünschten Kartendaten, und der Server erledigt Drucken, Encodieren, kontaktloses UID-Auslesen und Registrierung im 2N Access Commander, mit JSON-Antwort. Kein Treiber, kein USB, keine Arbeitsstation-Installationen.

Der primäre Endpoint: POST /api/issue

Ein Endpoint deckt 90% des operativen Bedarfs ab. Sie übergeben, was auf die Karte soll, für wen die Karte ist und optional welcher Drucker (bei Multi-Drucker-Setups). Der Server erledigt den Rest.

Authentifizierung

Alle Aufrufe erfordern ein Bearer-Token im Authorization-Header. Tokens werden in konstanter Zeit verglichen (keine Timing-Leaks). Der Service ist secure by default: ohne konfiguriertes Token verweigert ConoCard den Start.

Authorization: Bearer your-token-here

Request-Body (Beispiel)

{
  "guest": {
    "name": "Jane Doe",
    "reference": "booking-1234"
  },
  "validity": {
    "from": "2026-06-01T15:00:00Z",
    "until": "2026-06-05T11:00:00Z"
  },
  "printer": "192.168.1.42"
}

Response (JSON)

{
  "status": "issued",
  "uid": "04A5B6C7D8E9",
  "printed_at": "2026-05-30T13:42:18Z",
  "registered_in": "2n-access-commander",
  "audit_id": "01HXYZ..."
}

Code-Beispiele

curl

curl -X POST https://conocard.local/api/issue \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"guest":{"name":"Jane Doe"},"printer":"192.168.1.42"}'

Python (requests)

import requests, os

r = requests.post(
    "https://conocard.local/api/issue",
    headers={"Authorization": f"Bearer {os.environ['CONOCARD_TOKEN']}"},
    json={
        "guest": {"name": "Jane Doe"},
        "printer": "192.168.1.42",
    },
    timeout=30,
)
r.raise_for_status()
print(r.json()["uid"])

PHP

// guzzlehttp/guzzle
$client = new GuzzleHttp\Client();
$resp = $client->post('https://conocard.local/api/issue', [
  'headers' => ['Authorization' => 'Bearer ' . $token],
  'json'    => ['guest' => ['name' => 'Jane Doe'], 'printer' => '192.168.1.42'],
]);
$uid = json_decode($resp->getBody(), true)['uid'];

Audit-Log: JSON-Lines direkt ins SIEM

Jede Kartenausgabe — Erfolg und Fehler — wird in ein Append-only-Audit-Log im JSON-Lines-Format geschrieben. Eine Zeile pro Ereignis, direkt von Splunk, ELK, Microsoft Sentinel oder einem anderen SIEM einlesbar. Keine Parser, keine Schema-Konvertierungen.

{"ts":"2026-05-30T13:42:18Z","event":"issue.success","uid":"04A5B6C7D8E9","printer":"192.168.1.42","source":"api/jane.doe"}
{"ts":"2026-05-30T13:43:02Z","event":"issue.error","reason":"printer_unreachable","printer":"192.168.1.43"}

Mehrere Drucker von einem Server

Eine Instanz kann mehrere ZC350-Drucker gleichzeitig bedienen, über eine gemeinsame Control-Plane mit Source-IP-Demux. In der Praxis: konfigurieren Sie die Drucker-IP pro Request, oder hinterlegen Sie ein vordefiniertes Mapping in der Service-Konfiguration. Kein Eins-zu-eins-Verhältnis zwischen Server und Drucker.

Für Multi-Site-Szenarien läuft in der Regel eine Instanz pro Standort (in einer Linux-VM oder Windows-Server), oder eine zentrale Instanz mit VPN-Anbindung. Ein zentrales Multi-Site-Management-Dashboard steht auf der Roadmap.

ConoCard REST API vs. Zebra-Stack

Häufig gestellte Fragen