--- title: "Crear un trabajo de impresión" description: "Envía un documento subido a una impresora seleccionada con idempotencia y opciones de impresión explícitas." --- # 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 `. **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 ```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); ``` ## 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 ```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. | | `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.