Provision a venue from your software
Every call on this page acts on the live API: it creates customers and printers, and a test page prints on real paper. Run it only with a key you were given for this purpose. An agent must not run it unless the owner of the key asked and named the venue.
This page is for a software vendor, such as a property management or booking system, that sets printers up for its own customers: a hotel group, one hotel of the group, a printer at its front desk. Tillcast calls your company the organization, the hotel group a customer, the hotel a location and the device a printer. See the concepts overview. If your software only prints on printers that exist already, you need Integrate a point of sale and not this page.
The steps
Keys
Steps 1 to 5 need the scopes of the Installer preset: customers:read, customers:write, printers:read and printers:write. That key cannot print and cannot read jobs, so it is the right key for provisioning and a poor one to leave in a till. Step 6 needs jobs:write, which the Installer preset does not have. Use the key your point of sale already holds (the Printing preset), or let a person press Test print on the printer’s page in the dashboard.
- The key must cover the whole organization. A key limited to one customer cannot create customers (
403 restricted_key). - A person makes every key, in the dashboard, under API keys, after a six-digit code that Tillcast e-mails to them. A key cannot be created through the API, and neither can an organization. See Authentication and API keys.
- Keep the key in an environment variable on your server, never in a browser or an app.
Your own ids and safe retries
Put the id each object has in your own software in its client_reference_id: the account of the hotel group, the code of the hotel, the code of the printer. It is not unique and Tillcast never refuses it, so it does not stop you creating a second object. Two habits do that:
- Find before you create. Each list takes
client_reference_idand answers with every object that carries the value. An unknown value is an empty list. A search normally answers in one page withhas_more: false. When very many objects share a value, a search can answer a short page, even an empty one, withhas_more: trueand anext_cursor. That is not “nothing found”: follow the cursor untilhas_moreisfalsebefore you decide that nothing exists, see Pagination. If your ids are meant to be unique, stop and ask a person instead, as the sample below does. See Your own IDs. - Send an
Idempotency-Keywith every create. A retry with the same key and the same body answers the same object (200withIdempotent-Replayed: true), and nothing new is made. A key is remembered for 24 hours. The key is shared by all kinds of create of your organization, so use a different key for each one: the same key on a customer and on a location is422 idempotency_key_reused. A key made from your own ids and the kind of object works well, such asvenue-acct-1042-prop-17-location. Every id inside a key must be unique across all your venues. The key belongs to the whole organization, and a printer calledfront-deskexists in every hotel: if the printers of two hotels both use the keyvenue-front-desk-printer, the second create is422 idempotency_key_reused, so put the account and the code of the hotel into it. A hotel code that is only unique inside one account is not enough. A key is 1 to 64 visible ASCII characters, and aclient_reference_idcan be 128: with long ids the key can pass 64 and the create is400 idempotency_key_invalid, so shorten the ids in the key, or use a short hash of them.
Make the customer, the location and the printer
The ids in the answers are made up. Replace them with yours.
When the list is empty and has_more is false, create the customer. The answer is 201.
The id of a customer is cus_ and its 8-character code, which becomes the host of its printers’ URLs. Make the location under it.
Now the printer. Say the paper it prints on, 58mm or 80mm, and name no vendor, profile, print_options or allowed_mac. Tillcast then reads the maker from the printer’s first connection and a Star’s width from what the Star reports, so your software does not have to know which printer the venue bought. See Add a printer by its paper width.
The answer reads "vendor": "star" with "vendor_source": "default" and "detection": "pending" until the printer first connects: its maker is not known yet. Then vendor is star or epson, vendor_source is detected and detection is done, or undetected for a Star whose report cannot be used. Until then:
- A
PATCHthat namesprofile,print_optionsorallowed_mac, or turnswelcome_printon, is409 printer_not_identified. Wait for the first connection. - A page queued for it is made for a Star. If the printer turns out to be an Epson, the page ends
failedwith the reasonrendered_for_other_vendor, and nothing prints. - An Epson reports no line width, so its profile is the default of its paper (
profile_sourcedefault) until a person checks the width on paper in the dashboard, or you set itsprofilewith aPATCHonce it has connected.
If you know the maker, name it instead, with the profile that matches the paper. Nothing is detected then: the answer reads vendor_source explicit, paper_width null and detection done. The vendor cannot be changed afterwards, and a profile of the other maker is refused. Use one call or the other for a printer, not both, and a different Idempotency-Key. See Profiles and print options.
The url is in the answer of a create only. A replay of the call, the same key and the same body, answers 200 with url: null. A read and a list of printers have no url at all, so test for a missing url and not for null.
The same flow in TypeScript, for a server that provisions on demand. It returns the printer, and the URL when this call made the printer. It stops and asks for a person when two objects carry the same id, because Tillcast does not forbid that, and when a search says has_more.
The SDK packages that are published today have no paper_width field, so this sample names the maker and the profile.
Set TILLCAST_BASE_URL to https://api.tillcast.com on purpose. An SDK client with no base URL calls the live API, and process.env.NAME! only silences the type checker, so the sample stops when a variable is missing. See SDKs.
When an answer is lost
A create can work while its answer never reaches you. For a customer or a location the cure is the retry: send the same request with the same key and the same body, and you get the object. The SDKs do not retry a timeout or a dropped connection for you, see Retry safely.
For a printer the object is not enough, because the URL was in the lost 201. Decide by whether the URL has been seen:
A printer whose status is online, offline, wrong_host or mac_mismatch has been reached by a device that used the URL, so treat the URL as seen. never_connected means that no device has used it. customer_suspended and location_suspended come first whatever the printer did, so they tell you nothing about the URL: ask the person who installed the printer before you rotate the secret.
Give the URL to the venue
The printer URL is a password: anyone who holds the whole URL can poll as that printer and download its receipts. See Printer URL.
- Show it once, on a screen of yours behind your own sign-in, or hand it to the installer who types it into the printer, and let it go. Do not store it, log it, put it in a ticket or a chat message, or send it in an e-mail that others read. When it is lost, rotate the secret.
- The person types it into the printer’s settings and restarts the printer. A Star takes it in its CloudPRNT settings and an Epson in its Server Direct Print settings: send them to Set up a Star printer or Set up an Epson printer, and to the Printer setup checklist. The printer needs outgoing HTTPS and nothing else on the network.
Wait until the printer is online
Read the printer and look at status and last_seen_at.
statusgoes fromnever_connectedtoonlinewithin a poll or two, about 5 to 10 seconds, after the URL is typed in and the printer is restarted. Abrandandmodelappear for a Star. A printer added by its paper width also settles:vendor_sourcebecomesdetected, anddetectiongoes frompendingtodone, or toundetectedwhen a Star reports a paper that Tillcast cannot print on yet. A Star answers the question about its paper at its first connection, so this can take a poll longer. Ask again every few seconds for a few minutes, then stop and tell the installer.wrong_hostmeans the printer called a host that is not its own, for example a typo in the customer code, andmac_mismatchthat a device other than the allowed one connected: compare the URL typed in with the one you handed over. See Troubleshooting.last_seen_atis written at most once a minute, andonlineis not cleared when the printer is switched off. For a printer that was online some time ago, judge by how oldlast_seen_atis.- There is no webhook that tells you a printer connected: webhooks are planned and do not exist. Poll.
The first test page
A Star that connects for the first time prints a welcome receipt by itself, with the names of your location and printer, so the installer sees at once that the URL was typed correctly. An Epson prints none. See First connection.
Queue a test page after the printer is online, with a key that has jobs:write, or press Test print in the dashboard. On a Star a test page queued before the first connection takes the place of the welcome receipt, and it is offered to the printer for one hour only. For a printer added by its paper width, a page queued before the first connection is made for a Star and fails with rendered_for_other_vendor if the printer is an Epson.
The answer is a job of kind test. A printer takes at most 5 test prints in any minute and 3 waiting at a time. A test print queued again and again before the printer is online fills those three places, and the fourth is 429 rate_limited with Retry-After: 30 until the printer prints them or an hour has passed, so connect the printer first. See First connection. The paper decides whether it worked: someone has to look at it.
What only a person can do
Do not try to automate these, and an agent must not try:
- Sign up, create the organization and make the API keys. Both need a person and an e-mailed code.
- Put the printer in the venue, connect it to the network, and type the printer URL into its settings. Restart it.
- Look at the paper from the welcome receipt or the test page.
- Check the line width of an Epson that was added by its paper width: the sheet and its code are in the dashboard. Or set its
profilethrough the API once it has connected. - Replace a printer or reset it. A factory reset erases the address typed into the printer, so you rotate the secret and type the new URL in.
What is not there
- There is no sandbox. Every key is live, and the only way to see a printer work is a real printer. Test your provisioning code against a fake client of your own.
- There are no webhooks. Poll the printer, as above.
Remove a venue
Removing a venue is done in the other order. Clear the address in the printer first, because a printer keeps polling an address that no longer exists. Then delete the printer (DELETE /v1/printers/{printer}, which cancels its waiting jobs), then the location, then the customer. A customer that still has locations, or a location that still has printers, is 409 not_empty. To stop printing for a customer without deleting anything, use Suspension and pause.