API предварительной записи

Публичный API предварительной записи

Внешние системы (сайт, 1С, колл-центр, портал госуслуг) могут записывать клиентов на конкретные дату и время. Такой клиент появляется в общей очереди с бейджем «Запись 14:30»: его обслуживают в нужное время, но окно при этом не простаивает.

/api/queue/booking v1

Как это работает простыми словами

Клиент с записью — человек, который заранее выбрал дату и время через сайт, 1С или колл-центр. В очереди он виден с пометкой «Запись ЧЧ:ММ».

Клиент без записи (в технических текстах его называют walk-in) — человек, который пришёл без записи, взял талон в терминале и ждёт в живой очереди.

Пока до времени записи ещё далеко, специалист сначала приглашает тех, кто уже стоит в живой очереди. Иначе окно простаивало бы: записанный клиент придёт только через час, а люди без записи ждут прямо сейчас.

Окно защиты — последние несколько минут перед временем записи (по умолчанию 5 минут). В этот момент клиент с записью поднимается в начало очереди. Никто, кто пришёл без записи, уже не может встать перед ним — даже если он пришёл раньше.

Окно вызова — момент, с которого сотрудник может нажать «Вызвать». По умолчанию это ровно назначенное время. Окно можно открыть чуть раньше, но не раньше окна защиты.

Если клиент с записью опаздывает, он всё равно остаётся впереди, и его можно вызвать. Если он не появился за отведённое время (по умолчанию 15 минут), запись отменяется автоматически, чтобы не держать очередь.

Пример: запись на 15:00. В 14:00–14:55 сотрудник обслуживает живую очередь. В 14:55 начинается окно защиты — записанный клиент становится первым, обогнать его нельзя. В 15:00 его можно вызвать. Если он не пришёл к 15:15 — запись отменяется автоматически.

Базовый URL в примерах: 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).
Хотите проверить API без кода? Откройте API-проводник: он отправляет запросы в песочницу, показывает статус, 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_6b1f0c9d8e7a5b4c3d2e1f0a9b8c7d6e
  • Authorization: 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 выдавайте только доверенным супервизорским ключам.

Где взять ключ

  1. Войдите в админку под ролью с правом pages.api_keys (по умолчанию — root, head, admin).
  2. Откройте «Система» → «API-ключи»: /admin/api-keys.
  3. Нажмите «Создать ключ» и выберите тип: «Рабочий (live)» — для боевой интеграции, «Тестовый (sandbox)» — для прогонов.
  4. Отметьте права (scopes), срок действия и при необходимости ограничьте очереди/услуги. Пустой выбор без «Все» означает «ничего не разрешено».
  5. Скопируйте секрет сразу: он показывается один раз, в базе хранится только SHA-256. Если секрет потерян — сделайте «Перевыпустить» (старый ключ сразу перестанет работать).
  6. Храните секрет в переменной окружения или в секрете вашей системы, не в коде и не в репозитории. Передавайте его в 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

Быстрая проверка из терминала: услуги, слоты, создание, чтение, отмена.

Показать код
Загрузка...

Node.js

fetch и axios; готовый класс QueueBookingClient.

Показать код
Загрузка...

PHP

cURL и Guzzle; функции для всех методов.

Показать код
Загрузка...

Python

requests, класс QueueBookingClient.

Показать код
Загрузка...

C#

HttpClient, класс QueueBookingClient.

Показать код
Загрузка...

PowerShell

Invoke-RestMethod, функции для всех методов.

Показать код
Загрузка...

1С:Предприятие 8.3

BSL / HTTPСоединение и ЗащищённоеСоединение.

Показать код
Загрузка...

API версии v1 (путь /api/queue/booking). Документация обновляется вместе с релизом модуля booking.