API section

Printing

Printing through the cloud: a shop, warehouse or CRM server prints a PDF, images, HTML, ESC/POS and ZPL commands or a label template on a workplace printer; a queue while the workplace is offline, in order; status, cancelling and a webhook; workplace printers with their state.

GET	`/api/v1/print-jobs`	Recent print jobs
POST	`/api/v1/print-jobs`	Print on a workplace printer
POST	`/api/v1/print-jobs/{id}/cancel`	Cancel a print job
GET	`/api/v1/print-jobs/{id}`	Print job
GET	`/api/v1/devices/{id}/printers`	Workplace printers

Recent print jobs#

GET/api/v1/print-jobs

Newest first; deviceId — only this workplace, status — only in this state, idempotencyKey — find a job by your own key

Parameters

Name	In	Type
`idempotencyKey`	query	string
`deviceId`	query	integer int64
`status`	query	string
`limit`	query	integer int32

Response 200 application/json

Array · PrintJobView

idinteger int64
idempotencyKeystring
statusstring
deviceIdinteger int64
titlestring
printerstring
sourcestring
sizeBytesinteger int64
attemptsinteger int32
agentJobIdstring
createdAtstring date-time
expireAtstring date-time
doneAtstring date-time
errorError
2 fields · Error
- codestring
- messagestring

Errors — problem+json with a code field, see error codes.

Request example

curl

curl 'https://cloud.hw-connector.ru/api/v1/print-jobs' \
  -H 'X-Api-Key: hwk_…'

Print on a workplace printer#

POST/api/v1/print-jobs

Operation

Exactly one source: pdf, images, raw, text, html, htmlUrl, urls or label. A new job — 202, the same key — 200 with the same job, the same key with another document — 409. Workplace offline — the job waits (up to expireAfterSec or cloud.print.ttl-hours), jobs of one workplace reach the agent in order. Prefer: wait=N — wait for the outcome up to 60 s; the outcome — webhook to callbackUrl

Parameters

Name	In	Type	Description
`Idempotency-Key`	header	string
`Prefer`	header	string

Request body application/json required

Fields · PrintJobRequest

idempotencyKeystring
from 0
to 100
deviceIdinteger int64required
titlestring
from 0
to 200
printerstring
from 0
to 300
deviceinteger int32
rolestring
from 0
to 40
copiesinteger int32
from 1
to 20
pdfstring
imagesarray of string
rawstring
textobject
htmlstring
htmlUrlstring
from 0
to 2000
urlsarray of string
labelLabel
2 fields · Label
- namestringrequired
  from 0
  to 100
- datamap → string
optionsobject
expireAfterSecinteger int32
from 10
callbackUrlstring
pattern: https?://.+
from 0
to 500

JSON

{
  "idempotencyKey": "string",
  "deviceId": 1,
  "title": "string",
  "printer": "string",
  "device": 1,
  "role": "string",
  "copies": 1,
  "pdf": "string",
  "images": [
    "string"
  ],
  "raw": "string",
  "text": {},
  "html": "string",
  "htmlUrl": "string",
  "urls": [
    "string"
  ],
  "label": {
    "name": "string",
    "data": {
      "key": "string"
    }
  },
  "options": {},
  "expireAfterSec": 10,
  "callbackUrl": "string"
}

Response 200 application/json

Fields · PrintJobView

idinteger int64
idempotencyKeystring
statusstring
deviceIdinteger int64
titlestring
printerstring
sourcestring
sizeBytesinteger int64
attemptsinteger int32
agentJobIdstring
createdAtstring date-time
expireAtstring date-time
doneAtstring date-time
errorError
2 fields · Error
- codestring
- messagestring

Errors — problem+json with a code field, see error codes.

Request example

curl

curl -X POST 'https://cloud.hw-connector.ru/api/v1/print-jobs' \
  -H 'X-Api-Key: hwk_…' \
  -H 'Idempotency-Key: $(uuidgen)' \
  -H 'Prefer: wait=30' \
  -H 'Content-Type: application/json' \
  --data '{"idempotencyKey":"string","deviceId":1,"title":"string","printer":"string","device":1,"role":"string","copies":1,"pdf":"string","images":["string"],"raw":"string","text":{},"html":"string","htmlUrl":"string","urls":["string"],"label":{"name":"string","data":{"key":"string"}},"options":{},"expireAfterSec":10,"callbackUrl":"string"}'

Cancel a print job#

POST/api/v1/print-jobs/{id}/cancel

A job waiting for the workplace is cancelled at once; one already passed to the agent — only while the agent has not started it (printer busy). Started or finished — 409 PRINT_JOB_STARTED with the current state

Parameters

Name	In	Type	Description
`id`required	path	integer int64

Response 200 application/json

Fields · PrintJobView

idinteger int64
idempotencyKeystring
statusstring
deviceIdinteger int64
titlestring
printerstring
sourcestring
sizeBytesinteger int64
attemptsinteger int32
agentJobIdstring
createdAtstring date-time
expireAtstring date-time
doneAtstring date-time
errorError
2 fields · Error
- codestring
- messagestring

Errors — problem+json with a code field, see error codes.

Request example

curl

curl -X POST 'https://cloud.hw-connector.ru/api/v1/print-jobs/42/cancel' \
  -H 'X-Api-Key: hwk_…'

Print job#

GET/api/v1/print-jobs/{id}

status: QUEUED, SENDING, DONE, FAILED, CANCELLED, UNKNOWN, EXPIRED; error — why it was not printed or what it is waiting for

Parameters

Name	In	Type	Description
`id`required	path	integer int64

Response 200 application/json

Fields · PrintJobView

idinteger int64
idempotencyKeystring
statusstring
deviceIdinteger int64
titlestring
printerstring
sourcestring
sizeBytesinteger int64
attemptsinteger int32
agentJobIdstring
createdAtstring date-time
expireAtstring date-time
doneAtstring date-time
errorError
2 fields · Error
- codestring
- messagestring

Errors — problem+json with a code field, see error codes.

Request example

curl

curl 'https://cloud.hw-connector.ru/api/v1/print-jobs/42' \
  -H 'X-Api-Key: hwk_…'

Workplace printers#

GET/api/v1/devices/{id}/printers

A live request to the agent: system printers (with roles and state) and driverless printers. Workplace offline — 503 NOT_CONNECTED

Parameters

Name	In	Type	Description
`id`required	path	integer int64	register number from `GET /api/v1/devices`

Response 200 application/json

Array · Printer

namestring
kindstring
deviceinteger int32
isDefaultboolean
rolesarray of string
statestring
reasonsarray of string

Errors — problem+json with a code field, see error codes.

Request example

curl

curl 'https://cloud.hw-connector.ru/api/v1/devices/42/printers' \
  -H 'X-Api-Key: hwk_…'