Документация CloudPrint/Начало работы

Быстрый старт с CloudPrint API

Сначала выполните одну реальную печать целиком, а уже затем проектируйте очереди и фоновые retry. Каждый запрос ниже возвращает идентификатор для следующего шага, а конечный статус подтверждает фактический результат.

Что понадобится и где проходит граница

Нужны аккаунт CloudPrint, подключённый online-агент рядом с принтером и backend, который безопасно хранит client_secret. Внешняя система обращается только к https://public-api.cloudprint.me и никогда не вызывает локальный агент. Создайте client app со scope printers:read, documents:write, print_jobs:write, print_jobs:read.

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 тестового shell и вызовите /api/v1/me, чтобы сразу обнаружить неверный аккаунт или scope:

curl -sS https://public-api.cloudprint.me/api/v1/me \
  -H "Authorization: Bearer $ACCESS_TOKEN"

2. Выберите стабильный printer_id

curl -sS 'https://public-api.cloudprint.me/api/v1/printers?limit=100' \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Выберите запись, где принтер и агент имеют статус online. Сохраните 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 и варианты без отдельной загрузки описаны в разделе Документы.

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; для failed сохраните failure_reason. Неизвестный будущий статус считайте промежуточным. Успешный тест — нужный принтер напечатал ровно одну копию, а API вернул printed.

6. Сохраните данные для эксплуатации

Для каждого запроса записывайте X-Request-Id CloudPrint рядом с бизнес-ID. Можно передавать собственное безопасное значение в этом заголовке: CloudPrint вернёт его либо заменит небезопасное. Храните print_job_id, printer_id, ключ идемпотентности и переходы статуса. Retry после timeout повторяет тот же payload с тем же ключом; осознанная перепечатка получает новый ключ. Перед production изучите Задания печати.

Чек-лист перед запуском

• Храните API-ключи на backend и ограничивайте их аккаунтом владельца.
• Используйте исходящее подключение агента и не открывайте порты принтера в интернет.
• Сохраняйте стабильный идентификатор принтера, а не только отображаемое имя.
• Явно задайте обработку конечных статусов, повторов и защиту от двойной печати.

Следующие шаги

Авторизация OAuth2 Client CredentialsСоздайте client app CloudPrint, получите короткоживущий токен и безопасно храните учётные данные с минимальными scope.Подключение агента и выбор принтераУстановите агент CloudPrint, получите локальные очереди печати и сохраните стабильный printer_id с учётом возможностей принтера.Создание и отслеживание заданий печатиСоздавайте идемпотентные задания CloudPrint, проверяйте параметры принтера и отслеживайте результат до printed или failed.

OpenAPIОткрыть кабинетПолитика конфиденциальностиУсловияОплата и возвратDPA