--- title: "Druckauftrag erstellen" description: "Senden Sie ein hochgeladenes Dokument mit Idempotenz und expliziten Druckoptionen an einen ausgewählten Drucker." --- # 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 `. **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 ```bash 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 '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 ```json { "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.