Документація
RU UK
Особистий кабінет

Довідник адрес

Кожна адреса API: потрібне право, параметри, приклад запиту й відповіді, опис усіх полів.

На цій сторінці

Тут описано кожну адресу API: яке право вона потребує, які параметри приймає, що віддає і що означає кожне поле відповіді. Усі адреси відповідають JSON. Дані віддаються за GET, а дві адреси замовлень, POST /orders/check і POST /orders, приймають POST. Загальні правила запитів, вигляд значень і посторінкову видачу описано на сторінці «Запити та відповіді».

У прикладах магазин працює на shop.example.ua, а замість <ключ> підставляється ключ повністю, разом із номером і вертикальною рискою.

Адреса Право Список
GET /api/v1/me не потрібне ні
GET /api/v1/shop shop:read ні
GET /api/v1/storefronts shop:read так
GET /api/v1/order_statuses shop:read так
GET /api/v1/payment_methods shop:read так
GET /api/v1/shipping_methods shop:read так
GET /api/v1/warehouses shop:read так
GET /api/v1/customer_groups shop:read так
GET /api/v1/contact_types shop:read так
GET /api/v1/tax_rates shop:read так
GET /api/v1/categories catalog:read так
GET /api/v1/brands catalog:read так
GET /api/v1/product_types catalog:read так
GET /api/v1/features catalog:read так
GET /api/v1/products catalog:read так
GET /api/v1/products/{id} catalog:read ні
GET /api/v1/products/ids catalog:read так
GET /api/v1/skus catalog:read так
GET /api/v1/prices prices:read так
GET /api/v1/inventory inventory:read так
POST /api/v1/orders/check orders:create ні
POST /api/v1/orders orders:create ні
GET /api/v1/orders orders:read так
GET /api/v1/orders/{id} orders:read ні

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

Усі списки приймають параметри limit (від 1 до 200, типово 50) і offset (від 0, типово 0) і віддають поруч із data поля meta і links. Винятків два: /products/ids віддає типово 5000 номерів, щонайбільше 10 000, а /prices із параметром sku_ids віддає типово 100 записів.

Будь-яка інша адреса всередині /api/v1 відповідає 404 з кодом not_found, а наявна адреса з іншим методом відповідає 405 з кодом method_not_allowed.

Окремо стоїть GET /api/v1/openapi.json, опис API у форматі OpenAPI 3.1 для Postman і Swagger. Ключ йому не потрібен. Запити до нього не потрапляють у журнал, і заголовка X-Request-Id у відповіді немає. Як ним користуватися, розказано на сторінці «Що вміє API магазину».

GET /api/v1/me

Відомості про ключ, яким зроблено запит. Права не потрібні, адреса відповідає будь-якому чинному ключу. З неї зручно починати, щоб перевірити, що ключ працює і які права він має.

curl https://shop.example.ua/api/v1/me \
  -H "Authorization: Bearer <ключ>"

{
    "data": {
        "id": 3,
        "name": "Сайт партнера",
        "kind": "integration",
        "contact": { "id": 418, "name": "ФОП Коваленко" },
        "scopes": ["shop:read", "catalog:read", "prices:read", "inventory:read"],
        "rate_limit_per_minute": 120,
        "expires_at": "2026-12-31T21:59:59Z",
        "settings_changed_at": "2026-10-15T08:12:40Z",
        "api_version": "1"
    }
}
Поле Тип Що означає
id ціле номер ключа в магазині
name рядок назва ключа, яку власник задав у полі «Назва ключа»
kind рядок вид ключа. Зараз завжди integration
contact об’єкт контакт магазину, якому видано ключ. Ключ без контакту не працює, тому поле є завжди
contact.id ціле номер контакту
contact.name рядок ім’я контакту, як його записано в магазині
scopes масив рядків коди прав ключа, наприклад shop:read. Усі коди перелічено на сторінці «Ключі доступу та права»
rate_limit_per_minute ціле скільки запитів за хвилину магазин прийме за цим ключем
expires_at дата або null коли ключ перестане працювати, в UTC. null — ключ безстроковий
settings_changed_at дата або null час в UTC, коли власник востаннє змінив у ключа права, «Як віддавати залишки», «З яких складів» або «Опис товару» чи переніс ваш контакт до іншої категорії покупців. Категорію контакт може змінити й автоматично, за умовами категорій. null — нічого з цього не змінювали відтоді, як ключ видано. Назва ключа й обмеження цей час не зсувають. Якщо він пізніший за вашу минулу звірку, заберіть каталог, ціни й залишки заново. Докладно в розділі «Зміни: updated_since»
api_version рядок версія API, зараз "1"

