API предварительной записи
Публичный API предварительной записи
Внешние системы (сайт, 1С, колл-центр, портал госуслуг) могут записывать клиентов на конкретные дату и время. Такой клиент появляется в общей очереди с бейджем «Запись 14:30»: его обслуживают в нужное время, но окно при этом не простаивает.
Как это работает простыми словами
Клиент с записью — человек, который заранее выбрал дату и время через сайт, 1С или колл-центр. В очереди он виден с пометкой «Запись ЧЧ:ММ».
Клиент без записи (в технических текстах его называют walk-in) — человек, который пришёл без записи, взял талон в терминале и ждёт в живой очереди.
Пока до времени записи ещё далеко, специалист сначала приглашает тех, кто уже стоит в живой очереди. Иначе окно простаивало бы: записанный клиент придёт только через час, а люди без записи ждут прямо сейчас.
Окно защиты — последние несколько минут перед временем записи (по умолчанию 5 минут). В этот момент клиент с записью поднимается в начало очереди. Никто, кто пришёл без записи, уже не может встать перед ним — даже если он пришёл раньше.
Окно вызова — момент, с которого сотрудник может нажать «Вызвать». По умолчанию это ровно назначенное время. Окно можно открыть чуть раньше, но не раньше окна защиты.
Если клиент с записью опаздывает, он всё равно остаётся впереди, и его можно вызвать. Если он не появился за отведённое время (по умолчанию 15 минут), запись отменяется автоматически, чтобы не держать очередь.
Пример: запись на 15:00. В 14:00–14:55 сотрудник обслуживает живую очередь. В 14:55 начинается окно защиты — записанный клиент становится первым, обогнать его нельзя. В 15:00 его можно вызвать. Если он не пришёл к 15:15 — запись отменяется автоматически.
https://timira.ru/api/queue/bookingВажно:
timira.ru — наш основной домен, он используется
только для примеров. Каждый клиент должен подставить свой внешний IP
или домен, на котором развёрнута его копия системы электронной
очереди: например https://queue.client.ru/api/queue/booking или
https://203.0.113.10/api/queue/booking. Путь
/api/queue/booking одинаковый — меняется только хост.Все ответы — JSON. Аутентификация — по API-ключу, выпущенному в админке → API-ключи (право
pages.api_keys).
X-Request-Id и JSON-ответ. Тестовые брони
не попадают в живую очередь.
Быстрый старт
is_test=true брони, которые не попадают в живую
очередь, отчёты и на экраны. Для боевой работы выпустите отдельный
live-ключ в админке: «Система → API-ключи» →
/admin/api-keys.
1. Проверить ключ и получить услуги
curl -s "https://timira.ru/api/queue/booking/services" \
-H "X-API-Key: qk_test_sandbox_6b1f0c9d8e7a5b4c3d2e1f0a9b8c7d6e"
2. Получить свободные слоты
curl -s "https://timira.ru/api/queue/booking/slots?service_id=3&date=2026-12-01" \
-H "X-API-Key: qk_test_sandbox_6b1f0c9d8e7a5b4c3d2e1f0a9b8c7d6e"
3. Создать запись
curl -s -X POST "https://timira.ru/api/queue/booking" \
-H "X-API-Key: qk_test_sandbox_6b1f0c9d8e7a5b4c3d2e1f0a9b8c7d6e" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 6f1c2a9e-4b1d-4c8e-9a55-1c2f3d4e5f60" \
-d '{
"service_id": 3,
"scheduled_at": "2026-12-01T14:30:00+03:00",
"customer": { "name": "Иван", "phone": "+79990000000", "email": "i@example.ru" },
"note": "Комментарий"
}'
Аутентификация
Ключ передаётся одним из двух способов (приоритет — у первого):
X-API-Key: qk_test_sandbox_6b1f0c9d8e7a5b4c3d2e1f0a9b8c7d6eAuthorization: Bearer qk_test_sandbox_6b1f0c9d8e7a5b4c3d2e1f0a9b8c7d6e
Это тестовый ключ. Для боевой интеграции используйте live-ключ
(qk_live_...), выпущенный в админке.
Секрет хранится в базе только в виде SHA-256. При создании и ротации ключ показывается один раз — сохраните его в защищённом месте интеграции. В журнале действий и в ответах API открытый секрет не отображается.
У ключа есть права (scopes). Если у ключа нет права на операцию, API отвечает
403 scope_denied. Срок действия задаётся при выпуске; просроченный
ключ получает 401 api_key_expired.
| Право | Что разрешает |
|---|---|
services.read | Список очередей и услуг, доступных ключу |
slots.read | Правила записи и свободные слоты |
booking.read | Чтение одной брони по коду |
booking.read_all | Чтение броней, созданных другими ключами |
booking.list | Список броней за период |
booking.create | Создание брони |
booking.cancel | Отмена брони |
booking.reschedule | Перенос брони на другое время |
По умолчанию ключ видит только свои брони (по
api_key_id). Право booking.read_all выдавайте
только доверенным супервизорским ключам.
Где взять ключ
-
Войдите в админку под ролью с правом
pages.api_keys(по умолчанию — root, head, admin). - Откройте «Система» → «API-ключи»: /admin/api-keys.
- Нажмите «Создать ключ» и выберите тип: «Рабочий (live)» — для боевой интеграции, «Тестовый (sandbox)» — для прогонов.
- Отметьте права (scopes), срок действия и при необходимости ограничьте очереди/услуги. Пустой выбор без «Все» означает «ничего не разрешено».
- Скопируйте секрет сразу: он показывается один раз, в базе хранится только SHA-256. Если секрет потерян — сделайте «Перевыпустить» (старый ключ сразу перестанет работать).
-
Храните секрет в переменной окружения или в секрете вашей системы, не в
коде и не в репозитории. Передавайте его в
X-API-Key.
Тестовый ключ из песочницы уже создан миграцией. Если он отключён настройкой
«Разрешить тестовый ключ», запросы с ним получат 403 test_disabled.
Как правильно пользоваться API
- Интеграция должна быть серверной: не вставляйте live-ключ в JavaScript браузера или мобильное приложение и не храните его в Git.
- Используйте только HTTPS.
- Сначала прогоняйте сценарии на тестовом ключе; когда всё работает — переключайтесь на live-ключ.
-
Для
POST /api/queue/bookingпередавайтеIdempotency-Key(например, UUID): повтор после сетевого сбоя не создаст вторую бронь. -
Обрабатывайте HTTP-код и машинный
code:409 slot_taken— предложить другое время,401— проверить ключ/срок,403 scope_denied— добавить право,429— подождатьRetry-After. - Соблюдайте лимит 60 запросов/мин на ключ; справочники услуг и слоты кешируйте, а не запрашивайте на каждый вызов.
- Секрет live-ключа показывается один раз. При подозрении на утечку — «Перевыпустить» или отозвать ключ в админке.
Песочница (sandbox)
Для интеграционных прогонов используйте тестовый ключ. Его брони помечаются
is_test: true и не попадают в живую очередь, на
табло, в отчёты, дашборд, push-уведомления и админ-список талонов.
test qk_test_sandbox_6b1f0c9d8e7a5b4c3d2e1f0a9b8c7d6e
Ключ публичен по определению. Его можно отключить настройкой
«Разрешить тестовый ключ» в разделе «Предварительная запись»; тогда запросы
с ним получат 403 test_disabled. Тестовые брони автоматически
удаляются через сутки.
Номера тестовых талонов имеют префикс T- и не расходуют счётчик
живой очереди.
Идемпотентность и лимиты
-
POST /api/queue/bookingподдерживаетIdempotency-Key(до 200 символов). Повтор с тем же телом вернёт200и тот жеbooking_ref; тот же ключ с другим телом —422. Ключи живут 24 часа в БД и переживают рестарт. - Лимит — 60 запросов в минуту на ключ+IP, иначе
429сRetry-After: 60. - Все ответы содержат
X-Request-Id; передайте свой — он будет сохранён. -
Если функция выключена администратором, все методы отвечают
503 booking_disabled.
Готовые примеры
Нажмите «Показать код», чтобы посмотреть файл прямо на странице без скачивания. У каждого блока кода есть кнопка «Копировать» (в том числе внутри раскрытых примеров).
bash / curl
Быстрая проверка из терминала: услуги, слоты, создание, чтение, отмена.
Показать код
Загрузка...
1С:Предприятие 8.3
BSL / HTTPСоединение и ЗащищённоеСоединение.
Показать код
Загрузка...