API управления товарами

Аутентификация

Каждый запрос должен содержать действительный параметр token в строке запроса или JSON-теле. Он определяет авторизованную сессию продавца.

Справочник полей

[
    {
        "name": "Tag name",  // or multilingual { "EN"=>"Field name", "ES"=>"Field name", ... }
        "uuid": "tag_uuid" // Unique tag identifier (required). Must be unique, UUID recommended. Used as reference key for product tags.
    },
    ...
]

{
    "tag_uuid": { // Reference to "uuid" from tag_category
        "name": "Field name", // or multilingual { "EN"=>"Field name", "ES"=>"Field name", ... }
        "value": "Field value", // or multilingual { "EN"=>"Field value", "ES"=>"Field value", ... }
    },
...
}

[
    {
        "name": "Field name", // or multilingual { "EN"=>"Field name", "ES"=>"Field name", ... }
        "value": "Field value", // or multilingual { "EN"=>"Field value", "ES"=>"Field value", ... }
    },
...
]

Выбор возвращаемых полей

По умолчанию API возвращает все поля. Чтобы ограничить ответ, передайте fields — массив публичных имён полей.

Пример

{
  "api": "product",
  "method": "get-all",
  "token": "...",
  "limit": 100,
  "offset": 0,
  "fields": ["product_id", "name", "price", "image", "external_id"]
}

Примечания

• fields должен содержать публичные имена полей из справочника.
• Если fields не передан, возвращаются все поля.
• Если ни одно имя в fields не является допустимым, для каждой строки возвращается пустой объект. Пагинация сохраняется.

Вес и габариты для доставки

Поля weight_g, length_mm, width_mm и height_mm описывают одну единицу товара с упаковкой. Это параметры товара, а не итоговой посылки заказа. Поле weight остаётся самостоятельным и автоматически с weight_g не синхронизируется.

Все четыре поля доступны в get-all, get-product, в выборе fields, в filter и для записи через put-products. Допустимы целые числа от 0 до 4294967295, в том числе строки из цифр. Отрицательные, дробные значения, null и логические значения не принимаются: в payload.data возвращается ошибка соответствующего товара; его поля не изменяются.

При обновлении можно передать только изменяемые параметры. Пропущенные поля сохраняют прежние значения; 0 сбрасывает параметр в «не указан». У существующих товаров после добавления полей и у новых товаров без этих параметров значения равны 0.

Записать вес и габариты

{
  "api": "product",
  "method": "put-products",
  "token": "...",
  "fields": ["product_id", "weight_g", "length_mm", "width_mm", "height_mm"],
  "payload": [{
    "product_id": 12345,
    "weight_g": 750,
    "length_mm": 200,
    "width_mm": 150,
    "height_mm": 100
  }]
}

Получить товары с известным весом

{
  "api": "product",
  "method": "get-all",
  "token": "...",
  "fields": ["product_id", "name", "weight_g", "length_mm", "width_mm", "height_mm"],
  "filter": {"weight_g": {"gt": 0}}
}

1. Получить все товары

Возвращает плоский список всех товаров продавца.

Запрос

Методы: GET / POST
URL: https://api.onstor.ru/common/merchant/1.0/?api=product&method=get-all&token={token}&limit={limit}&offset={offset}

Обязательные параметры запроса

Ответ

Возвращает список товаров с метаданными и полями на настроенных языках.

2. Получить категории товаров

Получает группы товаров с учётом связей родителя и потомка.

Запрос

Метод: GET / POST
URL: https://api.onstor.ru/common/merchant/1.0/?api=product&method=get-categories&token={token}

3. Получить сведения о товаре

Возвращает подробные сведения об указанном товаре.

Запрос

Метод: GET / POST
URL: https://api.onstor.ru/common/merchant/1.0/?api=product&method=get-product&token={token}&product_id={product_id}

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

4. Фильтрация результатов

Методы get-all и get-categories поддерживают универсальный объект filter для SQL-фильтрации.

Внутри filter используются публичные имена полей.

Поддерживаемые операторы

Простой фильтр AND

{
  "filter": {
    "enable": {"eq": 1},
    "price": {"gte": 10}
  }
}

Результат:

enable = 1 AND price >= 10

Группы AND / OR

