Автоматизация работы с магазином Ozon с помощью Google-таблиц и Ozon Seller API.

Всем привет! Меня зовут Дмитрий, и я, вместе с командой GoogleSheets.ru, занимаюсь аналитикой и автоматизацией бизнеса и его интеграцией во внешние системы. Для этих целей мы разрабатываем различные веб-сервисы и приложения, но иногда, когда это рационально, используем Google-таблицы и скрипты Google Apps Script (дальше я их буду называть просто скриптами).

Я веду рубрику "Ozon и Google-таблицы: продаём товары «в клеточках»" вместе с площадкой Озон для разработчиков, где рассказываю о способах интеграции Google-таблиц с магазином Ozon с помощью Ozon Seller API и хотел бы поделиться этим материалом с аудиторией Хабра.

Мой опыт автоматизации бизнеса говорит о том, что Google-таблицами для решения тех или иных задач, связанных с работой на маркетплейсах, не пользуются две категории продавцов. Первая категория — это по-настоящему большой бизнес, использующий специальные и дорогие решения, а вторая — те, кто про этот инструмент по каким-то причинам ещё не знают. Согласитесь, большинство продавцов в эти категории не попадает.

Когда-то давно я уже публиковал решение и библиотеку для переноса цен из Google-таблицы, но с того времени возможности Ozon Seller API сильно расширились, да и методы изменились. Поэтому, несмотря на то что старая версия API ещё работает, библиотека уже не является актуальной, а реализация методов текущей версии API применительно к скриптам требует отдельного рассмотрения и демонстрации.

Я собираюсь в нескольких статьях раскрыть реализацию методов актуального Ozon Seller API применительно к Google-таблицам и продемонстрировать их практическое применение в интересах продавца. А начну я с ответа на самый частый вопрос, который мне задают: «Как выгрузить товары из Ozon в Google-таблицу?». 

Библиотека

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

Библиотека опубликована на GitHub, где её можно рассмотреть более подробно, а все методы и типы в ней полностью соответствуют официальной документации Ozon Seller API. Чтобы можно было поставить себе галочку за соблюдение принципа разделения ответственности, упростить поддержку и исключить путаницу, ничего, кроме того, что есть в документации, в этой библиотеке нет. Различные функции-помощники, синтаксический сахар и вообще всё, что не касается методов Ozon Seller API, будет в статьях и таблице-примере.

Инструкция как подключить библиотеку к скрипту ниже

Итак, библиотека подключена. Теперь нужно подключить службу Sheets, потому что для работы с таблицей мы будем использовать Google Sheets API, что существенно ускорит выполнение скрипта, особенно в операциях записи данных. Так же подробно инструкцию я расписывать не буду, так как она гораздо проще. Нужно нажать на иконку «+» напротив раздела «Сервисы» и выбрать «Google Sheets API», ничего не меняя.

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

Скрипт для загрузки товаров

Давайте теперь разберёмся со структурой скрипта. Из иллюстраций к инструкции о подключении библиотеки к скрипту видно, что я разделил его на три файла: index, tools и configs. В файле index будут размещены основные исполняемые функции, в tools — функции-помощники для обработки данных и рутинных действий, а в configs — константы с настройками.

Настройки

Позволю себе не рассказывать о том, как получить ключи для доступа к API. На эту тему доступно очень много материалов — уверен, это не составит для вас проблемы. Тем не менее это самый важный пункт настроек, без которого точно ничего не получится. Открываем файл configs и первым делом меняем ключи на свои.

Теперь нужно определить, куда и какие данные записывать.

Для того чтобы определить лист для записи данных о товарах, нужно вписать его название в переменную ProductsSheetName. Обязательно убедитесь, что лист с таким названием есть в таблице, иначе получите ошибку при выполнении скрипта.

Далее в том же файле в качестве переменной fieldsToShow определён массив с перечнем всех полей, которые возвращаются API в объекте товара, и их описаниями.

/**Перечень и описание всех полей товара
 * Если какое-то из них не нужно в таблице,
 * поле достаточно просто закомментировать ("//" в начале строки)
 * или наоборот, убрать "//" из начала строки, чтобы это полу выводилось в таблицу
 */
