Create a job
Queues a job for a printer. The document is document, an array of blocks, or receiptline, text in ReceiptLine, the markup language of receipt printers; exactly one of the two is sent, and both or neither is 422 document_invalid. Tillcast turns it into the commands of the printer’s profile when it accepts the request.
Blocks. document is an array in print order. Each block is one visible unit and says its type: text, row, table, rule, image, barcode, qr, cut or feed. The text of a block prints as it is written, whatever characters it has: a |, a {, a line of - or a ~ in a name is a character and not markup. A block that is not valid is 422 document_invalid, and param is the path of a problem (the first by block and cell), such as document[3].rows[1][0].size. A document has at most 1000 blocks, and the same receipt written in ReceiptLine is at most 256 KB (413 document_too_large).
Text. receiptline is 1 byte to 256 KB of UTF-8 after the JSON is decoded and not only white space. The markup characters of ReceiptLine apply in it, so text of your own must be escaped; it is for documents written for other ReceiptLine tools, pasted from the ReceiptLine demo, or made by software of yours that writes the language. Its warnings count lines and columns of this text; for blocks they count those of the same receipt written in ReceiptLine.
The command property of ReceiptLine, which would send raw printer commands, is refused (422 document_command_not_allowed), and so is a hexadecimal escape that rebuilds a control character inside a text. The document is not stored and is never returned. The answer says which profile and transport the job was rendered with and lists its warnings: the places where the renderer did something other than the document says. The printer prints the job the next time it polls. A request body may be up to 800 KB. The rendered job may be up to 256 KB, or less for a profile that says so (90 KB for epson-legacy-80mm-42); a larger one is 413 rendered_too_large. Send an Idempotency-Key so that a retry does not queue a second job: a replay returns the job that was made, with its warnings, and renders nothing. {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.
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 body returns the first result (200, with Idempotent-Replayed: true) instead of making a second object; the same key with a different body is an error (422). Keys are remembered for 24 hours.
Request
The id of this job in your own system, such as an order number: 1 to
128 characters. It is not unique and never refused for being used
already, so a retry that is a new request makes a second job; send an
Idempotency-Key to make a retry safe. Find the jobs that carry it with
GET /v1/jobs?client_reference_id=. No personal data.
What to print, as blocks: an array in print order, each block one
visible unit that says its type (text, row, table, rule,
image, barcode, qr, cut, feed). Tillcast turns it into the
commands of the printer when it accepts the request. The text of a block
prints as it is written: nothing in it is markup. Send this or
receiptline, not both; one of them is required.
Seconds the job can be offered to the printer: 60 to 604800. The
default is 86400 (24 hours). A whole number: 3600.0 is 3600, a
fraction is 400 parameter_invalid.
What to print, as text in ReceiptLine, the markup language of receipt
printers: 1 byte to 256 KB of UTF-8 and not only white space. The
markup characters of the language apply in it (|, {, }, -
alone on a line, ~, _, ", a backtick, ^, \): text of your own
must be escaped, which document does for you. For documents written
for other ReceiptLine tools, pasted from the ReceiptLine demo, or made
by software of yours that writes the language. The command property is
refused (422 document_command_not_allowed). Send this or document,
not both.
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.