Documentación de CloudPrint/Referencia de la API

Crear un trabajo de impresión desde una URL

Descarga un documento desde una URL HTTPS pública y crea el documento y el trabajo en una sola solicitud.

POST/api/v1/print-jobs/from-urlVersión de la API: v1operationId: createPrintJobFromUrlVer como Markdown

Qué hace este método

Descarga un documento desde una URL HTTPS pública y crea el documento y el trabajo en una sola solicitud.

Autenticación

Envía un token de corta duración en Authorization: Bearer <access_token>.

Permisos necesarios: documents:write, print_jobs:write

Solicitud

URL de producción: https://public-api.cloudprint.me/api/v1/print-jobs/from-url

Parámetros

Nombre	Ubicación	Tipo	Obligatorio	Descripción	Restricciones
Idempotency-Key	header	string	no	Clave estable generada por el cliente para que los reintentos devuelvan el resultado original sin crear duplicados.	maxLength: 128
X-Request-Id	header	string	no	Identificador opcional para rastrear la solicitud; CloudPrint devuelve un valor seguro en la cabecera de respuesta.	maxLength: 128; example: "order-100045-attempt-1"

Cuerpo de la solicitud

Tipo de contenido: application/json

Nombre	Tipo	Obligatorio	Descripción	Restricciones
document_url	string (uri)	sí	URL HTTPS pública desde la que CloudPrint descarga el documento.	example: "https://files.example.com/labels/order-100045.pdf"
document_filename	string | null	no	Nombre de archivo usado para detectar el formato y facilitar el diagnóstico.	example: "order-100045.pdf"
document_format	string | null	no	Formato de impresión explícito, por ejemplo pdf o raw. Ambos formatos usan documents:write.	enum: pdf, raw; example: "pdf"
document_raw_language	string | null	no	Lenguaje de comandos de los datos RAW, por ejemplo ZPL o TSPL.	enum: tspl, zpl, cpcl, escpos; example: null
printer_id	string (uuid)	sí	UUID estable de la impresora de destino en CloudPrint.	—
copies	integer	no	Número de copias que CloudPrint solicita a la impresora.	min: 1; max: 99; example: 1
intent	string	no	Finalidad del trabajo de impresión; ayuda al diagnóstico y a elegir valores predeterminados adecuados.	enum: document, shipping_label, product_label, invoice, packing_slip, a4_document, receipt; example: "shipping_label"
color_mode	string	no	Modo de color solicitado; default usa la configuración de la impresora.	enum: default, monochrome, color; example: "default"
duplex_mode	string	no	Modo de impresión a una o dos caras solicitado.	enum: default, simplex, duplex_long_edge, duplex_short_edge; example: "default"
media_width_mm	number | null	no	Anchura solicitada del soporte o la etiqueta en milímetros.	min: 1; max: 2000; example: 58
media_height_mm	number | null	no	Altura solicitada del soporte o la etiqueta en milímetros.	min: 1; max: 2000; example: 40
dpi	integer | null	no	Resolución de impresión en puntos por pulgada; usa un valor compatible con la impresora.	min: 72; max: 2400; example: 203
scale_mode	string	no	Determina si el documento conserva su tamaño o se ajusta al soporte de destino.	enum: none, fit; example: "none"
orientation	string	no	Orientación de página solicitada; default usa la configuración de la impresora.	enum: default, portrait, landscape; example: "default"
offset_x_mm	number	no	Desplazamiento horizontal de impresión en milímetros.	min: -2000; max: 2000; example: 0
offset_y_mm	number	no	Desplazamiento vertical de impresión en milímetros.	min: -2000; max: 2000; example: 0
margin_top_mm	number	no	Margen de impresión adicional en milímetros.	min: 0; max: 2000; example: 0
margin_right_mm	number	no	Margen de impresión adicional en milímetros.	min: 0; max: 2000; example: 0
margin_bottom_mm	number	no	Margen de impresión adicional en milímetros.	min: 0; max: 2000; example: 0
margin_left_mm	number	no	Margen de impresión adicional en milímetros.	min: 0; max: 2000; example: 0

Ejemplos de solicitud

cURL

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
  }'

Respuesta

Estado HTTP: 201 — Recurso creado.

Campos de respuesta

