Перейти к содержанию

Каталог

Здесь описаны коллекции витрины, категории учёта, фильтры коллекций и дополнительные поля. Создание товаров, привязка к коллекциям, свойства вариантов и типы цен описаны в разделе «Товары».

Связанные ресурсы: каналы продаж приложения, отзывы, склады и валюты склада.

Если передать тело без ожидаемого корневого объекта, API вернёт 422. Поле message укажет, какой ключ нужен, например collection. Чтение объекта с несуществующим идентификатором возвращает 404 с HTML-страницей.

Коллекции

Коллекция — раздел витрины. Корневая коллекция магазина приходит с пустым parent_id. Скрытая коллекция (is_hidden: true) в список входит. Коллекция, помеченная к удалению, из списка пропадает.

У обычной коллекции is_smart в ответе равен null. Ключ image есть только у коллекции с картинкой.

Список

GET /admin/collections.json без page и per_page возвращает все коллекции. Они сортируются по parent_id, затем по position. Коллекция без родителя находится в конце списка.

Для чтения дочерних коллекций передайте parent_id родительской коллекции. Значение parent_id=null возвращает коллекции без родителя.

Чтобы получать список по страницам, передайте page или per_page. Размер страницы ограничен диапазоном от 10 до 250: API заменяет значения за его пределами ближайшей границей. Количество страниц возвращается в заголовке X-TOTAL-PAGES. Если page меньше 1, API вернёт 422.

GET/admin/collections.json?per_page=10&page=1
Параметр Описание
per_page необязательный
число		 Количество коллекций на странице: от 10 до 250. Значения за пределами диапазона заменяются ближайшей границей.
page необязательный
число		 Номер страницы, начиная с 1.
parent_id необязательный
число		 Только дочерние коллекции. null — коллекции без родителя.
updated_since необязательный
строка		 Нижняя граница updated_at, граница входит в ответ. 
GET /admin/collections.json?per_page=10&page=1
Authorization: Basic API_KEY:API_PASSWORD
Accept: application/json

Ответ · 200

[
  {
    "id": 53486015,
    "parent_id": 53486010,
    "is_hidden": true,
    "is_smart": null,
    "position": 40,
    "recursive": true,
    "sort_type": 3,
    "title": "docs-api Витрина",
    "permalink": "docs-api-vitrina",
    "url": "/collection/docs-api-vitrina",
    "html_title": "HTML title",
    "meta_description": "md",
    "meta_keywords": "kw",
    "description": "<p>Описание <b>коллекции</b></p>",
    "seo_description": "seo",
    "field_values": [
      {
        "id": 1,
        "collection_field_id": 1,
        "value": "метка-1"
      }
    ]
  }
]

В ответе также есть created_at, updated_at и custom_template. Число страниц приходит в заголовке X-TOTAL-PAGES.

page=0 отвечает 422:

{"message":"page должен иметь значение, большее 0"}

Изменившиеся коллекции

Параметр updated_since возвращает коллекции, у которых updated_at больше либо равен указанному времени. Результат сортируется по updated_at, затем по id. Передавайте время целиком в параметре URL, кодируя двоеточия и знак смещения часового пояса.

Параметр from_id не меняет состав и порядок списка коллекций. Для следующего запроса изменяйте updated_since. Записи с граничным временем могут вернуться повторно, поскольку сравнение включает указанное время.

Если значение updated_since не удаётся разобрать как дату, фильтрация по времени не применяется. API возвращает список без этого ограничения, но сортирует его по updated_at и id.

GET/admin/collections.json?updated_since=2026-10-21T22%3A00%3A00%2B03%3A00
Параметр Описание
updated_since обязательный
строка		 Момент изменения. Коллекция с этим updated_at входит в ответ. 
GET /admin/collections.json?updated_since=2026-10-21T22%3A00%3A00%2B03%3A00
Authorization: Basic API_KEY:API_PASSWORD
Accept: application/json

Ответ · 200

[
  {
    "id": 53486015,
    "updated_at": "2026-10-21T22:14:15.000+03:00",
    "title": "docs-api Витрина"
  },
  {
    "id": 53486016,
    "updated_at": "2026-10-21T22:14:15.000+03:00",
    "title": "docs-api dup"
  }
]

У записи списка есть id, updated_at и title.

Создание и изменение

POST /admin/collections.json создаёт коллекцию и возвращает статус 201. Поле parent_id обязательно. Если permalink уже занят, InSales добавляет суффикс -2, не отклоняя запрос.

sort_type — код порядка товаров в коллекции. Чужой код отвечает 422, в ошибке sort_type со значением «имеет непредусмотренное значение».

