# Подключение, авторизация и ошибки Адрес API выбирает конфигурация приложения для нужного окружения. Все пути ниже начинаются с `/api/`; используйте HTTPS. Поля запросов и объявленные ответы находятся в [справочнике](reference.md) и [OpenAPI](openapi.json). ## Авторизация Покупатель запрашивает OTP через `/api/auth/otp/send` и подтверждает его через `/api/auth/otp/confirm`. Подтверждение возвращает JWT. Проверка `/api/auth/otp/verify` сама по себе JWT не выдаёт. Требования к регистрации нового пользователя указаны в схеме подтверждения. Авторизованные запросы передают `Authorization: Bearer `. Для обновления токена предусмотрен `/api/token/refresh`. После `401` допускается одна попытка обновления и один повтор исходного запроса. Не запускайте бесконечный цикл refresh. Восстановление PIN использует отдельный `X-Recovery-Key`. Отсутствие JWT допустимо только для операций с анонимным доступом. Необязательная авторизация не означает разрешение анонимно изменять заказы или профиль. Сборщик использует [отдельный вход и токены](picker.md); его JWT не заменяет покупательский токен. ## Магазин и язык Передавайте `X-Store-Id` с идентификатором выбранного магазина в запросах каталога, расчёта и оформления заказа. Без заголовка backend может выбрать основной магазин; клиенту следует задавать контекст явно. При смене магазина пересчитайте корзину. Магазин активной сборки определяется серверной сессией сборщика. Для русского содержания используйте `Accept-Language: ru`. Кэш каталога разделяйте по магазину и языку. Токены, платёжные ссылки, адреса, телефоны и полные тела пользовательских запросов не должны попадать в публичные примеры и журналы. ## Ошибки и повтор запросов `detail` может быть строкой или списком ошибок валидации с `loc`, `msg`, `type`. Если есть `code`, выбирайте поведение по нему, а пользователю показывайте локализованное сообщение. Неизвестный код должен обрабатываться без сбоя клиента. Picker дополнительно может вернуть актуальный `session` и задержку повтора. - `400` и `422`: исправьте запрос; автоматический повтор того же тела не поможет. - `401` и `403`: восстановите вход либо покажите отсутствие доступа. - `404`: объект недоступен; не пытайтесь определить владельца по ответу. - `409`: перечитайте состояние и разрешите конфликт; это не подтверждение успеха. - `429`, `502`, `503` и сетевые ошибки: применяйте ограниченные повторы с растущей задержкой и учитывайте `Retry-After`, если он присутствует. Для создания заказа и изменяющих picker-команд сохраните `Idempotency-Key` до отправки. Повтор неизвестного результата использует тот же ключ и то же тело. Новый ключ создаётся для нового действия. `IDEMPOTENCY_CONFLICT` требует остановить автоматические повторы. Для остальных изменяющих операций не предполагайте наличие идемпотентности: сначала проверьте контракт и актуальное состояние. Признак обязательности в OpenAPI отражает декларацию параметра. Picker проверяет наличие корректного ключа внутри обработчика, хотя схема заголовка может показывать его как необязательный. Для checkout обязательность ключа зависит от настройки сервера; клиенту следует всегда передавать его и сохранять при повторах.