Skip to navigation

Print a test page

View as Markdown

Queues one test page for a printer: a ReceiptLine document that is rendered with the printer’s own profile, so it has the width, the character set and the commands of that printer (StarPRNT for a Star, ESC/POS for an Epson) and its rules and its table reach the edges of the paper. page chooses which page. basic, the default, shows a heading, the printer’s name, the time in UTC, a table of three columns with lines, and one line in each type style (normal, bold, double width, double height, double width and height, underlined, inverted), then a cut. full shows the same heading and then, in five sections, the type styles, three alignments and the table with a cell that wraps, the Tillcast mark with a ruler, a gray ramp and a density bar as wide as the paper, fifteen barcodes (CODE128, CODE39, CODE93, ITF, Codabar, EAN-13, EAN-8, UPC-A and UPC-E at the module widths that matter) and ten QR codes (the four error correction levels, cell sizes 3 to 8, a Polish sentence and a longer text): print it on a Star and on an Epson and hold the two papers side by side. Any other value of page is 400 parameter_invalid, and so is a page that is given twice. The page is rendered the way a job is: the job lists the profile and the transport it was made with and its warnings, and a printer whose model needs a profile that it does not have is refused with 422 profile_mismatch. The Epson form has not been confirmed on a device yet, so a page that does not print on an Epson is not necessarily a mistake in how the printer was set up. The printer prints it the next time it polls, and the page is offered for one hour. It is a job of kind test: it is never billed and does not count as a print of yours. A printer takes at most 5 test prints in a minute and 3 waiting at a time, of either page (429 rate_limited, with Retry-After), and its queue of 50 jobs applies as for any job. The two limits stop a loop or a double click and are not a quota: calls made at the same moment can pass them, up to that queue. Send an Idempotency-Key so that a retry does not queue a second page; the same key with another page is 422 idempotency_key_reused. The dashboard calls it with the access token of a signed-in owner or developer instead of a key, naming the organization in Tillcast-Organization; the answer is the same, and the call writes an audit entry. A person is refused with permission_denied (a viewer), organization_suspended, organization_required (no header) or resource_missing (not a member of that organization). {printer} is the printer’s id; a MAC address is not accepted there.

Scope: jobs:write.

Authentication

AuthorizationBearer

A restricted API key, tc_rk_live_ and 32 characters. Send it as Authorization: Bearer <key>. A key lists its scopes, and each operation below names the one it needs; a key may also be limited to one customer. An owner or a developer of the organization makes a key in the dashboard, under API keys, after a code sent to their e-mail. The key is shown once, when it is made. An owner or a developer can revoke it there, and a revoked key stops working within a minute.

OR
AuthorizationBearer

The access token of a person signed in to the dashboard, from the dashboard Cognito pool. Dashboard only, except that POST /v1/customers, POST /v1/customers/{customer}/locations, POST /v1/locations/{location}/printers, PATCH /v1/printers/{printer}, DELETE /v1/printers/{printer}, POST /v1/printers/{printer}/rotate-secret and POST /v1/printers/{printer}/test-print also take it, by role (an owner or a developer, with the organization named in Tillcast-Organization).

Path parameters

printerstringRequired
The printer's id.

Headers

Idempotency-Keystring or nullOptional

A string of 1 to 64 visible ASCII characters that identifies this request. A retry with the same key and the same page returns the first result (200, with Idempotent-Replayed: true) instead of queueing a second page. Keys are remembered for 24 hours.

Query parameters

pageenumOptional

Which page to print: basic, the short page (the default), or full, the page with every barcode, every QR code and the images.

Allowed values:

Response headers

Idempotent-ReplayedstringOptional

true: this is the result of an earlier request with the same Idempotency-Key.

Response

A replay of an earlier request with the same Idempotency-Key.

client_reference_idstring or null

The id of this job in your own system, such as an order number, or null. Not unique: the same value can be on many jobs, and GET /v1/jobs?client_reference_id= lists every job that carries it (the last 7 days). No personal data.

completed_atstring or null
created_atstring
customerstring
delivered_atstring or null
expires_atstring
When the job stops being offered to the printer.
idstring
kindstring

api (yours), welcome (the first-connection receipt) or test (a test print: never billed).

locationstring
metadatamap from strings to strings or null
objectstring
printerstring
profilestring or null

The profile the document was rendered for: the id of a preset (x-tillcast-profiles lists them). A plain string and not an enum, so that a profile that is retired never breaks a client. null for a job that was queued as ready printer data and not rendered from a document, such as every job from before documents were rendered.

reasonstring or null
Why the job did not print.
result_codestring or null
The printer's own status code for the job.
size_byteslong>=0

The size in bytes of what the printer is sent: the rendered document, after the transport step. Not the size of the document you sent.

statusstring

queued, delivered, printed, failed, expired or cancelled.

transportstring or null

The transport step applied to the rendered bytes: its id and revision, such as cloudprnt-star.1. A later correction of a step changes new jobs only, and this tells which jobs were rendered with which. null where profile is.

warningslist of objects

What the renderer noticed in the document, in the order it happened: at most 21 (the first 20, and a too_many_warnings that says there were more). Always there, an empty list for a document with nothing to say. Kept with the job: a replay of the request and every later read return the same list.

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
409
Conflict Error
422
Unprocessable Entity Error
429
Too Many Requests Error
500
Internal Server Error