API предварительной записи
Ошибки и типовые ситуации
Все ошибки — JSON вида { "error": "текст", "code": "машинный_код" }.
https://timira.ru.
В рабочей интеграции замените его на внешний IP или домен установки клиента;
путь /api/queue/booking не меняется.
| HTTP | code | Когда возникает | Что делать |
|---|---|---|---|
| 400 | invalid_scheduled_at | Не передано или не разобрано время | Передайте ISO со смещением либо date+time |
| 400 | slot_in_past | До слота меньше min_lead_minutes | Выберите слот позже |
| 400 | slot_not_aligned | Время не попадает в сетку | Берите время из GET /slots |
| 400 | slot_outside_work_hours | Время вне рабочих часов | Используйте слоты из ответа GET /slots |
| 400 | day_closed | Праздник/выходной | Выберите рабочий день |
| 400 | date_in_past / date_too_far | Дата вне разрешённого диапазона | Соблюдайте max_days_ahead |
| 400 | contact_required | Нет телефона и e-mail при включённом требовании | Передайте контакт клиента |
| 400 | invalid_customer | Некорректный e-mail | Проверьте формат |
| 401 | api_key_required | Нет заголовка с ключом | Передайте X-API-Key |
| 401 | invalid_api_key | Ключ не найден или отозван | Проверьте ключ в админке |
| 401 | api_key_expired | Истёк срок действия | Выпустите новый ключ или продлите срок |
| 403 | scope_denied | У ключа нет нужного права | Добавьте scope ключу |
| 403 | queue_forbidden / service_forbidden | Услуга вне разрешённых ключу | Расширьте ограничения ключа |
| 403 | test_disabled | Песочница выключена | Используйте live-ключ или включите тестовый режим |
| 404 | booking_not_found | Нет брони с таким booking_ref (или она чужая) | Проверьте код и владельца ключа |
| 409 | slot_taken | Мест на слот больше нет | Выберите другой слот |
| 409 | call_too_early | Попытка вызвать бронь раньше окна вызова | Дождитесь scheduled_at − call_before_minutes |
| 409 | booking_not_active | Отмена/перенос неактивной брони | Проверьте status |
| 409 | idempotency_in_progress | Повтор, пока первый запрос ещё выполняется | Повторите через секунду |
| 422 | idempotency_conflict | Тот же Idempotency-Key, другое тело | Используйте новый ключ |
| 429 | rate_limited | Больше 60 запросов/мин | Повторите после Retry-After |
| 503 | booking_disabled | Функция выключена администратором | Включите «Предварительную запись» |
Типовые сценарии
Слот заняли между чтением и созданием
API проверяет ёмкость в транзакции с advisory-lock. Если места не осталось,
вернётся 409 slot_taken. Правильная реакция — заново запросить
GET /slots и предложить клиенту другое время.
Сеть оборвалась во время создания
Повторите тот же запрос с тем же Idempotency-Key. Если первый
запрос успел создать бронь, вы получите 200 с тем же
booking_ref и заголовком Idempotent-Replayed: true.
Клиент не пришёл
Через no_show_grace_minutes после времени записи бронь
автоматически переходит в cancelled (cron каждую минуту).
До этого её можно вызвать или отменить вручную.
Клиент позвонил и отказался
POST /api/queue/booking/{booking_ref}/cancel с
{"reason": "..."}. Отмена сразу обновляет экраны по WebSocket.
Нужно перенести запись
POST /api/queue/booking/{booking_ref}/reschedule. При переносе
на другой день номер талона перевыпускается из счётчика нового дня, чтобы
не совпасть с номером клиента, который пришёл без записи.