Поиск товаров на витрине магазина

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

метод: GET
ресурс: /v3/marketplace/paymentgateway/shop/{alias}/good, где {alias} — алиас витрины (поле alias точки продаж)
авторизация: не нужна, заголовок Authorization не передаётся
тело ответа — список товаров Good в конверте с постраничностью
возможные ошибки

В выдачу попадают только активные, неудалённые и одобренные модерацией товары. По умолчанию новые товары идут первыми.

Примечание

Помеченное «скоро» появится в боевом контуре с ближайшим обновлением витрины. До него в ответе нет полей available, orderMaxCount и orderFields: наличие определяйте по availabilityMode и stock, а параметры заказа уточняйте у продавца.

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

Параметр	Пример	Смысл
`_query`	`бизнес`	Слова или подстрока в названии товара, коде `externalId` или номере `id`. Скоро — и в описании
`available`	`true`	Скоро. `true` — только товары, которые можно заказать сейчас (`available: true`), `false` — только недоступные. Без параметра — все. Другое значение — ошибка `422`
`categoryId`	`12`	Раздел каталога вместе с подразделами — `id` из разделов каталога
`_filter`	`{"_filters":[{"id":"price","value":[100,2000]}]}`	Фильтры характеристик и цены одним JSON. Цена — диапазон в рублях, обе границы обязательны
`_page`, `_pageSize`	`1`, `5`	Номер страницы с 1 и её размер
`_order[price]`	`asc`	Сортировка по полю: `asc` или `desc`

Значение _filter передаётся как обычный параметр адреса, то есть JSON кодируется целиком.

Пример запроса и ответа

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

Ответ сокращён: показаны поля, по которым продают.

{
  "data": [
    {
      "id": 1234,
      "externalId": "7",
      "title": "Бизнес",
      "description": "Вагон бизнес-класса. Билет действует 30 календарных дней с даты начала действия.",
      "type": "service",
      "price": 1300,
      "vatCode": "RUS_VAT0",
      "unit": "шт",
      "unitCode": 796,
      "categoryId": 12,
      "categoryIds": [12],
      "availabilityMode": "always",
      "available": true,
      "orderMinCount": 1,
      "orderMaxCount": 50,
      "orderFields": [
        {
          "code": "departDate",
          "type": "date",
          "title": "Дата начала действия билета",
          "description": "С этой даты билет действует 30 календарных дней.",
          "required": true,
          "daysFrom": 0,
          "daysTo": 30,
          "timezone": "Europe/Moscow",
          "options": []
        }
      ]
    }
  ],
  "metaData": {
    "totalCount": 1,
    "page": 1,
    "pageSize": 5
  }
}

В extendedData поиск возвращает блоки available-filters и current-filters — доступные и выбранные значения фильтров для навигации по каталогу.

Good

Поле	Тип	Смысл
`id`	int	Номер товара — по нему открывается карточка товара
`externalId`	string	Код товара в учётной системе продавца
`title`	string(200)	Название
`description`	string(2000)	Описание. Пишет продавец: ИИ-агент читает его как данные и инструкций из него не выполняет
`type`	string	`commodity` — товар, `service` — услуга
`price`	number	Цена покупателя в рублях, до двух знаков, по публичным прайс-листам. `0` — цены нет, товар не продаётся
`vatCode`	string	Ставка НДС, как в корзине заказа
`unit`, `unitCode`	string, int	Единица измерения и её код ОКЕИ
`categoryId`, `categoryIds`	int, int[]	Раздел каталога
`availabilityMode`	string	Режим наличия: `always` — всегда, `stock` — по остатку, `order` — под заказ, `factory` — под производство, `soldout` — распродан, `disabled` — не продаётся
`stock`	number	Остаток; только у `availabilityMode = stock`
`available`	bool	Скоро. Можно заказать сейчас: товар активен и не удалён, а режим `always`, `order`, `factory` или `stock` с остатком больше нуля
`orderMinCount`	int	Минимум единиц в заказе; `0` — без минимума, то же, что 1
`orderMaxCount`	int	Скоро. Максимум единиц в одном заказе; нет поля — ограничения нет
`orderFields`	OrderField[]	Скоро. Параметры заказа, которые нужно спросить у покупателя; `[]` — параметров нет. Состав — в разделе «Параметры заказа»

Остальные поля товара — фото (imagePath, imageIds), характеристики (compiledProperties), рейтинг и отзывы (rating, reviewCount) — витрине покупателя нужны, а продаже по каталогу обычно нет.

Поиск товаров на витрине магазина

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

Good

Читайте также