Загрузка PDF и RAW-документов
Загружайте данные только после подготовки под выбранный принтер. Public API принимает PDF или явный RAW-язык; он не конвертирует DOC/DOCX, не покупает транспортные этикетки и не угадывает язык произвольных байтов.
Загрузите 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 для задания.
Загрузите 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'Разрешены zpl, tspl, cpcl, escpos. Принтер должен объявить тот же язык и RAW passthrough. Не отправляйте 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, private/reserved ranges, credentials и небезопасные redirect. Ответ имеет обычную форму задания.
Создайте задание из 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, 413 — слишком большой файл, 415 — неподдерживаемый тип, 422 — validation. Для логики используйте error, сообщение показывайте оператору и сохраняйте X-Request-Id.
Чек-лист перед запуском
- Используйте исходящее подключение агента и не открывайте порты принтера в интернет.
- Сохраняйте стабильный идентификатор принтера, а не только отображаемое имя.
- Проверяйте формат документа, размер страницы и ориентацию до создания задания.
- Явно задайте обработку конечных статусов, повторов и защиту от двойной печати.