const fieldsToShow = [
    'barcode' /** Штрихкод. */,
    // 'barcodes',  /** Все штрихкоды товара. */
    'buybox_price' /** Цена главного предложения на Ozon. */,
    // 'category_id',  /** Идентификатор категории. */
    // 'color_image',  /** Маркетинговый цвет. */
    'created_at' /** Дата и время создания товара. */,
    'fbo_sku' /** SKU товара, который продаётся со склада Ozon (FBO).*/,
    'fbs_sku' /** SKU товара, который продаётся со склада продавца (FBS и rFBS).*/,
    // 'id',  /** Номер задания на формирование документов. */
    /** Массив ссылок на изображения. Изображения в массиве расположены в порядке их расположения на сайте. Если параметр
     * `primary_image` не указан, первое изображение в массиве главное для товара.
     */
    // 'images',
    'primary_image' /** Главное изображение товара. */,
    // 'images360',  /** Массив изображений 360. */
    'has_discounted_item' /** Признак, что у товара есть уценённые аналоги на складе Ozon. */,
    /**
     * Признак, является ли товар уценённым:
     *   - Если товар создавался продавцом как уценённый — `true`.
     *   - Если товар не уценённый или был уценён Ozon — `false`.
     */
    'is_discounted',
    'discounted_stocks' /** Остатки уценённого товара на складе Ozon. */,
    'is_kgt' /** Признак крупногабаритного товара. */,
    /**
     * Валюта ваших цен. Cовпадает с валютой, которая установлена в настройках личного кабинета.
     * Возможные значения:
     *   - `RUB` — российский рубль,
     *   - `BYN` — белорусский рубль,
     *   - `KZT` — тенге,
     *   - `EUR` — евро,
     *   - `USD` — доллар США,
     *   - `CNY` — юань.
     */
    'currency_code',
    'marketing_price' /** Цена на товар с учётом всех акций. Это значение будет указано на витрине Ozon. */,
    'min_ozon_price' /** Минимальная цена на аналогичный товар на Ozon. */,
    'min_price' /** Минимальная цена товара после применения акций. */,
    'name' /** Название. */,
    'offer_id' /** Идентификатор товара в системе продавца — артикул. */,
    'old_price' /** Цена до учёта скидок. На карточке товара отображается зачёркнутой. */,
    'premium_price' /** Цена для клиентов с подпиской [Ozon Premium](https://docs.ozon.ru/common/ozon-premium/). */,
    'price' /** Цена товара с учётом скидок — это значение показывается на карточке товара. */,
    /** Ценовой индекс. Подробнее в [Базе знаний продавца]
     * (https://seller-edu.ozon.ru/docs/kontrol-kachestva/kak-my-kontroliruem-kachestvo-raboty-partnera.html#индекс-цен/).
     */
    'price_index',
    'recommended_price' /** Цена на товар, рекомендованная системой на основании схожих предложений. */,
    'status' /** Описание состояния товара. */,
    // 'sources',  /** Информация об источниках схожих предложений. */
    'stocks' /** Информация об остатках товара. */,
    'updated_at' /** Дата последнего обновления товара. */,
    // 'vat',  /** Ставка НДС для товара. */
    'visibility_details' /** Настройки видимости товара. */,
    'visible' /** Если товар выставлен на продажу — `true`. */,
];

Вы можете сами решить, какие из данных, перечисленных в этом массиве, вам нужно отображать в таблице. Для того чтобы исключить поле, достаточно его просто закомментировать. Обратите внимание, что данные, которые передаются по API от Ozon со временем могут измениться, поэтому при появлении новых полей в документации, их нужно будет внести и в скрипт.

И заключительный пункт настройки — настройка преобразования объектов с данными о товаре.

/** Настройки для обработки данных, полученных из Озон */
const flatConfig = {
    /** Как форматировать даты в ответе "date" - 29.03.2023; "dateTime" - 29.03.2023 15:08 */
    formatDate: 'dateTime',
    /** Список полей, которые нужно вывести в ответе, если не указан - выводятся
     *  все поля, за исключением указанных в списке excludeFields
     */
    onlyFields: fieldsToShow,
    /** Список полей, которые исключить из ответа. */
    excludeFields: [],
    /**Список полей, которые нужно оставить без изменений и преобразований */
    noFormatFields: ['offer_id'],
};

Эти настройки находятся в объекте flatConfig. Как раз в него передаются поля для вывода в таблице (свойство onlyFields). Также можно определить поля, которые нужно исключить из отображения в таблице, и те, которые нужно оставить без форматирования. Например, артикул 001234 в таблице будет числом 1234, потому что под капотом скриптов крутится JavaScript, известный своим коварством в подобных случаях. Именно поэтому в списке уже есть поле offer_id.

