Druckauftrag aus einer URL erstellen

Rufen Sie ein Dokument von einer öffentlichen HTTPS-URL ab und erstellen Sie Dokument und Druckauftrag in einer Anfrage.

POST/api/v1/print-jobs/from-urlAPI-Version: v1operationId: createPrintJobFromUrlAls Markdown anzeigen

Funktion dieser Methode

Rufen Sie ein Dokument von einer öffentlichen HTTPS-URL ab und erstellen Sie Dokument und Druckauftrag in einer Anfrage.

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/from-url

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_url`	`string (uri)`	ja	Öffentliche HTTPS-URL, von der CloudPrint das Dokument abruft.	example: `"https://files.example.com/labels/order-100045.pdf"`
`document_filename`	`string \| null`	nein	Dateiname für Formaterkennung und Diagnose.	example: `"order-100045.pdf"`
`document_format`	`string \| null`	nein	Explizites Druckformat, beispielsweise `pdf` oder `raw`.	enum: `pdf`, `raw`; example: `"pdf"`
`document_raw_language`	`string \| null`	nein	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.	—
`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/from-url \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: order-100045-label' \
  -d '{
    "document_url": "https://files.example.com/labels/order-100045.pdf",
    "document_filename": "order-100045.pdf",
    "printer_id": "11111111-1111-4111-8111-111111111111",
    "copies": 1,
    "intent": "shipping_label",
    "media_width_mm": 58,
    "media_height_mm": 40,
    "dpi": 203
  }'

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
`400`	Prüfen Sie Format und Parameter.
`401`	Authentifizierung fehlt oder ist ungültig.
`403`	Das Token hat nicht die erforderlichen Berechtigungen.
`409`	Die Anfrage widerspricht dem aktuellen Zustand.
`413`	Der Anfrageinhalt überschreitet die zulässige Größe.
`415`	Das Format wird nicht unterstützt.
`422`	Mindestens ein Feld ist ungültig.
`429`	Anfragelimit überschritten; beachten Sie Retry-After.
`500`	Interner CloudPrint-Fehler.

Hinweise zur Integration

Die Quelle muss eine öffentliche HTTPS-URL sein; localhost, private Netze, eingebettete Zugangsdaten und unsichere Weiterleitungen werden abgelehnt.
Verwenden Sie eine kurzlebige, eng begrenzte Download-URL mit ausreichender Gültigkeit.
Wenden Sie dieselben Regeln für Idempotenz und Statusverfolgung an.

Druckauftrag aus einer URL erstellen ​

Funktion dieser Methode ​

Authentifizierung ​

Anfrage ​

Parameter ​

Anfrageinhalt ​

Anfragebeispiele ​

cURL ​

Antwort ​

Antwortfelder ​

Beispielantwort ​

Fehler ​

Hinweise zur Integration ​

Verwandte Dokumentation ​