Skip to navigation

Create a job

View as Markdown

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

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.

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 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

This endpoint expects an object.
client_reference_idstring or nullOptional1-128 characters

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.

documentlist of objectsOptional

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.

expires_inlong or nullOptional

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.

metadatamap from strings to strings or nullOptional
Up to 10 pairs, 1 KB in all. No personal data.
receiptlinestringOptional1-262144 characters

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

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
402
Payment Required Error
403
Forbidden Error
404
Not Found Error
409
Conflict Error
413
Content Too Large Error
422
Unprocessable Entity Error
429
Too Many Requests Error
500
Internal Server Error