{ "openapi": "3.1.0", "info": { "title": "Публичный API CloudPrint", "version": "latest", "description": "CloudPrint позволяет backend-системам печатать PDF-документы, чеки и этикетки на принтерах,\nкоторые остаются внутри офиса, магазина, филиала или склада клиента.\n\n## Быстрый старт\n\n1. Создайте клиентское приложение в кабинете CloudPrint и сохраните `client_id`\n и одноразовый `client_secret` на своем backend-е.\n2. Получите OAuth2 Client Credentials токен через `POST /oauth/token`.\n3. Вызовите `GET /api/v1/agents` и `GET /api/v1/printers`, чтобы проверить,\n что локальный агент и нужный принтер онлайн.\n4. Сохраните стабильный `printer_id`, выбранный для каждого бизнес-сценария.\n5. Загрузите PDF или явную RAW-команду языка принтера через `POST /api/v1/documents`.\n6. Создайте задание печати через `POST /api/v1/print-jobs`.\n Если предварительная загрузка неудобна, используйте `POST /api/v1/print-jobs/from-url`\n или `POST /api/v1/print-jobs/from-base64`: оба коротких сценария создают обычный\n документ и задание печати одним запросом.\n7. Опрашивайте `GET /api/v1/print-jobs/{printJobId}`, пока задание не перейдет\n в статус `printed` или `failed`.\n\n## Авторизация\n\nПередавайте `Authorization: Bearer ` во все запросы, кроме `POST /oauth/token`.\nТокены живут недолго, поэтому кешируйте их почти до окончания `expires_in`, а не запрашивайте\nновый токен для каждого задания печати.\n\n## Запросы и ошибки\n\nДля заданий печати отправляйте JSON, для загрузки документов - `multipart/form-data`,\nдля получения токена - `application/x-www-form-urlencoded`.\nКаждый ответ содержит `X-Request-Id`; сохраняйте его рядом со своим номером заказа или отправления,\nчтобы поддержка могла найти тот же запрос.\nОшибки возвращают поля `error`, `error_code`, `message` и, при наличии, структурированные `details`.\n\n## Версионирование\n\n`latest` указывает на текущую публичную справку API. Стабильный контракт закреплен в URL как `/api/v1`.\nВ `v1` могут появляться совместимые добавления; ломающие изменения будут вынесены в новый major-path, например `/api/v2`." }, "servers": [ { "url": "https://public-api.cloudprint.by", "description": "Продакшен" } ], "paths": { "/api/v1/me": { "get": { "tags": [ "Авторизация" ], "summary": "Получить контекст текущего API-клиента", "operationId": "getApiClientContext", "responses": { "200": { "description": "Контекст текущего API-клиента", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiClientContext" } } } }, "401": { "description": "OAuth Bearer-токен недействителен" }, "429": { "description": "Превышен лимит запросов", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "description": "Используйте этот endpoint при первичной настройке, чтобы проверить, какой аккаунт, клиентское приложение и набор scope-ов представляет текущий токен.", "x-codeSamples": [ { "lang": "cURL", "source": "curl -sS https://public-api.cloudprint.by/api/v1/me \\\n -H \"Authorization: Bearer $ACCESS_TOKEN\"" } ] } }, "/api/v1/agents": { "get": { "tags": [ "Агенты" ], "summary": "Получить список агентов печати аккаунта", "operationId": "listAgents", "parameters": [ { "name": "limit", "in": "query", "description": "Максимальное количество агентов в ответе.", "required": false, "schema": { "type": "integer", "default": 50, "maximum": 100, "minimum": 1 } }, { "name": "cursor", "in": "query", "description": "Курсор из поля `next_cursor` предыдущего ответа.", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "Агенты печати аккаунта", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentList" } } } }, "401": { "description": "OAuth Bearer-токен недействителен" }, "403": { "description": "OAuth Bearer-токен не содержит scope `agents:read`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Превышен лимит запросов", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Непредвиденная ошибка" } }, "security": [ { "BearerAuth": [] } ], "description": "Возвращает локальные агенты печати, подключенные к аккаунту. Используйте поля `status`, `version` и `update`, чтобы показать операторам, онлайн ли desktop-агент и нужно ли обновить его перед печатью.", "x-codeSamples": [ { "lang": "cURL", "source": "curl -sS 'https://public-api.cloudprint.by/api/v1/agents?limit=50' \\\n -H \"Authorization: Bearer $ACCESS_TOKEN\"" } ] } }, "/oauth/token": { "post": { "tags": [ "Авторизация" ], "summary": "Выпустить OAuth2 access token по client credentials", "operationId": "issueOAuthToken", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "required": [ "grant_type", "client_id", "client_secret" ], "properties": { "grant_type": { "type": "string", "example": "client_credentials" }, "client_id": { "type": "string", "format": "uuid" }, "client_secret": { "type": "string" }, "scope": { "description": "Scope-ы через пробел. Запрос токена будет отклонен, если хотя бы один scope неизвестен или не выдан клиентскому приложению.", "type": "string", "example": "agents:read printers:read documents:write print_jobs:write print_jobs:read" } }, "type": "object" } } } }, "responses": { "200": { "description": "Access token выпущен", "content": { "application/json": { "schema": { "type": "object", "required": [ "token_type", "expires_in", "access_token" ], "properties": { "token_type": { "type": "string", "example": "Bearer" }, "expires_in": { "type": "integer", "example": 900 }, "access_token": { "type": "string", "example": "eyJ..." } } } } } }, "400": { "description": "Некорректный OAuth2-запрос" }, "401": { "description": "Некорректные OAuth2 client credentials" }, "429": { "description": "Превышен лимит запросов", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Обменивает id и secret клиентского приложения на короткоживущий Bearer-токен. Запрашивайте только те scope-ы, которые нужны текущей интеграции. Неизвестные или не выданные приложению scope-ы будут отклонены.", "x-codeSamples": [ { "lang": "cURL", "source": "curl -sS https://public-api.cloudprint.by/oauth/token \\\n -H 'Content-Type: application/x-www-form-urlencoded' \\\n --data-urlencode 'grant_type=client_credentials' \\\n --data-urlencode 'client_id=33333333-3333-4333-8333-333333333333' \\\n --data-urlencode 'client_secret=cpsec_...' \\\n --data-urlencode 'scope=agents:read printers:read documents:write print_jobs:write print_jobs:read'" }, { "lang": "PHP", "source": " [\n 'method' => 'POST',\n 'header' => \"Content-Type: application/x-www-form-urlencoded\\r\\n\",\n 'content' => http_build_query([\n 'grant_type' => 'client_credentials',\n 'client_id' => getenv('CLOUDPRINT_CLIENT_ID'),\n 'client_secret' => getenv('CLOUDPRINT_CLIENT_SECRET'),\n 'scope' => 'agents:read printers:read documents:write print_jobs:write print_jobs:read',\n ]),\n ],\n]));\n\n$token = json_decode((string) $response, true, flags: JSON_THROW_ON_ERROR)['access_token'];" } ] } }, "/api/v1/documents": { "post": { "tags": [ "Документы" ], "summary": "Загрузить документ для печати", "operationId": "uploadDocument", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "required": [ "file" ], "properties": { "file": { "description": "Поддерживаемые типы файлов: PDF и явные RAW-команды для принтера. Перед загрузкой конвертируйте DOC и DOCX в PDF.", "type": "string", "format": "binary" }, "document_format": { "type": [ "string", "null" ], "enum": [ "pdf", "raw" ], "example": "raw" }, "document_raw_language": { "type": [ "string", "null" ], "enum": [ "tspl", "zpl", "cpcl", "escpos" ], "example": "zpl" } }, "type": "object" } } } }, "responses": { "201": { "description": "Документ загружен", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadedDocument" } } } }, "400": { "description": "Некорректный запрос загрузки", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Загруженный файл слишком большой", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "415": { "description": "Тип загруженного файла не поддерживается Public API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Документ не прошел валидацию", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Превышен лимит запросов", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Непредвиденная ошибка" } }, "security": [ { "BearerAuth": [] } ], "description": "Загрузите файл перед созданием задания печати. Формат по умолчанию - PDF. Для RAW-печати передайте `document_format=raw` и явно укажите `document_raw_language`, например `zpl`.", "x-codeSamples": [ { "lang": "cURL", "source": "curl -sS https://public-api.cloudprint.by/api/v1/documents \\\n -H \"Authorization: Bearer $ACCESS_TOKEN\" \\\n -F \"file=@shipping-label.pdf\"" } ] } }, "/api/v1/print-jobs": { "get": { "tags": [ "Задания печати" ], "summary": "Получить список заданий печати", "operationId": "listPrintJobs", "parameters": [ { "name": "limit", "in": "query", "description": "Максимальное количество заданий печати в ответе.", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 100, "minimum": 1 } }, { "name": "cursor", "in": "query", "description": "Курсор из поля `next_cursor` предыдущего ответа.", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "Задания печати", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrintJobList" } } } }, "401": { "description": "OAuth Bearer-токен недействителен", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "OAuth Bearer-токен не содержит scope `print_jobs:read`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Превышен лимит запросов", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "description": "Возвращает последние задания печати с курсорной пагинацией. Используйте endpoint для операционных экранов и инструментов поддержки.", "x-codeSamples": [ { "lang": "cURL", "source": "curl -sS 'https://public-api.cloudprint.by/api/v1/print-jobs?limit=20' \\\n -H \"Authorization: Bearer $ACCESS_TOKEN\"" } ] }, "post": { "tags": [ "Задания печати" ], "summary": "Создать задание печати", "operationId": "createPrintJob", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "Необязательный ключ, который предотвращает создание дублей задания печати для того же аккаунта и payload.", "required": false, "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePrintJobRequest" } } } }, "responses": { "201": { "description": "Задание печати создано", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrintJob" } } } }, "409": { "description": "Конфликт ключа идемпотентности или неподдерживаемый маршрут печати. Для неподдерживаемых маршрутов причина указана в `details.reason`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Задание печати не прошло валидацию", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Превышен лимит запросов", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Непредвиденная ошибка" } }, "security": [ { "BearerAuth": [] } ], "description": "Создает задание печати для загруженного документа и выбранного принтера. При повторе после сетевого сбоя передавайте `Idempotency-Key`, чтобы избежать дублей печати.", "x-codeSamples": [ { "lang": "cURL", "source": "curl -sS https://public-api.cloudprint.by/api/v1/print-jobs \\\n -H \"Authorization: Bearer $ACCESS_TOKEN\" \\\n -H 'Content-Type: application/json' \\\n -H 'Idempotency-Key: order-100045-label' \\\n -d '{\n \"document_id\": \"44444444-4444-4444-8444-444444444444\",\n \"printer_id\": \"11111111-1111-4111-8111-111111111111\",\n \"copies\": 1,\n \"intent\": \"shipping_label\",\n \"media_width_mm\": 58,\n \"media_height_mm\": 40,\n \"dpi\": 203\n }'" }, { "lang": "PHP", "source": " '44444444-4444-4444-8444-444444444444',\n 'printer_id' => '11111111-1111-4111-8111-111111111111',\n 'copies' => 1,\n 'intent' => 'shipping_label',\n 'media_width_mm' => 58,\n 'media_height_mm' => 40,\n 'dpi' => 203,\n], JSON_THROW_ON_ERROR);\n\n$response = file_get_contents('https://public-api.cloudprint.by/api/v1/print-jobs', false, stream_context_create([\n 'http' => [\n 'method' => 'POST',\n 'header' => [\n 'Authorization: Bearer ' . getenv('CLOUDPRINT_ACCESS_TOKEN'),\n 'Content-Type: application/json',\n 'Idempotency-Key: order-100045-label',\n ],\n 'content' => $payload,\n ],\n]));\n\n$printJob = json_decode((string) $response, true, flags: JSON_THROW_ON_ERROR);" } ] } }, "/api/v1/print-jobs/from-base64": { "post": { "tags": [ "Задания печати" ], "summary": "Создать задание печати из base64-документа", "operationId": "createPrintJobFromBase64", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "Необязательный ключ, который предотвращает создание дублей задания печати для того же аккаунта и payload.", "required": false, "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePrintJobFromBase64Request" } } } }, "responses": { "201": { "description": "Задание печати создано", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrintJob" } } } }, "400": { "description": "Некорректный base64-запрос", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Конфликт ключа идемпотентности или неподдерживаемый маршрут печати. Для неподдерживаемых маршрутов причина указана в `details.reason`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Документ слишком большой", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "415": { "description": "Тип документа не поддерживается Public API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Задание печати не прошло валидацию", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Превышен лимит запросов", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Непредвиденная ошибка" } }, "security": [ { "BearerAuth": [] } ], "description": "Декодирует base64-документ, сохраняет его как обычный документ CloudPrint и создает задание печати одним запросом. Используйте этот способ только когда multipart-загрузка или скачивание по HTTPS URL неудобны, потому что base64 увеличивает размер запроса.", "x-codeSamples": [ { "lang": "cURL", "source": "curl -sS https://public-api.cloudprint.by/api/v1/print-jobs/from-base64 \\\n -H \"Authorization: Bearer $ACCESS_TOKEN\" \\\n -H 'Content-Type: application/json' \\\n -H 'Idempotency-Key: order-100045-label' \\\n -d '{\n \"document_base64\": \"JVBERi0xLjQK...\",\n \"document_filename\": \"order-100045.pdf\",\n \"printer_id\": \"11111111-1111-4111-8111-111111111111\",\n \"copies\": 1,\n \"intent\": \"shipping_label\",\n \"media_width_mm\": 58,\n \"media_height_mm\": 40,\n \"dpi\": 203\n }'" } ] } }, "/api/v1/print-jobs/from-url": { "post": { "tags": [ "Задания печати" ], "summary": "Создать задание печати из URL документа", "operationId": "createPrintJobFromUrl", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "Необязательный ключ, который предотвращает создание дублей задания печати для того же аккаунта и payload.", "required": false, "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePrintJobFromUrlRequest" } } } }, "responses": { "201": { "description": "Задание печати создано", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrintJob" } } } }, "400": { "description": "Некорректный URL-запрос", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Конфликт ключа идемпотентности или неподдерживаемый маршрут печати. Для неподдерживаемых маршрутов причина указана в `details.reason`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Удаленный документ слишком большой", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "415": { "description": "Тип документа не поддерживается Public API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Удаленный документ или задание печати не прошли валидацию", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Превышен лимит запросов", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Непредвиденная ошибка" } }, "security": [ { "BearerAuth": [] } ], "description": "Скачивает документ по публичному HTTPS URL, сохраняет его как обычный документ CloudPrint и создает задание печати одним запросом. Локальные URL, адреса приватных сетей и URL с учетными данными отклоняются.", "x-codeSamples": [ { "lang": "cURL", "source": "curl -sS https://public-api.cloudprint.by/api/v1/print-jobs/from-url \\\n -H \"Authorization: Bearer $ACCESS_TOKEN\" \\\n -H 'Content-Type: application/json' \\\n -H 'Idempotency-Key: order-100045-label' \\\n -d '{\n \"document_url\": \"https://files.example.com/labels/order-100045.pdf\",\n \"document_filename\": \"order-100045.pdf\",\n \"printer_id\": \"11111111-1111-4111-8111-111111111111\",\n \"copies\": 1,\n \"intent\": \"shipping_label\",\n \"media_width_mm\": 58,\n \"media_height_mm\": 40,\n \"dpi\": 203\n }'" } ] } }, "/api/v1/print-jobs/{printJobId}": { "get": { "tags": [ "Задания печати" ], "summary": "Получить статус задания печати", "operationId": "getPrintJob", "parameters": [ { "name": "printJobId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Задание печати", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrintJob" } } } }, "404": { "description": "Задание печати не найдено", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Превышен лимит запросов", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Непредвиденная ошибка" } }, "security": [ { "BearerAuth": [] } ], "description": "Опрашивайте одно задание печати, пока оно не перейдет в финальный статус. Считайте `printed` успешной печатью, а `failed` - видимой оператору ошибкой, которая может требовать действия поддержки.", "x-codeSamples": [ { "lang": "cURL", "source": "curl -sS https://public-api.cloudprint.by/api/v1/print-jobs/55555555-5555-4555-8555-555555555555 \\\n -H \"Authorization: Bearer $ACCESS_TOKEN\"" } ] } }, "/api/v1/printers": { "get": { "tags": [ "Принтеры" ], "summary": "Получить список принтеров аккаунта", "operationId": "listPrinters", "parameters": [ { "name": "limit", "in": "query", "description": "Максимальное количество принтеров в ответе.", "required": false, "schema": { "type": "integer", "default": 100, "maximum": 100, "minimum": 1 } }, { "name": "cursor", "in": "query", "description": "Курсор из поля `next_cursor` предыдущего ответа.", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "Принтеры аккаунта", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrinterList" } } } }, "429": { "description": "Превышен лимит запросов", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Непредвиденная ошибка" } }, "security": [ { "BearerAuth": [] } ], "description": "Возвращает принтеры, доступные аккаунту. Сохраняйте `printer_id`, а не локальные имена принтеров. Используйте `status`, `capabilities` и `endpoint`, чтобы решить, можно ли предлагать принтер в конкретном сценарии.", "x-codeSamples": [ { "lang": "cURL", "source": "curl -sS 'https://public-api.cloudprint.by/api/v1/printers?limit=100' \\\n -H \"Authorization: Bearer $ACCESS_TOKEN\"" } ] } } }, "components": { "schemas": { "ApiClientContext": { "required": [ "account_id", "account_name", "client_app_id", "client_app_name", "scopes" ], "properties": { "account_id": { "type": "string", "format": "uuid" }, "account_name": { "type": "string", "example": "Acme Print Ops" }, "client_app_id": { "type": "string", "format": "uuid" }, "client_app_name": { "type": "string", "example": "Warehouse integration" }, "scopes": { "type": "array", "items": { "type": "string" }, "example": [ "agents:read", "printers:read", "documents:write", "print_jobs:write", "print_jobs:read" ] } }, "type": "object" }, "UploadedDocument": { "required": [ "document_id", "original_filename", "mime_type", "document_format", "document_raw_language", "size_bytes" ], "properties": { "document_id": { "type": "string", "format": "uuid" }, "original_filename": { "type": "string", "example": "invoice.pdf" }, "mime_type": { "type": "string", "example": "application/pdf" }, "document_format": { "type": "string", "enum": [ "pdf", "raw" ], "example": "pdf" }, "document_raw_language": { "type": [ "string", "null" ], "enum": [ "tspl", "zpl", "cpcl", "escpos" ], "example": null }, "size_bytes": { "type": "integer", "example": 1024 } }, "type": "object" }, "CreatePrintJobRequest": { "required": [ "document_id", "printer_id" ], "properties": { "document_id": { "type": "string", "format": "uuid" }, "printer_id": { "type": "string", "format": "uuid" }, "copies": { "type": "integer", "minimum": 1, "example": 1 }, "intent": { "type": "string", "enum": [ "document", "shipping_label", "product_label", "invoice", "packing_slip", "a4_document", "receipt" ], "example": "shipping_label" }, "color_mode": { "type": "string", "enum": [ "default", "monochrome", "color" ], "example": "default" }, "duplex_mode": { "type": "string", "enum": [ "default", "simplex", "duplex_long_edge", "duplex_short_edge" ], "example": "default" }, "media_width_mm": { "type": [ "number", "null" ], "example": 58 }, "media_height_mm": { "type": [ "number", "null" ], "example": 40 }, "dpi": { "type": [ "integer", "null" ], "example": 203 }, "scale_mode": { "type": "string", "enum": [ "none", "fit" ], "example": "none" }, "orientation": { "type": "string", "enum": [ "default", "portrait", "landscape" ], "example": "default" }, "offset_x_mm": { "type": "number", "example": 0 }, "offset_y_mm": { "type": "number", "example": 0 }, "margin_top_mm": { "type": "number", "minimum": 0, "example": 0 }, "margin_right_mm": { "type": "number", "minimum": 0, "example": 0 }, "margin_bottom_mm": { "type": "number", "minimum": 0, "example": 0 }, "margin_left_mm": { "type": "number", "minimum": 0, "example": 0 } }, "type": "object" }, "CreatePrintJobFromUrlRequest": { "required": [ "document_url", "printer_id" ], "properties": { "document_url": { "description": "HTTPS URL документа для скачивания. Локальные адреса и хосты приватных сетей отклоняются.", "type": "string", "format": "uri", "example": "https://files.example.com/labels/order-100045.pdf" }, "document_filename": { "description": "Необязательное имя файла для диагностики и метаданных документа.", "type": [ "string", "null" ], "example": "order-100045.pdf" }, "document_format": { "type": [ "string", "null" ], "enum": [ "pdf", "raw" ], "example": "pdf" }, "document_raw_language": { "type": [ "string", "null" ], "enum": [ "tspl", "zpl", "cpcl", "escpos" ], "example": null }, "printer_id": { "type": "string", "format": "uuid" }, "copies": { "type": "integer", "minimum": 1, "example": 1 }, "intent": { "type": "string", "enum": [ "document", "shipping_label", "product_label", "invoice", "packing_slip", "a4_document", "receipt" ], "example": "shipping_label" }, "color_mode": { "type": "string", "enum": [ "default", "monochrome", "color" ], "example": "default" }, "duplex_mode": { "type": "string", "enum": [ "default", "simplex", "duplex_long_edge", "duplex_short_edge" ], "example": "default" }, "media_width_mm": { "type": [ "number", "null" ], "example": 58 }, "media_height_mm": { "type": [ "number", "null" ], "example": 40 }, "dpi": { "type": [ "integer", "null" ], "example": 203 }, "scale_mode": { "type": "string", "enum": [ "none", "fit" ], "example": "none" }, "orientation": { "type": "string", "enum": [ "default", "portrait", "landscape" ], "example": "default" }, "offset_x_mm": { "type": "number", "example": 0 }, "offset_y_mm": { "type": "number", "example": 0 }, "margin_top_mm": { "type": "number", "minimum": 0, "example": 0 }, "margin_right_mm": { "type": "number", "minimum": 0, "example": 0 }, "margin_bottom_mm": { "type": "number", "minimum": 0, "example": 0 }, "margin_left_mm": { "type": "number", "minimum": 0, "example": 0 } }, "type": "object" }, "CreatePrintJobFromBase64Request": { "required": [ "document_base64", "printer_id" ], "properties": { "document_base64": { "description": "Байты документа в кодировке base64.", "type": "string", "format": "byte" }, "document_filename": { "description": "Необязательное имя файла для диагностики и метаданных документа.", "type": [ "string", "null" ], "example": "order-100045.pdf" }, "document_format": { "type": [ "string", "null" ], "enum": [ "pdf", "raw" ], "example": "pdf" }, "document_raw_language": { "type": [ "string", "null" ], "enum": [ "tspl", "zpl", "cpcl", "escpos" ], "example": null }, "printer_id": { "type": "string", "format": "uuid" }, "copies": { "type": "integer", "minimum": 1, "example": 1 }, "intent": { "type": "string", "enum": [ "document", "shipping_label", "product_label", "invoice", "packing_slip", "a4_document", "receipt" ], "example": "shipping_label" }, "color_mode": { "type": "string", "enum": [ "default", "monochrome", "color" ], "example": "default" }, "duplex_mode": { "type": "string", "enum": [ "default", "simplex", "duplex_long_edge", "duplex_short_edge" ], "example": "default" }, "media_width_mm": { "type": [ "number", "null" ], "example": 58 }, "media_height_mm": { "type": [ "number", "null" ], "example": 40 }, "dpi": { "type": [ "integer", "null" ], "example": 203 }, "scale_mode": { "type": "string", "enum": [ "none", "fit" ], "example": "none" }, "orientation": { "type": "string", "enum": [ "default", "portrait", "landscape" ], "example": "default" }, "offset_x_mm": { "type": "number", "example": 0 }, "offset_y_mm": { "type": "number", "example": 0 }, "margin_top_mm": { "type": "number", "minimum": 0, "example": 0 }, "margin_right_mm": { "type": "number", "minimum": 0, "example": 0 }, "margin_bottom_mm": { "type": "number", "minimum": 0, "example": 0 }, "margin_left_mm": { "type": "number", "minimum": 0, "example": 0 } }, "type": "object" }, "PrintJob": { "required": [ "print_job_id", "document_id", "document_mime_type", "document_format", "document_raw_language", "printer_id", "status", "copies", "intent", "color_mode", "duplex_mode", "scale_mode", "orientation", "offset_x_mm", "offset_y_mm", "margin_top_mm", "margin_right_mm", "margin_bottom_mm", "margin_left_mm" ], "properties": { "print_job_id": { "type": "string", "format": "uuid" }, "document_id": { "type": "string", "format": "uuid" }, "document_mime_type": { "type": "string", "example": "application/pdf" }, "document_format": { "type": "string", "enum": [ "pdf", "raw" ], "example": "pdf" }, "document_raw_language": { "type": [ "string", "null" ], "enum": [ "tspl", "zpl", "cpcl", "escpos" ], "example": null }, "printer_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "example": "pending" }, "copies": { "type": "integer", "example": 1 }, "intent": { "type": "string", "enum": [ "document", "shipping_label", "product_label", "invoice", "packing_slip", "a4_document", "receipt" ], "example": "shipping_label" }, "color_mode": { "type": "string", "enum": [ "default", "monochrome", "color" ], "example": "default" }, "duplex_mode": { "type": "string", "enum": [ "default", "simplex", "duplex_long_edge", "duplex_short_edge" ], "example": "default" }, "media_width_mm": { "type": [ "number", "null" ], "example": 58 }, "media_height_mm": { "type": [ "number", "null" ], "example": 40 }, "dpi": { "type": [ "integer", "null" ], "example": 203 }, "scale_mode": { "type": "string", "enum": [ "none", "fit" ], "example": "none" }, "orientation": { "type": "string", "enum": [ "default", "portrait", "landscape" ], "example": "default" }, "offset_x_mm": { "type": "number", "example": 0 }, "offset_y_mm": { "type": "number", "example": 0 }, "margin_top_mm": { "type": "number", "minimum": 0, "example": 0 }, "margin_right_mm": { "type": "number", "minimum": 0, "example": 0 }, "margin_bottom_mm": { "type": "number", "minimum": 0, "example": 0 }, "margin_left_mm": { "type": "number", "minimum": 0, "example": 0 }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "reserved_at": { "type": [ "string", "null" ], "format": "date-time" }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "failure_reason": { "type": [ "string", "null" ] } }, "type": "object" }, "PrintJobList": { "required": [ "print_jobs", "next_cursor" ], "properties": { "print_jobs": { "type": "array", "items": { "$ref": "#/components/schemas/PrintJob" } }, "next_cursor": { "type": [ "string", "null" ] } }, "type": "object" }, "PrinterCapabilities": { "required": [ "backend", "language_profiles", "supports_custom_media", "supports_orientation", "supports_copies", "supports_duplex", "supports_color", "supports_scaling", "supports_offsets", "supports_printable_area", "supported_dpi", "supported_media_sizes", "supported_feed_types", "darkness_min", "darkness_max", "speed_min", "speed_max" ], "properties": { "backend": { "type": "string", "enum": [ "cups", "windows_native", "custom_command", "simulate" ], "example": "windows_native" }, "language_profiles": { "type": "array", "items": { "required": [ "language", "supported_commands", "compression_modes" ], "properties": { "language": { "type": "string", "enum": [ "tspl", "zpl", "cpcl", "escpos" ], "example": "zpl" }, "version": { "type": [ "string", "null" ], "example": "zpl2" }, "supported_commands": { "type": "array", "items": { "type": "string", "example": "gf" } }, "max_bitmap_width_dots": { "type": [ "integer", "null" ], "minimum": 1, "example": 812 }, "max_bitmap_height_dots": { "type": [ "integer", "null" ], "minimum": 1, "example": 1199 }, "compression_modes": { "type": "array", "items": { "type": "string", "example": "ascii-hex" } }, "codepage": { "type": [ "string", "null" ], "example": "utf-8" } }, "type": "object" } }, "supports_custom_media": { "type": "boolean" }, "supports_orientation": { "type": "boolean" }, "supports_copies": { "type": "boolean" }, "supports_duplex": { "type": "boolean" }, "supports_color": { "type": "boolean" }, "supports_scaling": { "type": "boolean" }, "supports_offsets": { "type": "boolean" }, "supports_printable_area": { "type": "boolean" }, "supported_dpi": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "supported_media_sizes": { "type": "array", "items": { "required": [ "width_mm", "height_mm" ], "properties": { "width_mm": { "type": "number", "format": "float" }, "height_mm": { "type": "number", "format": "float" } }, "type": "object" } }, "supported_feed_types": { "type": "array", "items": { "type": "string", "example": "gap" } }, "darkness_min": { "type": [ "integer", "null" ], "example": 0 }, "darkness_max": { "type": [ "integer", "null" ], "example": 30 }, "speed_min": { "type": [ "integer", "null" ], "example": 1 }, "speed_max": { "type": [ "integer", "null" ], "example": 14 } }, "type": "object" }, "PrinterEndpoint": { "required": [ "system_print_available", "raw_passthrough_available", "os", "driver_name", "port_name", "print_processor", "data_type", "connection_type", "default_media_profile_id", "default_media_profile" ], "properties": { "system_print_available": { "type": "boolean" }, "raw_passthrough_available": { "type": "boolean" }, "configuration_issue": { "type": [ "string", "null" ], "enum": [ "interactive_output_port" ] }, "os": { "type": [ "string", "null" ], "example": "linux" }, "driver_name": { "type": [ "string", "null" ], "example": "CUPS" }, "port_name": { "type": [ "string", "null" ], "example": "ipp://printer.local/ipp/print" }, "print_processor": { "type": [ "string", "null" ], "example": "cups" }, "data_type": { "type": [ "string", "null" ], "example": "RAW" }, "connection_type": { "type": [ "string", "null" ], "example": "cups" }, "default_media_profile_id": { "type": [ "string", "null" ] }, "default_media_profile": { "properties": { "width_mm": { "type": "number", "format": "float", "example": 100 }, "height_mm": { "type": "number", "format": "float", "example": 150 }, "dpi": { "type": "integer", "example": 203 }, "orientation": { "type": "string", "enum": [ "default", "portrait", "landscape" ] }, "feed_type": { "type": [ "string", "null" ], "example": "gap" }, "darkness": { "type": [ "integer", "null" ], "example": 15 }, "speed": { "type": [ "integer", "null" ], "example": 4 } }, "type": [ "object", "null" ] } }, "type": "object" }, "Printer": { "required": [ "printer_id", "agent_id", "local_identifier", "name", "status", "last_seen_at", "agent_name", "agent_hostname", "agent_status", "agent_last_seen_at", "capabilities", "endpoint" ], "properties": { "printer_id": { "type": "string", "format": "uuid" }, "agent_id": { "type": "string", "format": "uuid" }, "local_identifier": { "type": "string", "example": "zebra-zd421-usb-001" }, "name": { "type": "string", "example": "Warehouse Label Printer" }, "status": { "type": "string", "enum": [ "online", "offline", "unknown" ] }, "last_seen_at": { "type": [ "string", "null" ], "format": "date-time" }, "agent_name": { "type": [ "string", "null" ], "example": "Warehouse PC agent" }, "agent_hostname": { "type": [ "string", "null" ], "example": "warehouse-pc" }, "agent_status": { "type": [ "string", "null" ], "example": "online" }, "agent_last_seen_at": { "type": [ "string", "null" ], "format": "date-time" }, "capabilities": { "$ref": "#/components/schemas/PrinterCapabilities" }, "endpoint": { "$ref": "#/components/schemas/PrinterEndpoint" } }, "type": "object" }, "PrinterList": { "required": [ "printers", "next_cursor" ], "properties": { "printers": { "type": "array", "items": { "$ref": "#/components/schemas/Printer" } }, "next_cursor": { "type": [ "string", "null" ] } }, "type": "object" }, "AgentUpdate": { "required": [ "status", "current_version", "latest_version", "minimum_supported_version", "channel", "required" ], "properties": { "status": { "type": "string", "enum": [ "up_to_date", "available", "required", "unknown" ], "example": "available" }, "current_version": { "type": [ "string", "null" ], "example": "0.1.0" }, "latest_version": { "type": [ "string", "null" ], "example": "0.1.1" }, "minimum_supported_version": { "type": [ "string", "null" ], "example": "0.1.0" }, "channel": { "type": "string", "example": "stable" }, "required": { "type": "boolean", "example": false } }, "type": "object" }, "Agent": { "required": [ "agent_id", "name", "status", "update" ], "properties": { "agent_id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "example": "Warehouse PC agent" }, "status": { "type": "string", "example": "online" }, "installation_id": { "type": [ "string", "null" ] }, "hostname": { "type": [ "string", "null" ] }, "version": { "type": [ "string", "null" ] }, "update": { "$ref": "#/components/schemas/AgentUpdate" }, "last_seen_at": { "type": [ "string", "null" ], "format": "date-time" } }, "type": "object" }, "AgentList": { "required": [ "agents", "next_cursor" ], "properties": { "agents": { "type": "array", "items": { "$ref": "#/components/schemas/Agent" } }, "next_cursor": { "type": [ "string", "null" ] } }, "type": "object" }, "ErrorResponse": { "required": [ "error", "message" ], "properties": { "error": { "description": "Стабильный машиночитаемый код ошибки.", "type": "string" }, "error_code": { "type": [ "string", "null" ] }, "message": { "description": "Безопасное человекочитаемое сообщение об ошибке. Сообщение локализуется по `Accept-Language`, если есть поддерживаемый перевод.", "type": "string" }, "details": { "description": "Необязательная машиночитаемая диагностика для ошибок со структурированным контекстом.", "type": [ "object", "null" ], "example": { "reason": "missing_pdf_renderer" }, "additionalProperties": true } }, "type": "object" } }, "securitySchemes": { "BearerAuth": { "type": "http", "description": "Access token OAuth2 Client Credentials.", "bearerFormat": "JWT", "scheme": "bearer" } } }, "tags": [ { "name": "Авторизация", "description": "Получение OAuth2-токена и проверка контекста текущего клиентского приложения." }, { "name": "Принтеры", "description": "Поиск принтеров клиента, доступных через подключенные локальные агенты." }, { "name": "Агенты", "description": "Проверка подключенных локальных агентов печати, их статуса и состояния обновления." }, { "name": "Документы", "description": "Загрузка PDF или явных RAW-команд языка принтера перед созданием заданий печати." }, { "name": "Задания печати", "description": "Создание, просмотр и опрос заданий печати до статуса `printed` или `failed`." } ], "externalDocs": { "description": "Пошаговое руководство по интеграции с Public API", "url": "https://cloudprint.by/docs/getting-started/" }, "x-tagGroups": [ { "name": "Начните здесь", "tags": [ "Авторизация" ] }, { "name": "Сценарий печати", "tags": [ "Агенты", "Принтеры", "Документы", "Задания печати" ] } ] }