Skip to navigation

Add a printer

View as Markdown

Adds a printer to a location and returns the URL to type into the printer’s CloudPRNT server field. The URL holds the printer’s secret and is shown only in this answer: keep it, or rotate the secret later to get a new one. The customer and the location must be active. allowed_mac names the one device that may use the URL: an extra safeguard for this one address, not authentication. Without it, any device that holds the URL is accepted, and a printer is not tied to the first device that connects. A MAC address can be read from the label of a printer, but use the MAC the printer reports (mac once it has connected). The brand and the model are read from the printer after it has connected, and cannot be sent. A printer is a Star printer unless vendor says epson, an Epson printer that every organization may make and on which documents and the test page print (see vendor); its URL goes into the printer’s Server Direct Print setting. Send paper_width and no vendor, profile, print_options or allowed_mac and the maker is read from the printer’s first connection, and a Star’s width from what it reports (see paper_width). profile and print_options say how documents are printed on the printer (the paper width in characters, the text encoding, the command set); left out, the default of the vendor is used, and the answer says which one that is. They are checked before anything is made: a mistake in either is a 422 and no printer. 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 its URL is shown once there too. 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

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

locationstringRequired
The location'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.
namestringRequired1-64 characters
1 to 64 characters.
allowed_macstring or nullOptionalformat: "^([0-9A-Fa-f]{2}[:-]?){5}[0-9A-Fa-f]{2}$"

The one device that may use the printer’s URL, as a MAC address: twelve hexadecimal digits, with : or - between the pairs or none. Left out, or null, any device that holds the URL is accepted. With a device named, the MAC address the device reports must be this one, and a device that reports none is refused too: it gets a bare 403, and the status can become mac_mismatch when the refused device named itself and the printer has been quiet for a while. This is an extra safeguard for this one address, not authentication: the secret in the URL is the credential, a MAC address is printed on the printer’s label, and its first three bytes name the maker. A MAC address can be read from the label, but use the MAC the printer reports (mac of the printer once it has connected): some models print the Wi-Fi MAC on the label and report the Ethernet one. It needs a printer whose firmware reports its MAC address. An all-zero, broadcast or multicast address is refused. It is stored and returned in lower case with colons, and the same address may be named on any number of printers. A printer made with vendor epson reports no MAC address, so naming a device for it is refused (400 parameter_invalid).

client_reference_idstring or nullOptional1-128 characters

The id of this printer in your own system, 1 to 128 characters. It is not unique and never refused for being used already; search for it with GET /v1/printers?client_reference_id= before you create when you need to find the printer you made earlier, and send an Idempotency-Key so that a retried create makes one printer.

domainstring or nullOptional

The printer domain to make the URL on: print.tillcast.com, or a domain that Tillcast has set up and activated for your organization. Left out or null, the printer gets the domain Tillcast has chosen for your organization, which is print.tillcast.com unless it has set up one of its own for you. Any other value is 400 parameter_invalid naming domain, with the same words whether or not that domain exists. The host of the URL is always <code>.<domain> with the code Tillcast gives the customer: nothing you send makes a part of it. domain of the printer says which domain it has; it never changes.

paper_widthenum or nullOptional
Allowed values:
print_optionsobject or nullOptional

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.

profileenum or nullOptional

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

vendorenum or nullOptional
Allowed values:
welcome_printboolean or nullOptional

Print a welcome receipt when the printer first connects. On by default (the organization can switch it off for all its printers). A printer made with vendor epson prints none, whatever this says.

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. url is null.

allowed_macstring or null

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.

auth_error_atstring or null

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.

brandstring or nullRead-only<=64 characters

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.

client_reference_idstring or null

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.

conditionlist of strings

What the printer reports is wrong: paper_low, paper_out, cover_open, jam or error.

connectionstring

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

created_atstring
customerstring
idstring
locationstring
macstring or null

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.

modestring
modelstring or nullRead-only<=64 characters

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.

namestring
objectstring
pending_jobsinteger>=0
Jobs waiting for the printer that have not expired.
reported_macstring or null

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.

statusstring

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.

status_codestring or null

The printer’s last status code, such as 200 OK.

vendorstring

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

urlstring or null

The URL to type into the printer’s server setting: the CloudPRNT server field of a star printer, the Server Direct Print setting of an epson printer (see vendor). null when the answer is a replay of an earlier request with the same Idempotency-Key, because the URL is shown only once: rotate the secret for a new one.

detectionstring or nullOptional

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.

domainstring or nullOptional

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.

last_seen_atstring or nullOptional
When the printer last polled us. Only in the answer to a single printer.
paper_widthstring or nullOptional

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.

print_optionsobject or nullOptional

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.

profilestring or nullOptional

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.

profile_sourcestring or nullOptional

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.

vendor_sourcestring or nullOptional

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.

welcome_printboolean or nullOptional

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.

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
409
Conflict Error
422
Unprocessable Entity Error
500
Internal Server Error
503
Service Unavailable Error