Код Порядок
1 По алфавиту: А — Я
2 По алфавиту: Я — А
3 По дате: новые — старые
4 По дате: старые — новые
5 По цене: дорогие — дешёвые
6 По цене: дешёвые — дорогие
7 Ручная
8 По скидке: большая — маленькая
9 По скидке: маленькая — большая
10 По весовому коэффициенту: маленький — большой
11 По весовому коэффициенту: большой — маленький
12 Сначала непопулярные
13 Сначала популярные

recursive: true сохраняется в ответе. description принимает HTML. Значения дополнительных полей пишутся массивом field_values_attributes и возвращаются в field_values.

PUT /admin/collections/:id.json меняет те же поля и отвечает 200 объектом коллекции.

POST/admin/collections.json
Параметр Описание
collection[title] обязательный
строка		 Название коллекции.
collection[parent_id] обязательный
число		 id родительской коллекции.
collection[is_hidden] необязательный
логический		 Скрыть коллекцию на витрине.
collection[sort_type] необязательный
число		 Код порядка товаров, от 1 до 13.
collection[permalink] необязательный
строка		 Адрес коллекции. Занятое значение получает суффикс.
collection[position] необязательный
число		 Позиция среди соседей.
collection[recursive] необязательный
логический		 Включать товары вложенных коллекций.
collection[description] необязательный
строка		 Описание, можно с HTML.
collection[seo_description] необязательный
строка		 SEO-описание.
collection[html_title] необязательный
строка		 Заголовок страницы.
collection[meta_description] необязательный
строка		 Мета-описание.
collection[meta_keywords] необязательный
строка		 Ключевые слова.
collection[field_values_attributes] необязательный
массив		 Значения дополнительных полей: collection_field_id и value. 
POST /admin/collections.json
Authorization: Basic API_KEY:API_PASSWORD
Accept: application/json
Content-Type: application/json

{
  "collection": {
    "title": "docs-api Витрина",
    "parent_id": 53486010,
    "is_hidden": true,
    "sort_type": 3,
    "permalink": "docs-api-vitrina",
    "position": 40,
    "recursive": true,
    "description": "<p>Описание <b>коллекции</b></p>",
    "seo_description": "seo",
    "html_title": "HTML title",
    "meta_keywords": "kw",
    "meta_description": "md",
    "field_values_attributes": [
      {
        "collection_field_id": 1,
        "value": "метка-1"
      }
    ]
  }
}

Ответ · 201

{
  "id": 53486015,
  "parent_id": 53486010,
  "is_hidden": true,
  "is_smart": null,
  "position": 40,
  "recursive": true,
  "sort_type": 3,
  "title": "docs-api Витрина",
  "html_title": "HTML title",
  "meta_description": "md",
  "meta_keywords": "kw",
  "permalink": "docs-api-vitrina",
  "url": "/collection/docs-api-vitrina",
  "description": "<p>Описание <b>коллекции</b></p>",
  "seo_description": "seo",
  "field_values": [
    {
      "id": 1,
      "collection_field_id": 1,
      "value": "метка-1"
    }
  ]
}

Товар попадает в коллекцию отдельным запросом POST /admin/collects.json. Этот метод разобран в товарах.

Картинка

Картинка передаётся публичным адресом в image_attributes.src при создании и при PUT уже существующей коллекции. Пока файл обрабатывается, original_url равен /images/loading.gif.

POST/admin/collections.json
Параметр Описание
collection[title] обязательный
строка		 Название коллекции.
collection[parent_id] обязательный
число		 id родительской коллекции.
collection[image_attributes][src] обязательный
строка		 Публичный адрес файла картинки. 
POST /admin/collections.json
Authorization: Basic API_KEY:API_PASSWORD
Accept: application/json
Content-Type: application/json

{
  "collection": {
    "title": "docs-api Картинка",
    "parent_id": 53486010,
    "image_attributes": {
      "src": "https://upload.wikimedia.org/wikipedia/commons/c/ca/1x1.png"
    }
  }
}

Ответ · 201

{
  "id": 53486017,
  "title": "docs-api Картинка",
  "permalink": "docs-api-kartinka",
  "image": {
    "id": 1,
    "created_at": "2026-10-21T22:14:16.000+03:00",
    "original_url": "/images/loading.gif"
  }
}

Тот же объект image_attributes в PUT /admin/collections/:id.json отвечает 200 и тоже возвращает original_url равным /images/loading.gif, пока файл обрабатывается.

Умная коллекция

Умная коллекция собирает товары по фильтрам. POST с is_smart: true и пустым списком фильтров отвечает 422:

{"smart_collection_filters":["Настройте хотя бы один фильтр"]}

Создавайте умную коллекцию в два шага:

  1. Создайте обычную коллекцию.
  2. Отправьте PUT с is_smart и smart_collection_filters_attributes.

API вернёт 200 и is_smart: true. Фильтры в JSON коллекции не включаются. Если попытаться сразу создать умную коллекцию с фильтрами через POST, API вернёт 500 и не создаст коллекцию.

method_or_field_name задаёт поле и ключ через двоеточие. Для названия это title:. values — массив.

Поле Операторы
title: contain, not_contain
price: between
discount: greater_than
created_at: greater_than, less_than, greater_than_or_equal, less_than_or_equal, older_than, younger_than
property:ID in, empty, notempty

Для фильтра по свойству укажите его идентификатор после двоеточия в method_or_field_name. С операторами empty и notempty массив values может быть пустым. В примере ниже фильтр выбирает товары по подстроке в названии.

Состав умной коллекции пересчитывается после сохранения.

PUT/admin/collections/53486018.json
Параметр Описание
id обязательный
число		 id уже созданной коллекции.
collection[is_smart] обязательный
логический		 Включить умную коллекцию.
collection[smart_collection_filters_attributes] обязательный
массив		 Фильтры: method_or_field_name, operator, values. 
PUT /admin/collections/53486018.json
Authorization: Basic API_KEY:API_PASSWORD
Accept: application/json
Content-Type: application/json

{
  "collection": {
    "is_smart": true,
    "smart_collection_filters_attributes": [
      {
        "method_or_field_name": "title:",
        "operator": "contain",
        "values": ["Gallery"]
      }
    ]
  }
}

Ответ · 200

{
  "id": 53486018,
  "parent_id": 53486010,
  "is_hidden": false,
  "is_smart": true,
  "sort_type": 7,
  "title": "docs-api page 0",
  "permalink": "docs-api-page-0",
  "url": "/collection/docs-api-page-0",
  "field_values": []
}

Удаление

DELETE /admin/collections/:id.json у дочерней коллекции отвечает 200 и {"status":"ok"}. Следующий GET этой коллекции — 404 с HTML-страницей.

Тот же DELETE у корневой коллекции тоже отвечает {"status":"ok"}, и коллекция остаётся на месте.

DELETE/admin/collections/53486025.json
Параметр Описание
id обязательный
число		 id дочерней коллекции. 
DELETE /admin/collections/53486025.json
Authorization: Basic API_KEY:API_PASSWORD
Accept: application/json

Ответ · 200

{"status":"ok"}

Категории

Категория задаёт раздел учёта товара и указывается в его поле category_id. Идентификатор коллекции витрины в этом поле использовать нельзя.

GET /admin/categories.json возвращает все категории без постраничного деления. Сортировка и фильтрация по updated_since и parent_id работают так же, как у коллекций. Параметр from_id не меняет список. Объект категории содержит только id, parent_id, title, position, created_at и updated_at.

POST /admin/categories.json отвечает 201. Меняются title, parent_id и position.

POST/admin/categories.json
Параметр Описание
category[title] обязательный
строка		 Название категории.
category[parent_id] необязательный
число		 id родительской категории.
category[position] необязательный
число		 Позиция среди соседей. 
POST /admin/categories.json
Authorization: Basic API_KEY:API_PASSWORD
Accept: application/json
Content-Type: application/json

{
  "category": {
    "title": "docs-api Учёт",
    "parent_id": 1,
    "position": 5
  }
}

Ответ · 201

{
  "id": 9,
  "parent_id": 1,
  "title": "docs-api Учёт",
  "position": 5,
  "created_at": "2026-10-21T22:14:20.000+03:00",
  "updated_at": "2026-10-21T22:14:20.000+03:00"
}

Удаление

При удалении дочерней категории DELETE /admin/categories/:id.json возвращает {"status":"ok"}. Следующее чтение категории возвращает 404. Товары, находившиеся в этой категории, переносятся в архив.

DELETE корневой категории тоже отвечает {"status":"ok"}, и категория остаётся.

Фильтры коллекций

Фильтр коллекции — SEO-страница внутри коллекции с собственным названием, адресом и набором параметров товара и свойств варианта. Методы доступны, если фильтры коллекций входят в тариф магазина.

GET /admin/collection_filters.json возвращает список по страницам. По умолчанию на странице до 500 записей. Параметр per_page ограничен диапазоном от 10 до 500; значения за пределами диапазона заменяются ближайшей границей. Заголовка X-TOTAL-PAGES нет.

