Справочник API

Витрина и корзина

запрос каталога витрины

curl -s "https://api.amarix.ru/products?public=true" \
  -H "X-Site-Source: casher"

Гостевой режим

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

Когда гость входит в учётную запись, его корзина сливается с той, что была у него раньше.

Какой остаток видит покупатель

В каталоге витрины поле остатка у размера — это доступный остаток: физический минус то, что уже зарезервировано под чужие неоплаченные заказы. Поэтому покупатель не увидит вещь, которая вот-вот уедет к другому.

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

GET/products

Каталог витрины

Товары магазина с размерами, ценами и доступными остатками.

Доступ:Без авторизации

Магазин определяется заголовком витрины. Без него платформа не станет гадать и вернёт пустой список — это защита от случайной выдачи чужого каталога.

Заголовки

Параметр	Тип	Обязателен	Описание
`X-Site-Source`	string	да	Код магазина. Без него ответ будет пустым, хотя код останется успешным.

Параметры запроса

Параметр	Тип	Обязателен	Описание
`public`	true	да	Отсечь скрытые товары и товары «только по ссылке». Витрина обязана его передавать.
`category`	string \| number	нет	Число понимается как идентификатор категории, строка — как её точное название.
`search`	string	нет	Поиск по названию и адресному имени.
`hasDiscount`	true \| false	нет	Только со скидкой либо только без неё.
`collectionId`	string	нет	Товары одной коллекции.
`sortBy`	string	нет	Порядок. Неизвестное значение молча заменяется порядком по умолчанию.name_asc · name_desc · price_asc · price_desc · newest · oldest

Поля ответа

Поле	Тип	Описание
`price`	number	Цена товара.в копейках
`discount`	number	Скидка: копейки при типе «сумма», проценты при типе «процент».
`sizes[].quantity`	number	Доступный остаток — физический минус резервы. Именно его показывают покупателю.
`sizes[].isVisible`	boolean	Показывать ли размер на витрине.
`freeShipping`	boolean	У товара бесплатная доставка.
`productGroups`	array	Связанные товары — например, тот же фасон в других цветах.

Ошибки

Код	Ответ сервера	Когда возникает	Что делать
200	`[]`	Заголовок магазина не передан или код неизвестен.	Это не ошибка, а осознанный отказ угадывать. Проверьте заголовок, если список неожиданно пуст.
500	`{"error":"Internal server error"}`	Сбой на стороне платформы.	—

GET/products/{slug}

Карточка товара

Один товар по адресному имени или числовому идентификатору.

Доступ:Без авторизации

Параметры пути

Параметр	Тип	Обязателен	Описание
`slug`	string \| number	да	Адресное имя товара либо его идентификатор.

Ошибки

Код	Ответ сервера	Когда возникает	Что делать
404	`{"error":"Товар не найден"}`	Товара нет, он скрыт, либо принадлежит другому магазину.	—

GET/categories

Категории

Разделы каталога с числом товаров.

Доступ:Без авторизации

Параметры запроса

Параметр	Тип	Обязателен	Описание
`visibleOnly`	true	нет	Только видимые покупателю.
`brandId`	number	нет	Категории конкретного магазина.

Ошибки

Код	Ответ сервера	Когда возникает	Что делать
500	`{"error":"Internal server error"}`	Сбой на стороне платформы.	—

GET/cart

Корзина

Содержимое корзины покупателя или гостя.

Доступ:Гостевая сессияСессия сотрудника

Гостевая корзина живёт по паре заголовков — идентификатору гостя и его подписи. Подпись выдаёт платформа, подделать её нельзя. Когда гость входит в учётную запись, его корзина сливается с пользовательской.

Заголовки

Параметр	Тип	Обязателен	Описание
`X-Site-Source`	string	да	Код магазина: корзина у каждого магазина своя.
`X-Guest-ID`	string	нет	Идентификатор гостя. Для гостевой корзины обязателен.
`X-Guest-Token`	string	нет	Подпись идентификатора, выданная платформой.

Ошибки

Код	Ответ сервера	Когда возникает	Что делать
401	`Invalid guest session`	Подпись гостя не сходится с идентификатором.	—

