Работа с товарами и модификациями

Товар (product) и модификация (variant) — базовые сущности каталога МойСклад. Разберём, как их создавать, связывать характеристиками, задавать цены и штрихкоды через JSON API 1.2.

Типы товарных сущностей

В каталоге МойСклад несколько типов номенклатуры, и у каждого свой ресурс:

Обобщённый список всей номенклатуры отдаёт ресурс /entity/assortment — он объединяет товары, модификации, комплекты и услуги в одну коллекцию.

Создание товара

Товар создаётся POST-запросом с минимальным телом — обязательно только name:

POST /entity/product
{
  "name": "Кофе зерновой 1 кг",
  "code": "COF-1000",
  "article": "CF1000",
  "weight": 1.0
}

В ответ приходит созданный объект с присвоенным id и meta. Для обновления используется PUT по URL объекта:

PUT /entity/product/{id}

• code — внутренний код, article — артикул поставщика.
• uom — единица измерения (ссылка meta на справочник).
• productFolder — группа товаров (ссылка meta).

Модификации и характеристики

Модификация (variant) — это вариант товара, отличающийся значениями характеристик: цвет, размер. Она обязательно ссылается на родительский товар и содержит массив characteristics.

POST /entity/variant
{
  "product": { "meta": { "href": ".../entity/product/{id}", "type": "product" } },
  "characteristics": [{ "name": "Размер", "value": "XL" }]
}

Собственное имя модификации формируется автоматически из имени товара и значений характеристик, задавать его вручную не нужно.

Цены товара

Цены хранятся в двух полях. Закупочная — в buyPrice, продажные — в массиве salePrices. Каждая продажная цена привязана к типу цен через meta.

"salePrices": [{
  "value": 45000,
  "priceType": { "meta": { "href": ".../pricetype/{id}", "type": "pricetype" } }
}]

Список типов цен запрашивается из метаданных компании: GET /context/companysettings/pricetype. При обновлении цен передавайте только изменяемые типы — остальные останутся прежними.

Штрихкоды и артикулы

Штрихкоды хранятся в массиве barcodes. МойСклад поддерживает несколько форматов, каждый — как отдельный ключ объекта:

• ean13 — 13-значный EAN;
• ean8 — 8-значный EAN;
• code128 — Code 128;
• gtin — глобальный номер товара.

Пример:

"barcodes": [ { "ean13": "4600000000017" } ]

Один товар может иметь несколько штрихкодов. При импорте следите за уникальностью: попытка записать существующий в аккаунте штрихкод другому товару вернёт ошибку валидации.

Ассортимент и поиск товара

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

GET /entity/assortment?filter=article=CF1000

Быстрый поиск по подстроке в имени, коде и артикуле выполняет параметр search:

GET /entity/assortment?search=кофе

Ассортимент — правильная точка входа, когда нужно сопоставить каталог сайта с номенклатурой МойСклад по артикулу или штрихкоду.

Итог

Каталог МойСклад через JSON API строится из товаров, модификаций, комплектов и услуг, а обобщающая точка входа — /entity/assortment. Товар создаётся минимальным телом с name, модификации привязываются характеристиками, цены и штрихкоды хранятся в массивах, а денежные значения всегда — в копейках. Эти правила покрывают большинство сценариев наполнения и синхронизации каталога.

Именно на этой модели мы строим обмен каталогом между МойСклад и сайтом на 1С-Битрикс: сопоставление по артикулу, корректная передача цен и вариантов, обработка конфликтов штрихкодов. Если нужен надёжный двусторонний обмен товарами, поможем спроектировать модуль обмена под ваши правила.