Публичный API · OpenAPI 1.0.0

API Ezerbox

Каталог, корзина и заказы по HTTP. Это тот же API, на котором работает наша витрина: если он сломается — витрина сломается тоже. Поэтому контракт здесь не «примерный», а настоящий: его проверяет тест на каждом прогоне.

  • 32 эндпоинтов
  • JSON · {data, meta, error}
  • ETag и 304 на чтение
  • CORS по магазину
  • 19 схем

Как начать

Магазин определяется доменом: один и тот же API обслуживает все витрины, а какой именно — решает Host. Поэтому базовый адрес — поддомен магазина, а не общий эндпоинт с идентификатором в пути.

Базовый адрес: https://demo.ezerbox.com

Покупательские вызовы (каталог, корзина, заказ) авторизации не требуют: витрина не должна заставлять регистрироваться, чтобы купить. Управление каталогом и заказами живёт в кабинете селлера и в публичный контракт не входит.

Каталог и магазин

curl -s https://demo.ezerbox.com/v1/shop
curl -s https://demo.ezerbox.com/v1/categories
curl -s "https://demo.ezerbox.com/v1/products?sort=price_asc&stock=in&per_page=24"
curl -s https://demo.ezerbox.com/v1/products/kruzhka-termo-400

Корзина без cookie

Идентификатор корзины — 32 hex-символа. Его принимает заголовок X-Cart-Id (приоритет), поле cart_id в теле или параметр запроса, а ответ всегда возвращает актуальный X-Cart-Id. Cookie не нужен: так корзиной пользуется мобильное приложение.

curl -s -X POST https://demo.ezerbox.com/v1/cart/items \
  -H 'Content-Type: application/json' \
  -H 'X-Cart-Id: 0123456789abcdef0123456789abcdef' \
  -d '{"slug": "kruzhka-termo-400", "qty": 1}'

curl -s -X POST https://demo.ezerbox.com/v1/cart/validate \
  -H 'X-Cart-Id: 0123456789abcdef0123456789abcdef'

Заказ

Idempotency-Key обязателен: двойное нажатие «Оформить» и ретрай в плохой сети не должны создавать второй заказ. Повтор с тем же ключом вернёт тот же заказ и meta.duplicate = true.

curl -s -X POST https://demo.ezerbox.com/v1/orders \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 6f1c4d2a-7f0e-4a53-9b3e-2f5f0f6a1c11' \
  -d '{
    "cart_id": "0123456789abcdef0123456789abcdef",
    "customer": {"name": "Иван", "phone": "+7 900 000-00-00"},
    "delivery": {"method": "pickup"}
  }'

Что важно знать заранее

  • Деньги — строкой с двумя знаками: "1290.00". Число с плавающей точкой в деньгах — источник расхождений.
  • Чтение кэшируется клиентом: ETag и Cache-Control, повторный запрос с If-None-Match отдаёт 304.
  • Лимит — token bucket в Redis: при превышении 429, Retry-After и code: rate_limited.
  • Ошибка всегда в конверте {data: null, meta, error: {code, message, fields?, request_id}}.
Публичный JSON API магазина. Один и тот же бэкенд обслуживает все витрины:
какой магазин отвечает, определяется доменом (acme.example.com) или
заголовком X-Tenant (только с internal-токеном).

Контракт версионируется префиксом пути: /v1. Изменения внутри v1 —
только аддитивные (новые поля, новые эндпоинты). Удаление или смена
семантики — это /v2.

Деньги передаются строкой с двумя знаками ("1290.00"), а не числом:
float в денежных расчётах — источник ошибок округления.

Эндпоинты

Разделы — по тегам спецификации. У каждого эндпоинта: параметры, тело запроса (если есть) и коды ответов. Всё это сгенерировано из того же 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 Ошибка

Сервисные проверки

1 · тег service

GET /health

Живость процесса

Публичный liveness: только {"status":"ok"}. Диагностика (env, лаг
event loop, воркеры, карта зависимостей) и readiness живут на
internal-слушателе под X-Internal-Token и наружу не публикуются.
Ответы

200 Успешный ответ

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 Ошибка

Схемы

Общие объекты контракта. Ссылки на них есть в описании эндпоинтов, а полностью — в спецификации.

Envelope

Поле Тип Описание
data обязательное any
meta обязательное Meta
error Error

Meta

Поле Тип Описание
request_id string
schema_version integer
pagination object

Error

Поле Тип Описание
code обязательное string Машиночитаемый код: not_found, validation_failed, rate_limited и т. п.
message обязательное string
fields object
request_id string

Product

Товар магазина

