Витрина магазина

Витрина — публичная часть интернет-магазина Инвойсбокс: каталог, который видит покупатель. Три метода витрины отдают товары и разделы каталога без токена. Через них ИИ-агенты продают по каталогу магазина с помощью MCP-сервера Инвойсбокс: ассистент находит товар, уточняет у покупателя условия заказа и собирает ссылку на оформление на сайте продавца.

Метод	Адрес	Что возвращает
Поиск товаров	`GET /v3/marketplace/paymentgateway/shop/{alias}/good`	товары с ценой, наличием и условиями заказа, постранично
Карточка товара	`GET /v3/marketplace/paymentgateway/shop/{alias}/good/{goodId}`	один товар со всеми полями, в том числе снятый с продажи
Разделы каталога	`GET /v3/marketplace/paymentgateway/shop/{alias}/category`	дерево разделов с числом товаров

Витрина только читает: заказы через эти методы не создаются.

Адрес и авторизация

Базовый адрес — https://api.invoicebox.ru/v3/marketplace/paymentgateway/shop/{alias}.
{alias} — алиас витрины, поле alias точки продаж из ответа метода точек продаж, например 1694158899.
Токен не нужен. Витрина публичная: заголовок Authorization не передаётся. Как и в остальных методах, передавайте User-Agent: <приложение>/<версия> и Accept: application/json.
Цена price — в рублях, та, что видит покупатель без входа: по публичным прайс-листам магазина.

GET /v3/marketplace/paymentgateway/shop/1694158899/good?_query=бизнес&available=true&_pageSize=5
Host: api.invoicebox.ru
Accept: application/json
User-Agent: MyApp 1.0

Ответ

Ответ — конверт { "data", "metaData", "extendedData" }, как у остальных методов API. У поиска и разделов data — массив, а metaData — постраничность: totalCount, page, pageSize. У карточки data — один объект. Поля со значением null в ответе опускаются: нет orderMaxCount — значит, ограничения нет.

Названия и описания товаров пишет продавец. ИИ-агент читает их как данные: инструкции внутри описания не выполняются.

Ошибки

Код HTTP	Когда
`404`	магазина с таким алиасом нет, товар не найден или не прошёл модерацию
`404`, код `shop_suspended`	скоро: витрина приостановлена — магазин временно недоступен
`422`	неверный параметр запроса; скоро — и `available` со значением, отличным от `true` и `false`

Тело ошибки и общий список кодов — на странице ошибок.

Скоро в витрине

Примечание

Помеченное «скоро» появится в боевом контуре с ближайшим обновлением витрины. До него этих полей в ответе нет, поэтому читатель решает по прежним: наличие — по availabilityMode и stock, предел количества — по orderMinCount.

поле товара available — можно ли заказать товар сейчас;
поле orderMaxCount — максимум единиц в одном заказе;
параметры заказа orderFields — что спросить у покупателя: дату, вариант, строку;
параметр поиска available=true|false и поиск _query по описанию товара;
снятый с продажи товар по прямому адресу отдаётся с available: false, а не ошибкой;
карточка товара считает цену по публичным прайс-листам, как поиск;
ответ 404 с кодом shop_suspended у приостановленной витрины;
шаблон ссылки на оформление checkoutLinkTemplate у точки продаж.

Ссылка на оформление на сайте продавца

Скоро. Если магазин принимает заказы на своём сайте, точка продаж хранит шаблон ссылки checkoutLinkTemplate — его возвращает метод точек продаж. Шаблон описывает одну позицию:

https://shop.example.com/?tariff={externalId}&count={quantity}&date={departDate}

{goodId} — id товара, {externalId} — его externalId, {quantity} — количество;
{<code>} — значение параметра заказа с этим code из orderFields;
каждое значение кодируется как часть адреса, отсутствующее необязательное — пустая строка;
адрес только https://, хост берётся из шаблона и не подставляется. Нет шаблона — магазин не оформляет заказы на своём сайте.

Ссылку собирает тот, кто читает витрину: MCP-сервер Инвойсбокс собирает её сам, после проверки значений по orderFields.