Ещё один элемент настройки — способ преобразования даты из исходного состояния в формат, понятный Google-таблицам. Тут можно определить, как значения даты и времени будут отображаться в таблице.

Получение данных о товарах из Ozon

С настройкой закончили. Теперь можно загружать данные о товарах.

Для того чтобы получить информацию о товарах API предоставляет два метода. Первый отдаёт их идентификаторы, согласно переданным условиям, а второй — возвращает полный перечень информации о переданном списке идентификаторов.

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

Как видно на иллюстрации ниже, в результате наших действий мы получим массив объектов с информацией о товарах и уровнем вложенности полей не более одного. Это необходимо для корректного преобразования данных в табличный формат. Данные для передачи в качестве параметров запросов в точности соответствуют документации, поэтому трудностей с их изменением возникнуть не должно.

Запись данных о товарах в Google-таблицу

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

Преобразование и запись данных в таблицу после их загрузки по API выглядит следующим образом:

function loadAndWriteProductsInfo() {
    /** Инициализируем апи клиент */
    const client = OzonApi.client(keys);
    const productsIdsListResponse = client.productApiGetProductList({
        filter: {
            /*  Можно отфильтровать по offer_id, чтобы получить другие данные о товаре */
            // offer_id: [''],
            /* или по product_id */
            // product_id: [''],
            /** Здесь фильтр "по видимости", подробнее - https://docs.ozon.ru/api/seller/#operation/ProductAPI_GetProductList */
            visibility: 'ALL',
        },
        limit: 20,
    });

    /** Пересобираем ответ со списком товаров в список offer_id */
    const productsOfferIds = productsIdsListResponse.result.items.map((item) => item.offer_id);

    /**Запрашиваем информацию о товарах по полученному списку offer_id */
    const productsInfoListResponse = client.productApiGetProductInfoListV2({
        offer_id: productsOfferIds,
    });
    /** 
     *  Достаем объекты с информацией о товарах из ответа Озон
     *  и "сплющиваем" объекты в соответствии с настройками "flatConfig"
     */
    const productsFlatCollection = productsInfoListResponse.result.items
        .map(product => flatter(product, flatConfig));
    
    /**
     * Пересобираем данные в формат, подходящий для записи в таблицу 
     * (массив массивов, где каждый вложенный массив - строка)
     */
    const productsInfoGrid = collectionToGrid(productsFlatCollection, { includeHeader: true });
    
    /**Записываем данные в таблицу на лист указанный в настройках с помощью Sheets Api */
    writeGridToTable(productsInfoGrid, productsSheetName);
    showMsg();
}

Функция для записи в таблицу вынесена в файл tools и выглядит так:

/**
 * Очищает и затем записывает данные в указанный лист таблицы
 * @param {Array<Array<string|number|undefined>>} grid - массив массивов(строк) с данными для записи
 * @param {string} sheetName - Имя листа, в который данные будут записываться
 */
function writeGridToTable(grid, sheetName) {
    const table = SpreadsheetApp.getActive();
    const tableId = table.getId();
    const sheetForWrite = table.getSheetByName(sheetName);

    const clearResult = Sheets.Spreadsheets.Values.clear(
        {},
        tableId,
        buildA1String(1, 1, 90, 1000000, sheetName),
    );
    const rangeForWrite = buildA1String(1, 1, grid[0].length, grid.length, sheetName);

    const writeResult = Sheets.Spreadsheets.Values.append(
        {
            majorDimension: 'ROWS',
            range: rangeForWrite,
            values: grid,
        },
        tableId,
        rangeForWrite,
        {
            valueInputOption: 'USER_ENTERED',
        },
    );
    table.toast('Данные успешно записаны', 'GoogleSheets.ru');
    return true;
}

И вообще рекомендую заглянуть в файл tools — там ещё много интересного.

Заключение

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

Я постарался максимально доступно не просто изложить инструкцию, а рассказать о самом решении, не останавливаясь при этом на разборе каждой строчки кода. 

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

Моё мнение по поводу информативности артикулов сильно изменилось, после того как я начал составлять названия товаров под ключевые запросы в категории. Теперь верю.)

Если у вас остались вопросы или что-то не получается, приходите в чатик «Таблицы и Скрипты Гугл», где мы помогаем разобраться с Таблицами и Скриптами.

А еще больше интересных интеграций, разбор реальных кейсов и хитрости при работе с Таблицами можно найти в нашем Телеграм-канале «Таблицы Гугл»