Skip to content

The booking protocol ​

The addresses a booking page talks to once the bookings module is on, the page the platform serves to the visitor, what the visitor is told without the page doing anything, and the challenge in front of a booking. What to draw with them is bookings on the site; what the module reads from the schema is modules.

At a glance ​

wherethe site's own host; every answer Cache-Control: no-store
timesUTC instants in RFC 3339; zone in the answer is the business's
several unitscount, on /api/availability and in /api/book — never units, nights or days
moneyamount_minor and costs_minor in the site's currency, currency beside them
a field that is not in the table400 JTK_E_BOOKING_FIELD_UNKNOWN to somebody the site knows; dropped for a stranger, and get_site lists it in booking_drops
the visitor's page/_booking/<token>, manage_path in the booking's answer; dressed by /_jtk/booking.css
TurnstileGET /api/turnstile for the key; send its token as turnstile
the versionX-Jtk-Booking: 1 on every request; absent is version 1

Versions ​

The protocol has a version, and a page says which it speaks: the header X-Jtk-Booking on every request to the addresses below, 1 today. The kit sends it; a page that sends none is version 1, which is every page built before versions had a name.

A booking page is a file in a build, so a change to the platform reaches a site only when its kit is updated and the site built again. The platform therefore keeps answering every version a live site still speaks:

  • Within a version the protocol only grows. A field may be added to what a page sends or to an answer; nothing is renamed, removed, or changed in meaning or unit. A page of version 1 keeps working against every platform that answers version 1.
  • A change that cannot be made that way is a new version. The platform reads an older page's requests in the newer shape and answers in the shape that page reads, for as long as a live site speaks the older version.
  • A version is retired only when no live site speaks it. The platform notes the version each site's page last spoke: get_site says it (booking_protocol, booking_protocol_says), and preflight says when it is behind — update @jtakeit/kit in the repository and build.
  • A version the platform does not answer is refused to the studio and its agent with JTK_E_BOOKING_PROTOCOL, naming the versions it does answer; a visitor's booking goes ahead on the platform's reading.

The addresses ​

All on the site's own host. Every answer is Cache-Control: no-store.

GET /api/availability?service=<slug>[&service=<slug>…]&from=<RFC3339>&to=<RFC3339>[&resource=<slug>][&party=<n>][&count=<n>][&class=<slug>]{ zone, horizon, contact, scale, combine, slots: [{ start, ends, free: [<resource slugs>] }], party_max, words }. A month at most. words is the form's words in the business's — { uk: { "form.book": "Орендувати", … }, en: …, de: … }, the kind's dictionary with the site's own words over it; draw them rather than a salon's «Записатися» at a car rental. service repeats for a visit of several: the length is their sum and free lists only the resources that do all of them — allowed only where the settings' combine is on, refused otherwise; combine in the answer says which, as the owner set it now, so a checklist built while it was on keeps to one choice after it is turned off. Starts are UTC instants; zone is the business's, for a page that says "all times are Zurich time". free lists the resources that do the service and have room, smallest table first. party_max is the largest party the site takes — zero means the form never asks — and the page learns it from the first answer. scale is "daily" for a business that lets things by the day and empty otherwise: every letting starts at midnight, so a page that shows a clock shows «00:00» on every start — say the days instead, start to ends. horizon is how many days ahead the business takes bookings, as set now (zero: no limit) — over the one the page was built with. contact is what the visitor has to leave: "either" a telephone or an email, or "both"
GET /api/turnstile{ sitekey } — the widget to render, or "" for none. See Turnstile
POST /api/book{ service, start, name, phone, email, note, resource?, party?, count?, class?, turnstile?, services? } → 201 { id, state, start, ends, amount_minor, currency, token, manage_path, telegram_url, services: [{ slug, title, takes_minutes, costs_minor }] }. services is the visit of several, service alone the one-service form; the price is the sum of what each may be charged, snapshotted on the booking. name and one of phone/email are required — a telephone of seven to fifteen digits, an email that is one address — or both where the answer's contact is "both"; a filled field that is neither is refused whatever it says: `400 { error: "JTK_E_VISITOR_CONTACT", message, field: "phone"
POST /api/pay{ booking: <id>, return?: <path on this host> } → { url }, the payment page. Only for a booking whose amount_minor is not zero; the slot is held at least thirty minutes for it
GET /api/booking?token=…the visitor's own booking: state, times, the names of what was booked, whether it may still be changed and until when, and the business's scale — "daily" means say its dates, not its midnights — and words, the page's in the business's («Ваша оренда», «Скасувати оренду»), by language
POST /api/booking/cancel · POST /api/booking/move{ token } · { token, start }. Open until the business's cancellation window; a move is checked against availability exactly as a first booking is
POST /api/booking/ack{ token, mark } — the customer's that works to the business's change of their confirmed booking: written down, nothing moved. mark is the change_mark the booking was read with; an older one is refused (409), because there is a newer change to answer. GET /api/booking says asks_answer, change_mark and change_was: { start, ends, resource? } — where it was before the change — while it asks
POST /api/booking/proposal/accept · POST /api/booking/proposal/decline{ token, mark } — the customer's answer to another time the business offers for a request, proposal in GET /api/booking: { start, ends, resource, until, mark, reason?, state: "open" } while one is open — reason is the owner's own words, to show as text. Accepted, the booking moves there and is confirmed; the place is checked again, and taken meanwhile it is refused (409), the offer is over and the request stays as it was. Declined, the whole request is withdrawn — ask the customer before you send it. A booking paid online at another price is refused with JTK_E_MOVE_PRICE_CHANGES, as a move is. Where none is open, last_proposal is the last one and how it ended — state accepted, declined, expired, replaced, withdrawn (by the business, or with its own answer to the request) or lost (taken meanwhile), with no mark — so a page says what happened rather than nothing; an accepted one says what the yes changed, changed: time, place (whose it is, at the same time) or both — absent where that was not kept, which is to be read as the time; a refused answer is the page's cue to read the booking again
GET /api/booking.ics?token=…the calendar file

