CloudPrint-Dokumentation/API-Referenz

Druckauftrag erstellen

Senden Sie ein hochgeladenes Dokument mit Idempotenz und expliziten Druckoptionen an einen ausgewählten Drucker.

POST/api/v1/print-jobsAPI-Version: v1operationId: createPrintJobAls Markdown anzeigen

Funktion dieser Methode

Senden Sie ein hochgeladenes Dokument mit Idempotenz und expliziten Druckoptionen an einen ausgewählten Drucker.

Authentifizierung

Senden Sie ein kurzlebiges Token in Authorization: Bearer <access_token>.

Erforderliche Scopes: print_jobs:write

Anfrage

Produktions-URL: https://public-api.cloudprint.me/api/v1/print-jobs

Parameter

Name	Position	Typ	Erforderlich	Beschreibung	Einschränkungen
Idempotency-Key	header	string	nein	Stabiler, vom Client erzeugter Schlüssel, damit Wiederholungen das ursprüngliche Ergebnis liefern und kein Duplikat erstellen.	maxLength: 128
X-Request-Id	header	string	nein	Optionale Kennung zur Anfrageverfolgung; CloudPrint gibt einen sicheren Wert im Antwort-Header zurück.	maxLength: 128; example: "order-100045-attempt-1"

Anfrageinhalt

Inhaltstyp: application/json

Name	Typ	Erforderlich	Beschreibung	Einschränkungen
document_id	string (uuid)	ja	Stabile UUID, die nach einem erfolgreichen Dokument-Upload zurückgegeben wird.	—
printer_id	string (uuid)	ja	Stabile CloudPrint-UUID des Zieldruckers.	—
copies	integer	nein	Anzahl der Exemplare, die CloudPrint beim Drucker anfordert.	min: 1; max: 99; example: 1
intent	string	nein	Geschäftlicher Zweck des Druckauftrags für die Diagnose und sinnvolle Standardwerte.	enum: document, shipping_label, product_label, invoice, packing_slip, a4_document, receipt; example: "shipping_label"
color_mode	string	nein	Gewünschter Farbmodus; default verwendet die Druckereinstellungen.	enum: default, monochrome, color; example: "default"
duplex_mode	string	nein	Gewünschter ein- oder beidseitiger Druckmodus.	enum: default, simplex, duplex_long_edge, duplex_short_edge; example: "default"
media_width_mm	number | null	nein	Gewünschte Breite des Druckmediums oder Etiketts in Millimetern.	min: 1; max: 2000; example: 58
media_height_mm	number | null	nein	Gewünschte Höhe des Druckmediums oder Etiketts in Millimetern.	min: 1; max: 2000; example: 40
dpi	integer | null	nein	Zielauflösung in Punkten pro Zoll; verwenden Sie einen vom Drucker unterstützten Wert.	min: 72; max: 2400; example: 203
scale_mode	string	nein	Legt fest, ob das Dokument seine Größe behält oder an das Zielmedium angepasst wird.	enum: none, fit; example: "none"
orientation	string	nein	Gewünschte Seitenausrichtung; default verwendet die Druckereinstellungen.	enum: default, portrait, landscape; example: "default"
offset_x_mm	number	nein	Horizontaler Druckversatz in Millimetern.	min: -2000; max: 2000; example: 0
offset_y_mm	number	nein	Vertikaler Druckversatz in Millimetern.	min: -2000; max: 2000; example: 0
margin_top_mm	number	nein	Zusätzlicher Druckrand in Millimetern.	min: 0; max: 2000; example: 0
margin_right_mm	number	nein	Zusätzlicher Druckrand in Millimetern.	min: 0; max: 2000; example: 0
margin_bottom_mm	number	nein	Zusätzlicher Druckrand in Millimetern.	min: 0; max: 2000; example: 0
margin_left_mm	number	nein	Zusätzlicher Druckrand in Millimetern.	min: 0; max: 2000; example: 0

Anfragebeispiele

cURL