Чтобы получить фильтры одной коллекции, передайте collection_id. С ним список сортируется по position, без него — по коллекции и позиции.

При создании и изменении передавайте данные в корневом объекте filter. При создании API возвращает 201, при изменении — 200. В ответе характеристики находятся в поле characteristis: сохраняйте именно такое написание ключа. Значения дополнительных полей в ответ не включаются.

properties_attributes и options_attributes ищут параметр и свойство по названию и создают отсутствующие. Повтор того же набора параметров и свойств в той же коллекции отвечает 422:

{"properties_attributes":["Уже существует фильтр с такими параметрами и свойствами"]}

Название фильтра уникально внутри коллекции.

POST/admin/collection_filters.json
Параметр Описание
filter[title] обязательный
строка		 Название фильтра. Уникально внутри коллекции.
filter[collection_id] обязательный
число		 id коллекции.
filter[permalink] необязательный
строка		 Адрес фильтра.
filter[description] необязательный
строка		 Описание, можно с HTML.
filter[seo_description] необязательный
строка		 SEO-описание.
filter[html_title] необязательный
строка		 Заголовок страницы.
filter[meta_keywords] необязательный
строка		 Ключевые слова.
filter[meta_description] необязательный
строка		 Мета-описание.
filter[properties_attributes] необязательный
массив		 Параметры товара: title параметра и value характеристики.
filter[options_attributes] необязательный
массив		 Свойства варианта: title свойства и value значения.
filter[field_values_attributes] необязательный
массив		 Значения полей коллекции: handle и value. В ответе фильтра их нет. 
POST /admin/collection_filters.json
Authorization: Basic API_KEY:API_PASSWORD
Accept: application/json
Content-Type: application/json

{
  "filter": {
    "title": "docs-api фильтр",
    "collection_id": 53486010,
    "permalink": "docs-api-filter",
    "description": "<p>seo</p>",
    "html_title": "t",
    "meta_keywords": "k",
    "meta_description": "m",
    "properties_attributes": [
      {
        "title": "docs-api Материал",
        "value": "Лён"
      }
    ],
    "options_attributes": [
      {
        "title": "Размер",
        "value": "M"
      }
    ]
  }
}

Ответ · 201

{
  "id": 1,
  "collection_id": 53486010,
  "title": "docs-api фильтр",
  "permalink": "docs-api-filter",
  "description": "<p>seo</p>",
  "html_title": "t",
  "meta_keywords": "k",
  "meta_description": "m",
  "seo_description": null,
  "characteristis": [
    {
      "id": 609,
      "property_id": 61541224,
      "position": 1,
      "title": "Лён",
      "permalink": "lyon"
    }
  ],
  "option_values": [
    {
      "id": 21063150,
      "option_name_id": 2517839,
      "position": 13,
      "title": "M",
      "image_url": null,
      "permalink": "m"
    }
  ]
}

PUT /admin/collection_filters/:id.json с новым title и permalink отвечает 200 и тем же набором characteristis и option_values. DELETE /admin/collection_filters/:id.json удаляет фильтр.

Дополнительные поля коллекции

Для дополнительного поля коллекции используйте тип CollectionField::TextField или CollectionField::TextArea. Другие значения type приводят к ответу 500, поле при этом не создаётся.

POST /admin/collection_fields.json отвечает 201. В ответе есть application_id и application_title приложения, от имени которого создано поле. Повтор handle отвечает 422:

{"handle":["Свойство с таким пермалинком уже существует"]}

GET /admin/collection_fields/:id.json читает поле по числовому id. Если в сегменте пути есть не только цифры, поле ищется по handle.

POST/admin/collection_fields.json
Параметр Описание
collection_field[title] обязательный
строка		 Название поля.
collection_field[handle] необязательный
строка		 Системное имя. Уникально в магазине.
collection_field[type] обязательный
строка		 CollectionField::TextField или CollectionField::TextArea.
collection_field[position] необязательный
число		 Позиция поля.
collection_field[is_hidden] необязательный
логический		 Скрыть поле. 
POST /admin/collection_fields.json
Authorization: Basic API_KEY:API_PASSWORD
Accept: application/json
Content-Type: application/json

{
  "collection_field": {
    "title": "docs-api Метка",
    "handle": "docs_api_label",
    "type": "CollectionField::TextField"
  }
}

Ответ · 201

{
  "id": 1,
  "handle": "docs_api_label",
  "type": "CollectionField::TextField",
  "application_id": 12,
  "position": 3,
  "is_hidden": null,
  "title": "docs-api Метка",
  "application_title": "docs-catalog"
}

Значение поля

