Как это работает
- Витрина вызывает метод, который начинает сессию (например, вход). В ответе приходит заголовок
X-Session-Id. - Витрина сохраняет значение (в
localStorageили в памяти приложения) и передаёт его заголовкомX-Session-Idво все следующие запросы. - Запросы без заголовка сессию не создают и не получают: гость, который только читает каталог, остаётся без сессии.
В теле ответа идентификатора сессии нет.
Какие методы начинают сессию
Только те, что меняют состояние сессии:
- вход и выход:
POST /api/auth/login,loginByCode,loginByYandex,loginByVK,register,resendCode,confirm,logout; - корзина и заказ:
POST /api/sale/basket,basket/batch,setLocation,setDelivery,basketCoupon,order/refresh,order/save,DELETE /api/sale/basketCoupon; - списки:
POST /api/list(избранное, сравнение); - запись в инфоблок:
POST /api/iblock/{код}/elements; - формы:
POST /api/service/webForm,POST /api/service/subscribe.
В документации API у таких методов есть строка «Начинает сессию: ID приходит в заголовке ответа X-Session-Id».
Пример: вход и запрос с сессией
curl -i -X POST "https://example.ru/api/auth/login" \
-H "Content-Type: application/json" \
-d '{"username": "user@example.ru", "password": "secret"}' В заголовках ответа:
HTTP/1.1 200 OK
X-Session-Id: JLfAjGOFZ3qb2elyU2VIxlhvt1kYjQMZ
Access-Control-Expose-Headers: X-Session-Id Дальше витрина передаёт его заголовком:
curl "https://example.ru/api/user" -H "X-Session-Id: JLfAjGOFZ3qb2elyU2VIxlhvt1kYjQMZ" Допустимое значение — 16–128 символов из A-Z a-z 0-9 , -. Неподходящее значение равносильно отсутствию заголовка. Истёкший или неизвестный идентификатор не принимается: сервер выдаёт новую сессию и пишет данные только в неё, поэтому витрине нужно всегда сохранять X-Session-Id из ответов методов, начинающих сессию.
В Swagger идентификатор вводится один раз кнопкой «Authorize» (схема apiKey в заголовке X-Session-Id).
Единый 401
Методы только для вошедших пользователей (GET/POST/DELETE /api/user, /api/profile, заказы, изменение и удаление своих элементов инфоблока) отвечают гостю одинаково: HTTP 401 и тело
{
"success": false,
"error": "Требуется авторизация"
} Проверка выполняется до разбора параметров: гость получает 401, а не 400 за пропущенный параметр. Витрина смотрит на статус 401 и показывает форму входа, текст ошибки читает из поля error. Метод, выключенный настройками инфоблока (запись), по-прежнему отвечает 404 «Не найдено» — он проверяется раньше.
CORS
Если витрина работает на другом домене, браузер запрашивает у API разрешение. Список сайтов задаётся на вкладке «Основное»: «Сайты, с которых разрешены запросы к API из браузера» (по строке на сайт, со схемой, без слэша в конце), а «Адрес основной витрины» разрешён всегда.
Допустимы маски:
| Запись | Что разрешает |
|---|---|
https://example.ru | ровно этот адрес |
https://*.example.ru | любой поддомен, но не сам example.ru |
http://localhost:* | любой порт локальной разработки |
Звёздочка заменяет только целую метку поддомена или порт. Слишком широкие маски (*, https://*, https://*.ru) настройки не сохранят и покажут ошибку. Для разрешённого сайта API отвечает заголовками:
Access-Control-Allow-Origin: http://localhost:3000
Access-Control-Allow-Credentials: true
Access-Control-Allow-Headers: X-Token, Origin, Content-Type, X-Auth-Token, Accept, api_key, Authorization, X-Session-Id
Access-Control-Expose-Headers: X-Session-Id Access-Control-Expose-Headers нужен, чтобы браузер отдал витрине заголовок X-Session-Id из ответа. Если заголовки CORS выставляет nginx, добавьте туда X-Session-Id в Allow-Headers и Expose-Headers. Маски хостов для картинок — в теме Настройки модуля.
Что почитать после сессии
- Быстрый старт
- Запись в инфоблок через API: создание элементов гостем и пользователем.
- Личные данные в инфоблоке:
own=Y.