curl -sS https://public-api.cloudprint.me/api/v1/print-jobs \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: order-100045-label' \
  -d '{
    "document_id": "44444444-4444-4444-8444-444444444444",
    "printer_id": "11111111-1111-4111-8111-111111111111",
    "copies": 1,
    "intent": "shipping_label",
    "media_width_mm": 58,
    "media_height_mm": 40,
    "dpi": 203
  }'

PHP

<?php

$payload = json_encode([
    'document_id' => '44444444-4444-4444-8444-444444444444',
    'printer_id' => '11111111-1111-4111-8111-111111111111',
    'copies' => 1,
    'intent' => 'shipping_label',
    'media_width_mm' => 58,
    'media_height_mm' => 40,
    'dpi' => 203,
], JSON_THROW_ON_ERROR);

$response = file_get_contents('https://public-api.cloudprint.me/api/v1/print-jobs', false, stream_context_create([
    'http' => [
        'method' => 'POST',
        'header' => [
            'Authorization: Bearer ' . getenv('CLOUDPRINT_ACCESS_TOKEN'),
            'Content-Type: application/json',
            'Idempotency-Key: order-100045-label',
        ],
        'content' => $payload,
    ],
]));

$printJob = json_decode((string) $response, true, flags: JSON_THROW_ON_ERROR);

Antwort

HTTP-Status: 201 — Ressource erstellt.

Antwortfelder

Name	Typ	Erforderlich	Beschreibung	Einschränkungen
print_job_id	string (uuid)	ja	Stabile UUID des Druckauftrags; für Statusabfragen und Support speichern.	—
document_id	string (uuid)	ja	Stabile UUID, die nach einem erfolgreichen Dokument-Upload zurückgegeben wird.	—
document_mime_type	string	ja	MIME-Typ des bereitgestellten Dokuments.	example: "application/pdf"
document_format	string	ja	Explizites Druckformat, beispielsweise pdf oder raw.	enum: pdf, raw; example: "pdf"
document_raw_language	string | null	ja	Druckerbefehlssprache der RAW-Daten, beispielsweise ZPL oder EPL.	enum: tspl, zpl, cpcl, escpos; example: null
printer_id	string (uuid)	ja	Stabile CloudPrint-UUID des Zieldruckers.	—
status	string	ja	Aktueller Ressourcen- oder Prozessstatus; verwenden Sie die Enum-Werte der jeweiligen Methode.	enum: pending, reserved, printing, printed, failed, cancelled; example: "pending"
copies	integer	ja	Anzahl der Exemplare, die CloudPrint beim Drucker anfordert.	min: 1; max: 99; example: 1
intent	string	ja	Geschäftlicher Zweck des Druckauftrags für die Diagnose und sinnvolle Standardwerte.	enum: document, shipping_label, product_label, invoice, packing_slip, a4_document, receipt; example: "shipping_label"
color_mode	string	ja	Gewünschter Farbmodus; default verwendet die Druckereinstellungen.	enum: default, monochrome, color; example: "default"
duplex_mode	string	ja	Gewünschter ein- oder beidseitiger Druckmodus.	enum: default, simplex, duplex_long_edge, duplex_short_edge; example: "default"
media_width_mm	number | null	ja	Gewünschte Breite des Druckmediums oder Etiketts in Millimetern.	min: 1; max: 2000; example: 58
media_height_mm	number | null	ja	Gewünschte Höhe des Druckmediums oder Etiketts in Millimetern.	min: 1; max: 2000; example: 40
dpi	integer | null	ja	Zielauflösung in Punkten pro Zoll; verwenden Sie einen vom Drucker unterstützten Wert.	min: 72; max: 2400; example: 203
scale_mode	string	ja	Legt fest, ob das Dokument seine Größe behält oder an das Zielmedium angepasst wird.	enum: none, fit; example: "none"
orientation	string	ja	Gewünschte Seitenausrichtung; default verwendet die Druckereinstellungen.	enum: default, portrait, landscape; example: "default"
offset_x_mm	number	ja	Horizontaler Druckversatz in Millimetern.	min: -2000; max: 2000; example: 0
offset_y_mm	number	ja	Vertikaler Druckversatz in Millimetern.	min: -2000; max: 2000; example: 0
margin_top_mm	number	ja	Zusätzlicher Druckrand in Millimetern.	min: 0; max: 2000; example: 0
margin_right_mm	number	ja	Zusätzlicher Druckrand in Millimetern.	min: 0; max: 2000; example: 0
margin_bottom_mm	number	ja	Zusätzlicher Druckrand in Millimetern.	min: 0; max: 2000; example: 0
margin_left_mm	number	ja	Zusätzlicher Druckrand in Millimetern.	min: 0; max: 2000; example: 0
created_at	string (date-time)	ja	Von CloudPrint erfasster ISO-8601-Zeitstempel.	—
reserved_at	string | null (date-time)	ja	Von CloudPrint erfasster ISO-8601-Zeitstempel.	—
started_at	string | null (date-time)	ja	Von CloudPrint erfasster ISO-8601-Zeitstempel.	—
completed_at	string | null (date-time)	ja	Von CloudPrint erfasster ISO-8601-Zeitstempel.	—
failure_reason	string | null	ja	Maschinenlesbarer oder diagnostischer Grund für einen fehlgeschlagenen Druck.	—

