/api/v1/print/agent/claim
auth: nonePrint-agent first-run setup. Exchanges the one-time SetupToken (issued via `POST /print/tills/setup-token`) for a permanent TillToken — the SetupToken itself IS the credential for this single call. Returns the till + plaintext token (only time it is returned). Fires `TILL_CLAIMED` audit.
handlers: PrintAgentController.claim
| name | required | default | description |
|---|---|---|---|
setupToken bodystring | yes | — | One-time token from the setup-token endpoint. |
shopId bodystring | yes | — | Business id surfaced to the agent. |
shopName bodystring | yes | — | Business display name. |
tillName bodystring | yes | — | Operator-supplied till name. |
machineId bodystring | yes | — | Stable machine identifier (host fingerprint). |
posRegisterId bodystring | no | — | AMICUS POS register id — recorded on `Tills.PosRegisterId` for register→till routing on push. |
APIResponseDataObject<{ till: TillDTO; tillToken: string }>APIError/api/v1/print/agent/jobs
auth: tilltokenReturn PENDING print jobs for the authenticated till. Polled by the agent as a fallback to the SSE wake channel.
handlers: PrintAgentController.listJobs
No parameters.
APIResponseDataList<PrintJobDTO>APIError/api/v1/print/agent/jobs/stream
auth: tilltokenSSELong-lived SSE channel — emits a `wake` event whenever a new PrintJob is published for this till so the agent can fetch + print without waiting for the next poll tick. Keep-alive `:keepalive` comment every 25 s to beat reverse-proxy idle timeouts.
handlers: PrintAgentController.streamJobs
No parameters.
text/event-streamAPIError/api/v1/print/agent/jobs/:id/ack
auth: tilltokenAgent ack — mark a print job `PRINTED` (success) or `FAILED` (USB / printer error). The repository asserts the job belongs to the authenticated till and is still in a settable state.
handlers: PrintAgentController.ackJob
| name | required | default | description |
|---|---|---|---|
id pathinteger | yes | — | PrintJobId (coerced from string digits). |
status body'PRINTED' | 'FAILED' | no | PRINTED | Outcome (defaults to PRINTED). |
emptyAPIErrorAPIError/api/v1/print/agent/heartbeat
auth: tilltokenPeriodic heartbeat — updates `Tills.IsOnline=1` and `LastSeenAt=now`. Sent by the agent on every poll tick / SSE reconnect.
handlers: PrintAgentController.heartbeat
No parameters.
emptyAPIError