The names and shapes in the table are the whole of it, generated from the API's own struct. A field or a parameter that is not there — or a number sent as a string — is refused to somebody the site knows (a preview, the studio, its agent) with 400 { error: "JTK_E_BOOKING_FIELD_UNKNOWN", fields, takes }: which names were wrong, and every name that would have been read. From a stranger it is dropped and the booking goes ahead without it, so a visitor is never turned away for the page's mistake — which is why the form is tried on the preview before anybody else uses it. Dropped is not unheard: get_site answers with booking_drops first — each name, where it was sent, how many times this month — until the page stops sending it. A name is kept only where a page could have meant it: letters, digits, _ and -, at most 40 characters; every other key is counted as (a name that is no field).

state is confirmed or pending, which on the page is the difference between you are booked and we will confirm shortly. A booking that costs money is pending until it is paid, whatever the confirmation mode: send the visitor to /api/pay and say so.

The visitor's page ​

/_booking/<token> is served by the platform on every site: the booking, add to calendar, reminders in Telegram, move and cancel. Link to it from the page that says "received" — manage_path in the booking's answer — and it is in every email the visitor gets. Show the link itself there too, with a word that it is the booking's key: nothing else opens the booking, and a visitor who closes the tab has only what they kept.

The page is plain on purpose, and it wears the site's clothes when the site brings them: it links a stylesheet at /_jtk/booking.css on the site's own host (in an Astro site, public/_jtk/booking.css), and a site without one costs nothing but a 404 the browser forgets. The page is styled by its ids — title, site, state, when, what, with, note, actions, ics, tg, move, cancel, mover, month, days-row, prev, next, slots, err — and the classes btn, row, quiet, days, days-row, days-arrow, is-chosen, month and slots; set color-scheme yourself, or the page follows the visitor's. Moving a booking is a row of seven days and the times of the one picked, on a 24-hour clock in every language. A site that wants more than clothes draws its own page over the four addresses above; the platform's page is the floor, not the ceiling.

What the visitor is told without the page doing anything ​

With an email on the booking: received, confirmed, refused, cancelled, moved, and reminders a day and two hours before — in the site's language, with the calendar file attached to a confirmation. With Telegram: the same, once they press the deep link (telegram_url) and the bot binds their chat. The page's whole job is to show both links.

Turnstile ​

GET /api/turnstile answers { "sitekey": "…" } — the public key of the widget that challenges this host — or an empty key when nothing does. Render the Turnstile widget with that key and send what it produces as turnstile in POST /api/book; with an empty key, render nothing and send nothing.

The page never carries a key of its own, because which widget covers a host is the platform's to decide: one widget covers every address on our zones, and a client's own domain is put into a widget of its own the moment it is attached. A booking takes something — with confirmation by hand a pending row holds its slot for days — and a script writing a page of them is a business that cannot be booked.