GET /api/v1/shop

Основні налаштування магазину: назва, країна, часовий пояс, валюти, мови й одиниці продажу. Право: shop:read.

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

{
    "data": {
        "name": "CartiX Демо",
        "country": "UA",
        "timezone": "Europe/Kyiv",
        "base_currency": "UAH",
        "currencies": [
            { "code": "UAH", "rate": "1.000000" },
            { "code": "USD", "rate": "41.250000" },
            { "code": "EUR", "rate": "48.100000" }
        ],
        "locales": ["ru", "uk", "en"],
        "main_locale": "ru",
        "units": ["pcs", "m", "kg", "g", "l", "m²"]
    }
}
Поле Тип Що означає
name рядок назва магазину з його загальних налаштувань
country рядок країна магазину, дволітерний код ISO 3166-1, наприклад UA
timezone рядок часовий пояс магазину у форматі IANA, наприклад Europe/Kyiv. За ним рахуються терміни дії ключів і всі «сьогодні» в магазині
base_currency рядок основна валюта магазину, код ISO 4217. У ній зберігаються ціни
currencies масив валюти магазину з курсами
currencies[].code рядок код валюти ISO 4217
currencies[].rate рядок курс, тобто скільки основної валюти коштує одна одиниця цієї валюти. Шість знаків після крапки. В основної валюти завжди "1.000000"
locales масив рядків коди мов, увімкнених у магазині
main_locale рядок основна мова магазину
units масив рядків коди стандартних одиниць продажу: pcs штуки, m метри, kg кілограми, g грами, l літри, m² квадратні метри

Курс читається так: якщо в USD "rate": "41.250000", а основна валюта UAH, один долар коштує 41,25 гривні. Суму в доларах отримують діленням суми в гривнях на курс.

GET /api/v1/storefronts

Вітрини магазину. Один магазин може мати кілька сайтів-вітрин зі своїм доменом, валютою та мовами. Право: shop:read. Порядок: спершу основна вітрина, далі решта за номером.

curl https://shop.example.ua/api/v1/storefronts \
  -H "Authorization: Bearer <ключ>"

{
    "data": [
        {
            "id": 1,
            "name": "Основна вітрина",
            "domain": "shop.example.ua",
            "currency": "UAH",
            "locales": ["ru", "uk", "en"],
            "default_locale": "uk",
            "is_default": true,
            "is_enabled": true
        }
    ],
    "meta": { "total": 1, "limit": 50, "offset": 0 },
    "links": { "next": null, "prev": null }
}
Поле Тип Що означає
id ціле номер вітрини
name рядок назва вітрини в панелі
domain рядок домен вітрини без протоколу
currency рядок валюта, у якій вітрина показує ціни, код ISO 4217
locales масив рядків мови вітрини
default_locale рядок мова, якою вітрина відкривається типово
is_default логічне основна вітрина магазину
is_enabled логічне вітрину ввімкнено

GET /api/v1/order_statuses

Статуси замовлення й переходи між ними. Право: shop:read. Порядок: як статуси розставлено в налаштуваннях магазину.

Статус має номер id і код code, обидва не повторюються. Код власник може змінити в налаштуваннях, крім коду refunded, а номер статусу не змінюється.

curl https://shop.example.ua/api/v1/order_statuses \
  -H "Authorization: Bearer <ключ>"

