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

Ошибки и типовые ситуации

Все ошибки — JSON вида { "error": "текст", "code": "машинный_код" }.

Примеры в документации используют основной домен https://timira.ru. В рабочей интеграции замените его на внешний IP или домен установки клиента; путь /api/queue/booking не меняется.
HTTPcodeКогда возникаетЧто делать
400invalid_scheduled_atНе передано или не разобрано времяПередайте ISO со смещением либо date+time
400slot_in_pastДо слота меньше min_lead_minutesВыберите слот позже
400slot_not_alignedВремя не попадает в сеткуБерите время из GET /slots
400slot_outside_work_hoursВремя вне рабочих часовИспользуйте слоты из ответа GET /slots
400day_closedПраздник/выходнойВыберите рабочий день
400date_in_past / date_too_farДата вне разрешённого диапазонаСоблюдайте max_days_ahead
400contact_requiredНет телефона и e-mail при включённом требованииПередайте контакт клиента
400invalid_customerНекорректный e-mailПроверьте формат
401api_key_requiredНет заголовка с ключомПередайте X-API-Key
401invalid_api_keyКлюч не найден или отозванПроверьте ключ в админке
401api_key_expiredИстёк срок действияВыпустите новый ключ или продлите срок
403scope_deniedУ ключа нет нужного праваДобавьте scope ключу
403queue_forbidden / service_forbiddenУслуга вне разрешённых ключуРасширьте ограничения ключа
403test_disabledПесочница выключенаИспользуйте live-ключ или включите тестовый режим
404booking_not_foundНет брони с таким booking_ref (или она чужая)Проверьте код и владельца ключа
409slot_takenМест на слот больше нетВыберите другой слот
409call_too_earlyПопытка вызвать бронь раньше окна вызоваДождитесь scheduled_at − call_before_minutes
409booking_not_activeОтмена/перенос неактивной брониПроверьте status
409idempotency_in_progressПовтор, пока первый запрос ещё выполняетсяПовторите через секунду
422idempotency_conflictТот же Idempotency-Key, другое телоИспользуйте новый ключ
429rate_limitedБольше 60 запросов/минПовторите после Retry-After
503booking_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. При переносе на другой день номер талона перевыпускается из счётчика нового дня, чтобы не совпасть с номером клиента, который пришёл без записи.

Если ошибка повторяется, приложите X-Request-Id из ответа и время запроса.