Nombre	Tipo	Obligatorio	Descripción	Restricciones
print_job_id	string (uuid)	sí	UUID estable del trabajo de impresión; guárdalo para consultar el estado y solicitar soporte.	—
document_id	string (uuid)	sí	UUID estable devuelto después de subir correctamente el documento.	—
document_mime_type	string	sí	Tipo MIME del documento proporcionado.	example: "application/pdf"
document_format	string	sí	Formato de impresión explícito, por ejemplo pdf o raw. Ambos formatos usan documents:write.	enum: pdf, raw; example: "pdf"
document_raw_language	string | null	sí	Lenguaje de comandos de los datos RAW, por ejemplo ZPL o TSPL.	enum: tspl, zpl, cpcl, escpos; example: null
printer_id	string (uuid)	sí	UUID estable de la impresora de destino en CloudPrint.	—
status	string	sí	Estado actual del recurso o flujo; usa los valores enum específicos del método.	enum: pending, reserved, printing, printed, failed, cancelled; example: "pending"
copies	integer	sí	Número de copias que CloudPrint solicita a la impresora.	min: 1; max: 99; example: 1
intent	string	sí	Finalidad del trabajo de impresión; ayuda al diagnóstico y a elegir valores predeterminados adecuados.	enum: document, shipping_label, product_label, invoice, packing_slip, a4_document, receipt; example: "shipping_label"
color_mode	string	sí	Modo de color solicitado; default usa la configuración de la impresora.	enum: default, monochrome, color; example: "default"
duplex_mode	string	sí	Modo de impresión a una o dos caras solicitado.	enum: default, simplex, duplex_long_edge, duplex_short_edge; example: "default"
media_width_mm	number | null	sí	Anchura solicitada del soporte o la etiqueta en milímetros.	min: 1; max: 2000; example: 58
media_height_mm	number | null	sí	Altura solicitada del soporte o la etiqueta en milímetros.	min: 1; max: 2000; example: 40
dpi	integer | null	sí	Resolución de impresión en puntos por pulgada; usa un valor compatible con la impresora.	min: 72; max: 2400; example: 203
scale_mode	string	sí	Determina si el documento conserva su tamaño o se ajusta al soporte de destino.	enum: none, fit; example: "none"
orientation	string	sí	Orientación de página solicitada; default usa la configuración de la impresora.	enum: default, portrait, landscape; example: "default"
offset_x_mm	number	sí	Desplazamiento horizontal de impresión en milímetros.	min: -2000; max: 2000; example: 0
offset_y_mm	number	sí	Desplazamiento vertical de impresión en milímetros.	min: -2000; max: 2000; example: 0
margin_top_mm	number	sí	Margen de impresión adicional en milímetros.	min: 0; max: 2000; example: 0
margin_right_mm	number	sí	Margen de impresión adicional en milímetros.	min: 0; max: 2000; example: 0
margin_bottom_mm	number	sí	Margen de impresión adicional en milímetros.	min: 0; max: 2000; example: 0
margin_left_mm	number	sí	Margen de impresión adicional en milímetros.	min: 0; max: 2000; example: 0
created_at	string (date-time)	sí	Marca de tiempo ISO 8601 registrada por CloudPrint.	—
reserved_at	string | null (date-time)	sí	Marca de tiempo ISO 8601 registrada por CloudPrint.	—
started_at	string | null (date-time)	sí	Marca de tiempo ISO 8601 registrada por CloudPrint.	—
completed_at	string | null (date-time)	sí	Marca de tiempo ISO 8601 registrada por CloudPrint.	—
failure_reason	string | null	sí	Motivo legible por máquina o de diagnóstico registrado cuando falla la impresión.	—

Ejemplo de respuesta

{
  "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"
}

Errores

Estado HTTP	Descripción
400	Comprueba el formato y los parámetros.
401	Falta la autenticación o no es válida.
403	El token no tiene permisos suficientes.
409	La solicitud entra en conflicto con el estado actual.
413	El cuerpo supera el tamaño permitido.
415	El formato no es compatible.
422	Uno o varios campos no son válidos.
429	Se superó el límite de solicitudes; respeta Retry-After.
500	Error interno de CloudPrint.
503	Servicio temporalmente no disponible.

Recomendaciones de integración

• La fuente debe ser una URL HTTPS pública; se rechazan localhost, redes privadas, credenciales embebidas y redirecciones inseguras.
• Usa una URL de descarga breve, limitada y válida durante el tiempo suficiente. PDF y RAW conservan el permiso existente documents:write.
• Corrige el documento tras un 422; reintenta un 503 temporal de inspección con espera progresiva y limitada.
• Aplica las mismas reglas de idempotencia y seguimiento.

Documentación relacionada

Crear un trabajo de impresiónEnvía un documento subido a una impresora seleccionada con idempotencia y opciones de impresión explícitas.Crear un trabajo de impresión desde Base64Decodifica un documento Base64 pequeño y crea el documento y el trabajo en una sola solicitud.Obtener el estado de un trabajo de impresiónConsulta el estado de un trabajo hasta que sea printed, failed o cancelled.

Estado del servicioOpenAPIDeveloper PortalAbrir cuentaPolítica de privacidadTérminos de usoTratamiento de datosService Level Agreement