{
    "data": [
        {
            "id": 1,
            "code": "new",
            "name": { "ru": "Новый", "uk": "Новий", "en": "New" },
            "color": "#f59e0b",
            "is_default": true,
            "is_final": false,
            "marks_paid": false,
            "transitions": ["processing", "canceled", "refunded"]
        },
        {
            "id": 4,
            "code": "delivered",
            "name": { "ru": "Доставлен", "uk": "Доставлено", "en": "Delivered" },
            "color": "#10b981",
            "is_default": false,
            "is_final": true,
            "marks_paid": false,
            "transitions": []
        }
    ],
    "meta": { "total": 2, "limit": 50, "offset": 0 },
    "links": { "next": null, "prev": null }
}
Поле Тип Що означає
id ціле номер статусу
code рядок код статусу, наприклад new, processing, shipped, delivered, canceled. Власник може заводити власні статуси з власними кодами
name об’єкт або null назва статусу мовами магазину. Мова, якою статус не перекладено, в об’єкт не потрапляє. null — назви немає жодною мовою
color рядок колір статусу в панелі, у вигляді #rrggbb
is_default логічне з цього статусу починається кожне нове замовлення
is_final логічне завершальний статус, замовлення в ньому вважається закритим
marks_paid логічне перехід у цей статус позначає замовлення оплаченим
transitions масив рядків або null коди статусів, у які можна перевести замовлення з цього. null — переходи не обмежено, у будь-який статус. Порожній масив — із цього статусу перейти нікуди не можна

Статус із кодом refunded («Повернення») є в кожному магазині. Його код не змінюється, а перехід у нього повертає покупцеві гроші й закриває замовлення.

GET /api/v1/payment_methods

Способи оплати. Право: shop:read. Порядок: як способи розставлено в налаштуваннях магазину. Налаштувань способів, зокрема ключів платіжних систем, API не віддає ніколи.

curl https://shop.example.ua/api/v1/payment_methods \
  -H "Authorization: Bearer <ключ>"

{
    "data": [
        {
            "id": 1,
            "code": "cash_on_delivery",
            "name": { "ru": "Оплата при получении", "uk": "Оплата під час отримання", "en": "Cash on delivery" },
            "is_enabled": true,
            "all_storefronts": false
        },
        {
            "id": 5,
            "code": "wayforpay",
            "name": { "ru": "WayForPay", "uk": "WayForPay", "en": "WayForPay" },
            "is_enabled": true,
            "all_storefronts": true
        }
    ],
    "meta": { "total": 2, "limit": 50, "offset": 0 },
    "links": { "next": null, "prev": null }
}
Поле Тип Що означає
id ціле номер способу. Позначайте спосіб цим номером
code рядок вид способу, тобто як приймається оплата, наприклад cash_on_delivery, invoice, liqpay чи monobank. Способів одного виду може бути кілька, тому код не унікальний
name об’єкт назва способу мовами магазину. Якщо якоюсь мовою спосіб не перекладено, цією мовою стоїть основна назва. Так само спосіб бачить і покупець
is_enabled логічне спосіб увімкнено
all_storefronts логічне true — спосіб доступний на всіх вітринах. false — лише на вітринах, обраних у його налаштуваннях

GET /api/v1/shipping_methods

Способи доставки. Право: shop:read. Поля й порядок ті самі, що й у способів оплати. Налаштувань способів, зокрема ключів служб доставки, API не віддає.

curl https://shop.example.ua/api/v1/shipping_methods \
  -H "Authorization: Bearer <ключ>"

{
    "data": [
        {
            "id": 23,
            "code": "local_delivery",
            "name": { "ru": "Курьер по городу", "uk": "Кур’єр містом", "en": "City courier" },
            "is_enabled": true,
            "all_storefronts": true
        },
        {
            "id": 24,
            "code": "local_delivery",
            "name": { "ru": "Доставка по тарифам", "uk": "Доставка за тарифами", "en": "Доставка по тарифам" },
            "is_enabled": true,
            "all_storefronts": true
        }
    ],
    "meta": { "total": 2, "limit": 50, "offset": 0 },
    "links": { "next": null, "prev": null }
}
Поле Тип Що означає
id ціле номер способу
code рядок вид доставки, наприклад free_shipping, local_delivery. У прикладі два способи мають один вид, розрізняються вони номером
name об’єкт назва способу мовами магазину. Другий спосіб у прикладі не має англійського перекладу, тому для en стоїть основна назва
is_enabled логічне спосіб увімкнено
all_storefronts логічне true — спосіб доступний на всіх вітринах, false — лише на обраних

GET /api/v1/warehouses

