Quickstart: your first booking in 10 minutes
You’ll set up a barbershop with two barbers, find their open times, hold a slot while a customer pays, confirm it, and see Tiempo refuse a second booking for the same chair. Everything here runs in test mode with plain HTTP, so it works from any language.
Create a platform to get a test key (tpt_…). It’s shown once, so copy it. Then set three variables in your shell; you’ll fill in ACCOUNT in the first step.
1. Add a business
Each business on your platform is an account. Its timezone is where “Monday 09:00” is measured. Copy the id into ACCOUNT: every request about this business sends it in the Tiempo-Account header.
2. Add the barbers
Anything that can be booked is a resource: a barber, a chair, a room, a court. The type is yours to name. Create Ann and Bob and note their ids.
3. Give them working hours
A schedule is a weekly pattern of local times, starting on a date. Lunch breaks are just gaps between intervals; a list of several weeks makes a rota. Days off and holidays are blocks; one-off changes are overrides. A resource with no schedule is closed: hours are what make it bookable.
4. Find open times
Ask for 45 minutes with either barber. Tiempo returns every start time on a 15-minute grid where someone is free, with who. Your app shows these; it never works out availability itself.
5. Hold the slot
Creating a booking without a status places a hold: pending, with an expires_at 15 minutes away. It occupies the barber while your customer pays. Giving resources means “whichever is free, in this order”, and Tiempo picks atomically, so two customers can’t both get Ann.
Send an Idempotency-Key on every POST. If the network drops and you retry, you get the same booking back instead of a second one.
6. Confirm it
When payment succeeds, confirm. If the customer walks away, do nothing: the hold expires, the time frees up, and you get a booking.expired webhook. To book with no hold, send "status": "confirmed" when creating.
7. Try to double-book
Book the same barber at the same time again. Tiempo locks the barber while it checks, so this is refused even when two requests arrive in the same millisecond. A 409 booking_conflict says why, per segment: offer the customer other times rather than retrying.
8. Hear about changes
Every change is an event. Add one webhook endpoint for your whole platform and Tiempo POSTs each event to it, signed, retrying for about three days. Until your endpoint is live, read the same events from /v1/events.
Next: map your product onto Tiempo with a use-case guide, give your coding agent the rules file, or read the bookings reference.