Разделы — по тегам спецификации. У каждого эндпоинта: параметры, тело запроса
(если есть) и коды ответов. Всё это сгенерировано из того же
openapi.yaml, который проверяется в тестах.
Каталог и витрина
5 · тег catalog
GET
/v1/shop
Настройки магазина
Название, валюта, контакты, тема, меню опубликованных страниц. Внутренние
настройки (например, список разрешённых CORS-источников) наружу не отдаются.
Параметры
| Имя |
Где |
Тип |
Описание |
If-None-Match
|
header |
string |
|
Ответы
200 data.shop — настройки магазина
304 Ресурс не изменился: If-None-Match совпал с ETag, тело пустое
GET
/v1/categories
Дерево категорий
Только активные категории, вложенность — в children.
Параметры
| Имя |
Где |
Тип |
Описание |
If-None-Match
|
header |
string |
|
Ответы
200 data.categories — корневые узлы дерева
304 Ресурс не изменился: If-None-Match совпал с ETag, тело пустое
GET
/v1/products
Список товаров
Только опубликованные товары (status=active). Ответы кэшируемые: есть
ETag и Cache-Control: public, max-age=60, повторный запрос с
If-None-Match вернёт 304.
Параметры
| Имя |
Где |
Тип |
Описание |
q
|
query |
string |
Поиск по названию, артикулу и бренду |
category
|
query |
string |
ID категории, включая подкатегории |
sort
|
query |
string (new, old, name, price_asc, price_desc, stock_asc) |
Неизвестное значение означает «сначала новые» |
stock
|
query |
string (in, out) |
Наличие: in — есть, out — закончился |
min_price
|
query |
number |
Нижняя граница цены; нечисло игнорируется |
max_price
|
query |
number |
Верхняя граница цены; нечисло игнорируется |
page
|
query |
integer |
|
per_page
|
query |
integer |
|
If-None-Match
|
header |
string |
ETag предыдущего ответа |
Ответы
200 Страница каталога; meta.pagination содержит page/per_page/total/pages
304 Ресурс не изменился: If-None-Match совпал с ETag, тело пустое
GET
/v1/products/{slug}
Карточка товара
Параметры
| Имя |
Где |
Тип |
Описание |
slug
обязательный
|
path |
string |
|
If-None-Match
|
header |
string |
ETag предыдущего ответа |
Ответы
200 Товар; meta.schema_version — версия схемы магазина
304 Ресурс не изменился: If-None-Match совпал с ETag, тело пустое
404 Ошибка
GET
/v1/pages/{slug}
Статическая страница магазина
Доставка, возврат, гарантии. Только опубликованные.
Параметры
| Имя |
Где |
Тип |
Описание |
slug
обязательный
|
path |
string |
|
If-None-Match
|
header |
string |
|
Ответы
200 data.page — страница с title, body и seo
304 Ресурс не изменился: If-None-Match совпал с ETag, тело пустое
404 Ошибка
Корзина
6 · тег cart
GET
/v1/cart
Текущая корзина
Корзина живёт в Redis и привязана к магазину. Идентификатор приходит
заголовком X-Cart-Id (приоритет), параметром cart_id или cookie —
если клиент браузерный и работает через нашу витрину. Если идентификатор
отсутствует или невалиден, API создаёт новую корзину и возвращает её
номер в заголовке ответа X-Cart-Id: его нужно сохранить.
Параметры
| Имя |
Где |
Тип |
Описание |
X-Cart-Id
|
header |
string |
Идентификатор корзины (32 hex-символа). Предпочтительный способ для
приложений и внешних фронтов: не зависит от cookie и не требует менять
тело запроса. Ответ всегда содержит этот заголовок — с актуальным
идентификатором, включая случай, когда корзина только что создана. |
cart_id
|
query |
string |
32 hex-символа |
Ответы
200 Успешный ответ
DELETE
/v1/cart
Очистить корзину
Параметры
| Имя |
Где |
Тип |
Описание |
X-Cart-Id
|
header |
string |
Идентификатор корзины (32 hex-символа). Предпочтительный способ для
приложений и внешних фронтов: не зависит от cookie и не требует менять
тело запроса. Ответ всегда содержит этот заголовок — с актуальным
идентификатором, включая случай, когда корзина только что создана. |
cart_id
|
query |
string |
|
Ответы
200 Успешный ответ
POST
/v1/cart/validate
Проверить корзину перед оформлением
Один булев ответ data.valid: есть ли позиции и нет ли у них причин
быть недоступными (товар снят с продажи, не хватает остатка). Правило
живёт в API, чтобы приложение и тема не расходились в трактовке.
Параметры
| Имя |
Где |
Тип |
Описание |
X-Cart-Id
|
header |
string |
Идентификатор корзины (32 hex-символа). Предпочтительный способ для
приложений и внешних фронтов: не зависит от cookie и не требует менять
тело запроса. Ответ всегда содержит этот заголовок — с актуальным
идентификатором, включая случай, когда корзина только что создана. |
Ответы
200 Успешный ответ
POST
/v1/cart/items
Добавить товар в корзину
Параметры
| Имя |
Где |
Тип |
Описание |
X-Cart-Id
|
header |
string |
Идентификатор корзины (32 hex-символа). Предпочтительный способ для
приложений и внешних фронтов: не зависит от cookie и не требует менять
тело запроса. Ответ всегда содержит этот заголовок — с актуальным
идентификатором, включая случай, когда корзина только что создана. |
Тело запроса (обязательно)
| Поле |
Тип |
Описание |
slug
обязательное
|
string |
|
sku
|
string |
Артикул варианта. Обязателен, если у товара есть варианты |
qty
|
integer |
|
cart_id
|
string |
Альтернатива заголовку X-Cart-Id |
Ответы
200 Успешный ответ
400 Ошибка
PATCH
/v1/cart/items/{slug}
Изменить количество
Для товара с вариантами нужен sku: у одного товара может быть несколько
строк корзины («Размер M» и «Размер L»). Если sku не передан, а строк с
этим slug несколько, API вернёт 400 — иначе непонятно, какую менять.
Параметры
| Имя |
Где |
Тип |
Описание |
slug
обязательный
|
path |
string |
|
X-Cart-Id
|
header |
string |
Идентификатор корзины (32 hex-символа). Предпочтительный способ для
приложений и внешних фронтов: не зависит от cookie и не требует менять
тело запроса. Ответ всегда содержит этот заголовок — с актуальным
идентификатором, включая случай, когда корзина только что создана. |
Тело запроса (обязательно)
| Поле |
Тип |
Описание |
qty
обязательное
|
integer |
|
sku
|
string |
Артикул варианта |
cart_id
|
string |
|
Ответы
200 Успешный ответ
400 Ошибка
DELETE
/v1/cart/items/{slug}
Убрать товар из корзины
Параметры
| Имя |
Где |
Тип |
Описание |
slug
обязательный
|
path |
string |
|
X-Cart-Id
|
header |
string |
Идентификатор корзины (32 hex-символа). Предпочтительный способ для
приложений и внешних фронтов: не зависит от cookie и не требует менять
тело запроса. Ответ всегда содержит этот заголовок — с актуальным
идентификатором, включая случай, когда корзина только что создана. |
cart_id
|
query |
string |
|
sku
|
query |
string |
Артикул варианта |
Ответы
200 Успешный ответ
Заказы
5 · тег orders
GET
/v1/delivery/points
Пункты выдачи магазина
Активные пункты выдачи — для витрины, приложения и чужого фронта. Список
одинаков для всех покупателей, поэтому ответ кэшируемый (ETag,
Cache-Control). Пока договоров с перевозчиками нет, список заполняет
селлер: вручную или выгрузкой из личного кабинета перевозчика.
method — код способа получения (pickup, courier, pvz, ozon,
wb, post, cdek).
Параметры
| Имя |
Где |
Тип |
Описание |
method
|
query |
string |
Код способа получения |
city
|
query |
string |
|
If-None-Match
|
header |
string |
|
Ответы
200 data.points — точки, data.cities — города, где они есть
304 Ресурс не изменился: If-None-Match совпал с ETag, тело пустое
404 Ошибка
POST
/v1/delivery/quote
Стоимость доставки
Цена считается на сервере: витрина показывает результат, а сумма заказа
всё равно пересчитывается при создании. Если передан point_id, город
берётся из точки — прислать чужой адрес нельзя.
Тело запроса (обязательно)
Схема:
DeliveryQuoteInput
| Поле |
Тип |
Описание |
method
обязательное
|
string |
Код способа получения |
cart_id
|
string |
Корзина: сумма товаров берётся из неё |
items_total
|
integer |
Сумма товаров в копейках, если корзины нет |
city
|
string |
|
region
|
string |
|
point_id
|
integer |
Пункт выдачи: город и регион берутся из него |
Ответы
200 Успешный ответ
400 Ошибка
POST
/v1/orders
Оформить заказ
Требует заголовок Idempotency-Key. Повторная отправка с тем же ключом
возвращает тот же заказ и не создаёт дубль — защита от двойного нажатия
«Оплатить» и от ретраев на плохой связи.
Если покупатель вошёл (X-Customer-Session), заказ привязывается к
аккаунту и появляется в личном кабинете. Без входа заказ работает как
раньше: аккаунт — удобство, а не входной билет.
В ответе приходит access_token — пропуск к странице «спасибо». Без него
GET /v1/orders/{number} отвечает 404: номер заказа человекочитаем и
сам по себе доступа к данным покупателя не даёт.
Параметры
| Имя |
Где |
Тип |
Описание |
Idempotency-Key
обязательный
|
header |
string |
|
X-Customer-Session
|
header |
string |
Необязателен |
Тело запроса (обязательно)
Схема:
OrderInput
| Поле |
Тип |
Описание |
customer
обязательное
|
object |
Нужен e-mail или телефон — иначе некуда сообщить о заказе. |
delivery
обязательное
|
object |
|
payment
|
object |
Способ оплаты. Проверяется по настройкам магазина так же, как
доставка; при пустом значении берётся первый доступный. |
consent
обязательное
|
boolean |
Согласие на обработку персональных данных. Обязательно: без него
заказ отклоняется (422, fields.consent). Собирать имя, телефон и
адрес без согласия нельзя, поэтому это условие заказа, а не поле
«для галочки». |
promo
|
string |
Промокод. Необязателен; регистр не важен. Если код не действует,
заказ отклоняется (400, fields.promo), а не создаётся без скидки. |
source
|
string |
UTM-source с рекламной ссылки (instagram, vk, email). Нужен
только отчёту магазина «откуда пришли заказы»; пусто — прямой заход. |
Ответы
201 Успешный ответ
400 Ошибка
409 Ошибка
GET
/v1/orders/{number}
Заказ по номеру
Заказ отдаётся только вместе с токеном доступа из ссылки «спасибо»
(POST /v1/orders → access_token, письмо покупателю, возврат от
провайдера оплаты).
Номер заказа (ORD-XXXXXXXXXX) человекочитаем: его диктуют по телефону
и показывают на скриншотах, поэтому сам по себе он доступа не даёт.
Без верного токена ответ — 404, а не 403: иначе перебор номеров
превращается в проверку «такой заказ существует», а в заказе лежат
имя, телефон, e-mail и адрес доставки покупателя.
Параметры
| Имя |
Где |
Тип |
Описание |
number
обязательный
|
path |
string |
|
t
обязательный
|
query |
string |
Токен доступа из ссылки «спасибо» |
X-Order-Token
|
header |
string |
Тот же токен заголовком — для клиентов, которые не хотят носить секрет в адресе |
Ответы
200 Успешный ответ
404 Ошибка
POST
/v1/payments/{provider}/webhook
Уведомление платёжного провайдера
Вызывает провайдер, а не покупатель. Подпись проверяет расширение
провайдера, ядро сверяет сумму с заказом и ставит статус оплаты —
поэтому ошибка в разборе уведомления не может «оплатить» чужой заказ.
Магазин определяется заголовком Host (адрес витрины): у каждого
магазина свой адрес уведомлений, и провайдеру не нужно знать слаги.
Ответ 200 — уведомление принято, в том числе повторное: обработка
идемпотентна по паре (провайдер, external_id). 404 — подпись не
сошлась, уведомление не распознано или провайдер не подключён: на такой
запрос провайдер повторит доставку, и это правильно.
Параметры
| Имя |
Где |
Тип |
Описание |
provider
обязательный
|
path |
string |
Код расширения-провайдера |
Тело запроса (обязательно)
Ответы
200 Успешный ответ
404 Ошибка
reviews
2 · тег reviews
GET
/v1/products/{slug}/reviews
Отзывы товара
Только опубликованные отзывы: непроверенные видит селлер в кабинете, а
не покупатель. Ответ кэшируемый — ETag и Cache-Control: public,
max-age=60; повторный запрос с If-None-Match вернёт 304.
Параметры
| Имя |
Где |
Тип |
Описание |
slug
обязательный
|
path |
string |
|
limit
|
query |
integer |
|
If-None-Match
|
header |
string |
ETag предыдущего ответа |
Ответы
200 data.items — отзывы (свежие первыми), data.summary — средняя оценка и распределение
304 Ресурс не изменился: If-None-Match совпал с ETag, тело пустое
404 Ошибка
POST
/v1/reviews
Оставить отзыв
Отзыв создаётся в статусе «на проверке» и попадает на витрину после
решения селлера. Повторный отзыв с того же адреса о том же товаре в
течение 10 минут считается дублем (409), а частые отправки
ограничены лимитом (429).
Тело запроса (обязательно)
Схема:
ReviewInput
| Поле |
Тип |
Описание |
product
обязательное
|
string |
Slug товара |
rating
обязательное
|
integer |
|
author
обязательное
|
string |
Как подписать отзыв |
body
обязательное
|
string |
|
email
|
string |
Необязателен и никогда не публикуется |
website
|
string |
Honeypot: человек его не видит и не заполняет |
Ответы
201 Отзыв создан; pending=true — ждёт проверки
400 Ошибка
404 Ошибка
409 Ошибка
429 Ошибка
account
13 · тег account
POST
/v1/auth/register
Регистрация покупателя
Аккаунт нужен для истории заказов и отзывов, но не для покупки.
Пароль хранится только хэшем (argon2id). Повторная регистрация на тот
же e-mail — 409: без подтверждения почты «тихий вход» был бы захватом
аккаунта.
Тело запроса (обязательно)
| Поле |
Тип |
Описание |
email
обязательное
|
string |
|
password
обязательное
|
string |
|
password_repeat
|
string |
Если передан — должен совпадать |
name
обязательное
|
string |
|
Ответы
201 Аккаунт создан; session.sid передаётся далее в X-Customer-Session
400 Ошибка
409 Ошибка
429 Ошибка
POST
/v1/auth/login
Вход покупателя
Неверный e-mail и неверный пароль дают один и тот же ответ 401:
иначе форма входа показывает, зарегистрирован ли адрес в магазине.
Тело запроса (обязательно)
| Поле |
Тип |
Описание |
email
обязательное
|
string |
|
password
обязательное
|
string |
|
Ответы
200 Сессия создана: session.sid и CSRF-токен
400 Ошибка
401 Ошибка
429 Ошибка
POST
/v1/auth/verify-email
Подтвердить e-mail
Покупатель приходит по ссылке из письма, витрина передаёт токен сюда.
Токен не хранится: он подписан (HMAC) и живёт сутки. До подтверждения
GET /v1/account/orders отвечает 403: гостевая строка с заказами могла
достаться тому, кто просто знает чужой e-mail.
Тело запроса (обязательно)
| Поле |
Тип |
Описание |
token
обязательное
|
string |
|
Ответы
200 Успешный ответ
400 Ошибка
POST
/v1/auth/resend-verification
Отправить письмо подтверждения заново
Только для вошедшего покупателя: адрес берётся из сессии, поэтому запрос
не превращается в генератор писем на любой чужой адрес. Если адрес уже
подтверждён, письмо не отправляется, но ответ остаётся 200.
Параметры
| Имя |
Где |
Тип |
Описание |
X-Customer-Session
обязательный
|
header |
string |
|
Ответы
200 Успешный ответ
401 Ошибка
429 Ошибка
POST
/v1/auth/password/forgot
Запрос письма для смены пароля
Ответ всегда 200, даже если такого адреса нет: иначе форма
превращается в проверялку «зарегистрирован ли покупатель». Письмо
ставится в очередь и приходит только владельцу аккаунта с паролем.
Тело запроса (обязательно)
| Поле |
Тип |
Описание |
email
обязательное
|
string |
|
Ответы
200 Успешный ответ
429 Ошибка
POST
/v1/auth/password/reset
Смена пароля по ссылке из письма
Токен действует час и подписан назначением «reset»: ссылка из письма
«подтвердите адрес» здесь не подойдёт. После смены закрываются **все**
сессии покупателя — иначе украденная cookie пережила бы сброс.
Тело запроса (обязательно)
| Поле |
Тип |
Описание |
token
обязательное
|
string |
Из адреса /reset?token=… |
password
обязательное
|
string |
|
password_repeat
|
string |
Если передан — должен совпадать |
Ответы
200 Успешный ответ
400 Ошибка
429 Ошибка
POST
/v1/auth/logout
Выход
Удаляет сессию в Redis. Идемпотентен: повторный выход — тоже 200.
Параметры
| Имя |
Где |
Тип |
Описание |
X-Customer-Session
|
header |
string |
Идентификатор сессии |
Ответы
200 Успешный ответ
GET
/v1/account/orders
Мои заказы
Заказы, оформленные с этого аккаунта, свежие первыми. Ответ
персональный: Cache-Control: private, no-store, поэтому промежуточный
кэш его не сохранит.
403 — адрес не подтверждён: гостевая строка customers с заказами
могла достаться тому, кто знает чужой e-mail.
Параметры
| Имя |
Где |
Тип |
Описание |
X-Customer-Session
обязательный
|
header |
string |
|
Ответы
200 data.items — заказы со статусом и готовой подписью статуса
401 Ошибка
403 Ошибка
GET
/v1/account/reviews
Мои отзывы
Отзывы, оставленные под аккаунтом, — включая те, что ещё на проверке:
покупатель должен видеть, что отзыв дошёл.
Параметры
| Имя |
Где |
Тип |
Описание |
X-Customer-Session
обязательный
|
header |
string |
|
Ответы
200 data.items — отзывы с любым статусом
401 Ошибка
GET
/v1/account
Кто вошёл
Данные аккаунта и CSRF-токен для форм личного кабинета.
Параметры
| Имя |
Где |
Тип |
Описание |
X-Customer-Session
обязательный
|
header |
string |
|
Ответы
200 data.customer — аккаунт, data.csrf — токен формы
401 Ошибка
GET
/v1/wishlist
Избранное вошедшего покупателя
Список привязан к аккаунту и доступен на всех устройствах. Гостевое
избранное живёт в cookie; при входе фронт сливает его через
/v1/wishlist/merge. Ответ персональный: Cache-Control: private, no-store.
Параметры
| Имя |
Где |
Тип |
Описание |
X-Customer-Session
обязательный
|
header |
string |
|
Ответы
200 data.items — товары, data.slugs — их slug, data.count — количество
401 Ошибка
POST
/v1/wishlist/toggle
Добавить или убрать товар из избранного
Параметры
| Имя |
Где |
Тип |
Описание |
X-Customer-Session
обязательный
|
header |
string |
|
Тело запроса (обязательно)
| Поле |
Тип |
Описание |
slug
обязательное
|
string |
|
Ответы
200 Обновлённые data.items, data.slugs и data.count
401 Ошибка
404 Ошибка
POST
/v1/wishlist/merge
Слить гостевое избранное с аккаунтом
Вызывается фронтом после входа/регистрации; неизвестные и снятые товары игнорируются.
Параметры
| Имя |
Где |
Тип |
Описание |
X-Customer-Session
обязательный
|
header |
string |
|
Тело запроса (обязательно)
| Поле |
Тип |
Описание |
slugs
|
array<string> |
|
Ответы
200 Объединённый список: data.items, data.slugs, data.count
401 Ошибка