Быстрый старт с CloudPrint API
Начните с одной сквозной проверки печати. На каждом шаге API возвращает идентификатор для следующего запроса, а физический результат проверяется отдельно от итогового статуса задания.
Перед началом работы
Вам понадобятся аккаунт CloudPrint, компьютер с доступом к нужному принтеру, установленный на нём CloudPrint Agent со статусом online и сервер для безопасного хранения client_secret. Сервер отправляет запросы только в CloudPrint Public API и не обращается к локальному агенту напрямую. Создайте API-приложение с разрешениями printers:read, documents:write, print_jobs:write и print_jobs:read. Существующее разрешение documents:write подходит для готовых PDF и проверяемых RAW-документов.
Выберите доступный адрес API
В примерах используется основной адрес https://public-api.cloudprint.me. Если он недоступен из вашей сети, настройте клиент на официальное зеркало https://public-api.cloudprint.by. Оно обслуживает тот же API и не выбирает отдельный регион хранения данных. Подробные правила, включая требования к aud в RS256-подтверждениях, приведены в обзоре API.
1. Получите и проверьте токен
curl -sS https://public-api.cloudprint.me/oauth/token \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=YOUR_CLIENT_ID' \
--data-urlencode 'client_secret=YOUR_CLIENT_SECRET' \
--data-urlencode 'scope=printers:read documents:write print_jobs:write print_jobs:read'Ответ содержит токен и срок его действия:
{
"token_type": "Bearer",
"expires_in": 900,
"access_token": "eyJ..."
}Сохраните токен в переменной ACCESS_TOKEN тестовой командной оболочки и вызовите /api/v1/me, чтобы сразу обнаружить неверный аккаунт или недостающее разрешение:
curl -sS https://public-api.cloudprint.me/api/v1/me \
-H "Authorization: Bearer $ACCESS_TOKEN"2. Выберите принтер и сохраните его ID
curl -sS 'https://public-api.cloudprint.me/api/v1/printers?limit=100' \
-H "Authorization: Bearer $ACCESS_TOKEN"Агент должен быть online. Для консервативной автоматической маршрутизации используйте принтер со статусом online либо данными системной очереди cups_ipp/windows_spooler и accepting_jobs=true. Физическое предупреждение всё равно показывайте оператору. Сохраните printer_id; имя принтера может измениться и не подходит для маршрутизации. Перед RAW-печатью прочитайте раздел Агенты и принтеры.
3. Загрузите готовый документ
curl -sS https://public-api.cloudprint.me/api/v1/documents \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-F 'file=@invoice.pdf;type=application/pdf'В ответе будет идентификатор для задания:
{
"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
}Принимаются готовые PDF и явные RAW-команды ZPL, TSPL, CPCL или ESC/POS. Варианты без отдельной загрузки описаны в разделе Документы.
4. Создайте идемпотентное задание
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-18452-invoice-v1' \
-d '{
"document_id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
"printer_id": "11111111-1111-4111-8111-111111111111",
"copies": 1,
"intent": "invoice",
"color_mode": "default",
"duplex_mode": "default",
"scale_mode": "none",
"orientation": "default"
}'Параметры находятся на верхнем уровне JSON — объекта options в контракте нет. Сохраните print_job_id рядом с номером заказа или счёта:
{
"print_job_id": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb",
"document_id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
"document_mime_type": "application/pdf",
"document_format": "pdf",
"document_raw_language": null,
"printer_id": "11111111-1111-4111-8111-111111111111",
"status": "pending",
"copies": 1,
"intent": "invoice",
"color_mode": "default",
"duplex_mode": "default",
"media_width_mm": null,
"media_height_mm": null,
"dpi": null,
"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-06-08T10:12:00+00:00",
"reserved_at": null,
"started_at": null,
"completed_at": null,
"failure_reason": null
}5. Дождитесь итогового статуса
curl -sS https://public-api.cloudprint.me/api/v1/print-jobs/bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb \
-H "Authorization: Bearer $ACCESS_TOKEN"Продолжайте опрос при pending, reserved и printing. Остановитесь при printed, failed или cancelled. printed означает, что системная очередь приняла документ; этот статус не подтверждает физическую печать. Для failed сохраните failure_reason; при cancelled очередь не приняла документ. Неизвестный статус считайте промежуточным. Предрелизная проверка завершена, когда нужный принтер физически напечатал ровно одну копию, а задание перешло в printed.
6. Сохраните данные для диагностики
Для каждого запроса сохраняйте X-Request-Id CloudPrint вместе с идентификатором операции в вашей системе. В этом заголовке можно передать собственное безопасное значение: CloudPrint вернёт его или заменит, если оно не прошло проверку. Также храните print_job_id, printer_id, ключ идемпотентности и историю статусов. После тайм-аута повторите тот же запрос с тем же ключом. Для намеренной повторной печати создайте новую операцию и новый ключ. Перед запуском прочитайте раздел Задания печати.