API-Referenz¶

Die REST-API des Druckservers (tavletta serve) für Programme, die Etiketten drucken: jede Anfrage mit ihrer Rolle, ihren Feldern, Antworten und Fehlercodes. Eine Anleitung für ein Inventarprogramm mit Code in Python und C# ist Ein Inventarprogramm anbinden; die Installation des Servers Serverinstallation.

Diese Seite entsteht aus der OpenAPI-3.1-Beschreibung des Servers (tools/openapi_docs.py). Programme und Codegeneratoren lesen dieselbe Beschreibung: docs/openapi.yaml im Quellcode oder GET /api/v1/openapi.json von einem laufenden Server.

Grundlagen¶

• Adresse: http://<server>:8790/api/v1 oder die HTTPS-Adresse des Reverse Proxys. Die Beispiele verwenden $TAVLETTA dafür und $TOKEN für das Zugangstoken:

TAVLETTA=https://labels.example.com/api/v1
TOKEN=tav_0123456789ab_...

• JSON hinein und heraus (UTF-8). Anfragen mit Inhalt brauchen Content-Type: application/json und eine Content-Length.
• Jede Anfrage ausser GET /api/v1/health braucht den Header Authorization: Bearer <token>.
• Meldungen kommen in der Sprache von Accept-Language (z. B. de-CH), sonst auf Englisch. Codes ändern sich nie mit der Sprache: Programme prüfen den Code, Menschen lesen die Meldung.
• Unbekannte Felder werden abgewiesen (unknown_field): Ein Tippfehler druckt nie etwas anderes als gemeint.

Rollen¶

Jedes Zugangstoken hat eine Rolle (tokens.toml, erstellt mit tavletta token new). Eine Rolle darf, was die Rollen darüber dürfen.

Ein Token kann auf einige Drucker aus printers.toml beschränkt werden: Die anderen sind für es dann "nicht gefunden" (404 printer_not_found).

Fehler¶

Jeder Fehler ist JSON mit einem festen Code und einer Meldung für Menschen:

{"error": {"code": "label_not_found", "message": "No such label: asset-tag.tavletta"}}

printer_<code>: das Problem des Druckers, einer von generic, not_found, timeout, stalled, port_closed, busy, paused, cover_open, head_open, jam, media_jam, out_of_labels, out_of_paper, label_not_found, wrong_media, paper_size, page_too_large, too_long, too_wide, code_too_large, ribbon, ribbon_out, ribbon_direct, no_cassette, bad_cassette, supplies, format, resolution, queue_paused, job_held, job_canceled, usb_not_found, usb_permission, serial_permission, battery, overheat, unsupported_model, unknown_model, editor_lite.

Ein fehlgeschlagener Auftrag sagt in seinem error warum, mit diesen Codes:

Grenzen¶

Anfragen¶

Neben den Antworten, die bei jeder Anfrage stehen, kann jede Anfrage die allgemeinen Fehler der Tabelle oben bekommen: 401, 403, 405, 408, 421, 429 (too_many_requests), 500 und 503, und eine mit Inhalt 411, 413 (too_large) und 415.

GET /api/v1/health¶

Läuft der Server; ohne Token (für Health Checks).

• Rolle: keine (ohne Token)

curl "$TAVLETTA/health"

GET /api/v1/openapi.json¶

Diese Beschreibung (OpenAPI 3.1); ein Token mit beliebiger Rolle.

• Rolle: preview

curl -H "Authorization: Bearer $TOKEN" \
     "$TAVLETTA/openapi.json"

GET /api/v1/printers¶

Die Drucker aus printers.toml, die das Token verwenden darf, mit ihrem Zustand; ohne die Datei die Druckermodelle, die für jedes eingestellte Adresse und die gefundenen Drucker (--discover).

• Rolle: preview

curl -H "Authorization: Bearer $TOKEN" \
     "$TAVLETTA/printers"

GET /api/v1/printers/{id}/status¶

Einen Drucker nach seinem Zustand fragen: Material, Probleme, Auflösung.

• Rolle: preview

curl -H "Authorization: Bearer $TOKEN" \
     "$TAVLETTA/printers/it-cab/status"

GET /api/v1/labels¶

Die Etikettendateien im Etikettenordner und seinen Unterordnern.

• Rolle: preview

curl -H "Authorization: Bearer $TOKEN" \
     "$TAVLETTA/labels"

GET /api/v1/labels/{name}¶

Womit ein Etikett gefüllt werden kann: Elemente, Variablen, Datenspalten, Grösse, Zähler.

• Rolle: preview

curl -H "Authorization: Bearer $TOKEN" \
     "$TAVLETTA/labels/asset-tag"

POST /api/v1/preview¶

Das ausgefüllte Etikett als Bild; es wird nichts gedruckt.

• Rolle: preview

Felder des Inhalts:

curl -H "Authorization: Bearer $TOKEN" \
     -H 'Content-Type: application/json' \
     -d '{"label": "asset-tag", "printer": "it-cab", "data_rows": [{"AssetNumber": "100001"}], "format": "png"}' \
     -o preview.png \
     "$TAVLETTA/preview"

POST /api/v1/print¶

Drucken: Die Anfrage wird geprüft und dann eingereiht; jeder Drucker druckt einen Auftrag nach dem anderen.

• Rolle: print

Felder des Inhalts:

curl -H "Authorization: Bearer $TOKEN" \
     -H 'Content-Type: application/json' \
     -d '{"label": "asset-tag", "printer": "it-cab", "data_rows": [{"AssetNumber": "100001"}], "wait": 30}' \
     "$TAVLETTA/print"

GET /api/v1/jobs/{id}¶

Zustand eines Druckauftrags (ein print-Token: seine eigenen Aufträge; admin: alle). 24 Stunden nach dem Ende aufbewahrt.

• Rolle: print

curl -H "Authorization: Bearer $TOKEN" \
     "$TAVLETTA/jobs/$JOB"

DELETE /api/v1/jobs/{id}¶

Einen Auftrag abbrechen: sofort, solange er wartet, nach dem aktuellen Etikett, während er druckt.

• Rolle: print

curl -H "Authorization: Bearer $TOKEN" \
     -X DELETE \
     "$TAVLETTA/jobs/$JOB"

Antworten¶

Job¶

Label¶

NamedPrinter¶

Ein Drucker aus printers.toml.

PrinterStatus¶

Preview¶

Beispiel eines Auftrags:

{
  "id": "HxIwYqXuV4qYRBM7",
  "state": "done",
  "printer": "cab",
  "printer_name": "it-cab",
  "host": "cab-it.example.com",
  "owner": "inventory-tool",
  "label": "asset-tag.tavletta",
  "printed": 20,
  "total": 20,
  "rows_printed": 20,
  "cancel_requested": false,
  "error": null,
  "remark": null,
  "warnings": [],
  "created": "2026-11-12T15:34:45+00:00",
  "started": "2026-11-12T15:34:45+00:00",
  "finished": "2026-11-12T15:35:04+00:00"
}