POST/orders

Оформление заказа

Превращает корзину в заказ и ставит товар в резерв.

Доступ:Гостевая сессияСессия сотрудника

Собирает заказ из корзины того магазина, с витрины которого пришёл запрос. Итог считается как товары плюс доставка минус промокод. Сразу после создания товар встаёт в резерв на ограниченное время — чтобы его не купил кто-то другой, пока покупатель платит.

Тело запроса

Параметр	Тип	Обязателен	Описание
`lastName`	string	да	Фамилия получателя.
`firstName`	string	да	Имя получателя.
`phone`	string	да	Телефон.
`email`	string	нет	Почта для писем о заказе.
`city`	string	да	Город доставки. Для международной — страна.
`deliveryMethod`	string	нетпо умолчанию cdek_pvz	Способ доставки.cdek_pvz · cdek_courier · international
`pvzCode`	string	нет	Код пункта выдачи. Обязателен при доставке в пункт выдачи.
`street`	string	нет	Улица. Обязательна при курьерской доставке.
`house`	string	нет	Дом. Обязателен при курьерской доставке.
`promoCode`	string	нет	Промокод. Неподходящий код не роняет заказ — скидка просто не применится.
`agreedToTerms`	boolean	нет	Согласие с условиями.
`agreedToPrivacy`	boolean	нет	Согласие на обработку данных.

Ошибки

Код	Ответ сервера	Когда возникает	Что делать
400	`{"error":"Корзина пуста"}`	В корзине магазина ничего нет.	—
400	`{"error":"Выберите пункт выдачи СДЭК"}`	Доставка в пункт выдачи без указания пункта.	—
400	`{"error":"Укажите улицу и дом для курьерской доставки"}`	Курьерская доставка без адреса.	—
400	`{"error":"Укажите город доставки"}`	Не указан город.	—
400	`{"error":"Некоторые товары недоступны. Обновите корзину."}`	Товар распродан или снят с продажи.	—
400	`{"error":"Выбранный способ доставки недоступен"}`	Магазин отключил этот способ.	—
422	`{"error":"Подтвердите email в профиле, чтобы оформить заказ."}`	У покупателя не подтверждена почта.	—

POST/orders/validate-promo

Проверка промокода

Считает скидку до оформления заказа — для показа в корзине.

Доступ:Без авторизации

Тело запроса

Параметр	Тип	Обязателен	Описание
`code`	string	да	Промокод.
`cartTotalKopeks`	number	да	Сумма товаров.

Поля ответа

Поле	Тип	Описание
`valid`	boolean	Применим ли код.
`discountKopeks`	number	Размер скидки.в копейках
`message`	string	Причина отказа, готовая к показу покупателю.

Ошибки

Код	Ответ сервера	Когда возникает	Что делать
200	`{"valid":false,"message":"Промокод не найден"}`	Кода нет в этом магазине.	Отказ приходит с успешным кодом ответа: причина в поле message, её можно показать покупателю как есть.

GET/orders/hash/{hash}

Отслеживание заказа

Состояние заказа по публичной ссылке, без входа.

Доступ:Без авторизации

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

Параметры пути

Параметр	Тип	Обязателен	Описание
`hash`	string	да	Ключ из ссылки.

Ошибки

Код	Ответ сервера	Когда возникает	Что делать
404	`{"error":"Заказ не найден"}`	Ключ неверный.	—

Учётные записи покупателей

Регистрация, вход и восстановление пароля живут по адресам, начинающимся с /auth. Учётная запись покупателя привязана к магазину: одна и та же почта в двух магазинах — это два разных покупателя, и войти учётной записью соседнего магазина нельзя.

Чего на витрине нет

Чтобы не искать: в платформе отсутствуют как сущности

отзывы и оценки товаров — их негде хранить и нечем отдавать;
подписка на поступление и подписка на снижение цены как отдельная функция.

Уведомление о поступлении всё же работает, но иначе: письмо уходит тем, у кого товар в избранном и подтверждена почта, когда сотрудник снимает пометку «продано». То есть роль подписки играет избранное.