Добавление товаров в каталог и редактирование информации о них
Добавляет товары в каталог или редактирует информацию об уже имеющихся товарах.
Чтобы добавить новый товар, передайте его с новым идентификатором, который раньше никогда не использовался в каталоге. Старайтесь сразу передать как можно больше информации — она потребуется Маркету для подбора подходящей карточки или создания новой. Если известно, какой карточке на Маркете соответствует товар, можно сразу указать идентификатор этой карточки (SKU на Маркете) в поле marketSKU.
Для новых товаров обязательно укажите параметры: offerId, name, category, pictures, vendor, description.
Чтобы отредактировать информацию о товаре, передайте новые данные, указав в offerId соответствующий ваш SKU. Поля, в которых ничего не меняется, можно не передавать.
Правила использования SKU
-
У каждого товара SKU должен быть свой.
-
SKU товара нельзя менять — можно только удалить товар и добавить заново с новым SKU.
-
Уже заданный SKU нельзя освободить и использовать заново для другого товара. Каждый товар должен получать новый идентификатор, до того никогда не использовавшийся в вашем каталоге.
Данные в каталоге обновляются не мгновенно
Это занимает до нескольких минут.
| ⚙️ Лимит: 5000 товаров в минуту, не более 500 товаров в одном запросе |
|---|
Request
POST
https://api.partner.market.yandex.ru/businesses/{businessId}/offer-mappings/update
Path parameters
|
Name |
Type |
Description |
|
businessId* |
integer<int64> |
Идентификатор кабинета. Чтобы узнать идентификатор, воспользуйтесь запросом GET campaigns. |
Body
{
"offerMappings": [
{
"offer": {
"offerId": "string",
"name": "Ударная дрель Makita HP1630, 710 Вт",
"category": "string",
"pictures": [
"string"
],
"videos": [
"string"
],
"vendor": "LEVENHUK",
"barcodes": [
46012300000000
],
"description": "string",
"manufacturerCountries": [
"Россия"
],
"weightDimensions": {
"length": 65.55,
"width": 50.7,
"height": 20,
"weight": 1.001
},
"vendorCode": "VNDR-0005A",
"tags": [
"до 500 рублей"
],
"shelfLife": {
"timePeriod": 0,
"timeUnit": "HOUR",
"comment": "string"
},
"lifeTime": {
"timePeriod": 0,
"timeUnit": "HOUR",
"comment": "string"
},
"guaranteePeriod": {
"timePeriod": 0,
"timeUnit": "HOUR",
"comment": "string"
},
"customsCommodityCode": 8517610008,
"certificates": [
"string"
],
"boxCount": 0,
"condition": {
"type": "PREOWNED",
"quality": "PERFECT",
"reason": "string"
},
"type": "DEFAULT",
"downloadable": false,
"adult": false,
"age": {
"value": 0,
"ageUnit": "YEAR"
},
"params": [
{
"name": "Wi-Fi",
"value": "есть"
}
],
"purchasePrice": {
"value": 0,
"currencyId": "RUR"
},
"additionalExpenses": {
"value": 0,
"currencyId": "RUR"
},
"cofinancePrice": {
"value": 0,
"currencyId": "RUR"
}
},
"mapping": {
"marketSku": 0
}
}
]
}
|
Name |
Type |
Description |
|
offerMappings* |
Перечень товаров, которые нужно добавить или обновить. |
UpdateOfferMappingDTO
Информация о товаре.
|
Name |
Type |
Description |
|
offer* |
Параметры товара. |
|
|
mapping |
Информация о карточке товара на Маркете. |
UpdateOfferDTO
Параметры товара.
|
Name |
Type |
Description |
|
offerId* |
string |
Ваш SKU — идентификатор товара в вашей системе. Разрешена любая последовательность длиной до 80 знаков. В нее могут входить английские и русские буквы, цифры и символы Правила использования SKU:
|
|
name |
string |
Составляйте название по схеме: тип + бренд или производитель + модель + особенности, если есть (например, цвет, размер или вес) и количество в упаковке. Не включайте в название условия продажи (например, «скидка», «бесплатная доставка» и т. д.), эмоциональные характеристики («хит», «супер» и т. д.). Не пишите слова большими буквами — кроме устоявшихся названий брендов и моделей. Оптимальная длина — 50–60 символов, максимальная — 256. Рекомендации и правила
|
|
category |
string |
Категория, к которой магазин относит свой товар. Она помогает точнее определить для товара категорию в каталоге Маркета. Указывайте конкретные категории — например, набор ножей лучше отнести к категории Столовые приборы, а не просто Посуда. Выбирайте категории, которые описывают товар, а не абстрактный признак — например, Духи, а не Подарки. |
|
pictures |
string[] |
Ссылки на изображения товара. Изображение по первой ссылке считается основным, остальные дополнительными. Требования к ссылкам
✅ ✅ ❌ ❌ Ссылки на изображение должны быть постоянными. Нельзя использовать динамические ссылки, меняющиеся от выгрузки к выгрузке. Если нужно заменить изображение, выложите новое изображение по новой ссылке, а ссылку на старое удалите. Если просто заменить изображение по старой ссылке, оно не обновится. |
|
videos |
string[] |
Ссылка (URL) на видео товара. Внимание Пока действует временное ограничение: ссылка может быть только одна. Требования к ссылке
✅ ✅ ❌ ❌ Ссылки на видео должны быть постоянными. Нельзя использовать динамические ссылки, меняющиеся от выгрузки к выгрузке. Если нужно заменить видео, выложите новое видео по новой ссылке, а ссылку на старое удалите. Если просто заменить видео по старой ссылке, оно не обновится. |
|
vendor |
string |
Название бренда или производителя. Должно быть записано так, как его пишет сам бренд. |
|
barcodes |
string[] |
Указывайте в виде последовательности цифр. Подойдут коды EAN-13, EAN-8, UPC-A, UPC-E или Code 128. Для книг указывайте ISBN. Для товаров определенных категорий и торговых марок штрихкод должен быть действительным кодом GTIN. Обратите внимание: внутренние штрихкоды, начинающиеся на 2 или 02, и коды формата Code 128 не являются GTIN. Что такое GTIN
|
|
description |
string |
Подробное описание товара: например, его преимущества и особенности. Не давайте в описании инструкций по установке и сборке. Не используйте слова «скидка», «распродажа», «дешевый», «подарок» (кроме подарочных категорий), «бесплатно», «акция», «специальная цена», «новинка», «new», «аналог», «заказ», «хит». Не указывайте никакой контактной информации и не давайте ссылок. Можно использовать теги:
Оптимальная длина — 400–600 символов, максимальная — 6000. |
|
manufacturerCountries |
string[] |
Страна, где был произведен товар. Записывайте названия стран так, как они записаны в списке.
|
|
weightDimensions |
Габариты упаковки и вес товара. |
|
|
vendorCode |
string |
Артикул товара от производителя. |
|
tags |
string[] |
Метки товара, используемые магазином. Покупателям теги не видны. По тегам можно группировать и фильтровать разные товары в каталоге — например, товары одной серии, коллекции или линейки. Максимальная длина тега 20 символов. У одного товара может быть максимум 10 тегов. Всего можно создать не больше 50 разных тегов.
|
|
shelfLife |
Срок годности — период, по прошествии которого товар становится непригоден. Указывайте срок, указанный на банке или упаковке. Текущая дата, дата поставки или дата отгрузки значения не имеет. Обязательно указывайте срок, если он есть. В комментарии укажите условия хранения. Например, «Хранить в сухом помещении». |
|
|
lifeTime |
Срок службы — период, в течение которого товар должен исправно выполнять свою функцию. Обязательно указывайте срок, если он есть. В комментарии укажите условия хранения. Например, «Использовать при температуре не ниже −10 градусов». |
|
|
guaranteePeriod |
Гарантийный срок — период, в течение которого можно бесплатно заменить или починить товар. Обязательно указывайте срок, если он есть. В комментарии опишите особенности гарантийного обслуживания. Например, «Гарантия на аккумулятор — 6 месяцев». |
|
|
customsCommodityCode |
string |
Код товара в единой Товарной номенклатуре внешнеэкономической деятельности (ТН ВЭД) — 10 или 14 цифр без пробелов. Обязательно укажите, если он есть.
|
|
certificates |
string[] |
Номера документов на товар: сертификата, декларации соответствия и т. п. Передавать можно только номера документов, сканы которого загружены в личном кабинете продавца по инструкции.
|
|
boxCount |
integer<int32> |
Количество грузовых мест. Параметр используется, если товар представляет собой несколько коробок, упаковок и так далее. Например, кондиционер занимает два места — внешний и внутренний блоки в двух коробках. Для товаров, занимающих одно место, не передавайте этот параметр. |
|
condition |
Состояние уцененного товара. Используется только для товаров, продаваемых с уценкой. |
|
|
type |
Особый тип товара. Указывается, если товар — книга, аудиокнига, лекарство, музыка, видео или поставляется под заказ.
|
|
|
downloadable |
boolean |
Признак цифрового товара. Укажите |
|
adult |
boolean |
Параметр включает для товара пометку 18+. Устанавливайте ее только для товаров, которые относятся к удовлетворению сексуальных потребностей. |
|
age |
Если товар не предназначен для детей младше определенного возраста, укажите это. Возрастное ограничение можно задавать в годах (с нуля, с 6, 12, 16 или 18) или в месяцах (любое число от 0 до 12). |
|
|
params |
Характеристики, которые есть только у товаров конкретной категории — например, диаметр колес велосипеда или материал подошвы обуви.
Используйте POST businesses/{businessId}/offer-cards/update для передачи характеристик товара, которые специфичны для его категории. Так переданные характеристики с большей вероятностью попадут на карточку. |
|
|
purchasePrice |
Себестоимость — затраты на самостоятельное производство товара или закупку у производителя или поставщиков. |
|
|
additionalExpenses |
Дополнительные расходы на товар. Например, на доставку или упаковку. |
|
|
cofinancePrice |
Цена для скидок с Маркетом Маркет может компенсировать до половины скидки. Назначьте минимальную цену до вычета тарифов, по которой готовы продавать товар, а мы рассчитаем скидку и размер софинансирования. Если Маркет не готов софинансировать скидку, покупатель её не увидит. |
UpdateMappingDTO
Карточка на Маркете, которая, с вашей точки зрения, подходит товару. Чтобы определить идентификатор подходящей карточки, воспользуйтесь поиском в кабинете (Товары → Каталог → Загрузить товары).
|
Name |
Type |
Description |
|
marketSku |
integer<int64> |
Идентификатор карточки на Маркете. Может отсутствовать в ответе, если товар еще не привязан к карточке. |
OfferWeightDimensionsDTO
Габариты упаковки и вес товара.
Если товар занимает несколько коробок, перед измерением размеров сложите их компактно.
|
Name |
Type |
Description |
|
length* |
number |
Длина упаковки в см.
|
|
width* |
number |
Ширина упаковки в см.
|
|
height* |
number |
Высота упаковки в см.
|
|
weight* |
number |
Вес товара в кг с учетом упаковки (брутто).
|
TimePeriodDTO
Временной отрезок с комментарием. Требования к содержанию комментария зависят от контекста использования параметра и указаны в описании поля, которое его содержит.
|
Name |
Type |
Description |
|
timePeriod* |
integer |
Продолжительность в указанных единицах. |
|
timeUnit* |
Единица измерения. |
|
|
comment |
string |
Комментарий. |
OfferConditionDTO
Состояние уцененного товара.
|
Name |
Type |
Description |
|
type |
Тип уценки.
|
|
|
quality |
Внешний вид товара.
|
|
|
reason |
string |
Описание товара. Подробно опишите дефекты, насколько они заметны и где их искать. |
OfferType
Особый тип товара:
MEDICINE— лекарства.BOOK— книги.AUDIOBOOK— аудиокниги.ARTIST_TITLE— музыкальная и видеопродукция.ON_DEMAND— товары на заказ.
|
Type |
Description |
|
Enum: |
AgeDTO
Возраст в заданных единицах измерения.
|
Name |
Type |
Description |
|
value* |
number |
Значение. |
|
ageUnit* |
Единица измерения.
|
OfferParamDTO
Параметры товара.
Используйте POST businesses/{businessId}/offer-cards/update для передачи характеристик товара, которые специфичны для его категории. Так переданные характеристики с большей вероятностью попадут на карточку.
|
Name |
Type |
Description |
|
name* |
string |
Название. Должно совпадать с названием характеристики на Маркете. Узнать его можно из Excel-шаблона категории или через запрос POST category/{categoryId}/parameters.
|
|
value* |
string |
Значение.
|
BasePriceDTO
Цена на товар.
|
Name |
Type |
Description |
|
value* |
number |
Значение. |
|
currencyId* |
string |
Валюта. Если |
TimeUnitType
Единица измерения времени:
HOUR— час;DAY— сутки;WEEK— неделя;MONTH— месяц;YEAR— год.
|
Type |
Description |
|
Enum: |
OfferConditionType
Тип уценки:
PREOWNED— бывший в употреблении товар, раньше принадлежал другому человеку.SHOWCASESAMPLE— витринный образец.REFURBISHED— повторная продажа товара.REDUCTION— товар с дефектами.RENOVATED— восстановленный товар.
REFURBISHED — специальное значение для одежды, обуви и аксессуаров. Используется только для уцененных товаров из этой категории. Другие значения для одежды, обуви и аксессуаров не используются.
|
Type |
Description |
|
Enum: |
OfferConditionQualityType
Внешний вид товара:
PERFECT— идеальный.EXCELLENT— отличный.GOOD— хороший.
|
Type |
Description |
|
Enum: |
AgeUnitType
Единицы измерения возраста:
YEAR— год.MONTH— месяц.
|
Type |
Description |
|
Enum: |
Responses
200 OK
Все обязательные поля товаров заполнены, поэтому новые товары и внесенные изменения сохранены в каталоге.
Body
{
"status": "OK"
}
|
Name |
Type |
Description |
|
status |
Тип ответа. |
ApiResponseStatusType
Тип ответа.
|
Type |
Description |
|
Enum: |
400 Bad Request
Убедитесь, что все обязательные поля заполнены.
⚠️ Даже если проблема связана всего с одним товаром в запросе, в каталог не отправится ни один.
Body
{
"status": "OK",
"errors": [
{
"code": "string",
"message": "string"
}
]
}
|
Name |
Type |
Description |
|
status |
Тип ответа. |
|
|
errors |
Список ошибок. |
ApiErrorDTO
Общий формат ошибки.
|
Name |
Type |
Description |
|
code* |
string |
Код ошибки. |
|
message |
string |
Описание ошибки. |
401 Unauthorized
В запросе не указаны данные для авторизации.
Body
{
"status": "OK",
"errors": [
{
"code": "string",
"message": "string"
}
]
}
|
Name |
Type |
Description |
|
status |
Тип ответа. |
|
|
errors |
Список ошибок. |
403 Forbidden
Данные для авторизации неверны или доступ к ресурсу запрещен.
Body
{
"status": "OK",
"errors": [
{
"code": "string",
"message": "string"
}
]
}
|
Name |
Type |
Description |
|
status |
Тип ответа. |
|
|
errors |
Список ошибок. |
404 Not Found
Запрашиваемый ресурс не найден.
Body
{
"status": "OK",
"errors": [
{
"code": "string",
"message": "string"
}
]
}
|
Name |
Type |
Description |
|
status |
Тип ответа. |
|
|
errors |
Список ошибок. |
420 Method Failure
Превышено ограничение на доступ к ресурсу.
Body
{
"status": "OK",
"errors": [
{
"code": "string",
"message": "string"
}
]
}
|
Name |
Type |
Description |
|
status |
Тип ответа. |
|
|
errors |
Список ошибок. |
423 Locked
К ресурсу нельзя применить указанный метод.
Body
{
"status": "OK",
"errors": [
{
"code": "string",
"message": "string"
}
]
}
|
Name |
Type |
Description |
|
status |
Тип ответа. |
|
|
errors |
Список ошибок. |
500 Internal Server Error
Внутренняя ошибка сервера.
Body
{
"status": "OK",
"errors": [
{
"code": "string",
"message": "string"
}
]
}
|
Name |
Type |
Description |
|
status |
Тип ответа. |
|
|
errors |
Список ошибок. |
Что такое GTIN
GTIN — это уникальный номер, присвоенный товару в единой международной базе GS1. Из этого номера получается штрихкод формата EAN, UPC или ISBN.
Как убедиться, что товар есть в базе
Проверить код можно на странице проверки на сайте ассоциации GS1. Если товар не находится, запросите код GTIN у вашего поставщика.
Как получить GTIN для своих товаров
Чтобы получить коды GTIN, производителю нужно вступить в ассоциацию GS1 и зарегистрировать товары.