Документация
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² квадратные метры

Курс читается так: при "rate": "41.250000" у USD и основной валюте 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