{ "openapi": "3.1.0", "info": { "title": "Public API CloudPrint", "version": "latest", "description": "CloudPrint pozwala systemom backendowym drukować dokumenty PDF, paragony i etykiety na drukarkach,\nktóre pozostają w biurze, sklepie, oddziale lub magazynie klienta.\n\n## Szybki start\n\n1. Utwórz aplikację kliencką w panelu CloudPrint i zapisz\n `client_id` oraz jednorazowy `client_secret` na swoim backendzie.\n2. Pobierz token OAuth2 Client Credentials przez `POST /oauth/token`.\n3. Wywołaj `GET /api/v1/agents` i `GET /api/v1/printers`, aby potwierdzić,\n że lokalny agent i docelowa drukarka są online.\n4. Zapisz stabilny `printer_id` wybrany dla danego procesu biznesowego.\n5. Prześlij PDF lub jawne dane RAW języka drukarki przez `POST /api/v1/documents`.\n6. Utwórz zadanie przez `POST /api/v1/print-jobs`.\n Gdy osobne przesłanie pliku jest niewygodne, użyj `POST /api/v1/print-jobs/from-url`\n albo `POST /api/v1/print-jobs/from-base64`. Oba skróty tworzą dokument\n i zwykłe zadanie druku w jednym żądaniu.\n7. Odpytuj `GET /api/v1/print-jobs/{printJobId}`, aż zadanie osiągnie\n status `printed` albo `failed`.\n\n## Uwierzytelnianie\n\nPrzekazuj `Authorization: Bearer ` do każdego endpointu poza `POST /oauth/token`.\nTokeny są krótkotrwałe, dlatego przechowuj je w cache prawie do końca `expires_in`,\nzamiast pobierać nowy token dla każdego zadania.\n\n## Żądania i błędy\n\nDla zadań wysyłaj JSON, dla dokumentów `multipart/form-data`,\na dla tokenu `application/x-www-form-urlencoded`.\nKażda odpowiedź zawiera `X-Request-Id`. Zapisuj go obok własnego identyfikatora\nzamówienia lub przesyłki, aby wsparcie mogło odnaleźć to samo żądanie.\nBłędy zawierają `error`, `error_code`, `message` i opcjonalne dane `details`.\n\n## Wersjonowanie\n\n`latest` wskazuje bieżącą dokumentację Public API, natomiast stabilny kontrakt jest zapisany w URL jako `/api/v1`.\nW `v1` mogą pojawiać się zgodne rozszerzenia; zmiany łamiące zgodność otrzymają nową wersję główną, np. `/api/v2`." }, "servers": [ { "url": "https://public-api.cloudprint.me", "description": "Produkcja" } ], "paths": { "/api/v1/me": { "get": { "tags": [ "Uwierzytelnianie" ], "summary": "Pobierz kontekst bieżącego klienta API", "operationId": "getApiClientContext", "responses": { "200": { "description": "Kontekst bieżącego klienta API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiClientContext" } } } }, "401": { "description": "Token OAuth Bearer jest nieprawidłowy" }, "429": { "description": "Przekroczono limit żądań", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "description": "Użyj tego endpointu podczas konfiguracji, aby potwierdzić konto, aplikację kliencką i scopes bieżącego tokenu.", "x-codeSamples": [ { "lang": "cURL", "source": "curl -sS https://public-api.cloudprint.me/api/v1/me \\\n -H \"Authorization: Bearer $ACCESS_TOKEN\"" } ] } }, "/api/v1/agents": { "get": { "tags": [ "Agenci" ], "summary": "Pobierz agentów druku konta", "operationId": "listAgents", "parameters": [ { "name": "limit", "in": "query", "description": "Maksymalna liczba agentów w odpowiedzi.", "required": false, "schema": { "type": "integer", "default": 50, "maximum": 100, "minimum": 1 } }, { "name": "cursor", "in": "query", "description": "Kursor z pola `next_cursor` poprzedniej odpowiedzi.", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "Agenci druku konta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentList" } } } }, "401": { "description": "Token OAuth Bearer jest nieprawidłowy" }, "403": { "description": "Token OAuth Bearer nie zawiera scope `agents:read`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Przekroczono limit żądań", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Nieoczekiwany błąd" } }, "security": [ { "BearerAuth": [] } ], "description": "Zwraca lokalnych agentów druku połączonych z kontem. Użyj `status`, `version` i `update`, aby pokazać operatorowi, czy agent jest online i czy wymaga aktualizacji przed drukowaniem.", "x-codeSamples": [ { "lang": "cURL", "source": "curl -sS 'https://public-api.cloudprint.me/api/v1/agents?limit=50' \\\n -H \"Authorization: Bearer $ACCESS_TOKEN\"" } ] } }, "/oauth/token": { "post": { "tags": [ "Uwierzytelnianie" ], "summary": "Pobierz token OAuth2 przy użyciu danych klienta", "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": "Scopes rozdzielone spacjami. Żądanie tokenu zostanie odrzucone, jeśli dowolny scope jest nieznany lub nie został przyznany aplikacji.", "type": "string", "example": "agents:read printers:read documents:write print_jobs:write print_jobs:read" } }, "type": "object" } } } }, "responses": { "200": { "description": "Token dostępu został wydany", "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": "Nieprawidłowe żądanie OAuth2" }, "401": { "description": "Nieprawidłowe dane klienta OAuth2" }, "429": { "description": "Przekroczono limit żądań", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Wymienia identyfikator i sekret aplikacji na krótkotrwały token Bearer. Żądaj tylko scopes potrzebnych integracji; nieznane lub nieprzyznane scopes są odrzucane.", "x-codeSamples": [ { "lang": "cURL", "source": "curl -sS https://public-api.cloudprint.me/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": [ "Dokumenty" ], "summary": "Prześlij dokument do druku", "operationId": "uploadDocument", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "required": [ "file" ], "properties": { "file": { "description": "Obsługiwane są PDF i jawne dane RAW drukarki. Przed przesłaniem skonwertuj DOC i DOCX do 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": "Dokument został przesłany", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadedDocument" } } } }, "400": { "description": "Nieprawidłowe żądanie przesłania", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Przesłany plik jest za duży", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "415": { "description": "Typ przesłanego pliku nie jest obsługiwany przez Public API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Walidacja dokumentu nie powiodła się", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Przekroczono limit żądań", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Nieoczekiwany błąd" } }, "security": [ { "BearerAuth": [] } ], "description": "Prześlij plik przed utworzeniem zadania. PDF jest formatem domyślnym. Dla druku RAW wyślij `document_format=raw` i jawny `document_raw_language`, np. `zpl`.", "x-codeSamples": [ { "lang": "cURL", "source": "curl -sS https://public-api.cloudprint.me/api/v1/documents \\\n -H \"Authorization: Bearer $ACCESS_TOKEN\" \\\n -F \"file=@shipping-label.pdf\"" } ] } }, "/api/v1/print-jobs": { "get": { "tags": [ "Zadania druku" ], "summary": "Pobierz listę zadań druku", "operationId": "listPrintJobs", "parameters": [ { "name": "limit", "in": "query", "description": "Maksymalna liczba zadań w odpowiedzi.", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 100, "minimum": 1 } }, { "name": "cursor", "in": "query", "description": "Kursor z pola `next_cursor` poprzedniej odpowiedzi.", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "Zadania druku", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrintJobList" } } } }, "401": { "description": "Token OAuth Bearer jest nieprawidłowy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Token OAuth Bearer nie zawiera scope `print_jobs:read`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Przekroczono limit żądań", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "description": "Zwraca ostatnie zadania z paginacją kursorową. Używaj tego endpointu w ekranach operacyjnych i narzędziach wsparcia.", "x-codeSamples": [ { "lang": "cURL", "source": "curl -sS 'https://public-api.cloudprint.me/api/v1/print-jobs?limit=20' \\\n -H \"Authorization: Bearer $ACCESS_TOKEN\"" } ] }, "post": { "tags": [ "Zadania druku" ], "summary": "Utwórz zadanie druku", "operationId": "createPrintJob", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "Opcjonalny klucz zapobiegający duplikatom zadań dla tego samego konta i payloadu.", "required": false, "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePrintJobRequest" } } } }, "responses": { "201": { "description": "Zadanie druku zostało utworzone", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrintJob" } } } }, "409": { "description": "Konflikt klucza idempotencji albo nieobsługiwana trasa druku. Przy nieobsługiwanej trasie przyczyna znajduje się w `details.reason`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Walidacja zadania druku nie powiodła się", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Przekroczono limit żądań", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Nieoczekiwany błąd" } }, "security": [ { "BearerAuth": [] } ], "description": "Tworzy zadanie dla przesłanego dokumentu i wybranej drukarki. Przy ponowieniu po błędzie sieci wysyłaj `Idempotency-Key`, aby uniknąć duplikatów.", "x-codeSamples": [ { "lang": "cURL", "source": "curl -sS https://public-api.cloudprint.me/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.me/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": [ "Zadania druku" ], "summary": "Utwórz zadanie z dokumentu base64", "operationId": "createPrintJobFromBase64", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "Opcjonalny klucz zapobiegający duplikatom zadań dla tego samego konta i payloadu.", "required": false, "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePrintJobFromBase64Request" } } } }, "responses": { "201": { "description": "Zadanie druku zostało utworzone", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrintJob" } } } }, "400": { "description": "Nieprawidłowe żądanie base64", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Konflikt klucza idempotencji albo nieobsługiwana trasa druku. Przy nieobsługiwanej trasie przyczyna znajduje się w `details.reason`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Dokument jest za duży", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "415": { "description": "Typ dokumentu nie jest obsługiwany przez Public API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Walidacja zadania druku nie powiodła się", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Przekroczono limit żądań", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Nieoczekiwany błąd" } }, "security": [ { "BearerAuth": [] } ], "description": "Dekoduje dokument base64, zapisuje go jako zwykły dokument CloudPrint i tworzy zadanie w jednym żądaniu. Używaj tylko wtedy, gdy multipart lub URL HTTPS są niepraktyczne, ponieważ base64 zwiększa rozmiar żądania.", "x-codeSamples": [ { "lang": "cURL", "source": "curl -sS https://public-api.cloudprint.me/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": [ "Zadania druku" ], "summary": "Utwórz zadanie z URL dokumentu", "operationId": "createPrintJobFromUrl", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "Opcjonalny klucz zapobiegający duplikatom zadań dla tego samego konta i payloadu.", "required": false, "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePrintJobFromUrlRequest" } } } }, "responses": { "201": { "description": "Zadanie druku zostało utworzone", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrintJob" } } } }, "400": { "description": "Nieprawidłowe żądanie URL", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Konflikt klucza idempotencji albo nieobsługiwana trasa druku. Przy nieobsługiwanej trasie przyczyna znajduje się w `details.reason`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Zdalny dokument jest za duży", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "415": { "description": "Typ dokumentu nie jest obsługiwany przez Public API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Walidacja zdalnego dokumentu lub zadania nie powiodła się", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Przekroczono limit żądań", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Nieoczekiwany błąd" } }, "security": [ { "BearerAuth": [] } ], "description": "Pobiera dokument z publicznego URL HTTPS, zapisuje go w CloudPrint i tworzy zadanie w jednym żądaniu. Lokalne, prywatne i zawierające dane logowania adresy URL są odrzucane.", "x-codeSamples": [ { "lang": "cURL", "source": "curl -sS https://public-api.cloudprint.me/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": [ "Zadania druku" ], "summary": "Pobierz status zadania druku", "operationId": "getPrintJob", "parameters": [ { "name": "printJobId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Zadanie druku", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrintJob" } } } }, "404": { "description": "Nie znaleziono zadania druku", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Przekroczono limit żądań", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Nieoczekiwany błąd" } }, "security": [ { "BearerAuth": [] } ], "description": "Odpytuj zadanie aż do statusu końcowego. Traktuj `printed` jako sukces, a `failed` jako błąd widoczny dla operatora, który może wymagać wsparcia.", "x-codeSamples": [ { "lang": "cURL", "source": "curl -sS https://public-api.cloudprint.me/api/v1/print-jobs/55555555-5555-4555-8555-555555555555 \\\n -H \"Authorization: Bearer $ACCESS_TOKEN\"" } ] } }, "/api/v1/printers": { "get": { "tags": [ "Drukarki" ], "summary": "Pobierz drukarki konta", "operationId": "listPrinters", "parameters": [ { "name": "limit", "in": "query", "description": "Maksymalna liczba drukarek w odpowiedzi.", "required": false, "schema": { "type": "integer", "default": 100, "maximum": 100, "minimum": 1 } }, { "name": "cursor", "in": "query", "description": "Kursor z pola `next_cursor` poprzedniej odpowiedzi.", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "Drukarki konta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrinterList" } } } }, "429": { "description": "Przekroczono limit żądań", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Nieoczekiwany błąd" } }, "security": [ { "BearerAuth": [] } ], "description": "Zwraca drukarki widoczne na koncie. Zapisuj `printer_id`, a nie lokalne nazwy. Użyj `status`, `capabilities` i `endpoint`, aby zdecydować, czy drukarka może obsłużyć dany proces.", "x-codeSamples": [ { "lang": "cURL", "source": "curl -sS 'https://public-api.cloudprint.me/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": "URL HTTPS dokumentu do pobrania. Hosty lokalne i prywatne są odrzucane.", "type": "string", "format": "uri", "example": "https://files.example.com/labels/order-100045.pdf" }, "document_filename": { "description": "Opcjonalna nazwa pliku używana w diagnostyce i metadanych dokumentu.", "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": "Bajty dokumentu zakodowane w base64.", "type": "string", "format": "byte" }, "document_filename": { "description": "Opcjonalna nazwa pliku używana w diagnostyce i metadanych dokumentu.", "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": "Stabilny, maszynowo odczytywalny kod błędu.", "type": "string" }, "error_code": { "type": [ "string", "null" ] }, "message": { "description": "Bezpieczny komunikat błędu dla człowieka. Jest lokalizowany zgodnie z `Accept-Language`, jeśli tłumaczenie jest dostępne.", "type": "string" }, "details": { "description": "Opcjonalne dane diagnostyczne dla błędów ze strukturalnym kontekstem.", "type": [ "object", "null" ], "example": { "reason": "missing_pdf_renderer" }, "additionalProperties": true } }, "type": "object" } }, "securitySchemes": { "BearerAuth": { "type": "http", "description": "Token dostępu OAuth2 Client Credentials.", "bearerFormat": "JWT", "scheme": "bearer" } } }, "tags": [ { "name": "Uwierzytelnianie", "description": "Pobranie tokenu OAuth2 i sprawdzenie kontekstu aplikacji klienckiej." }, { "name": "Drukarki", "description": "Wykrywanie drukarek klienta widocznych przez połączonych lokalnych agentów." }, { "name": "Agenci", "description": "Sprawdzanie połączonych agentów druku, ich statusu i stanu aktualizacji." }, { "name": "Dokumenty", "description": "Przesyłanie PDF lub jawnych danych RAW języka drukarki przed utworzeniem zadania." }, { "name": "Zadania druku", "description": "Tworzenie, wyświetlanie i odpytywanie zadań do statusu `printed` albo `failed`." } ], "externalDocs": { "description": "Instrukcja integracji z Public API krok po kroku", "url": "https://cloudprint.me/pl/docs/getting-started/" }, "x-tagGroups": [ { "name": "Zacznij tutaj", "tags": [ "Uwierzytelnianie" ] }, { "name": "Proces drukowania", "tags": [ "Agenci", "Drukarki", "Dokumenty", "Zadania druku" ] } ] }