Beispielantwort

{
  "print_job_id": "11111111-1111-4111-8111-111111111111",
  "document_id": "11111111-1111-4111-8111-111111111111",
  "document_mime_type": "application/pdf",
  "document_format": "pdf",
  "document_raw_language": null,
  "printer_id": "11111111-1111-4111-8111-111111111111",
  "status": "pending",
  "copies": 1,
  "intent": "shipping_label",
  "color_mode": "default",
  "duplex_mode": "default",
  "media_width_mm": 58,
  "media_height_mm": 40,
  "dpi": 203,
  "scale_mode": "none",
  "orientation": "default",
  "offset_x_mm": 0,
  "offset_y_mm": 0,
  "margin_top_mm": 0,
  "margin_right_mm": 0,
  "margin_bottom_mm": 0,
  "margin_left_mm": 0,
  "created_at": "2026-08-06T12:00:00Z",
  "reserved_at": "2026-08-06T12:00:00Z",
  "started_at": "2026-08-06T12:00:00Z",
  "completed_at": "2026-08-06T12:00:00Z",
  "failure_reason": "string"
}

Fehler

HTTP-Status	Beschreibung
401	Authentifizierung fehlt oder ist ungültig.
403	Das Token hat nicht die erforderlichen Berechtigungen.
409	Die Anfrage widerspricht dem aktuellen Zustand.
422	Mindestens ein Feld ist ungültig.
429	Anfragelimit überschritten; beachten Sie Retry-After.
500	Interner CloudPrint-Fehler.

Hinweise zur Integration

• Senden Sie für jede wiederholbare Anfrage einen stabilen Idempotency-Key.
• 201 bedeutet, dass der Auftrag existiert, nicht dass Papier bedruckt wurde. Fragen Sie bis printed, failed oder cancelled ab.
• Prüfen Sie die Optionen gegen die Druckerfunktionen.

Verwandte Dokumentation

Dokument zum Drucken hochladenLaden Sie vor dem Erstellen eines Druckauftrags ein druckfertiges PDF oder explizite RAW-Druckersprachdaten hoch.Status eines Druckauftrags abrufenFragen Sie den Status eines Druckauftrags ab, bis er printed, failed oder cancelled lautet.Idempotentes Erstellen von DruckaufträgenVerhindern Sie doppelte Ausdrucke, wenn Anfragen nach Timeout oder Netzwerkfehler wiederholt werden.

DienststatusOpenAPIDeveloper PortalKonto öffnenDatenschutzerklärungNutzungsbedingungenZahlungen und ErstattungenDPAService Level Agreement