Каталог: разделы и товары

Каталог нужен для товарных сегментов, подстановки товаров в письма и расчёта выручки по позициям. Он состоит из двух частей — дерева разделов и самих товаров — и выгружается в этом же порядке: сначала разделы, потом товары.

Сопоставление полей товаров одно на проект, независимо от того, каким коннектором присланы данные.

Разделы каталога

Разделы передаются плоским списком: у каждого свой идентификатор и ссылка на родителя. Дерево платформа строит сама, вложенность любой глубины.

POST /products/syncSections

{
  "sections": [
    { "id": "10", "name": "Одежда",    "parent_id": null, "active": "Y" },
    { "id": "11", "name": "Верхняя",   "parent_id": "10", "active": "Y" },
    { "id": "12", "name": "Куртки",    "parent_id": "11", "active": "Y" }
  ]
}

Поле	Обязательно	Описание
`id`	да	Ваш идентификатор раздела
`name`	да	Название раздела
`parent_id`	нет	Ваш идентификатор родительского раздела. Для разделов верхнего уровня — `null`
`active`	нет	`Y` или `N`. По умолчанию `Y`

Требования и особенности:

sections — непустой массив;
имена полей читаются без учёта регистра, можно присылать ID, NAME, PARENT_ID;
порядок элементов в массиве не важен: родитель может идти после потомка;
выгружайте всё дерево целиком — так платформа сразу разложит вложенность. Отдельные разделы можно присылать по событиям изменения;
ссылки по кругу (раздел является родителем сам себе через цепочку) платформа обнаруживает и помечает все участники цепочки как ошибочные.

Ответ

{
  "success": true,
  "code": 200,
  "data": {
    "results": [
      { "client_id": "10", "status": "created" },
      { "client_id": "11", "status": "updated" },
      { "client_id": "12", "status": "parent_not_synced" }
    ],
    "summary": {
      "created": 1, "updated": 1, "unchanged": 0,
      "parent_not_synced": 1, "cycle": 0, "error": 0
    }
  }
}

Значение `status`	Что означает
`created`	Раздел создан
`updated`	Раздел найден и обновлён
`unchanged`	Раздел уже есть, изменений нет
`parent_not_synced`	Родительский раздел ещё не передан. Пришлите его — и повторите этот раздел
`cycle`	Раздел участвует в круговой ссылке. Исправьте связи на своей стороне
`error`	Раздел не принят, причина в `message`

Товары

Товар передаётся плоским объектом: служебные поля и все характеристики одним уровнем.

POST /products/sync

{
  "products": [
    {
      "ID": "5501",
      "ACTIVE": "Y",
      "PUBLISHED": "Y",
      "AVAILABLE": "Y",
      "PRODUCT_TYPE": "simple",
      "SECTION_IDS": ["12"],
      "NAME": "Куртка зимняя Аврора",
      "PREVIEW_TEXT": "Тёплая куртка с капюшоном",
      "DETAIL_TEXT": "<p>Подробное описание</p>",
      "DETAIL_PAGE_URL": "https://example.ru/catalog/kurtka-avrora/",
      "PREVIEW_PICTURE": "https://example.ru/upload/avrora-small.jpg",
      "DETAIL_PICTURE": "https://example.ru/upload/avrora.jpg",
      "PRICE": 12900,
      "OLD_PRICE": 15900,
      "CURRENCY": "RUB",
      "QUANTITY": 7,
      "MEASURE": "шт",
      "COLOR": "синий",
      "SIZE": ""
    }
  ]
}

Требования и особенности:

products — непустой массив;
ID обязателен — это ваш идентификатор товара, по нему идёт создание или обновление;
за один запрос отправляйте не больше 50 товаров;
картинки и файлы передавайте абсолютными ссылками, доступными извне: платформа сохраняет ссылку, а не файл;
пустые характеристики передавайте пустой строкой "" — так они попадут в список полей для сопоставления;
множественные значения передавайте массивом: "COLOR": ["синий", "чёрный"].

Служебные поля

Эти поля платформа обрабатывает сама, сопоставлять их не нужно. Имена читаются без учёта регистра.

