Print a test page
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
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.
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
Headers
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
Which page to print: basic, the short page (the default), or full, the page with every barcode, every QR code and the images.
Response headers
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.
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.
api (yours), welcome (the first-connection receipt) or test (a test
print: never billed).
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.
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.
queued, delivered, printed, failed, expired or cancelled.
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.
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.