Склади магазину. Право: shop:read. Порядок: за пріоритетом складу, далі за номером.

curl https://shop.example.ua/api/v1/warehouses \
  -H "Authorization: Bearer <ключ>"

{
    "data": [
        { "id": 1, "name": "Основний", "type": "real", "city": "Київ", "is_pickup": true, "is_enabled": true },
        { "id": 2, "name": "Склад у Львові", "type": "real", "city": "Львів", "is_pickup": false, "is_enabled": true },
        { "id": 5, "name": "Усі склади", "type": "virtual", "city": null, "is_pickup": false, "is_enabled": true }
    ],
    "meta": { "total": 3, "limit": 50, "offset": 0 },
    "links": { "next": null, "prev": null }
}
Поле Тип Що означає
id ціле номер складу
name рядок назва складу
type рядок real — справжній склад із товаром. virtual — збірний склад, що об’єднує кілька справжніх
city рядок або null місто складу, якщо його вказано
is_pickup логічне зі складу можна забрати замовлення самовивозом
is_enabled логічне склад увімкнено

GET /api/v1/customer_groups

Категорії покупців, наприклад «Роздріб», «Оптовики», «Постійні». За категорією магазин дає покупцям особливі ціни. Право: shop:read. Порядок: за пріоритетом категорії від більшого до меншого, далі за назвою.

curl https://shop.example.ua/api/v1/customer_groups \
  -H "Authorization: Bearer <ключ>"

{
    "data": [
        { "id": 3, "code": "wholesale", "name": "Оптовики", "is_default": false, "is_enabled": true },
        { "id": 2, "code": "regular", "name": "Постійні", "is_default": false, "is_enabled": true },
        { "id": 1, "code": "retail", "name": "Роздріб", "is_default": true, "is_enabled": true }
    ],
    "meta": { "total": 3, "limit": 50, "offset": 0 },
    "links": { "next": null, "prev": null }
}
Поле Тип Що означає
id ціле номер категорії
code рядок код категорії латиницею
name рядок назва категорії
is_default логічне до цієї категорії потрапляють нові покупці. Така категорія в магазині одна або її немає
is_enabled логічне категорію ввімкнено

GET /api/v1/contact_types

Види контактів, тобто ким бувають покупці й партнери магазину. Право: shop:read. Порядок: як види розставлено в налаштуваннях магазину.

curl https://shop.example.ua/api/v1/contact_types \
  -H "Authorization: Bearer <ключ>"

{
    "data": [
        { "id": 1, "code": "person", "base_kind": "person", "name": { "ru": "Физлицо", "uk": "Фізособа", "en": "Person" } },
        { "id": 2, "code": "company", "base_kind": "company", "name": { "ru": "Компания", "uk": "Компанія", "en": "Company" } }
    ],
    "meta": { "total": 2, "limit": 50, "offset": 0 },
    "links": { "next": null, "prev": null }
}
Поле Тип Що означає
id ціле номер виду
code рядок код виду
base_kind рядок person — людина, company — компанія. Власник може завести власні види, але кожен із них належить до одного з цих двох
name об’єкт або null назва виду мовами магазину

GET /api/v1/tax_rates

Ставки податку. Податок у магазині вже входить у ціну товару, тому ставка нічого не додає до суми замовлення, а показує, який податок у ціні є. Право: shop:read. Порядок: як ставки розставлено в налаштуваннях магазину.

curl https://shop.example.ua/api/v1/tax_rates \
  -H "Authorization: Bearer <ключ>"

{
    "data": [
        { "id": 1, "name": "ПДВ 20%", "rate": "20.000", "is_default": true },
        { "id": 2, "name": "ПДВ 7%", "rate": "7.000", "is_default": false },
        { "id": 3, "name": "Без ПДВ", "rate": "0.000", "is_default": false }
    ],
    "meta": { "total": 3, "limit": 50, "offset": 0 },
    "links": { "next": null, "prev": null }
}
Поле Тип Що означає
id ціле номер ставки
name рядок назва ставки
rate рядок розмір ставки у відсотках, три знаки після крапки: "20.000" означає 20 %
is_default логічне основна ставка. Її отримують товари, яким ставку не задали. Основна ставка в магазині одна
Оновлено 21 жовтня 2026