Поле	Обязательно	Описание
`products`	да	Непустой массив товаров. При пустом — ошибка, `"code": 400`
`ID`	да	Ваш идентификатор товара
`ACTIVE`	нет	Активность товара. `Y`/`N`; принимаются также `1`, `true`, `yes`. Если не передано — `Y`
`SECTION_IDS`	нет	Массив ваших идентификаторов разделов, в которых состоит товар
`PRODUCT_TYPE`	нет	Тип товара: `simple` — обычный, `parent` — товар с торговыми предложениями, `offer` — торговое предложение. Если не передано — `simple`
`PARENT_ID`	да, для `offer`	Ваш идентификатор родительского товара. Для остальных типов не нужен
`PUBLISHED`	нет	Виден ли товар в витрине. `Y`/`N`
`AVAILABLE`	нет	Доступен ли к покупке. `Y`/`N`

Поля, которые нужно сопоставить

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

Обязательно должно быть сопоставлено название товара — без него товар не будет собран и вернётся статус mapping_required.

Поля платформы, доступные для сопоставления:

Поле платформы	Смысл
`NAME`	Название товара. Обязательное
`PREVIEW_TEXT`, `DETAIL_TEXT`	Краткое и полное описание
`DETAIL_PAGE_URL`	Ссылка на страницу товара
`PREVIEW_PICTURE_URL`, `DETAIL_PICTURE_URL`	Ссылки на картинки
`PRICE`, `OLD_PRICE`	Цена и цена до скидки
`CURRENCY`	Валюта. Если не передана — `RUB`
`QUANTITY`	Остаток
`MEASURE`	Единица измерения. Если не передана — `шт`

Кроме них маркетолог может создать в кабинете собственные характеристики товара и сопоставить с ними ваши поля — например COLOR или SIZE.

Список ваших полей пополняется сам

В отличие от клиентов, у товаров список доступных для сопоставления полей накапливается по всем присланным товарам. Поля, встречающиеся только у части ассортимента, тоже будут доступны.

Ответ

{
  "success": true,
  "code": 200,
  "data": {
    "results": [
      { "xml_id": "5501", "status": "updated", "iblock_element_id": 884, "message": null }
    ]
  }
}

Значение `status`	Что означает
`created`	Товар создан
`updated`	Товар найден и обновлён
`mapping_required`	Данные сохранены, но не сопоставлено название товара. Товар появится после настройки сопоставления
`invalid_json`	Сохранённые данные не удалось прочитать
`error`	Товар не принят, причина в `message`

Торговые предложения

Товар с вариантами передаётся как несколько записей:

Родитель — PRODUCT_TYPE: "parent".
Каждый вариант — PRODUCT_TYPE: "offer" и PARENT_ID с идентификатором родителя.

{
  "products": [
    { "ID": "5600", "PRODUCT_TYPE": "parent", "NAME": "Футболка Базовая", "SECTION_IDS": ["14"] },
    { "ID": "5601", "PRODUCT_TYPE": "offer", "PARENT_ID": "5600", "NAME": "Футболка Базовая, M", "PRICE": 1900, "SIZE": "M" },
    { "ID": "5602", "PRODUCT_TYPE": "offer", "PARENT_ID": "5600", "NAME": "Футболка Базовая, L", "PRICE": 1900, "SIZE": "L" }
  ]
}

Если торговое предложение придёт раньше родителя, платформа примет его и сама поставит в очередь команд команду SYNC_PRODUCT — запрос прислать родителя. Порядок внутри одного запроса не важен.

В списках каталога и в сегментах торговые предложения не показываются отдельно — они свёрнуты в родительский товар.

Удаление товаров

POST /products/delete

{ "ids": ["5501", "5502"] }

Поле	Обязательно	Описание
`ids`	да	Массив ваших идентификаторов товаров. Одиночный товар можно передать как `{ "id": "5501" }`. Если не передан ни `ids`, ни `id` — ошибка, `"code": 400`

Удаление мягкое: товар помечается удалённым и перестаёт попадать в каталог, сегменты и письма, но история заказов с ним сохраняется. Ответ — массив results со статусом по каждому идентификатору.

Разделы не удаляются

Отдельного метода удаления раздела нет. Передайте раздел с "active": "N" — он перестанет использоваться.

Что дальше

Передать заказы с этими товарами — «Заказы».
Передавать добавления в корзину — «Визиты и корзина».

Разделы каталога​

Ответ​

Товары​

Служебные поля​

Поля, которые нужно сопоставить​

Ответ​

Торговые предложения​

Удаление товаров​

Что дальше​

Разделы каталога

Ответ

Товары

Служебные поля

Поля, которые нужно сопоставить

Ответ

Торговые предложения

Удаление товаров

Что дальше