Subir un documento para imprimir
Sube un PDF listo para imprimir o datos RAW en un lenguaje de impresora definido antes de crear el trabajo.
Qué hace este método
Sube un PDF listo para imprimir o datos RAW en un lenguaje de impresora definido antes de crear el trabajo.
Autenticación
Envía un token de corta duración en Authorization: Bearer <access_token>.
Permisos necesarios: documents:write
Solicitud
URL de producción: https://public-api.cloudprint.me/api/v1/documents
Parámetros
| Nombre | Ubicación | Tipo | Obligatorio | Descripción | Restricciones |
|---|---|---|---|---|---|
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: multipart/form-data
| Nombre | Tipo | Obligatorio | Descripción | Restricciones |
|---|---|---|---|---|
file | string (binary) | sí | Documento PDF o RAW binario enviado como multipart form data. | — |
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: "raw" |
document_raw_language | string | null | no | Lenguaje de comandos de los datos RAW, por ejemplo ZPL o TSPL. | enum: tspl, zpl, cpcl, escpos; example: "zpl" |
Ejemplos de solicitud
cURL
bash
curl -sS https://public-api.cloudprint.me/api/v1/documents \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-F "file=@shipping-label.pdf"Respuesta
Estado HTTP: 201 — Recurso creado.
Campos de respuesta
| Nombre | Tipo | Obligatorio | Descripción | Restricciones |
|---|---|---|---|---|
document_id | string (uuid) | sí | UUID estable devuelto después de subir correctamente el documento. | — |
original_filename | string | sí | Nombre original del archivo registrado al subir el documento. | example: "invoice.pdf" |
mime_type | string | sí | Tipo MIME del instalador publicado o del documento guardado. | 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 |
size_bytes | integer | sí | Tamaño del documento guardado en bytes. | example: 1024 |
Ejemplo de respuesta
json
{
"document_id": "11111111-1111-4111-8111-111111111111",
"original_filename": "invoice.pdf",
"mime_type": "application/pdf",
"document_format": "pdf",
"document_raw_language": null,
"size_bytes": 1024
}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. |
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
- El permiso existente
documents:writecubre PDF y RAW. Para RAW, envíadocument_format=rawydocument_raw_languagede forma explícita. - Convierte DOC y DOCX a PDF en el servidor antes de subirlos.
- Corrige el documento tras un
422; reintenta un503temporal de inspección con espera progresiva y limitada. - Guarda el
document_idpara crear el trabajo.
Documentación relacionada
Preparar documentosSube un PDF listo para imprimir o datos RAW explícitos antes de crear un trabajo.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 una URLDescarga un documento desde una URL HTTPS pública y crea el documento y el trabajo en una sola solicitud.