Update a printer
Renames a printer, switches its welcome receipt, sets, replaces or
removes the one device its address allows (allowed_mac; null removes
it), or changes how documents are printed on it (profile, and
print_options as a whole). The brand and the model are read from the
printer and cannot be changed. An epson printer prints no welcome
receipt, so a welcome_print of true leaves it off, and it reports no
MAC address, so a device cannot be set for it (400 parameter_invalid). A
new profile is judged together with the print_options the printer
already has: send print_options too, or null, when the options do not
fit the new profile (422 print_options_invalid). A printer made with
paper_width and no maker has no known maker until it has connected and
reported itself: until then an edit that names profile, print_options or
allowed_mac, or turns welcome_print on, is 409 printer_not_identified
(a printer that connected and never reports is deleted and added again with
its maker named), and the name and the client reference id can be changed at
any time. An edit
that is refused changes nothing, also what in it was right. After a 5xx, an edit that
names profile or print_options together with another field may be half
made: retrieve the printer and send what is missing. The device can be
changed at any time, also while the printer is polling. Take care with an edit
while a receipt is printing: if it leaves out the device that holds the
job, the device’s confirmation is refused with 403, the job is offered
again after its deadline, and once the device is allowed again the receipt
can print a second time. A hardware swap is an edit of the allowed device:
set the new printer’s MAC address. 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 a
call by a person writes an audit entry that names the fields it changed
and never a value. A person is refused with permission_denied (a
viewer), organization_suspended, organization_required (no header) or
resource_missing (not a member of that organization).
Scope: printers: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
Request
Replaces the device allowed to use the printer’s URL (see
allowed_mac of the request that makes a printer); null removes it,
so that any device that holds the URL is accepted, and left out it stays
as it is. It can be changed at any time, also while the printer is
polling: a device that the new value leaves out is refused from then on,
within about a second, and one it names is let in about 30 seconds
later, plus its poll interval. An edit that leaves out a device while it
is printing makes its confirmation fail with 403, so the receipt can
print a second time once the value is repaired. For a hardware swap, set
the new printer’s MAC address. A printer made with vendor epson
reports no MAC address, so a device cannot be set for it
(400 parameter_invalid), as at create; null is always accepted.
Sets or changes the id of this printer in your own system (see
client_reference_id of the request that makes a printer); null takes
it away, and left out it stays as it is. It is not unique, so it is
never refused for being used already.
What can be set on top of a profile, each field optional. A field left out
keeps the profile’s own value. The ranges are checked when the printer is
made or changed: a value outside its range, or an encoding the profile
does not take, is 422 print_options_invalid naming the field.
The id of a profile a printer can be set to. x-tillcast-profiles of the contract says what each is for and how far it has been checked on a real printer (evidence).
Switches the welcome receipt (see welcome_print of the request that
makes a printer). A printer made with vendor epson prints none:
true is accepted and leaves it off.
Response
The one device allowed to use this printer’s address; null means that
any device that holds the address is accepted. See allowed_mac of the
request that sets it.
When a refused request last left a hint: wrong_host (the host is not
the printer’s) or mac_mismatch (the address names an allowed device
and another device connected). null when there is none.
Read from the printer itself; null until it has connected and
answered. It cannot be set through the API. Text the printer sent,
kept to ASCII letters, digits and . _ - + ( ) /: a claim of whoever
holds the printer’s address, not verified. Treat it as untrusted text.
The id of this printer in your own system, such as kitchen-1, or
null. Not unique: the same value can be on many objects, and
GET /v1/printers?client_reference_id= lists every printer that
carries it. null for every printer made before the field existed.
What the printer reports is wrong: paper_low, paper_out,
cover_open, jam or error.
never_connected, connected or disconnected (the printer has
connected and has not polled for about 4 minutes: its status is
offline unless a suspension or a refused request comes first).
The MAC address the printer reported on its last accepted poll. For
display only: it never addresses or authenticates a printer, and it is a
claim by whoever polled with the address secret, not a verified fact.
null until the first poll, and for a printer that does not report one.
Read from the printer itself; null until it has connected and
answered. It cannot be set through the API. Text the printer sent,
kept to ASCII letters, digits and . _ - + ( ) /: a claim of whoever
holds the printer’s address, not verified. Treat it as untrusted text.
While status is mac_mismatch: the MAC address of the device that was
refused, taken from the refused request. Also a claim: compare it with
the label of your printer before you allow it. null otherwise.
never_connected, online, offline (the printer has connected and
has not polled for about 4 minutes), wrong_host, mac_mismatch (the
address names an allowed device and another device connected),
customer_suspended or location_suspended.
The printer’s last status code, such as 200 OK.
star or epson: set when the printer is made and never changed (see
vendor of the request that adds a printer), with one exception: a
printer made with paper_width and no maker reads star until its first
connection names the maker, once (vendor_source says which case it is).
What is left for the server to settle on the printer. pending: it was made with paper_width and nothing
that names its maker, and has not been settled yet (its maker is set by its first connection, and a Star’s width
by what the printer reports). undetected: a Star reported something Tillcast cannot print on yet (Star Line
mode, 104 mm paper), or nothing usable, so it prints with the default of its paper. done: every other printer,
one made before this field included. A plain string and not an enum. Only in the answer to a single printer,
not in a list.
The printer domain the printer’s URL is on: print.tillcast.com, or a domain that Tillcast has set
up for your organization. The host of the URL is <code of the customer>.<domain>: the code is
Tillcast’s own random code of the customer (the part of the customer’s id after cus_), never an
id of yours. It is recorded when the printer is made and kept when its secret is replaced. Only in
the answer to a single printer, not in a list.
The paper the printer was made for: 58mm, 80mm, or null when it was made without paper_width. Set when
the printer is made and never changed. Only in the answer to a single printer, not in a list.
What can be set on top of a profile, each field optional. A field left out
keeps the profile’s own value. The ranges are checked when the printer is
made or changed: a value outside its range, or an encoding the profile
does not take, is 422 print_options_invalid naming the field.
The profile documents are rendered for (command set, paper width in
characters and text encoding): the id of a preset, the one set with
profile or, while none is set, the default of the printer’s vendor
(star-starprnt-utf8-80mm for a star printer, epson-80mm-48 for an
epson one). It is the profile the printer prints with, also for a
printer made before profiles could be chosen, and, for a printer made
with paper_width and no profile, the one detected from the printer or
confirmed on paper (profile_source says which). A plain string and not an
enum, so that a profile that is retired never breaks a client;
x-tillcast-profiles of the contract lists the ones a printer can be
set to. Only in the answer to a single printer, not in a list.
Where profile comes from. default: nobody chose, so the default of the paper and the maker applies.
detected: a Star’s own report chose the width. confirmed: a calibration code chose it. explicit: a request
or an edit named it, and every printer made before this field existed. A plain string and not an enum, so that a
word added later never breaks a client. Only in the answer to a single printer, not in a list.
Where vendor comes from. default: no maker was named, so the printer reads star until its first
connection names the maker. detected: the first connection decided it. explicit: the request that made the
printer named it, or the printer was made without paper_width, or before that field existed: the server never
changes an explicit maker. A plain string and not an enum, so that a word added later never breaks a client.
Only in the answer to a single printer, not in a list.
Whether the printer prints a welcome receipt on its first connection.
An epson printer prints none: it reads false. Only in the answer
to a single printer.