Поле Тип Описание
id обязательное string
slug обязательное string
name обязательное string
description string|null
price обязательное string Строка с двумя знаками, например 1290.00
old_price string|null
currency обязательное string Код ISO-4217
status обязательное string (draft, active, archived)
stock integer
kind string (goods, service) Вид позиции. В публичном списке /v1/products только goods
service object Параметры услуги; у товара значения null
sku string|null
brand string|null
category_id string|null
rating string|null Средняя оценка опубликованных отзывов («4.50»); null — отзывов нет
rating_count integer Число опубликованных отзывов
images array<string> Ключи объектов в хранилище (1200x1200 WebP). Понимает только наша медиа-раздача
thumbs array<string> Ключи превью 300x300
image_urls array<string> Готовые адреса картинок — их и нужно показывать клиенту
thumb_urls array<string> Готовые адреса превью
gallery array<object> Картинки по порядку показа, с id (нужен кабинету для управления)
seo object
weight string|null Вес в килограммах строкой: 0.500
dimensions object Габариты в сантиметрах (для расчёта доставки)
options array<object> Параметры товара с произвольными названиями («Размер», «Цвет»,
«Ёмкость накопителя»). Пусто — обычный товар без вариантов.
variants array<ProductVariant> Комбинации параметров. В списке товаров пусто — там есть has_variants и price_from
has_variants boolean У товара есть параметры: витрине нужно показать выбор
price_from string|null Минимальная цена среди вариантов — для «от N ₽» в каталоге
specs array<object> Характеристики товара: «Материал», «Страна», «Гарантия». Плоский
список в порядке, заданном продавцом. Незаполненные характеристики
сюда не попадают — на витрине их нет вовсе.

ProductVariant

Вариант товара: конкретная комбинация параметров со своей ценой и остатком

Поле Тип Описание
id обязательное string
sku обязательное string Артикул варианта, уникален в пределах товара
name string|null Название варианта, обычно пусто
price обязательное string Цена варианта строкой; пустая цена варианта заменена ценой товара
old_price string|null
stock обязательное integer
options обязательное object Снимок выбранных значений: {"Размер": "M"}
is_active boolean Вариант в продаже; выключенный не показывается на витрине
image string|null Ключ картинки варианта в хранилище
image_url string|null Готовый адрес картинки варианта

CartItem

Поле Тип Описание
slug обязательное string
sku string|null Артикул варианта; null — обычный товар
variant_name string|null «Размер: M · Цвет: синий» для показа в корзине
options object Выбранные параметры варианта
name обязательное string
price обязательное string
qty обязательное integer
sum обязательное string
stock integer
available boolean
image string|null
thumb string|null
image_url string|null Готовый адрес картинки
thumb_url string|null Готовый адрес превью
issue string|null Причина, по которой позиция недоступна

Cart

Поле Тип Описание
id обязательное string
items обязательное array<CartItem>
total обязательное string
currency обязательное string
count обязательное integer
issues array<string>

DeliveryPoint

Пункт выдачи магазина. Пока договоров с перевозчиками нет, это данные
селлера: он вносит адреса вручную или выгрузкой из личного кабинета.
Колонка external_id держит код пункта у перевозчика, поэтому при
появлении API те же строки начнут обновляться синхронизацией.

Поле Тип Описание
id integer
method string Код способа получения
method_title string Подпись способа для списка
external_id string Код пункта у перевозчика; пусто — свой пункт
title string
address string
city string
region string
lat string|null Широта строкой: без потери точности
lon string|null
work_hours string
is_active boolean

DeliveryQuoteInput

Поле Тип Описание
method обязательное string Код способа получения
cart_id string Корзина: сумма товаров берётся из неё
items_total integer Сумма товаров в копейках, если корзины нет
city string
region string
point_id integer Пункт выдачи: город и регион берутся из него

Order

Поле Тип Описание
number обязательное string
access_token string Пропуск к заказу для страницы «спасибо». Приходит **только** в ответе
на POST /v1/orders; в GET /v1/orders/{number} его нет — пропуск
не раздаётся повторно. Дальше передаётся как ?t= или заголовком
X-Order-Token.
status обязательное string (new, processing, shipped, done, returned, cancelled)
total обязательное string Итог к оплате: товары + доставка − скидка
items_total string Сумма позиций без доставки и скидки
delivery_price string Стоимость доставки; 0.00 — бесплатно
discount_total string Скидка по промокоду; 0.00 — кода не было
promo_code string Промокод на момент заказа; пусто — без кода
currency обязательное string
created_at обязательное string
items обязательное array<object>
customer object
delivery object
payment object

OrderInput

