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_slot0 — автоматически: число активных рабочих мест очереди

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 — авто).

Как формируются слоты

  1. Берутся рабочие часы: общие настройки, иначе часы услуги, иначе 08:00–17:00.
  2. Если включено «Учитывать рабочие часы и производственный календарь», закрытые дни (праздники/выходные) не отдают слоты.
  3. Сетка начинается с начала рабочего дня с шагом slot_step_minutes; последний слот — до окончания рабочего дня.
  4. Слоты раньше «сейчас + min_lead_minutes» помечаются past.
  5. Слоты, где число активных броней достигло ёмкости, помечаются booked.

Для круглосуточной организации (work_24h=1) сетка строится с 00:00 до 23:45.

Порядок в живой очереди

Чтобы понять порядок, достаточно трёх понятий:

  • Клиент без записи (в технических текстах — walk-in) — пришёл, взял талон в терминале и ждёт в живой очереди.
  • Клиент с записью — заранее выбрал дату и время; в очереди виден с бейджем «Запись ЧЧ:ММ».
  • Окно защиты — последние lock_before_minutes минут перед временем записи (по умолчанию 5).

Сначала очередь выглядит так:

  1. Отложенные талоны (клиент отошёл) — в начале, как и раньше.
  2. Клиенты с записью, у которых уже началось окно защиты — в начале, по времени записи.
  3. Клиенты без записи — по приоритету услуги, затем по времени создания талона.
  4. Клиенты с записью на более позднее время — в конце; они видны с временем, но их ещё нельзя вызвать.

Что это значит на практике:

  • Пока окно защиты не началось, клиент без записи может оказаться раньше записанного — так окно не простаивает, пока записанный ещё не пришёл.
  • Когда окно защиты началось, записанный клиент уже впереди, и обогнать его нельзя — даже если кто-то без записи пришёл раньше.
  • Вызвать записанного можно с 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.

Часовой пояс и рабочие часы настраиваются в «Организации» и «Предварительной записи».