Entwickler-Doku
Printaloft ist eine kleine HTTPS-API. Sie schicken ein PDF an eine Rolle, Printaloft gibt es an die richtige Station und sagt Ihnen, was passiert ist.
Grundlagen
Basisadresse: https://printcloud.apps.ubartas.cloud. Jede Anfrage trägt Ihren API-Schlüssel als „Authorization: Bearer pck_…“. Schlüssel gibt es je Konto, jeder ist einzeln sperrbar.
Eine Rolle ist ein Name, den Sie wählen, zum Beispiel packing-slip, invoice oder label. In Ihrem Konto zeigt jede Rolle auf einen Drucker und Schacht an einer Station. Ihr Code kennt nur Rollen.
Auftrag senden
POST /v1/jobs mit dem PDF als Base64 (bis 20 MB). Mit ?wait=50 wartet die Anfrage bis zu 50 Sekunden auf den Endstand.
idempotencyKey ist Pflicht und je Druck eindeutig. Nehmen Sie etwas Festes aus Ihrem System, zum Beispiel Bestellnummer, Beleg und Versuch.
curl -X POST "https://printcloud.apps.ubartas.cloud/v1/jobs?wait=50" \
-H "Authorization: Bearer pck_…" \
-H "Content-Type: application/json" \
-d '{
"idempotencyKey": "order-1042:packing-slip:1",
"role": "packing-slip",
"pdfBase64": "JVBERi0xLjcK…",
"fileName": "packing-slip-1042.pdf",
"jobName": "Order 1042"
}'Die Antwort
201 bei einem neuen Auftrag, 200, wenn derselbe Schlüssel wiederkommt. status ist queued, delivered, spooled, printed, failed, cancelled oder expired. ok ist nur bei printed true.
Ist der Auftrag nach der Wartezeit noch nicht fertig, fragen Sie mit GET /v1/jobs/<jobId>?wait=50 nach.
{
"ok": true,
"accepted": true,
"jobId": "job_7f3c…",
"status": "printed",
"message": "Gedruckt.",
"printer": "Brother HL-L5100DN (Schacht 2)",
"stationOnline": true
}Stand abfragen
Liefert dasselbe Objekt wie oben. Beliebig oft wiederholbar, es druckt nie etwas.
curl "https://printcloud.apps.ubartas.cloud/v1/jobs/job_7f3c…?wait=50" \
-H "Authorization: Bearer pck_…"Wiederholen ohne Doppeldruck
Netzfehler und Zeitlimits kommen vor. Wiederholen Sie mit demselben idempotencyKey: Sie erreichen denselben Auftrag, nichts wird doppelt gedruckt. Derselbe Schlüssel mit anderem PDF gibt 409.
Ein gewollter Nachdruck bekommt einen neuen Schlüssel, zum Beispiel indem Sie den Versuch am Ende hochzählen.
Abbrechen und Fristen
POST /v1/jobs/<jobId>/cancel bricht einen Auftrag ab. POST /v1/jobs/cancel nimmt jobIds, idempotencyKeys oder allOpen mit olderThanSec. Abbrechen geht für alles, was noch nicht im Spooler liegt.
Jeder Auftrag hat eine Frist bis zum Spooler: Vorgabe 15 Minuten, oder expiresInSec je Auftrag (30 Sekunden bis 24 Stunden). Danach ist er expired und wird nie gedruckt.
curl -X POST "https://printcloud.apps.ubartas.cloud/v1/jobs/cancel" \
-H "Authorization: Bearer pck_…" \
-H "Content-Type: application/json" \
-d '{ "allOpen": true, "olderThanSec": 600 }'Fehler
400 ungültiger Auftrag, 401 Schlüssel fehlt oder gesperrt, 409 gleicher Schlüssel mit anderem Inhalt, 413 PDF zu groß. Bei 5xx ohne accepted: true wurde der Auftrag nicht angenommen; mit demselben Schlüssel wiederholen ist ungefährlich.
Der Agent
Ein Windows-Dienst für den PC neben den Druckern. Einmal mit einem Code aus Ihrem Konto koppeln; danach baut er nur ausgehende HTTPS-Verbindungen auf, holt Aufträge ab, druckt über den Windows-Spooler und meldet zurück.
Agent und API-Schlüssel gibt es mit dem frühen Zugang. Schreiben Sie an mail@printaloft.com.