vsmsconnect — API — print

← all endpoints

GET/api/v1/businesses/:businessId/print/tills auth: jwt (administrator)

List every registered till for the business — name, machine id, `IsDefault`, `IsOnline`, `LastSeenAt`, and optional `LocationId`.

handlers: PrintController.listTills

Inputs

namerequireddefaultdescription
businessId path
uuid		yes—Target business UUID. `requireBusinessAccess` enforces this matches the JWT.

Outputs

200
APIResponseDataList<TillDTO>
Till list.
PUT/api/v1/businesses/:businessId/print/tills/:tillId/name auth: jwt (administrator)

Rename a till. Fires `TILL_RENAMED` audit (resource type `TILL`).

handlers: PrintController.renameTill

Inputs

namerequireddefaultdescription
businessId path
uuid		yes—Target business UUID.
tillId path
uuid		yes—Target till UUID.
tillName body
string		yes—New display name (1–500 chars).

Outputs

200
APIResponseDataObject<TillDTO>
Updated till.
404
APIError
Till not found for this business.
POST/api/v1/businesses/:businessId/print/tills/:tillId/test auth: jwt (administrator)

Dispatch a test PrintJob (`type='TEST'`) to the till. The agent picks it up on its next poll or via the SSE wake stream. Fires `TEST_PRINT_SENT` audit.

handlers: PrintController.testPrint

Inputs

namerequireddefaultdescription
businessId path
uuid		yes—Target business UUID.
tillId path
uuid		yes—Target till UUID.

Outputs

200
APIResponseDataObject<{ printJobId: number }>
Newly created print-job id.
404
APIError
Till not found for this business.
POST/api/v1/businesses/:businessId/print/tills/setup-token auth: jwt (administrator)

Generate a one-time setup token used by the print agent's first-run wizard to claim a permanent TillToken. Optionally binds the resulting till to a specific Location (TAXCORE-246) — single-location merchants omit and the claim resolves to the business default. Fires `TILL_SETUP_TOKEN_GENERATED` audit.

handlers: PrintController.generateSetupToken

Inputs

namerequireddefaultdescription
businessId path
uuid		yes—Target business UUID.
locationId body
uuid		no—Optional Location to bind the till to. Validated against the business — invalid → 422 LOCATION_NOT_FOUND.

Outputs

200
APIResponseDataObject<{ setupToken: string }>
Raw one-time setup token (only returned once).
422
APIError
LOCATION_NOT_FOUND — `locationId` does not belong to this business.
PATCH/api/v1/businesses/:businessId/print/default-till auth: jwt (administrator)

Set the default till for the business. Future auto-print jobs that don't carry an explicit till routing key target this till. Fires `TILL_DEFAULT_SET` audit.

handlers: PrintController.setDefaultTill

Inputs

namerequireddefaultdescription
businessId path
uuid		yes—Target business UUID.
tillId body
uuid		yes—Till UUID to mark default.

Outputs

200
APIResponseDataObject<TillDTO>
Updated till.
404
APIError
Till not found.
GET/api/v1/businesses/:businessId/print/jobs auth: jwt (administrator)

List print jobs for the business, optionally filtered by status.

handlers: PrintController.listPrintJobs

Inputs

namerequireddefaultdescription
businessId path
uuid		yes—Target business UUID.
status query
'PENDING' | 'PRINTED' | 'FAILED' | 'STALE'		no—Filter by `Status`.

Outputs

200
APIResponseDataList<PrintJobDTO>
Print jobs.
POST/api/v1/businesses/:businessId/print/jobs/:id/retry auth: jwt (administrator)

Reset a `FAILED` or `STALE` print job back to `PENDING` so the agent will pick it up again. Fires `PRINT_JOB_RETRIED` audit.

handlers: PrintController.retryPrintJob

Inputs

namerequireddefaultdescription
businessId path
uuid		yes—Target business UUID.
id path
integer		yes—PrintJobId (BIGINT IDENTITY, coerced from string digits).

Outputs

200
APIResponseDataObject<PrintJobDTO>
Updated print job.
404
APIError
Print job not found or not retriable.