Загрузка PDF и RAW-документов
Передавайте документ, уже подготовленный для выбранного принтера. Public API принимает готовые PDF-файлы и поддерживаемые RAW-команды. Он не преобразует DOC/DOCX и не создаёт транспортные этикетки. Для RAW всегда явно указывайте формат и язык, не полагаясь на определение по содержимому.
Загрузите PDF
curl -sS https://public-api.cloudprint.me/api/v1/documents \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-F 'file=@invoice.pdf;type=application/pdf'Успешная загрузка возвращает HTTP 201:
{
"document_id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
"original_filename": "invoice.pdf",
"mime_type": "application/pdf",
"document_format": "pdf",
"document_raw_language": null,
"size_bytes": 1024
}Сохраните document_id для задания. До публикации документа CloudPrint проверяет его на вредоносный код, повреждённую или зашифрованную структуру, активное содержимое, вложения и небезопасные размеры страниц. Удаляемые действия и интерактивные формы могут быть сведены в безопасный PDF.
Загрузите RAW
curl -sS https://public-api.cloudprint.me/api/v1/documents \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-F 'file=@label.txt;type=application/octet-stream' \
-F 'document_format=raw' \
-F 'document_raw_language=zpl'Для RAW сохраняется существующее разрешение documents:write. Разрешены zpl, tspl, cpcl, escpos. Принтер должен объявить тот же язык и RAW passthrough. CloudPrint принимает поддерживаемые команды печати и форматирования, но отклоняет неизвестные команды, постоянную запись, настройку устройства и доступ к файлам. Не отправляйте PDF как RAW.
Создайте задание из публичного URL
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: shipment-18452-label-url-v1' \
-d '{
"document_url": "https://files.example.com/labels/shipment-18452.pdf",
"document_filename": "shipment-18452.pdf",
"printer_id": "11111111-1111-4111-8111-111111111111",
"copies": 1,
"intent": "shipping_label",
"media_width_mm": 100,
"media_height_mm": 150,
"dpi": 203
}'URL должен использовать HTTPS. CloudPrint отклоняет localhost, адреса частных и зарезервированных сетей, встроенные учётные данные и небезопасные перенаправления. Ответ имеет обычную форму задания.
Создайте задание из Base64
curl -sS https://public-api.cloudprint.me/api/v1/print-jobs/from-base64 \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: receipt-18452-base64-v1' \
-d '{
"document_base64": "JVBERi0xLjQK...",
"document_filename": "receipt-18452.pdf",
"printer_id": "11111111-1111-4111-8111-111111111111",
"copies": 1,
"intent": "receipt"
}'Используйте для небольших inline-документов. Base64 увеличивает размер; для больших файлов лучше multipart или короткоживущий публичный URL. Ответ имеет обычную форму задания.
Выберите способ передачи
Для файлов на вашем сервере обычно подходит multipart-загрузка через /documents. Используйте /from-url, если готовый файл доступен по безопасному публичному HTTPS URL, а /from-base64 — для небольших сгенерированных документов. Во всех методах, которые создают задание, передавайте Idempotency-Key.
Проверьте до загрузки
Проверяйте тип, размер, геометрию страницы или носителя и ориентацию. Офисные файлы конвертируйте сами. Транспортную этикетку сначала получите у перевозчика; CloudPrint начинает работу с готового PDF или ZPL. Серверная проверка — последний рубеж защиты, а не замена проверке созданных вами документов.
Ошибки загрузки
400 — неверный запрос multipart/form-data, 413 — слишком большой файл, 415 — неподдерживаемый тип, 422 — неверный запрос или документ не прошёл проверку безопасности. Не повторяйте неизменённый запрос после 422. Код 503 означает, что проверка временно недоступна: повторяйте запрос с тем же ключом идемпотентности, постепенно увеличивая интервал. Для логики используйте error, более точную причину читайте из error_code, сообщение показывайте оператору и сохраняйте X-Request-Id.