Общая информация об интеграции с Wildberries

Данная статья описывает общие сведения об интеграции модуля «Экспорт на порталы + API» с торговой площадкой Wildberries, а также содержит информацию об особенностях выгрузки на Wildberries, частых проблемах и способах их решения.

На момент написания статьи актуальная версия API Wildberries – 1.4, версия модуля экспорта – 12.3.0, версия служебных инструментов АКРИТ – 6.4.10.

 

На стороне Wildberries актуальные понятия сейчас – карточка (одна страница), номенклатура (цвет), размер - это три уровня организации товаров на портале Wildberries, и все эти уровни должны выгружаться всегда, для каждого товара, но в разных случаях с разными особенностями.

На стороне модуля, который работает на системе управления сайтом 1С-Битрикс, структура иная: товар, а в нём (если задано) – торговые предложения.

Получается, одна из важнейших задач модуля – выгрузить одно- или двухуровневую систему товаров сайта в трёхуровневую систему Wildberries, на начальном этапе настроек это представляет основную сложность, при этом в разных случаях два уровня нужно выгружать по-разному.

Также это накладывает ограничения на выгружаемые данные. Например, на данный момент в модуле нет лёгкой возможности объединить в одной карточке несколько номенклатур, если для каждой из них должны быть заданы свои размеры: повторим, что структура Битрикса – двухуровневая, и именно в связи с этим возникает данного ограничение в рамках модуля.

Также, важно понимать, что в Wildberries существуют атрибуты – это дополнительные данные для товаров, и они отличаются для каждой категории, причём имеются атрибуты как необязательные, так и обязательные. Кроме того, некоторые атрибуты должны иметь значения, взятые из справочников Wildberries (т.е. не допускается передавать значения, взятые не из справочников – это приведёт к ошибке загрузке товара) – их возможные значения можно посмотреть, если в строке поля нажать на символ восклицательного знака.

Всё вышесказанное добавляет сложности как в понимании принципов успешной выгрузки товаров на Wildberries, так и в общий процесс настройки. Однако на данный момент, несмотря на все сложности и технические особенности Wildberries, все проблемы решаемы. Поэтому, рекомендуем внимательно ознакомиться с данной инструкцией, с описанием формата выгрузки (в профиле), и с подсказками, повсеместно оставленными в форме настроек профиля (символ вопроса, на который нужно навести курсор чтобы появился текст подсказки).

Базовая настройка профиля

Для начала работы необходимо выполнить предварительные действия:

1.       В личном кабинете Wildberries получить API-ключ, сразу скопируйте его себе,

2.       Установить модуль «Экспорт на порталы + API»,

3.       Создать в модуле новый профиль: плагин – «Wildberries.ru», формат – «Wildberries.ru (API) - Карточка товара NEW»,

4.       Ознакомьтесь с описанием (на главной странице профиля) – оно содержит важнейшую информацию для успешной настройки, к тому же оно периодически дополняется, поэтому иногда можете к нему возвращаться,

5.       В поле «Токен авторизации» скопируйте ключ, полученный в п.1, проверьте что он работает:

6.       Нажмите кнопку «Применить»,

7.       На вкладке «Настройки инфоблоков» выберите инфоблок с товарами, и выполните базовые настройки:

7.1.    Вкладка «Настройки ТП»: выберите необходимый режим работы, в зависимости от того, какую структуру карточек/номенклатур/размеров Вы хотите получить (это всё подробно описано на первой странице профиля).

7.2.    Вкладка «Категории»: выберите (при необходимости), из каких разделов каталога модуль должен отобрать товары для выгрузки (параметры «Режим выбранных разделов» и «Выгружать товары из следующих разделов»).

7.3.    Вкладка «Категории»: нажмите кнопку «Добавить категории». Появится окно, в котором нужно найти нужную категорию, после чего нажать кнопку «Сохранить». Этой настройкой мы сообщаем модулю, в какие категории Wildberries мы хотим выгружать товары. Можно выбрать несколько категорий, но, поверьте нам, что и с одной категорией зачастую сложно справиться. Более одной категории мы не рекомендуем, хотя технически это возможно, но с учётом всех нюансов Wildberries Вам будет очень сложно настроить выгрузку. Общее правило: чем меньше товаров выгружает профиль, тем легче его настроить.

