Подключение, авторизация и ошибки
Адрес 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 обязательность ключа зависит от настройки сервера; клиенту следует всегда передавать его и сохранять при повторах.
Версия: a0f83a6f89d582854b126a89a7623bb1d484a004 · TEST. Markdown