Documentación de CloudPrint/Referencia de la API

Crear un trabajo de impresión

Envía un documento subido a una impresora seleccionada con idempotencia y opciones de impresión explícitas.

POST/api/v1/print-jobsVersión de la API: v1operationId: createPrintJobVer como Markdown

Qué hace este método

Envía un documento subido a una impresora seleccionada con idempotencia y opciones de impresión explícitas.

Autenticación

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

Permisos necesarios: print_jobs:write

Solicitud

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

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_id	string (uuid)	sí	UUID estable devuelto después de subir correctamente el documento.	—
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 \
  -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);

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.	enum: pdf, raw; example: "pdf"
document_raw_language	string | null	sí	Lenguaje de comandos de los datos RAW, por ejemplo ZPL o EPL.	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
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.
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.

Recomendaciones de integración

• Envía un Idempotency-Key estable en toda solicitud que pueda repetirse.
• 201 significa que el trabajo existe, no que el papel se haya impreso. Consulta hasta printed, failed o cancelled.
• Valida las opciones con las capacidades de la impresora.

Documentación relacionada

Subir un documento para imprimirSube un PDF listo para imprimir o datos RAW en un lenguaje de impresora definido antes de crear el trabajo.Obtener el estado de un trabajo de impresiónConsulta el estado de un trabajo hasta que sea printed, failed o cancelled.Creación idempotente de trabajos de impresiónEvita impresiones duplicadas al repetir solicitudes después de un tiempo de espera agotado o un fallo de red.

Estado del servicioOpenAPIDeveloper PortalAbrir cuentaPolítica de privacidadTérminos de usoPagos y reembolsosTratamiento de datosService Level Agreement