7.4.    Вкладка «Категории»: после выбора категорий Wildberries нажмите кнопку «Загрузить атрибуты категорий». Это определит все выбранные Вами категории и загрузит для них атрибуты. Это очень важное действие, его необходимо выполнять всегда после выбора категории Wildberries. После окончания загрузки атрибутов обновите страницу (можно нажать «Применить», можно нажать F5 на клавиатуре).

7.5.    Вкладка «Фильтр товаров»: задайте условия, по которым будут отбираться товары. Для начала мы рекомендуем указать фильтр по ID товара, чтобы на примере одного товара проверять выгрузку – это лучший способ разобраться в особенностях настройки.

После выполнения указанных шагов профиль имеет базовые настройки, но ещё не готов для выгрузки. Необходимо заполнить поля. В зависимости от выбранного режима работы с ТП настройка полей требуется как для товаров, так и для торговых предложений: для выгрузки товара будут использованы поля товаров, для выгрузки ТП будут использованы поля ТП, хотя здесь много нюансов, о которых расскажем ниже.

 

Режимы работы с торговыми предложениями

Интеграция с Wildberries, как и модуль в целом, поддерживает четыре режима структуры, в зависимости от выбранного значения в параметре «Режим работы ТП».

В целом, общий смысл понятен по названию каждого из режимов, но для исключения недопонимания опишем их подробно.

Режим «Если у товара есть ТП - только ТП, иначе только товар»

Данный режим – это всего лишь автоматический выбор между двумя другими режимами: если для выгружаемого товара найдено хотя бы одно торговое предложение – активируется режим «Только ТП», иначе – режим «Только товары».

Режим «Выгружать все: и товары, и ТП»

В этом режиме модуль будет всегда выгружать одну номенклатуру с множеством вложенных размеров. Получается, что данные по номенклатуре (предмет, артикул, фотографии и атрибуты) берутся из товара, а размеры – из того же товара (если для товара в полях задано хотя одно из полей: techSize, wbSize, skus) и из вложенных товаров. В большинстве случаев сам товар не должен попадать в массив размеров sizes, поэтому в полях товаров не нужно заполнять эти три указанных поля. Тогда получится, что основа номенклатуры будет из товара (из вкладки «Поля товаров»), а размеры – только из торговых предложений (вкладка «Поля ТП») – т.е. так, как нужно в большинстве случаев выгрузки размерных товаров.

Режим «Только товары»

В отличие от остальных режимов, здесь абсолютно не учитываются торговые предложения, они никогда не выгружаются. Учитывая то, что массив sizes должен быть в любом случае, в него попадают данные из самого товара, т.е. получается, что в массиве sizes будет один элемент, в котором techSize, wbSize, skus и price будут взяты из полей товара.

Режим «Только ТП»

В отличие от остальных режимов, данный режим выгружает не одну номенклатуру, а сразу несколько (причём все они должны быть объединены на Wildberries в одну карточку).

Для каждого выгружаемого товара модуль находит торговые предложения, по каждому из которых и будет оформлена отдельная номенклатура. И в качестве данных для каждой из номенклатур (предмет, артикул, фотографии, атрибуты) будет взята информация только из вкладки «Поля ТП», при этом в массиве sizes каждой из номенклатур будет по одному элементу, взятому также из вкладки «Поля ТП» (techSize, wbSize, skus, price).

 

Таким образом, заполнение полей на обеих вкладках («Поля товаров» и «Поля ТП») требуется в зависимости от выбранного режима работы с торговыми предложениями: его необходимо выставлять в соответствии с желаемой структурой номенклатур/размеров.

 

Атрибуты товаров

Атрибуты товара – это дополнительные поля товаров, которые Wildberries задаёт для каждой категории отдельно. Они содержат дополнительную информацию о товаре: часть из них будет показана пользователям, часть – для служебного использования. При работе с модулем необходимо загружать атрибуты категорий (кнопка «Загрузить атрибуты категорий» на вкладке «Категории») после изменения выбранной категории Wildberries и применения изменений в профиле.

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

Однако работа с атрибутами – это основная сложность на втором этапе выгрузки (когда один тестовый товар успешно выгружен, и возникла задача выгрузки сразу нескольких или многих товаров). Для различных атрибутов существуют свои требования, в первую очередь это касается атрибутов-справочников, значения в которых обязательно должны соответствовать тем, которые «знает» Wildberries, выгрузка других значений приведёт к ошибке.

