Довідники каталогу

У довідниках каталогу лежать категорії, бренди, типи товарів і характеристики з усіма значеннями. Товар посилається на них номерами (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&locale=uk" \
  -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/uk/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/uk/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/uk/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 }
}

У прикладі запит зроблено з locale=uk, тому посилання ведуть на українську версію вітрини.

Категорії «за умовами» до поля 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 }
}