Передавайте документ, уже подготовленный для выбранного принтера. Public API принимает готовые PDF-файлы и поддерживаемые RAW-команды. Он не преобразует DOC/DOCX и не создаёт транспортные этикетки. Для RAW всегда явно указывайте формат и язык, не полагаясь на определение по содержимому.
## Загрузите PDF ```bash curl -sS https://public-api.cloudprint.me/api/v1/documents \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -F 'file=@invoice.pdf;type=application/pdf' ``` Успешная загрузка возвращает HTTP 201: ```json { "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 ```bash 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 ```bash 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 ```bash 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`. ## Следующие шаги