Интеграция товаров

Методы Partner API позволяют настроить автоматическую загрузку товаров в UDS и обновление информации по загруженным товарам (цены, описание, количество, фотографии и т.п.) из Вашей учетной системы. 

Загрузить товар возможно через Partner API согласно нашей документацией в пункте Items 

Примечание: В каждой категории может быть не больше 20 подкатегорий, количество товаров ограничено согласно лимиту в разделе Товары и услуги в UDS Бизнес. 

Примеры запросов в Partner API

Важно! В компании должен быть подключен модуль Товары и услуги в UDS Store.

Первичная загрузка товаров в UDS:

1. В учетной системе должен быть выбор товаров, которые будут синхронизироваться в UDS. Например, это может быть флаг в карточке товара ( загружать в UDS) или выбор категорий товаров, которые будут загружаться.

2. При первичной выгрузки товаров из учетной системы в UDS сначала создается дерево категорий товаров: сначала необходимо выгрузить категории первого уровня, далее загружаются категории второго уровня с указанием идентификатора (nodeId)  категории первого уровня в UDS, затем загружаются категории третьего уровня с указанием идентификатора (nodeId) категории второго уровня в UDS.

3. Затем загружаются товары с указанием nodeId категории, в которой должен находиться товар

4. В учетной системе должен быть сохранен id товара или категории, который вернулся в ответе от UDS при создании - это необходимо для дальнейшего обновления информации о товаре или категории

5. Также рекомендуется сохранять в учетной системе контрольную сумму данных (применять хеш-функцию) по каждому товару или категорий, которые отправляются в UDS - это может быть полезно для обновления товаров в UDS. В случае внесения изменений в карточку товара на стороне учетной системы новая контрольная сумма не будет совпадать с сохраненной и это может быть триггером для обновления товара в UDS. 

Обновление списка товаров в UDS:

1. Массовое обновление списков товаров в компании рекомендуется осуществлять в нерабочее время не чаще двух раз в сутки для избежания превышения ограничений по количеству запросов по API.

2. Интеграционный модуль должен понимать какие товары необходимо обновлять в UDS из-за изменений в товаре в учетной системе. На стороне учетной системы проверяется контрольная сумма данных по товару или категории на текущий момент и сравнивается с сохраненной, которая была отправлена в UDS. Если сумма не совпадает, то необходимо отправить в UDS запрос на изменение товара или категории и сохранить новую контрольную сумму в учетную систему.

3. Отправлять в UDS запрос на обновление информации по товару или категории только при условии наличия изменений в учетной системе.

4. Если при обновлении товара от UDS вернулась ошибка, необходимо ее обработать и внести корректировку. Без внесения изменений в отправляемые данные повторная отправка запроса на обновление товара нее допускается

1. Загрузка категории товаров.

Для начала нужно загрузить категории товаров - нужно отправить POST запрос на https://api.uds.app/partner/v2/goods и в теле запроса указать название категории ("name"),  идентификатор категории ("externalId" - может состоять только из цифр и латинских букв), тип  - CATEGORY, параметр "hidden" - скрыть ли категорию и "nodeId" - id категории, для которой эта категория является подкатегорией.

{
 "name": "Кофе",
 "nodeId": null,
 "externalId": "category_coffee",
 "data": 
   {
   "type": "CATEGORY"
   },
"hidden": false
}

Если информация заполнена корректно, то в ответ придет статус 200 ОК, информация о загруженной категории и в разделе Товары и услуги в UDS Бизнес появится новая категория. Вы можете сохранить из ответа id категории (далее он используется как параметр nodeId )- он нужен будет для загрузки подкатегорий и товаров в эту категорию или для обновления инфромации о категории. 

После загрузки всех категорий, можно начать загрузку товаров.

2. Загрузка товаров

Для примера рассмотрим загрузку товара Капучино разного объема (маленький 100 мл - 100 рублей, средний 200 мл - 150 рублей и большой 300 мл - 200 рублей).