Тело POST /v1/orders. Соответствует OrderInput::validate().

Поле Тип Описание
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). Нужен
только отчёту магазина «откуда пришли заказы»; пусто — прямой заход.

Shop

Публичная часть настроек магазина: то, что нужно витрине, приложению и
внешнему фронту. Инфраструктурные настройки (например, cors_origins)
наружу не отдаются.

Поле Тип Описание
shop_name string
currency string Код ISO-4217
contact_email string
contact_phone string
description string
legal_name string Наименование продавца для подвала витрины
legal_inn string ИНН: 10 или 12 цифр, только цифры
legal_ogrn string ОГРН или ОГРНИП: 13 или 15 цифр
legal_address string Адрес продавца для подвала витрины
metrika_id string Номер счётчика Яндекс.Метрики; пусто — аналитики нет
demo_mode string (, 1) Демонстрационный магазин: 1 — платформа показывает на витрине
плашку «заказы не выполняются». Пусто — обычный магазин.
checkout object Правила оформления заказа: доступные способы получения и оплаты.
Считаются из настроек магазина. Суммы — строки DECIMAL, рядом те же
значения в копейках (целыми): клиент, который пересчитывает итог сам,
не должен разбирать «3 000,00».
domain string Слаг магазина (поддомен)
theme string Выбранная тема витрины
theme_accent string Устаревшее поле: единственный цвет акцента до появления палитры.
Остаётся запасным значением роли accent для магазинов, которые
ещё не сохранили палитру своей темы.
theme_palettes object Свои цвета витрины по темам: {"aurora": {"bg": "#faf8f5", "ink": "#14161a"}}.
Набор ролей объявляет сама тема (theme.json → palette), поэтому
ключи внутри объекта зависят от шаблона: у светлой темы это bg,
paper, ink, accent, у тёмной — bg, panel, ink, accent.
Значения — только #rrggbb. Палитры независимы: смена темы не
сбрасывает цвета ранее настроенного шаблона.
theme_palette_modes object Что показывать в каждой теме: custom — свои цвета из theme_palettes,
original — цвета шаблона. Отсутствие ключа означает custom для
магазинов, созданных до появления режима. Сброс к оригиналу не удаляет
свои цвета, поэтому режим можно переключать в обе стороны.
theme_palette_originals object Снимок оригинальных цветов темы на момент настройки палитры:
{"aurora": {"bg": "#faf8f5", "ink": "#14161a"}}. Нужен витрине и
письмам, чтобы режим original показывал цвета именно того шаблона,
а не фирменные, и чтобы сравнение не зависело от чтения манифеста.
pages array<object> Опубликованные страницы — для меню

Category

Узел дерева категорий

Поле Тип Описание
id string
slug string
name string
children array<Category>

Page

Статическая страница магазина

Поле Тип Описание
slug обязательное string
title обязательное string
body обязательное string HTML/текст, как его ввёл селлер
seo обязательное object

Review

Поле Тип Описание
id обязательное string
product_slug обязательное string Товар, о котором отзыв
product_name обязательное string
author обязательное string Подпись покупателя; e-mail наружу не отдаётся
rating обязательное integer
body обязательное string
status обязательное string (pending, published, rejected)
verified обязательное boolean true — отзыв связан с заказом магазина
created_at обязательное string Дата создания, Y-m-d H:i:s

ReviewSummary

Поле Тип Описание
avg string Средняя оценка строкой («4.50»); null — отзывов нет
count integer
distribution object Сколько отзывов на каждую оценку: {"5": 8, "4": 3, …}

ReviewInput

Поле Тип Описание
product обязательное string Slug товара
rating обязательное integer
author обязательное string Как подписать отзыв
body обязательное string
email string Необязателен и никогда не публикуется
website string Honeypot: человек его не видит и не заполняет

Customer

Поле Тип Описание
id обязательное string
email обязательное string Как ввёл покупатель; сравнение идёт по нормализованному
name обязательное string
created_at обязательное string
email_verified boolean Адрес подтверждён письмом; до подтверждения заказы в кабинете закрыты

Session

Сессия покупателя. sid передаётся в заголовке X-Customer-Session;
cookie держит фронт. Живёт в Redis месяц и переживает рестарт.

Поле Тип Описание
sid обязательное string 32 hex-символа
csrf обязательное string Токен для форм личного кабинета
expires_in обязательное integer TTL в секундах

Интерактивная консоль

Консоль — это Swagger UI. Она загружается с CDN (unpkg.com) только после нажатия кнопки: страница остаётся быстрой, а без интернета весь текст документации выше всё равно доступен. Для запросов к живому API понадобится демо-магазин.