Товары


Товары являются одной из основных сущностей платформы Zenky.io. Каждый товар может быть помещён в различные категории, иметь список характеристик, вариантов и изображений.

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

Используемые структуры

Товар

{
    "id": "8ffdf871-fb9f-4465-b728-e54970ce5386",
    "short_id": "8ffdf871fb9fe538",
    "slug": "iphone-11-pro",
    "hidden": false,
    "track_inventory": false,
    "name": "iPhone 11 Pro",
    "description": "Революционная система трёх камер — гораздо больше возможностей и неизменная простота в использовании. Беспрецедентное увеличение ресурса аккумулятора. И потряса­ющий процессор с расши­ренной поддержкой технологий машинного обучения, который открывает для iPhone большие новые перспек­тивы. Представляем iPhone 11 Pro. Он достоин своего имени.",
    "single_variant": false,
    "unit_type": {
        "id": "piece",
        "name": "Штука",
        "short_name": "шт"
    },
    "weight": {
        "grams": 0,
        "full": "0 граммов",
        "short": "0 гр."
    },
    "share": null,
    "created_at": {
        "timezone": "Asia\/Irkutsk",
        "datetime_utc": "2020-03-01 00:00:00",
        "datetime": "2020-03-01 08:00:00",
        "datetime_at": "01.03.2020 в 08:00",
        "date": "01.03.2020",
        "diff": "1 год назад",
        "timestamp": 1583020800,
        "iso_utc": "2020-03-01T00:00:00+00:00",
        "iso": "2020-03-01T08:00:00+08:00"
    },
    "updated_at": {
        "timezone": "Asia\/Irkutsk",
        "datetime_utc": "2021-02-09 06:00:13",
        "datetime": "2021-02-09 14:00:13",
        "datetime_at": "09.02.2021 в 14:00",
        "date": "09.02.2021",
        "diff": "2 месяца назад",
        "timestamp": 1612850413,
        "iso_utc": "2021-02-09T06:00:13+00:00",
        "iso": "2021-02-09T14:00:13+08:00"
    }
}

Описание полей

Вариант товара

{
    "id": "8ffdfbd4-4b63-458a-930f-ec3dd5faf063",
    "product_id": "8ffdf871-fb9f-4465-b728-e54970ce5386",
    "discount_id": null,
    "name": "iPhone 11 Pro 64 ГБ Серый космос",
    "has_discount": false,
    "price": {
        "value": 8999000,
        "short": "89 990",
        "trimmed": "89990",
        "full": "89 990₽",
        "currency": {
            "code": "RUB",
            "name": "Российский рубль",
            "thousands_separator": " ",
            "decimals_separator": ".",
            "prefix": "",
            "suffix": "₽",
            "symbol": "₽"
        }
    },
    "original_price": null,
    "discount_difference": null,
    "discount_percentage": null,
    "sku": "iphone-11-pro-01",
    "barcode": "iphone-11-pro-01",
    "created_at": {
        "timezone": "Asia\/Irkutsk",
        "datetime_utc": "2020-03-01 00:00:00",
        "datetime": "2020-03-01 08:00:00",
        "datetime_at": "01.03.2020 в 08:00",
        "date": "01.03.2020",
        "diff": "1 год назад",
        "timestamp": 1583020800,
        "iso_utc": "2020-03-01T00:00:00+00:00",
        "iso": "2020-03-01T08:00:00+08:00"
    },
    "updated_at": {
        "timezone": "Asia\/Irkutsk",
        "datetime_utc": "2020-03-01 00:00:00",
        "datetime": "2020-03-01 08:00:00",
        "datetime_at": "01.03.2020 в 08:00",
        "date": "01.03.2020",
        "diff": "1 год назад",
        "timestamp": 1583020800,
        "iso_utc": "2020-03-01T00:00:00+00:00",
        "iso": "2020-03-01T08:00:00+08:00"
    },
    "prices": [
        {
            "id": "8ffdfd5d-2df0-49da-9107-8c9aab0967e3",
            "price_type_id": "8ffdea87-0960-4669-8bc8-4b23d6045535",
            "stock_id": null,
            "discount_id": null,
            "has_discount": false,
            "price": {
                "value": 8999000,
                "short": "89 990",
                "trimmed": "89990",
                "full": "89 990₽",
                "currency": {
                    "code": "RUB",
                    "name": "Российский рубль",
                    "thousands_separator": " ",
                    "decimals_separator": ".",
                    "prefix": "",
                    "suffix": "₽",
                    "symbol": "₽"
                }
            },
            "original_price": null,
            "discount_difference": null,
            "discount_percentage": null,
            "created_at": {
                "timezone": "Asia\/Irkutsk",
                "datetime_utc": "2020-03-01 00:00:00",
                "datetime": "2020-03-01 08:00:00",
                "datetime_at": "01.03.2020 в 08:00",
                "date": "01.03.2020",
                "diff": "1 год назад",
                "timestamp": 1583020800,
                "iso_utc": "2020-03-01T00:00:00+00:00",
                "iso": "2020-03-01T08:00:00+08:00"
            },
            "updated_at": {
                "timezone": "Asia\/Irkutsk",
                "datetime_utc": "2020-03-01 00:00:00",
                "datetime": "2020-03-01 08:00:00",
                "datetime_at": "01.03.2020 в 08:00",
                "date": "01.03.2020",
                "diff": "1 год назад",
                "timestamp": 1583020800,
                "iso_utc": "2020-03-01T00:00:00+00:00",
                "iso": "2020-03-01T08:00:00+08:00"
            }
        }
    ]
}

Описание полей

Короткие идентификаторы

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

Поле short_id является сокращённой версией оригинального идентификатора товара (поле id), а поле slug содержит в себе транслитерированное название товара, которое так же можно использовать в URL.

Короткие ID поддерживаются во всех методах API товаров.

Фильтрация товаров

Фильтрация по характеристикам

Фильтрация по характеристикам товаров описана в отдельном документе.

Фильтрация по ценам

Для фильтрации товаров по ценам можно использовать 2 GET-параметра: min_price для минимальной цены и max_price для максимальной цены. Значением может быть как целочисленное значение, так и значение с плавающей точкой (цена с копейками).

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

Если передаются оба параметра, значение параметра min_price должно быть меньше max_price.

Получение диапазона цен

Если вам необходимо отобразить в интерфейсе минимальную и максимальную цены товаров, эти значения можно получить, выполнить GET-запрос на URL https://api.zenky.io/v2/products/prices.

В ответе будет представлена следующая структура:

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

Если в указанной категории нет товаров, значением полей min и max будет NULL.

Фильтрация по видимости товаров

По умолчанию API списка товаров возвращает только публичные товары (такие товары, у которых поле hidden установлено в true).

Аутентифицированные пользователи, у которых есть доступ к выбранному магазину, могут так же получить скрытые товары с помощью фильтра visibility.

Фильтр visibility может иметь одно из следующих значений:

  • all — вернуть все товары (как скрытые, так и видимые);
  • hidden — вернуть только скрытые товары;
  • visible — вернуть только видимые товары (поведение по умолчанию).

Гости и пользователи, у которых нет доступа к магазину, не могут просматривать скрытые товары как в API списка, так и в API просмотра конкретного товара. Однако скрытый товар может выдаваться в других ответах API, где отсутствие скрытого товара может нарушать логику работы приложений.

Пересчёт стоимости

Для получения новой стоимости товаров с одним или несколькими выбранными модификаторами можно использовать отдельный API вместо ручного подсчёта.

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

Получение стоимости

Для получения стоимости необходимо отправить POST-запрос на URL https://api.zenky.io/v2/products/{productId}/variants/{variantId}/price ({productId} — ID товара, а {variantId} — ID варианта товара) со следующими полями:

Каждый элемент массива modifiers должен быть объектом со следующими полями:

Структура ответа

В ответе будет содержаться объект со следующей структурой (поле data опущено):

Использование данных

Поля price, original_price, has_discount, discount_difference и discount_percentage могут быть использованы для отображения новой цены покупателю. Мы рекомендуем сохранять аналогичные поля из объекта price варианта товара и отображать их в том случае, если покупатель не выбрал ни один модификатор.

По полю modifiers_hash можно определять, добавлен ли вариант товара с выбранным набором (и количеством) модификаторов в корзину (поле modifiers_hash варианта товара в корзине).

Методы

Список поддерживаемых методов для работы с товарами.

Список товаров

Просмотр товара

Удаление товара

Массовое удаление товаров