[PATCH] Изменение продукта
Описание запроса
PATCH /v1/product/[product id]
Запрос позволяет изменить свойства продукта.
Данные для отправки запроса
- Endpoints URL:
- Боевая среда: https://api.ecommerce.softline.com/v1/product
- Тестовая среда: https://api.ecommerce.softline.com.demoslweb.com/v1/product
- Метод: PATCH
- Формат: JSON
- Авторизация: с помощью токена
Вы можете получить его в ответ на запросы: Пример передачи параметра в URL: /v1/product/123456
- Формат значения:
Bearer [token]
- Вместо [token] подставьте значение token, полученное в ответ на запрос к Authentication API.
- family_name - не обязательный параметр
- name - не обязательный параметр
- variants - не обязательный параметр
Особенности обновления данных
Обратите внимание, для следующих параметров происходит полное обновление всех вложенных элементов, если параметр передан в запросе:
- Цены - variants
- Локализация - localization_values
- Настройки отображения - display_settings
- Настройки продления лицензии - renew_settings
- Настройки предложения дополнительных продуктов - cross_sell
- Настройки TYPO - typo
- Данные для локализации TYPO - typo.localization_values
- Данные для электронной доставки продукта - license_data
- Данные о наличии продукта в реестре российского ПО - software_registry
Для этих параметров:
- Если параметр передан, то все (а не только переданные) соответствующие ему вложенные данные будут полностью перезаписаны.
- Если параметр отсутствует в запросе на обновление, то ранее заполненные значения не изменятся.
Например:
- При создании продукта было передано поле localization_values и в нем данные для локали cs_CZ.
- В запросе на обновление было передано поле localization_values и в нем только данные для локали en_EN.
- Результат:
- В продукте останутся только данные для en_EN.
- Данные для cs_CZ будут удалены.
В этом примере, чтобы добавить перевод для другого языка к имеющемуся, вам необходимо передать в запросе данные для всех локалей, для которых должен быть перевод (в приведенном примере это cs_CZ и en_EN).
Пример запроса
{
"family_name": "Демо-продукт",
"name": "Лицензия на 1 год",
"is_publish": true,
"image_url": "https://my-shop.com/images/product-1234.png",
"description": "<p><strong>Тестовый продукт</strong></p>",
"comment_for_manager": "Комментарий для менеджера",
"url_to_instructions": "https://www.google.com",
"url_to_download": "https://www.google.com",
"business_segment": "b2c",
"available_for_sale": "all",
"is_service": true,
"license_type": "new",
"licence_term": "P1Y",
"device_quantity": 1,
"renew_settings": {
"product_id_for_renew": [
4645130,
4645131,
4645131
],
"renew_ar": {
"enable": true,
"required": false
},
"renew_pmr": true,
"renew_email": false
},
"localization_values": {
"en_EN": {
"family_name": "Test product",
"name": "1 PC/1 year",
"description": "<p><strong>Test product</strong> for test purchase</p>",
"comment_for_cart": "This is a test purchase.",
"comment_for_product_top": "The license is valid for 1 year.",
"comment_for_product_middle": "New version of the test product.",
"comment_for_product_for_AR": "The license is renewed automatically.",
"comment_for_product_for_MR": "You will need to manually renew your license after 1 year.",
"comment_for_product_bottom": "This license is not for sale or activation outside of the country."
}
},
"display_settings": {
"hide_name": true,
"hide_item_quantity": true
},
"variants": [
{
"vendor_code": "1",
"sku": "111",
"from": 1,
"to": 5,
"price": {
"RUB": {
"currency": "USD",
"price": "99.99"
}
}
},
{
"vendor_code": "1",
"sku": "111",
"from": 6,
"price": {
"RUB": {
"currency": "USD",
"price": "80.99"
}
}
}
],
"cross_sell": {
"type": "add_to_basket",
"status": true,
"date_from": "2020-10-15 14:18:00",
"date_to": "2020-10-25 14:18:00",
"removal_available": true,
"quantity_change_available": false,
"product_id": [
4645130,
4645131
]
},
"typo": {
"status": true,
"date_from": "2020-10-15 14:18:40",
"date_to": "2020-10-25 14:18:40",
"localization_values": {
"ru_RU": {
"comment_for_typo": "Специальное предложение"
},
"en_EN": {
"comment_for_typo": "Special offer"
}
},
"product_id": [
4645130,
4645131
]
},
"license_data": {
"ru_RU": {
"customer_notification": "Ключ активации: {KEY}"
},
"en_EN": {
"customer_notification": "Key: {KEY}"
}
},
"software_registry": {
"status": true,
"date": "2020-10-15",
"url": "https://reestr.digital.gov.ru/reestr/111",
"registration_number": 111
}
}
Особенности удаления данных
Если вы хотите при обновлении удалить какие-либо свойства продукта:
- Для параметров, перечисленных в предыдущем разделе, происходит полная замена ранее переданных данных на новые значения, если параметр присутствует в запросе. При этом:
- Если вы хотите заменить все старые значения на новые, то достаточно просто передать новые значения
- Если нужно удалить настройки продления, то передайте false в соответствующих параметрах (renew_settings.renew_ar.enable, renew_settings.renew_pmr, renew_settings.renew_email). При этом будут автоматически удалена привязка продуктов для продления (renew_settings.product_id_for_renew). Сами продукты для продления останутся в системе
- Если нужно настройкам отображения (display_settings) продукта вернуть значения по умолчанию, то передайте параметр с пустым значением ({})
- Если нужно удалить настройки дополнительных продуктов / TYPO-предложения, то передайте статус false в соответствующих объектах (cross_sell.status, typo.status),
- Если нужно удалить локализованные значения (localization_values), то передайте пустые массивы данных для соответствующего языка
- Удалить все цены у продукта нельзя
- Удалить данные для электронной доставки продукта (license_data) нельзя, если вы хотите перестать использовать индивидуальные значения для продуктов и вернуться к настройкам по умолчанию, то обратитесь в службу поддержки
- При удалении данных о включении продукта в реестр российского ПО нужно передать только вложенный параметр software_registry.status со значением false
- Для удаления описания продукта, URL инструкции, URL загрузки и т.п. значений, передайте их пустыми (""). На текущий момент не поддерживается удаление изображения продукта, обратитесь в службу поддержки, если нужно его удалить
Пример запроса для удаления данных продукта
{
"description": "",
"comment_for_manager": "",
"url_to_instructions": "",
"url_to_download": "",
"licence_term": "",
"localization_values": {
"en_EN": {}
},
"display_settings": {},
"renew_settings": {
"product_id_for_renew": [],
"renew_ar": {
"enable": false,
"required": false
},
"renew_pmr": false,
"renew_email": false
},
"typo": {
"status": false
},
"cross_sell": {
"status": false
},
"software_registry": {
"status": false
}
}
Ответ на запрос
В ответ на запрос вы получите код ответа сервера, соответствующий результату обработки.
В зависимости от кода в теле ответа могут присутствовать дополнительные параметры.
Положительный ответ
При успешной обработке запроса вы получите код ответа сервера HTTP/1.1 200 OK.
Ответ об ошибке
В случае ошибки при обработке запроса вы получите код ответа сервера, соответствующий результату обработки.
В зависимости от кода в теле ответа могут присутствовать дополнительные параметры.
Справочник HTTP-кодов ответа сервера при ошибке
Код ответа сервера | Описание |
HTTP/1.1 400 Bad Request | Запрос не валиден (ошибка в параметрах; не переданы необходимые данные и т.п.). В теле ответа будет передан дополнительный код ошибки (один или несколько). |
HTTP/1.1 401 Unauthorized | Неуспешная аутентификация. В теле ответа будет передан дополнительный код ошибки (один или несколько). |
HTTP/1.1 404 Not found | Неверный URL запроса или продукт не найден. Проверьте адрес запроса. В теле ответа может быть передан дополнительный код ошибки (один или несколько). |
HTTP/1.1 500 Request Error | Ошибка на стороне сервера. Повторите запрос позднее или обратитесь в службу поддержки. |
Справочник дополнительных кодов ошибок для HTTP 400
Справочник этих ошибок совпадает с ошибками при создании продукта.
Справочник дополнительных кодов ошибок для HTTP 401
Справочник этих ошибок одинаковый для всех API, которые используют авторизацию по токену.
Справочник дополнительных кодов ошибок для HTTP 404
Error | Message | Описание |
Если хотя бы одна ошибка из списка ниже найдена, то она возвращается в ответе на запрос, остальные ошибки не проверяются. | ||
11200 | Product not found | Запрос не может быть выполнен. Продукт с переданным id не найден или у вас нет доступа к нему. |
Пример ответа об ошибке
{
"errors": [{
"error": 1010,
"message": "Invalid field value: name"
}, {
"error": 1010,
"message": "Invalid field value: family_name"
}
]
}