И в этом заключается основная сложность: на сайте в различных товарах могут быть различные значения, в различном виде, и их потребуется переводить к тому виду, которому ожидает увидеть Wildberries. Это можно сделать средствами модуля (обычно для этого используются замены в тексте, или программируемые обработчики), но наиболее простой, наглядный и эффективный способ – создавать для выгрузки на Wildberries отдельные свойства, в которых будут прописаны «нужные» значения, не требующие дополнительной обработки.

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

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

Атрибуты и категории товаров

Одним из атрибутов является атрибут «Предмет», указывающий на категорию товара, по которой определяются другие атрибуты.

В момент выгрузки модуль получает значение данного атрибута для товара, таким образом модуль «знает», в какую категорию будет выгружаться товар, и значит атрибуты будет использовать только для этой категории. Частая проблема заключается в том, что при попытке настроить в одном профиле несколько категорий вызывает большую путаницу: кажется, что атрибут должен выгружаться, ведь в профиле задано значение, а по факту не выгружается. А потом оказывается, что атрибут задан для одной категории, а для другой не задан.

 

Процесс выгрузки карточек

Когда профиль и поля товаров и предложений настроены, можно пробовать выгружать товары. Тестовую выгрузку можно выгружать в ручном режиме, нажимая на кнопку «Запустить» или «Запустить вручную», однако большие выгрузки рекомендуем выгружать через запуск в фоне или по расписанию, т.к. выгрузка товаров на Wildberries – длительный процесс, и запуск в фоне уменьшает вероятность ошибок, связанных с веб-сервером.

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

Затем, когда все товары переданы, выполняется следующий шаг – передача цен. Причём формирование цен идёт на первом этапе (данные для каждого товара берутся из полей и сохраняются в служебные данные, которые можно посмотреть в предпросмотре – например, нажать Alt-F в профиле) для каждого товара, а на втором этапе – передача собранных ранее данных. Передача цен выполняется относительно долго, т.к. согласно документации, мы должны указывать ID номенклатуры для каждого товара, т.е. модуль должен для товара запросить данные, и взять ID номенклатуры.

На третьем этапе выполняется отправка остатков. Причём остатки, согласно документации, отправляются по штрихкоду, указанному в нашей выгрузке, поэтому дополнительные запросы не требуются, и поэтому остатки выгружаются пакетами по 100 товаров.

Разберём подробно процесс отправки основных данных по товару (первый этап).

Как было указано ранее, в зависимости от выбранного режима работы с торговыми предложениями, модуль составляет для каждого товара необходимую структуру в виде JSON-объекта (представляющему карточку будущего товара), к которому предъявляются строгие требования:

• карточка товара – это контейнер для номенклатур (условно, массив номенклатур), поэтому в предпросмотре этот объект должен выглядеть как [номенклатура1, номенклатура2], например, [{“vendorCode”: “test1”, “characteristics”: {…}, …}], [{“vendorCode”: “test2”, “characteristics”: {…}, …}]

• в каждой номенклатуре всегда должны быть три элемента – vendorCode (артикул), characteristics (атрибуты) и sizes (размеры). Каждый атрибут – это отдельный вложенный в characteristics объект, структура которого зависит от множественности: единичные выгружаются в простом виде {“key”: “value”}, а множественные – в виде {“key“:[“value1”, “value2”]}. В объекте sizes выгружаются размеры, каждый из которых должен содержать следующие поля: techSize (размер поставщика), wbSize (российский размер), цена в рублях, баркоды (в виде массива).

Подробно расскажем про артикул (vendorCode). Это основное поле для привязки товаров. Именно по данному полю модуль определяет какую операцию следует выполнить для товара – создание нового товара (если в личном кабинете продавца ещё нет номенклатуры с таким артикулом), либо обновление существующей номенклатуры (если она уже загружена ранее).

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

Таким образом, главное правило привязок (связей товаров на сайте и на Wildberries) – совпадение передаваемых артикулов с артикулами на Wildberries.

В качестве проверки Вы можете самостоятельно смотреть карточки товаров – как полный список, так и карточки по фильтру (то, что будет искать модуль при выгрузке каждого товара) – это всё выполняется на вкладке «Проверка API» в профиле.