{
  "filter": {
    "and": [
      {"enable":{"eq":1}},
      {"is_category":{"eq":0}}
    ],
    "or": [
      {"name":{"like":"%cola%"}},
      {"description":{"like":"%cola%"}}
    ]
  }
}

Только OR

{
  "filter": {
    "or": [
      {"discount_type":{"eq":1}},
      {"discount_type":{"eq":2}}
    ]
  }
}

Полный пример

{
  "api": "product",
  "method": "get-all",
  "token": "...",
  "limit": 50,
  "offset": 0,
  "fields": ["product_id","name","price","external_id"],
  "filter": {
    "and":[
      {"enable":{"eq":1}},
      {"price":{"between":[10,50]}}
    ],
    "or":[
      {"external_id":{"is_null":false}},
      {"external_key":{"is_null":false}}
    ]
  }
}

Важные замечания

• Указывайте % в выражениях LIKE вручную.
• in: [] → всегда false.
• nin: [] → всегда true.
• Логические значения преобразуются автоматически; рекомендуется использовать 0 / 1.

5. Создать / обновить товары

Создаёт или обновляет данные товаров.

Примечание: отправляйте тело запроса как raw JSON (Content-Type: application/json).

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

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

{
    "api": "product",
    "method": "put-products",
    "token": "...",
    "language": "EN",
    "translate": true,
    "webhook": "https://webhook.site/4082430c-24eb-4df8-9903-d895fa668b5f",
    "payload": [...]
}

Если передан product_id или external_id существующего товара, запись обновляется. Если товар не найден, автоматически создаётся новый.

Иерархию товаров можно создать двумя способами:

1. Вложенность через child:
   Позволяет задать вложенные товары непосредственно в родительском объекте:

   "payload": [
       {
           "name": "New Category",
           "external_id": "ext_id_cat_1",
           "description": {"EN": "Category Description"},
           "image": "https://...",
           "child": [
               {
                   "name": "Product 1",
                   "external_id": "ext_id_prod_1",
                   "description": {"EN": "Description for Product 1"},
                   "image": "https://..."
               },
               {
                   "name": "Product 2",
                   "external_id": "ext_id_prod_2",
                   "description": {"EN": "Description for Product 2"},
                   "image": "https://..."
               }
           ]
       }
   ]

2. Указавparent_id:
   Позволяет добавить товар в существующую родительскую категорию:

   {
       "name": "Child Product",
       "external_id": "ext_id_new_child",
       "parent_id": 12345
   }

Язык и перевод

Параметр language задаёт исходный язык контента. При translate = true система переводит контент на остальные языки компании продавца.

Контент можно передать строкой или объектом с кодами языков:

• "name": "Some text"
• "name": { "EN": "Some text" }

При частичных переводах автоматически заполняются только отсутствующие языки. Например, компания поддерживает EN, ES и IL, а в запросе передано:

{
  "name": {
    "EN": "Some text",
    "ES": "Un poco de texto"
  }
}

В этом случае автоматически создаётся только отсутствующий перевод IL.

Уведомления webhook

В поле webhook задаётся URL обратного вызова. На него отправляется POST-запрос, когда:

• Загруженные изображения (например, image и homepage_image) обработаны и готовы;
• Автоматические переводы, запущенные через translate: true, завершены.

Это позволяет обновлять клиентское приложение после завершения асинхронной обработки.

Тело webhook

После обработки изображений и перевода система отправляет POST-запрос на указанный URL webhook со следующим телом:

{
  "request_id": "13",
  "status": "OK"
}

• request_id соответствует payload.request_id из ответа put-products
• status — OK при успехе или ERROR при ошибке обработки

Требования к URL изображений

image и homepage_image должны содержать действительные общедоступные URL файлов изображений. Сервер загружает и обрабатывает изображения по этим адресам.

6. Удалить выбранные товары

Примечание: отправляйте тело запроса как raw JSON (Content-Type: application/json).

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

Удаляет один или несколько товаров по идентификаторам товаров.

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

{
    "api": "product",
    "method": "delete-products",
    "token": "...",
    "use_external_id": true,
    "payload": [12345, 54321]
}

Удаляет один или несколько товаров по внешним идентификаторам.

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

{
    "api": "product",
    "method": "delete-products",
    "token": "...",
    "use_external_id": true,
    "payload": ["external_id_1"]
}

7. Удалить все товары

Удаляет все товары продавца.

URL

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

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