Для этого нужно отправить POST запрос на https://api.uds.app/partner/v2/goods и в теле запроса указать название товара ("name"), id категории ("nodeId"), внешний id товара ("externalId"- может состоять только из цифр и латинских букв), тип товара - ITEM (обычный товар),  VARYING_ITEM (товар с вариантами), описание товара ( "description"), артикул( "sku") и параметр "hidden" - скрыть ли товар. Если товар имеет несколько вариантов, то необходимо добавить названия вариантов товара и их цены.

Если товар акционный, то нужно передать в объекте "offer" параметры "skipLoyalty" - применять ли бонусную программу к товару и "offerPrice" - акционную цену товара. Если у товара тип VARYING_ITEM, то объект "offer" должен быть у каждого варианта товара.

Если у товара нужно указать доступное количество, то нужно передать в объекте "inventory" параметр "inStock" количество товара (только целое число) . Если у товара неограниченное количество, то нужно передать "inStock":null. Если у товара тип VARYING_ITEM, то объекте "inventory" должен быть у каждого варианта товара.

Для загрузки весового товара (только для товара с type=ITEM и кроме единицы измерения PIECE) нужно передать:

• "increment": минимальная единица, на которую клиент может изменять количество товара; 

• "measurement": единицы измерения товара: CENTIMETRE (целое число), METRE (дробное число), MILLILITRE (целое число), LITRE (дробное число), GRAM (целое число), KILOGRAM (дробное число); 

• "minQuantity": минимальное количество товара, доступное к заказу.

Для загрузки товара с изображением загрузите сначала изображение на наш сервер и передайте список идентификаторов изображений в параметре "photos" в "data". (процесс загрузки изображений более описан в инструкция по загрузке изображений) 

{
    "name": "Капучино",
    "nodeId": 123456,
    "externalId": "coffee_cappuccino",
    "data": {
        "type": "VARYING_ITEM",
        "description": "Классический капучино",
        "photos": ["id1", "id2"],
        "variants": [
            {
                "name": "Маленький 100 мл",
                "price": 100.0,
                "sku": 1,
                "offer": {
                    "skipLoyalty": true,
                    "offerPrice": 90
                         },
                "inventory": {
                   "inStock": 100,
                          }
            },
            {
                "name": "Средний 200 мл",
                "price": 150.0,
                "sku": 2,
                "offer": {
                    "skipLoyalty": true,
                    "offerPrice": 130
                          },
                "inventory": {
                  "inStock": 70,
                     }
            },
            {
                "name": "Большой 300 мл",
                "price": 200.0,
                "sku": 3,
                "offer": {
                    "skipLoyalty": true,
                    "offerPrice": null
                      },
                "inventory": {
                 "inStock": null,
                   }
            }
        ]
    },
    "hidden": false
}

Если информация заполнена корректно, то в ответ придет статус 200 ОК и информация о загруженном товаре. Вы можете сохранить id товара- он нужен будет для внесении изменении в информацию о товаре.

В случае успешной загрузки товара в разделе Товары и услуги в UDS Бизнес должен появится загруженный товар в соответствующей категории.

3. Изменение информации о товаре

При необходимости Вы можете внести изменения в информацию о товаре: поменять цену, описание, поменять категорию или добавить/удалить варианты.

Для внесения изменения через Partner API в информацию о товаре необходимо отправить PUT запрос https://api.uds.app/partner/v2/goods/{id} и вместо {id} указать id товара.

Если у товара нужно указать доступное количество, то нужно передать в объекте "inventory" параметр "inStock" количество товара (только целое число) . Если у товара неограниченное количество, то нужно передать "inStock":null. Если у товара тип VARYING_ITEM, то объекте "inventory" должен быть у каждого варианта товара.

Для примера удалим у товара одну фотографию, установим неограниченное количество товара и добавим еще один вариант товара и поменяем цены другим:

{
  "name": "Капучино",
  "nodeId": 123456,
  "externalId": "coffee_cappuccino",
  "data":
   {
    "type": "VARYING_ITEM",
    "description": "Классический капучино",
     "photos": ["id2"],
    "variants": 
     [
      {
        "name": "Маленький 100 мл",
        "price": 110.0,
        "sku": 1,
        "inventory": {
             "inStock": null,
          }
      },
      {
        "name": "Средний 200 мл",
        "price": 160.0,
        "sku": 2,
        "inventory": {
             "inStock": null,
          }
      },
      {
        "name": "Большой 300 мл",
        "price": 220.0,
        "sku": 3,
        "inventory": {
             "inStock": null,
          }
      },
      {
        "name": "Мега 500 мл",
        "price": 300.0,
        "sku": 4,
        "inventory": {
             "inStock": null,
          }
      }
    ]
  }
"hidden":false
}

Если информация заполнена корректно, то в ответ придет статус 200 ОК, информация о загруженном товаре и поменяется информация о товаре в UDS Бизнес.
Важно! Если у товара не нужно обновлять фотографии, то рекомендуется или прислать исходное значение параметра photos, или не присылать параметр. Не допускается повторная загрузка одних и тех же фотографий при обновлении товара 

4. Удаления товара/категории 

Для удаление через Partner API в информацию о товаре/категории необходимо отправить DELETE запрос https://api.uds.app/partner/v2/goods/{id} и вместо {id} указать id товара.

Весовые товары

Например, необходимо создать товар, который продается в метрах (measurement) наотрез и его можно отрезать в сантиметрах. Всего длина товара 10 м (inventory). Минимальная длина покупки товара 1 м (minQuantity), отрезается по 0.05 м (increment) (то есть нельзя купить 1.23 м, можно или 1.25 м, или 1.2 м). Цена товара указывается за единицу измерения, в нашем случае за метр товара (price).

Допускается создание товаров с increment и minQuntity с типом CENTIMETRE, GRAM, MILLILITRE; для LITRE, KILOGRAM, METRE нужно создавать без этих значений.

Логика такая, что единица товара граммы(миллилитры) - целое число и не может быть дробным.

Килограммы(литры) могут быть целыми и дробными. Если нужно создать товар, который заказывается в целых числах, то указывается KILOGRAM, если десятичный, то указывается GRAM, increment и minQuantity

Тогда inventory =10, increment = 0.05, minQuantity=1, measurement = CENTIMETRE, price = 1000,

Запрос на создание товара:

{
"name": "Товар (на отрез)",
"nodeId": null,
"externalId": "atest1234",
    "data": {
         "type": "ITEM",
         "description": "Пробный товар",
         "sku": "123",
         "price": 10,
         "offer": null,
         "inventory": {
             "inStock": 10000
         },
         "photos": null,
         "increment":5,
         "measurement": "CENTIMETRE",
         "minQuantity": 100
    },
"hidden": false
}

Важно! Для совместимости с предыдущими версиями в ответе количество товара, цену за товар, шаг заказа и минимальное количество товара для заказа конвертируется в минимальную единицу, то есть метры в сантиметры, литры в миллилитры, килограммы в граммы

Ответ на создание дробного товара в метрах

{
"blocked": false,
"dateCreated": "2022-04-14T13:42:23.825Z",
"id": 599779,
"hidden": false,
"data": {
    "photos": [],
    "increment": 5,
    "type": "ITEM",
    "offer": null,
    "measurement": "CENTIMETRE",
    "price": 10.00,
    "description": "Пробный товар",
    "minQuantity": 100,
    "sku": "123",
    "inventory": {
        "inStock": 1000
    }
},
"imageUrls": [],
"externalId": "ates01234",
"name": "Товар (на отрез)"
}

inventory = 10 м переведено в 1000 см, increment = 0.05 м переведено в 5 см, minQuantity= 1м переведено в 100 см, measurement = METRE переведено в CANTIMETRE , price = 1000 за 1м переведено в 10 за 1 сантиметр товара

Список возможных ошибок: