Справочники каталога

В справочниках каталога лежат категории, бренды, типы товаров и характеристики со всеми значениями. Товар ссылается на них номерами (category_ids, brand.id, type_id, options), поэтому справочники стоит забрать раньше товаров.

Все четыре адреса требуют права catalog:read, отдают списки страницами и принимают общие параметры limit, offset, locale и storefront_id. Что от них зависит и какие ошибки бывают, описано на странице «Каталог: видимость и синхронизация». Справочники короткие, поэтому просите их с limit=200.

Переводимые поля (name, value) приходят объектом по языкам магазина. Язык, на котором поле не заполнено, в объект не попадает, а если поле не заполнено ни на одном языке, приходит null.

GET /api/v1/categories#

Категории, видимые на витрине, плоским списком в порядке дерева. Сразу за разделом идут его подразделы. Право: catalog:read. Какие категории считаются видимыми, описано на странице «Каталог: видимость и синхронизация».

Листания по after_id у категорий нет. Список короткий, поэтому забирайте его целиком. Категория, которую выключили или отдали другой витрине, из списка пропадает. Уберите её и у себя.

curl "https://shop.example.ua/api/v1/categories?limit=200" \
  -H "Authorization: Bearer <ключ>"

{
    "data": [
        {
            "id": 303,
            "parent_id": null,
            "slug": "electrics-and-lighting",
            "name": { "ru": "Электрика и свет", "uk": "Електрика та світло", "en": "Electrics and lighting" },
            "type": "static",
            "depth": 0,
            "sort": 1,
            "url": "https://shop.example.ua/electrics-and-lighting/",
            "updated_at": "2026-08-13T18:20:34Z"
        },
        {
            "id": 304,
            "parent_id": 303,
            "slug": "lampochki",
            "name": { "ru": "Лампочки", "uk": "Лампочки" },
            "type": "static",
            "depth": 1,
            "sort": 2,
            "url": "https://shop.example.ua/electrics-and-lighting/lampochki/",
            "updated_at": "2026-10-17T07:34:44Z"
        },
        {
            "id": 330,
            "parent_id": 303,
            "slug": "do-100-grn",
            "name": { "ru": "Всё до 100 грн", "uk": "Усе до 100 грн" },
            "type": "dynamic",
            "depth": 1,
            "sort": 9,
            "url": "https://shop.example.ua/electrics-and-lighting/do-100-grn/",
            "updated_at": "2026-09-02T10:15:00Z"
        }
    ],
    "meta": { "total": 3, "limit": 200, "offset": 0 },
    "links": { "next": null, "prev": null }
}

Категории «по условиям» в поле category_ids товара не попадают, потому что магазин не проверяет условия для каждого товара в ответе. Чтобы получить товары такой категории, запросите /products?category_id=330. Этот фильтр подбирает товары по условиям категории так же, как витрина.

GET /api/v1/brands#

Бренды магазина. Право: catalog:read. Порядок: как значения расставлены в характеристике бренда, затем по номеру.

В магазине бренды хранятся как значения характеристики, которую владелец назначил брендом. Поэтому id бренда совпадает с номером этого значения. Тот же номер приходит в поле brand.id товара и принимается фильтром /products?brand_id=. Если характеристика бренда в магазине не назначена, список пустой.

Своих параметров у адреса нет.

curl "https://shop.example.ua/api/v1/brands?limit=200" \
  -H "Authorization: Bearer <ключ>"

{
    "data": [
        {
            "id": 2368,
            "slug": "philips",
            "name": { "ru": "Philips", "uk": "Philips", "en": "Philips" },
            "logo": "https://shop.example.ua/storage/brands/2/1040/philips.svg",
            "website": "https://www.philips.ua",
            "url": "https://shop.example.ua/brand/philips/"
        },
        {
            "id": 2375,
            "slug": null,
            "name": { "ru": "Feron" },
            "logo": null,
            "website": null,
            "url": null
        }
    ],
    "meta": { "total": 2, "limit": 200, "offset": 0 },
    "links": { "next": null, "prev": null }
}

Бренд, страницу которого владелец выключил или отдал другой витрине, в список не попадает. Бренд без страницы виден всегда.

GET /api/v1/product_types#

Типы товаров. Тип задаёт набор характеристик и единицу продажи, которые товар получает по умолчанию. Право: catalog:read. Порядок: как типы расставлены в настройках каталога, затем по номеру. От витрины список не зависит.

Своих параметров у адреса нет.

curl "https://shop.example.ua/api/v1/product_types?limit=200" \
  -H "Authorization: Bearer <ключ>"

{
    "data": [
        {
            "id": 83,
            "code": "lamps",
            "name": { "ru": "Лампы", "uk": "Лампи" },
            "unit": "pcs",
            "qty_step": "1.000",
            "qty_min": "1.000",
            "feature_ids": [605, 612, 615, 616, 627]
        },
        {
            "id": 91,
            "code": "cable",
            "name": { "ru": "Кабель", "uk": "Кабель" },
            "unit": "m",
            "qty_step": "0.500",
            "qty_min": "1.000",
            "feature_ids": [640, 641]
        }
    ],
    "meta": { "total": 2, "limit": 200, "offset": 0 },
    "links": { "next": null, "prev": null }
}

Единицу, шаг и минимум типа магазин подставляет товару, когда владелец заводит товар или меняет ему тип и не задаёт эти значения сам. Если потом владелец поправит настройки типа, у заведённых товаров ничего не поменяется. Единица продажи приходит в поле unit товара и одна для всех его артикулов. Шаг и наименьшее количество приходят у каждого артикула своими полями, ровно такими, какие применит корзина. Заказывайте по ним, а не по значениям типа.

GET /api/v1/features#

Характеристики со словарём значений. Право: catalog:read. Порядок: как характеристики расставлены в справочнике, затем по номеру. От витрины список не зависит.

Служебные характеристики, скрытые от покупателя, сюда не попадают. Опции покупки (for_skus: true) приходят всегда, даже скрытые, потому что на них ссылаются артикулы в поле options.

Своих параметров у адреса нет.

curl "https://shop.example.ua/api/v1/features?limit=200" \
  -H "Authorization: Bearer <ключ>"

{
    "data": [
        {
            "id": 616,
            "code": "light",
            "name": { "ru": "Свет", "uk": "Світло" },
            "type": "text",
            "format": "select",
            "dimension": null,
            "unit": null,
            "for_skus": true,
            "is_filterable": true,
            "applies_to_all_types": false,
            "product_type_ids": [83],
            "values": [
                { "id": 2426, "value": { "ru": "нейтральный", "uk": "нейтральне" }, "color": null },
                { "id": 2428, "value": { "ru": "холодный белый", "uk": "холодне біле" }, "color": null }
            ]
        },
        {
            "id": 596,
            "code": "color",
            "name": { "ru": "Цвет", "uk": "Колір" },
            "type": "color",
            "format": "select",
            "dimension": null,
            "unit": null,
            "for_skus": true,
            "is_filterable": true,
            "applies_to_all_types": true,
            "product_type_ids": [],
            "values": [
                { "id": 2348, "value": { "ru": "белый", "uk": "білий" }, "color": "#FFFFFF" }
            ]
        },
        {
            "id": 606,
            "code": "height",
            "name": { "ru": "Высота", "uk": "Висота" },
            "type": "number",
            "format": "single",
            "dimension": "length",
            "unit": "mm",
            "for_skus": false,
            "is_filterable": false,
            "applies_to_all_types": false,
            "product_type_ids": [83],
            "values": []
        }
    ],
    "meta": { "total": 3, "limit": 200, "offset": 0 },
    "links": { "next": null, "prev": null }
}