Начните с одной сквозной проверки печати. На каждом шаге 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](../api/overview/). ## 1. Получите и проверьте токен ```bash 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' ``` Ответ содержит токен и срок его действия: ```json { "token_type": "Bearer", "expires_in": 900, "access_token": "eyJ..." } ``` Сохраните токен в переменной `ACCESS_TOKEN` тестовой командной оболочки и вызовите `/api/v1/me`, чтобы сразу обнаружить неверный аккаунт или недостающее разрешение: ```bash curl -sS https://public-api.cloudprint.me/api/v1/me \ -H "Authorization: Bearer $ACCESS_TOKEN" ``` ## 2. Выберите принтер и сохраните его ID ```bash 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-печатью прочитайте раздел [Агенты и принтеры](../api/agents-and-printers/). ## 3. Загрузите готовый документ ```bash curl -sS https://public-api.cloudprint.me/api/v1/documents \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -F 'file=@invoice.pdf;type=application/pdf' ``` В ответе будет идентификатор для задания: ```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 } ``` Принимаются готовые PDF и явные RAW-команды ZPL, TSPL, CPCL или ESC/POS. Варианты без отдельной загрузки описаны в разделе [Документы](../api/documents/). ## 4. Создайте идемпотентное задание ```bash 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` рядом с номером заказа или счёта: ```json { "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. Дождитесь итогового статуса ```bash 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`, ключ идемпотентности и историю статусов. После тайм-аута повторите тот же запрос с тем же ключом. Для намеренной повторной печати создайте новую операцию и новый ключ. Перед запуском прочитайте раздел [Задания печати](../api/print-jobs/). ## Следующие шаги