В момент окончания выгрузки карточки модуль сохраняет элемент в историю задач выгрузки (на вкладке «Лог и история», внизу), вне зависимости от успеха операции. Важный нюанс: в режиме выгрузки только цен и остатков история задач выгрузки не ведётся. В истории задач по каждой карточке можно посмотреть тип операции (создание [/content/v1/cards/upload] или обновление [/content/v1/cards/update]), результат выполнения запроса (код ответа должен быть 200), отправленный JSON-объект и полученный результат.

На данном этапе очень важно понимать следующее: модуль просто выгружает подряд все товары, проверяя только факт успешной выгрузки. При этом, успешно выгруженные товары не обязательно будут выгружены на Wildberries. В случае наличия каких-то проблем в данных товары будут размещены в разделе «Черновики», где по каждому из товаров будет показана проблема, из-за которой он не выгрузился. Черновик можно удалить (только в личном кабинете), а можно исправить данные и выгрузить снова – при успехе черновик удалится, и будет создан новый товар.

Далее, нужно также понимать, что, если товар успешно отправлен с сайта, модуль сразу выгружает его фотографии. При этом, если товар был добавлен в черновик, его на Wildberries не существует как товара, поэтому выгрузка фотографий приведёт к ошибке «Ошибка выгрузки фотографий для … Неверный запрос: по данному артикулу не нашлось карточки товара». В данном случае эта ошибку решать отдельно не нужно, она решится сама, как только товар будет успешно выгружен (не попадая в статус черновика).

 

Некоторые особенности выгрузки

Баркоды

Wildberries запрещает изменение баркода. Другими словами, если Вы ранее в товаре выгрузили размер с баркодом TEST123 – покуда этот товар существует, в нём всегда должен выгружаться размер с таким баркодом. Соответственно, менять баркоды также нельзя.

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

Чтобы отменить это поведение модуля, на главной странице профиля была добавлена опция «Не дополнять массив sizes из ранее выгруженного товара», однако она необходима лишь для тестирования – т.к. если проблема имеется, эта галочка не способна её решить, но она способна показать, что выгрузка в обычном режиме также не работает (т.к. иногда возникает желание проверить).

 

Выгрузка цен

При выгрузке цен иногда может возникать ошибка «данных номенклатур не было в выгруженном с портала шаблоне: […], добавление строк в шаблон запрещено» - по информации разработчиков, в таком случае необходимо просто подождать, однако в случае если это не помогает, необходимо обратиться в техподдержку Wildberries.

Также, Wildberries теперь запрещает поднимать цену за один раз более чем на 20%. Т.е. если на какой-либо существующий товар цена в новой выгрузке поднялась более чем на 20%, выгрузка цены по такому товару не пройдёт.

Последние обновления модуля добавляют механизм, корректирующий цены: теперь поднятие цены за одну выгрузку ограничивается в 20%. Непосредственно перед отправкой цен модуль запрашивает данные по ценам из Wildberries, и, зная актуальные цены, уменьшает значения цен в выгрузке. Например, модуль видит, что для товара цена на WB сейчас 500р, а Вы пытаетесь выгрузить 1000р – модуль выгрузит цену 600р, при следующей загрузке – 720р, затем – 864р, и только потом 1000р. При этом интервал между выгрузками должен быть значительный – не менее 1-2 минут (а иногда и более), т.к. цены на WB меняются не сразу после выгрузки.

Таким образом, правильная цена выгружается только через несколько раз. Это неудобно, но это единственное, как можно обойти данную проблему. Поэтому, при выгрузке цен теперь необходимо заглядывать в лог, если там есть сообщения о частичном поднятии цен – значит, потребуется дополнительная выгрузка.

При выгрузке цен в логе часто можно встретить ошибку «все номенклатуры с ценами из списка уже загружены, новая загрузка не создана». Собственно, это не ошибка. Это уведомление, которое говорит о том, что выгрузка цен не требуется, т.к. эти цены уже заданы. Т.е. если на WB товар имеет цену 1000руб, то выгрузка цены 1000руб приведёт к данной ошибке. Эту ошибку нужно игнорировать. В скором времени надеемся, что WB прекратит считать это ошибкой.

 

Выгрузка в режиме только цен и остатков

На главной странице профиля имеется галочка «Режим выгрузки только цен и остатков», которая добавляет в выгрузку новый режим работы: в таком режиме карточки товаров не выгружаются (не создаются и не обновляются), а выгружаются только цены и остатки.

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

При этом, нужно понимать, что выгрузка только цен и остатков будет выполняться не мгновенно (как, например, на других торговых площадках), т.к. для обновления цен мы вынуждены запрашивать идентификаторы номенклатур из Wildberries.

