Obtener el estado de un trabajo de impresión
Consulta el estado de un trabajo hasta que sea printed, failed o cancelled.
Qué hace este método
Consulta el estado de un trabajo hasta que sea printed, failed o cancelled.
Autenticación
Envía un token de corta duración en Authorization: Bearer <access_token>.
Permisos necesarios: print_jobs:read
Solicitud
URL de producción: https://public-api.cloudprint.me/api/v1/print-jobs/{printJobId}
Parámetros
| Nombre | Ubicación | Tipo | Obligatorio | Descripción | Restricciones |
|---|---|---|---|---|---|
printJobId | path | string (uuid) | sí | UUID estable del trabajo de impresión indicado en la ruta. | — |
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
El método no tiene cuerpo de solicitud.
Ejemplos de solicitud
cURL
bash
curl -sS https://public-api.cloudprint.me/api/v1/print-jobs/55555555-5555-4555-8555-555555555555 \
-H "Authorization: Bearer $ACCESS_TOKEN"Respuesta
Estado HTTP: 200 — Solicitud completada.
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
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"
}Errores
| Estado HTTP | Descripción |
|---|---|
401 | Falta la autenticación o no es válida. |
403 | El token no tiene permisos suficientes. |
404 | No se encontró el recurso. |
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
- Consulta el estado a intervalos razonables y detente en
printed,failedocancelled. - Guarda
failure_reason,print_job_idyX-Request-Idpara soporte. - No crees otro trabajo solo porque se haya agotado el tiempo de espera de una consulta.
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.Listar trabajos de impresiónConsulta trabajos recientes con paginación por cursor para paneles operativos y herramientas de soporte.Solución de problemasDiagnostica trabajos fallidos sin provocar una segunda impresión por accidente.