Professional appointments
The professional-appointments slice gives a professional their own view of the appointments on the schedules they own, and the commands to add and cancel them. It shares the appointment records and the owner lock with public booking, so a manual booking and a client booking cannot both take the same time.
As in the other professional slices, the owner comes from the verified session, and a schedule or appointment that belongs to someone else gives the same not-found result as a missing one. No appointment or client contact detail is disclosed for a foreign schedule.
Reading history
The owner reads appointments for one schedule and an inclusive range of local dates. Archived schedules can still be read. The result includes confirmed and cancelled appointments, each with:
- its local date, start, and end in the schedule's time zone, plus the exact start and end instants;
- its status and source:
manual,browser, ortelegram; - the client name, phone, Telegram handle, and private comment, where kept;
- the service snapshot recorded at booking time;
- for a recurring visit, its rule and occurrence date.
A visit that ends at local midnight is shown as ending at 24:00.
Creating a manual booking
The professional books a client by schedule, local date, start, and end, with a client name and optional phone, Telegram handle, service, and comment. The command commits in one transaction that:
- locks the owner, so concurrent bookings for this professional run one at a time;
- checks the idempotency key (see below);
- requires an owned, unarchived schedule;
- converts the local times through the schedule's time zone. A time that does not exist or occurs twice because of a daylight-saving change is rejected, not shifted;
- if a service is given, requires an active service on that schedule whose duration equals the booked length, and copies its snapshot;
- rejects any overlap with a confirmed appointment on any of the owner's schedules.
A manual booking is placed by the professional, so it does not check offered availability, booking channels, phone blocks, or the entitlement that public bookings need. It also creates no new-booking notice for the professional; see Booking notifications.
Retrying safely
Every manual booking carries a client-generated idempotency key. The API stores the key with a hash of the request body:
- The same key and the same body return the original appointment, so a retry after a lost response does not book twice.
- The same key with a different body, or a key used by another owner, is a conflict.
Recurring appointments
A manual booking can repeat every 1 to 4 weeks. Its length must then be 15 to 480 minutes. The command stores a rule with the client details and service snapshot, books the first visit, and creates occurrences for the next 56 days in the same transaction.
Later occurrences are created on demand. Before reading a date range, a client of the API asks the slice to extend all of the schedule's rules through the last date it needs. Extension is idempotent: each rule and date maps to at most one appointment. An occurrence that cannot be created is not moved elsewhere. It is recorded as a generation issue instead:
| Issue | Cause |
|---|---|
conflict | The time overlaps another confirmed appointment of the owner |
dst_gap | The local start does not exist on that date |
dst_overlap | The local start occurs twice on that date |
The extension reports how many occurrences it created and how many issues it recorded.
Cancelling
Cancellation changes a confirmed appointment's status to cancelled and
records that the professional cancelled it. The row and its details stay in
history, and its time becomes free for a later valid booking. Cancelling an
already cancelled appointment changes nothing and records no further notice.
For a recurring visit the professional chooses a scope:
| Scope | Effect |
|---|---|
occurrence | Cancels this visit and records a skipped date, so extension never recreates it |
future | Cancels this visit and every later created occurrence, and stops the rule from creating more |
Earlier occurrences are never touched.
In the same transaction, the slice records a cancellation notice for the professional when that preference is on, and a cancellation notice for every affected appointment a client has claimed. After the commit it sends live hints to the professional and to those client accounts. A failed hint does not undo the cancellation; the stored notices are found on the next load. See Booking notifications.