Внимание! В режиме выгрузки только цен заполнение баркода также является обязательным, но не для выгрузки, а для построения общей структуры товара, чтобы правильно построить структуру карточки/номенклатуры, и правильно выбрать цену (из товара или из ТП).

 

Размерные и безразмерные товары

На Wildberries можно выгружать как размерные товары (напр., футболки), так и безразмерные (напр, игрушки), в случае с размерными товарами указание размера поставщика и российского размера обязательно, а в случае с безразмерными товарами указание размеров запрещено – в этом случае в качестве размера поставщика нужно указать ноль, а в российском размере ничего не указывать, чтобы была передана пустая строка (пустая строка – это не пробел, это строка длиной 0 символов).

 

Выгрузка фотографий

В качестве фотографий можно выгружать только изображения формата JPG и PNG (расширения .jpg и .png). Другие расширения не разрешены.

Также, при настройке поля с фотографией в профиле, следите, чтобы в настройках поля в параметре «Режим множественных значений» было значение «Оставить множественным», иначе выгрузка более чем одного изображения будет приводить к ошибке.

 

Дополнительные рекомендации

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

Наименование (атрибут, имеется не во всех категориях) должно иметь длину не более 60 символов.

Атрибут ТНВЭД должен выгружаться только числом, без текстового пояснения.

Результаты загрузки цен в личном кабинете можно посмотреть в разделе «Цены и скидки» - «История загрузок», а текущие цены можно скачать в разделе «Цены и скидки» - «Установка цены» (сначала нажать «СФОРМИРОВАТЬ EXCEL С ТЕКУЩИМИ ДАННЫМИ», затем «СКАЧАТЬ EXCEL»).

Самая важная рекомендация в работе с выгрузкой на Wildberries – просматривайте лог, в тексте ошибок часто содержится вся информация, причём на русском языке, нужно лишь понять для какого товара возникла ошибка и почему (хотя некоторые ошибки всё же мало понятны по смыслу).

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

Проверка API

В профиле доступна вкладка «Проверка API». Она создана для ручной проверки методов согласно документации на сайте https://openapi.wb.ru/. Эти инструменты могут очень пригодиться при отладке (поиске проблем).

Например, вкладка «Карточки» позволяет просмотреть все товары, доступные в Вашем личном кабинете на Wilbderries. Это в некоторых случаях очень полезно, однако следует понимать, что в данном функционале очень неудобная постраничная навигация (так сделано на Wildberries): для перехода к следующей странице необходимо указать два поля из ответа на предыдущий запрос (updatedAt и nmID). Галочка «Автопагинация» сделана для того, чтобы эти два параметра автоматически подставлялись в соответствующие поля, таким образом при включённой автопагинации каждое следующее нажатие кнопки «Загрузить список карточек» открывает следующую страницу.

На вкладке «Фильтр» можно по артикулу найти номенклатуры – это именно то, что делает модуль перед выгрузкой каждого товара (для получения дополнительных служебных данных о товаре).

Очень полезная вкладка «Черновики» - она позволяет увидеть ошибки выгрузки. Черновики работают так, что пока данные по конкретному артикулу некорректные, они всегда попадают в черновик. Как только загружены корректные данные без ошибок, черновик становится карточкой товара. В личном кабинете черновики можно удалять.

На вкладке «Характеристики» можно получить список характеристик для категории (нужно указать название категории).

Вкладка «Цены» позволяет получить полный список цен. При этом, WB не предоставляет возможности просмотра только по одной номенклатуре – поэтому, модуль всегда получает цены для всех товаров личного кабинета (если много цен, вкладка браузера может подвисать), а если указать идентификатор номенклатуры – модуль из полученного полного набора данных отфильтрует данные для указанной номенклатуры.

Вкладка «Установка цены» позволяет вручную установить цену для одной заданной номенклатуры. Может быть очень полезно при поиске проблем, когда модуль по какой-то причине не выгружает цены. Проблемы с выгрузкой цен могут быть различные. Одна из возможных проблем – цена на товар не изменяется с ошибкой «на следующие номенклатуры указана слишком высокая цена. Рост более 20 процентов» - причём это может быть даже в случае, когда изменение цены составляет даже менее 1 процента – по таким ошибкам необходимо обращаться в техподдержку Wilbderries.