Чтобы сохранить значение вместе с коллекцией, передайте field_values_attributes. Для работы со значением отдельно доступны список, чтение и изменение. Отдельных методов создания и удаления нет.

GET /admin/collections/:collection_id/collection_field_values.json — значения этой коллекции. GET и PUT одного значения идут по id поля или по его handle.

Если значение ещё не сохранено, GET возвращает 200 и объект с пустыми id и value, не создавая запись. Для создания или изменения значения используйте PUT. Ответ содержит {"status":"ok"}; новое значение можно прочитать следующим GET.

GET/admin/collections/53486015/collection_field_values/9.json
Параметр Описание
collection_id обязательный
число		 id коллекции.
id обязательный
строка		 id поля или его handle. 
GET /admin/collections/53486015/collection_field_values/9.json
Authorization: Basic API_KEY:API_PASSWORD
Accept: application/json

Ответ · 200

{
  "id": null,
  "collection_field_id": 9,
  "value": null
}
PUT/admin/collections/53486015/collection_field_values/docs_api_label.json
Параметр Описание
collection_id обязательный
число		 id коллекции.
id обязательный
строка		 id поля или его handle.
collection_field_value[value] обязательный
строка		 Новое значение. 
PUT /admin/collections/53486015/collection_field_values/docs_api_label.json
Authorization: Basic API_KEY:API_PASSWORD
Accept: application/json
Content-Type: application/json

{
  "collection_field_value": {
    "value": "метка-2"
  }
}

Ответ · 200

{"status":"ok"}

Значения дополнительных полей

Создание дополнительных полей товара и варианта, а также запись значений вместе с товаром описаны в разделе «Товары». Ниже показана работа со значениями через отдельные методы. Пустой массив в карточке означает, что значений нет.

Товар

GET /admin/products/:product_id/product_field_values.json — значения товара. POST создаёт значение и отвечает 201. Повтор того же поля отвечает 422:

{"product_field_id":["уже существует"]}

В создании можно передать product_field_id или product_field_handle. Чтение, изменение и удаление идут по id значения или по handle поля.

PUT отвечает объектом значения. DELETE отвечает {"status":"ok"}, следующий список этого товара — [].

POST/admin/products/673/product_field_values.json
Параметр Описание
product_id обязательный
число		 id товара.
product_field_value[product_field_id] обязательный
число		 id поля. Вместо него можно передать product_field_handle.
product_field_value[value] обязательный
строка		 Значение. 
POST /admin/products/673/product_field_values.json
Authorization: Basic API_KEY:API_PASSWORD
Accept: application/json
Content-Type: application/json

{
  "product_field_value": {
    "product_field_id": 4586434,
    "value": "значение"
  }
}

Ответ · 201

{
  "id": 895989818,
  "product_field_id": 4586434,
  "value": "значение"
}
PUT/admin/products/673/product_field_values/docs_api_pf.json
Параметр Описание
product_id обязательный
число		 id товара.
id обязательный
строка		 id значения или handle поля.
product_field_value[value] обязательный
строка		 Новое значение. 
PUT /admin/products/673/product_field_values/docs_api_pf.json
Authorization: Basic API_KEY:API_PASSWORD
Accept: application/json
Content-Type: application/json

{
  "product_field_value": {
    "value": "новое"
  }
}

Ответ · 200

{
  "id": 895989818,
  "product_field_id": 4586434,
  "value": "новое"
}

Вариант

Для работы со значениями дополнительных полей варианта используйте путь /admin/variants/:variant_id/variant_field_values.json. Путь /admin/products/:product_id/variants/:variant_id/variant_field_values.json отвечает 404.

POST принимает variant_field_id или variant_field_handle и отвечает 201. PUT по handle отвечает объектом значения. После записи то же значение видно в variant_field_values карточки варианта.

POST/admin/variants/2176487181/variant_field_values.json
Параметр Описание
variant_id обязательный
число		 id варианта.
variant_field_value[variant_field_handle] обязательный
строка		 handle поля. Вместо него можно передать variant_field_id.
variant_field_value[value] обязательный
строка		 Значение. 
POST /admin/variants/2176487181/variant_field_values.json
Authorization: Basic API_KEY:API_PASSWORD
Accept: application/json
Content-Type: application/json

{
  "variant_field_value": {
    "variant_field_handle": "docs_api_vf",
    "value": "метка"
  }
}

Ответ · 201

{
  "id": 1,
  "variant_field_id": 1,
  "value": "метка"
}

PUT /admin/variants/2176487181/variant_field_values/docs_api_vf.json с новым value отвечает 200 и объект {"id":1,"variant_field_id":1,"value":"метка-2"}.