Remote Tasks

Remote tasks are for the pattern where a business server creates print jobs centrally and local Agents automatically pull and print them. This is a separate entry point from the browser SDK: the SDK is initiated by a web page connecting to the local Agent, while remote tasks are initiated by the local Agent polling the business server.

How It Works

After remote tasks are enabled, PrintBridge uses the same task URL for two request types:

GET  {endpoint_url}  Pull pending print tasks
POST {endpoint_url}  Report task status

After the local Agent receives a task, it downloads files, converts Office files, queues the job, and submits it to the system print queue. success in status reporting means the job has been submitted to the system print queue. It does not mean the printer has physically finished output.

Local Configuration

Parameter	Type	Default	Description
remote.enabled	boolean	false	Whether remote task polling is enabled.
remote.endpoint_url	string | null	null	Business server task URL. Must be http or https.
remote.bearer_token	string | null	null	Optional. When set, requests include Authorization: Bearer <token>.
remote.device_id	string | null	null	Optional. Device identifier sent in request headers and status reports.
remote.device_name	string | null	null	Optional. Human-readable device name sent in request headers and status reports.
remote.poll_interval_seconds	number	10	Task polling interval. Minimum value is 3 seconds.
remote.max_report_retries	number	10	Maximum retry count after status reporting fails. Minimum value is 1.
remote.history_retention_days	number	3	Number of days to retain local remote task records.

Request Headers

If a token is configured:

Authorization: Bearer <bearer_token>

If device information is configured:

X-PrintBridge-Device-Id: <device_id>
X-PrintBridge-Device-Name: <device_name>

When saving remote configuration or clicking “Test connection”, PrintBridge tests both GET and POST and also sends:

X-PrintBridge-Test: true

The business server can detect this header and only return a connectivity response without creating real print tasks.

Pull Response

The GET response can be an empty response, null, a single task object, or an array of task objects. Empty response and null both mean there are currently no tasks.

Single PDF task:

{
  "type": "print",
  "request_id": "REQ-001",
  "job_id": "JOB-001",
  "format": "pdf",
  "printer_name": "Office Printer",
  "file_url": "https://example.com/label.pdf",
  "copies": 1,
  "paper": {
    "width_mm": 60,
    "height_mm": 40
  }
}

Raw command task:

{
  "type": "print",
  "request_id": "REQ-RAW-001",
  "job_id": "JOB-RAW-001",
  "format": "raw",
  "printer_name": "TSC TE244",
  "data_base64": "U0laRSA2MCBtbSw0MCBtbQpHQVAgMiBtbSwwCkNMUwo="
}

Batch task:

{
  "type": "print_batch",
  "request_id": "REQ-002",
  "batch_id": "BATCH-001",
  "jobs": [
    {
      "job_id": "A-001",
      "format": "image",
      "file_url": "https://example.com/a.png",
      "copies": 1
    },
    {
      "job_id": "B-001",
      "format": "image",
      "file_url": "https://example.com/b.jpg",
      "copies": 2
    }
  ]
}

Task Fields

Field	Required	Description
type	Yes	print or print_batch.
request_id	Yes	Request ID generated by the business server and used to correlate status reports.
batch_id	Required for batch tasks	Batch task ID.
jobs	Required for batch tasks	Array of print jobs inside the batch.
job_id	Yes	Print job ID. It is also the local deduplication key for remote tasks. A recorded job_id will not be queued again.
format	Yes	pdf, image, png, jpg, jpeg, docx, xlsx, pptx, or raw.
printer_name	No	Target printer. If omitted, the local default printer is used.
file_url	Required for file tasks	Download URL for PDF, image, and Office files.
data_base64	Required for raw tasks	Base64 content for raw commands.
copies	No	Number of copies. Not supported for raw tasks.
paper	No	Paper size, for example { "width_mm": 60, "height_mm": 40 }. Not supported for raw tasks.

Raw tasks only submit the bytes decoded from data_base64 to the system print queue. Paper, copies, barcode, RFID, and other device-language parameters should be written into the raw commands by the business system.

Status Reporting

PrintBridge only reports three statuses to the remote server:

accepted
success
failed

Local queue status mapping:

queued    -> accepted
submitted -> success
failed    -> failed
cancelled -> failed

Status report body example:

{
  "event": "status",
  "event_id": "8c3f0f3a-0f6c-44c1-9e8e-1f0a60f5c813",
  "request_id": "REQ-001",
  "batch_id": "BATCH-001",
  "job_id": "JOB-001",
  "status": "success",
  "message": "submitted to system print queue",
  "occurred_at": "2026-07-06T10:00:00Z",
  "device_id": "f77160d2-fa59-4ddb-93d9-205cd2dec3ac",
  "device_name": "packing-station-01"
}

event_id is generated by the local Agent as a UUID v4 and persisted in SQLite. The remote server can use it as an idempotency key for status reports.

PrintBridge only treats HTTP 2xx as a successful report. Network errors or non-2xx responses are retried according to remote.max_report_retries. 401, 403, and 404 are treated as configuration errors; remote polling and status reporting pause until the user fixes the configuration.