Подключение, авторизация и ошибки

Адрес API выбирает конфигурация приложения для нужного окружения. Все пути ниже начинаются с /api/; используйте HTTPS. Поля запросов и объявленные ответы находятся в справочнике и OpenAPI.

Авторизация

Покупатель запрашивает OTP через /api/auth/otp/send и подтверждает его через /api/auth/otp/confirm. Подтверждение возвращает JWT. Проверка /api/auth/otp/verify сама по себе JWT не выдаёт. Требования к регистрации нового пользователя указаны в схеме подтверждения.

Авторизованные запросы передают Authorization: Bearer <ACCESS_TOKEN>. Для обновления токена предусмотрен /api/token/refresh. После 401 допускается одна попытка обновления и один повтор исходного запроса. Не запускайте бесконечный цикл refresh. Восстановление PIN использует отдельный X-Recovery-Key.

Отсутствие JWT допустимо только для операций с анонимным доступом. Необязательная авторизация не означает разрешение анонимно изменять заказы или профиль. Сборщик использует отдельный вход и токены; его 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 обязательность ключа зависит от настройки сервера; клиенту следует всегда передавать его и сохранять при повторах.

Версия: 8541d2c2730bee129f6fe6ea94c29878721733e8 · PROD. Markdown