API: Aufträge und Seriendruck
Druckaufträge aus Vorlagen und Daten anlegen, ihren Fortschritt verfolgen und die Warteschlange steuern.
Einen Auftrag anlegen
POST /api/v1/jobs nimmt entgegen, was gedruckt werden soll, und die Daten dazu. Jeder Datensatz ergibt ein Blatt.
| Feld | Bedeutung |
|---|---|
template_id | ID einer gespeicherten Vorlage. Alternativ ein vollständiges Dokument senden. |
document | Ein ganzes Dokument als JSON, statt einer Vorlage. |
records | Liste von Objekten mit den Platzhalterwerten, eines pro Blatt. |
csv | Dieselben Daten als CSV- oder JSON-Text, statt records. |
copies | Exemplare je Datensatz. Vorgabe 1. |
additional_template_ids | Vorlagen, die für jeden Datensatz nach der Hauptvorlage gedruckt werden, z. B. der Umschlag. |
scheduled_at | Nicht vor diesem Zeitpunkt beginnen (ISO 8601). |
confirm_each_page | Nach jedem Blatt warten, bis der Auftrag fortgesetzt wird (Handeinzug). |
strict | Auftrag ablehnen, wenn ein Platzhalter keinen Wert hat. |
strict_layout | Auftrag ablehnen, wenn ein Blatt außerhalb der Ränder oder in eine Post-Zone schreibt. |
hold | Auftrag pausiert anlegen; er wartet in der App auf Freigabe. |
callback_url | Adresse, die benachrichtigt wird, wenn der Auftrag beendet ist. |
seed | Feste Handschrift-Variante; ohne Angabe zufällig. |
curl -X POST http://127.0.0.1:8787/api/v1/jobs \
-H 'Content-Type: application/json' \
-d '{
"template_id": "voucher-qr",
"csv": "salutation;code\nFrau Schmidt;FHE93KL\nHerr Meier;KQ7X2MB",
"strict": true
}'Einen Auftrag verfolgen
GET /api/v1/jobs/{id} liefert den Auftrag mit jeder Seite. Der Zustand ist einer von:
| Zustand | Bedeutung |
|---|---|
scheduled | Wartet auf seine Startzeit. |
queued | Wartet auf den Drucker. |
printing | Ein Blatt wird geschrieben. |
paused | Von einem Menschen pausiert oder wartet auf Freigabe. |
waiting_for_paper | Wartet, bis das nächste Blatt eingelegt und bestätigt ist. |
done | Alle Blätter geschrieben. |
failed | Ein Blatt ist fehlgeschlagen; das Feld error nennt den Grund. |
canceled | Abgebrochen. |
Steuern
- POST /api/v1/jobs/{id}/pause, /resume und /cancel wirken auf einen Auftrag.
- Resume bestätigt auch einen Papierwechsel und druckt die restlichen Blätter eines fehlgeschlagenen Auftrags.
- POST /api/v1/queue/pause und /resume halten die ganze Warteschlange an und geben sie frei.
- GET /api/v1/jobs/{id}/pages/{page}/preview.svg liefert das Bild eines Blatts (Seitenzählung beginnt bei 0).
Warnungen
Jede Seite eines Auftrags trägt ihre Warnungen: ein Platzhalter ohne Wert, Text außerhalb der Ränder, ein QR-Code, der für den Stift zu klein ist. Lies sie vor einer großen Serie, oder sende strict und strict_layout, damit ein solcher Auftrag abgelehnt wird.