API предварительной записи
Расписание, слоты и правила
Слоты строятся в часовом поясе системы (timezone) по рабочим часам
организации и, если включено, по производственному календарю РФ.
https://timira.ru.
Каждый клиент должен обращаться к своему внешнему IP или домену, где
развёрнута его копия системы; путь /api/queue/booking одинаковый.
GET /schedule
Возвращает действующие правила без привязки к услуге.
{
"enabled": true,
"timezone": "Europe/Moscow",
"max_days_ahead": 30,
"slot_step_minutes": 15,
"min_lead_minutes": 15,
"lock_before_minutes": 5,
"call_before_minutes": 0,
"no_show_grace_minutes": 15,
"use_work_hours": true,
"capacity_per_slot": 0,
"work_hours": { "start": "08:00", "end": "17:00", "work_24h": false }
}
| Поле | Смысл |
|---|---|
max_days_ahead | На сколько дней вперёд можно записаться |
slot_step_minutes | Шаг сетки слотов от начала рабочего дня |
min_lead_minutes | Минимальный запас до слота от «сейчас» |
lock_before_minutes | За сколько минут до записи бронь поднимается в начало и её нельзя обогнать |
call_before_minutes | С какого момента бронь можно вызывать (0 — ровно в назначенное время) |
no_show_grace_minutes | Через сколько после времени записи бронь автоматически отменяется |
capacity_per_slot | 0 — автоматически: число активных рабочих мест очереди |
GET /slots?service_id=3&date=2026-12-01
date — YYYY-MM-DD в часовом поясе системы. Если не указана,
берётся сегодня. Ответ содержит available, reason и остаток
мест на каждом слоте.
{
"date": "2026-12-01",
"timezone": "Europe/Moscow",
"service": { "id": 3, "name": "Приём документов", "prefix": "П", "queue": { "id": 1, "name": "Окно 1" } },
"capacity": 2,
"closed": false,
"reason": null,
"slots": [
{ "time": "08:00", "iso": "2026-12-01T05:00:00.000Z", "available": false, "reason": "past", "capacity": 2, "booked": 0, "remaining": 2 },
{ "time": "08:15", "iso": "2026-12-01T05:15:00.000Z", "available": true, "reason": null, "capacity": 2, "booked": 0, "remaining": 2 },
{ "time": "10:00", "iso": "2026-12-01T07:00:00.000Z", "available": false, "reason": "booked", "capacity": 2, "booked": 2, "remaining": 0 }
]
}
Ёмкость считается по активным рабочим местам очереди. Если в очереди 3 окна,
на один слот можно записать 3 человека. Настройка booking_capacity_per_slot
задаёт ёмкость вручную (0 — авто).
Как формируются слоты
- Берутся рабочие часы: общие настройки, иначе часы услуги, иначе 08:00–17:00.
- Если включено «Учитывать рабочие часы и производственный календарь», закрытые дни (праздники/выходные) не отдают слоты.
- Сетка начинается с начала рабочего дня с шагом
slot_step_minutes; последний слот — до окончания рабочего дня. - Слоты раньше «сейчас + min_lead_minutes» помечаются
past. - Слоты, где число активных броней достигло ёмкости, помечаются
booked.
Для круглосуточной организации (work_24h=1) сетка строится с 00:00 до 23:45.
Порядок в живой очереди
Чтобы понять порядок, достаточно трёх понятий:
- Клиент без записи (в технических текстах — walk-in) — пришёл, взял талон в терминале и ждёт в живой очереди.
- Клиент с записью — заранее выбрал дату и время; в очереди виден с бейджем «Запись ЧЧ:ММ».
-
Окно защиты — последние
lock_before_minutesминут перед временем записи (по умолчанию 5).
Сначала очередь выглядит так:
- Отложенные талоны (клиент отошёл) — в начале, как и раньше.
- Клиенты с записью, у которых уже началось окно защиты — в начале, по времени записи.
- Клиенты без записи — по приоритету услуги, затем по времени создания талона.
- Клиенты с записью на более позднее время — в конце; они видны с временем, но их ещё нельзя вызвать.
Что это значит на практике:
- Пока окно защиты не началось, клиент без записи может оказаться раньше записанного — так окно не простаивает, пока записанный ещё не пришёл.
- Когда окно защиты началось, записанный клиент уже впереди, и обогнать его нельзя — даже если кто-то без записи пришёл раньше.
-
Вызвать записанного можно с
call_before_minutesдо времени записи. По умолчанию 0 — ровно в назначенное время (клиент может ещё не прийти).
Пример: запись на 15:00, окно защиты 5 минут. В 14:54 клиент без записи ещё
может быть раньше. В 14:55 запись поднимается в начало и обогнать её нельзя.
В 15:00 её можно вызвать. Если клиент не пришёл к 15:15, запись отменяется
автоматически (no_show_grace_minutes).
Сервер проверяет время вызова сам: прямой запрос
POST /api/queue/call/:id раньше call_before_minutes
вернёт 409 call_too_early.