Ключі доступу та права

Ключ відкриває доступ до API магазину. Кожному, хто підключається, власник видає окремий ключ. Тоді в журналі видно, хто які запити робив, а доступ, який більше не потрібен, можна закрити, не зачепивши інших.

Власник видає ключ не співробітникові, а контакту магазину, дропшиперу чи партнеру. Якщо співробітник, який видав ключ, звільниться, ключ і далі працюватиме. А якщо видалити сам контакт, разом із ним видаляться й усі його ключі.

Хто може видавати ключі#

Розділ ключів відкритий співробітникам із правом «Видавати ключі API». Це окреме право в ролях співробітників, і право на налаштування магазину його не дає.

Як видати ключ#

1. Відкрийте «Налаштування платформи», у групі «Платформа» оберіть «API магазину».
2. Натисніть плюс біля заголовка «Ключі доступу». Праворуч відкриється форма «Новий ключ».
3. У полі «Кому видаєте ключ» знайдіть контакт за ім’ям або телефоном. Поле обов’язкове, бо за цим контактом магазин рахуватиме ціни й записуватиме замовлення, що надійшли через API. Обрати можна лише контакт, який ви бачите в панелі. З правом «Бачити всі контакти» це будь-який контакт, без нього лише закріплені за вами. Якщо контакти вам у панелі не відкриті зовсім, пошук нічого не знайде й видати ключ не вийде.
4. У полі «Назва ключа» напишіть, як ключ називатиметься в списку ключів і в журналі запитів. Якщо назва ще порожня, після вибору контакту магазин підставить у неї ім’я контакту.
5. У блоці «Що дозволено» позначте права. Право «Бачити налаштування й довідники магазину» вже позначене. Потрібне хоча б одне право.
6. Під правами з’являться блоки налаштувань. З правом «Бачити товари й категорії» — блок «Каталог», із правом «Бачити залишки» — «Залишки». З правом «Створювати нові замовлення» — «Замовлення партнера» і «Склади для замовлень». Якщо позначено і залишки, і замовлення, склади обирають у блоці «Залишки». Блоки можна не чіпати, тоді діють типові значення. Докладно їх описано нижче.
7. За потреби заповніть блок «Обмеження»: кількість запитів за хвилину, дозволені IP-адреси та термін дії. Усе це можна залишити порожнім.
8. Натисніть «Видати ключ».

Під полями контакту й назви з’явиться блок «Збережіть ключ зараз», у ньому ключ повністю й кнопка «Скопіювати». Передайте ключ тому, хто підключається. Магазин зберігає лише відбиток ключа, тому більше цей ключ ніде не з’явиться. Якщо ключ загубиться, видайте новий.

У блоці «Як підключити» на тій самій сторінці вказано адресу API магазину й готовий приклад запиту curl. Його можна надіслати розробникові разом із ключем.

Який вигляд має ключ#

12|ctx_Hq4bR7mPz0LwX3sYt8VnK2cJd5aEf9gUiO1hBqWe6a1c94f7

Ключ складається з номера, вертикальної риски й секрету, що починається з ctx_. Передавати його потрібно повністю, у заголовку кожного запиту:

Authorization: Bearer 12|ctx_Hq4bR7mPz0LwX3sYt8VnK2cJd5aEf9gUiO1hBqWe6a1c94f7

У картці ключа в панелі видно, з чого він починається, наприклад ctx_Hq4b…. За цим початком ключ легко впізнати, але відновити його не можна.

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

Права#

Права обираються прапорцями й згруповані за розділами магазину. У запитах і відповідях API право позначається кодом.

Група	Прапорець у панелі	Код	Що відкриває
Магазин	Бачити налаштування й довідники магазину	shop:read	/shop і всі довідники: вітрини, статуси, способи оплати й доставки, склади, категорії покупців, види контактів, ставки податку
Каталог	Бачити товари й категорії	catalog:read	довідники каталогу: /categories, /brands, /product_types, /features; товари та артикули: /products, /products/{id}, /products/ids, /skus
Ціни	Бачити ціни	prices:read	/prices і блок price в артикулів в адресах каталогу
Залишки	Бачити залишки	inventory:read	/inventory і блок stock в артикулів в адресах каталогу
Замовлення	Бачити замовлення	orders:read	/orders і /orders/{id}: замовлення контакту ключа з усіх каналів
Замовлення	Створювати нові замовлення	orders:create	POST /orders/check і POST /orders: розрахунок і створення замовлення
Покупці	Бачити покупців	customers:read	адрес поки немає

Адреса /me прав не потребує й відповідає будь-якому чинному ключу.

Права prices:read і inventory:read працюють і без права на каталог. Ключу, який лише звіряє ціни, досить prices:read. Йому відкрито /prices, а /products відповість 403. Щоб ціни й залишки прийшли одразу в товарах, ключу потрібне право на каталог і право на ціни чи залишки.

Право «Бачити покупців» можна видати вже зараз, адреси під нього з’являться в наступних випусках. Права змінювати дані в магазині через API немає і не буде. Створювати замовлення можна, а змінювати чи скасовувати вже створені — ні.

Право «Створювати нові замовлення» не дає права бачити замовлення. Створене замовлення партнер отримає у відповіді на створення, але потім переглянути його вже не зможе. Якщо дропшиперу потрібно і передавати замовлення, і стежити за ними, позначте обидва прапорці. Як магазин приймає замовлення, описано на сторінці «Замовлення партнера».

Доповнення магазину можуть додавати до форми ключа власні права. Вони з’являються окремою групою під назвою доповнення.

Видати більше власних прав не можна#

Ключ не відкриває того, що закрито в панелі самому співробітникові, який його видає. Кожному праву ключа відповідає право співробітника:

Право ключа	Потрібне право співробітника
shop:read	досить права «Видавати ключі API»
catalog:read, prices:read, inventory:read	«Дивитися каталог»
orders:read	«Бачити всі замовлення»
orders:create	«Працювати із замовленнями»
customers:read	«Бачити всі контакти»

Прапорець права, якого співробітник не має, видно, але він не натискається, а під ним написано «У вас немає цього права в панелі, тому видати його не можна». Якщо таке право ключу вже видав хтось інший, співробітник може його зняти, але додати назад після збереження вже не зможе.

Налаштування каталогу, залишків і замовлень#

Ці налаштування вирішують, у якому вигляді партнер отримає дані та що магазин надсилає йому за замовленнями. Блоки видно у формі ключа, лише коли позначено потрібне право. Змінити налаштування можна будь-коли, вони діють із наступного запиту, і видавати ключ заново не потрібно.

Зміна налаштувань товари зміненими не робить, тому після неї партнерові варто забрати каталог і залишки заново. Час останньої зміни партнер бачить у полі settings_changed_at відповіді GET /api/v1/me.

Цей час зсувається й тоді, коли власник змінює права ключа, бо з новим правом у відповідях з’являються нові поля. Зсувається він і після перенесення контакту, якому видано ключ, до іншої категорії покупців, вручну або автоматично, бо від категорії залежать ціни партнера. Перейменування ключа й зміна обмежень його не зсувають.

Каталог#

Блок з’являється, коли позначено право «Бачити товари й категорії».

«Опис товару» вирішує, як приходять опис і короткий опис товару.

Значення	Що отримає партнер
«З розміткою» (типово)	безпечний HTML: залишаються абзаци, заголовки, списки, таблиці, посилання й зображення, а скрипти, вбудовані вікна, форми й обробники подій вирізаються
«Лише текст»	звичайний текст без тегів. Абзаци розділено порожнім рядком, пункти списків починаються з «• », клітинки таблиць розділено « | ». Зображення зникають, від посилань залишається текст

Які теги залишаються і який вигляд має текст, описано на сторінці «Товари та артикули».

Залишки й склади для замовлень#

Блок з’являється, коли позначено право «Бачити залишки» або «Створювати нові замовлення». Склади ключа впливають і на залишки, які бачить партнер, і на те, з яких складів магазин резервує товар під його замовлення. Тому заголовок і підказки блоку залежать від прав ключа:

Права ключа	Заголовок і підказка блоку	Підказка поля «З яких складів»
лише «Бачити залишки»	«Залишки». «Виберіть, у якому вигляді партнер побачить залишки і з яких складів.»	«Якщо залишити порожнім, партнер побачить залишки складів, з яких продає вітрина. Для дропшипера можна завести окремий склад і вибрати тут лише його.»
лише «Створювати нові замовлення»	«Склади для замовлень». «Виберіть, з яких складів магазин резервує товар під замовлення партнера.»	«Якщо залишити порожнім, магазин резервує товар на складах, з яких продає вітрина. Для дропшипера можна завести окремий склад і вибрати тут лише його.»
обидва права	«Залишки». «Виберіть, у якому вигляді партнер побачить залишки і з яких складів.»	«Партнер бачить залишки цих складів, і з них же магазин резервує товар під його замовлення. Якщо залишити порожнім, магазин бере склади, з яких продає вітрина.»

Поле «Як віддавати залишки» є в блоці, лише коли позначено «Бачити залишки».

«Як віддавати залишки».

Значення	Що отримає партнер
«Однією сумою» (типово)	лише загальне число, скільки можна продати за всіма складами ключа
«По кожному складу»	ще й розбивку: скільки можна продати з кожного складу, а в /inventory також скільки лежить і скільки відкладено під замовлення

«З яких складів». Якщо залишити поле порожнім (у ньому написано «Усі склади вітрини»), партнер побачить залишки складів, з яких продає вітрина, і з них же магазин резервує товар під його замовлення. Якщо вибрати склади, залишки й резерв рахуються лише за ними, навіть якщо вітрина з них не продає. Так для дропшипера можна завести окремий склад і вибрати тут лише його. Можна вибрати до 100 складів.

У списку є лише справжні склади, об’єднаних складів у ньому немає. Вимкнений склад видно з позначкою «(вимкнений, партнер бачить 0)». Вибір зберігається, але продати з такого складу нічого не можна, і партнер отримує за ним нуль. Залишки інших складів магазин замість вимкненого не підставляє.

Якщо вибраний склад видалити або зробити об’єднаним, він залишиться у виборі під своїм номером, наприклад «Склад №12 (видалений, партнер його не бачить)». З відповідей API такий склад зникає й нічого не додає до залишку, а на склади вітрини ключ не перемикається. Приберіть такий склад із вибору самі. Якщо видалено або зроблено об’єднаними всі вибрані склади, партнер бачить нуль за всіма артикулами з обліком залишку, а його замовлення на них без передзамовлення магазин не прийме: товару на цих складах немає.

Як магазин рахує залишки, описано на сторінці «Залишки».

Для замовлень партнера вибрані склади діють так само: наявність для його замовлення магазин перевіряє за цими складами й з них же резервує товар.

Замовлення партнера#

Блок з’являється, коли позначено право «Створювати нові замовлення». Під заголовком написано «Виберіть, що магазин надсилає партнерові за його замовленнями».

Про замовлення, що надійшли через API, магазин сам не пише ні партнерові, ні його покупцеві. Виняток один — електронний чек.

«Надсилати партнерові електронний чек» (типово ввімкнено). Підказка під перемикачем: «Чек прийде на пошту чи телефон з контакту партнера, якщо в касі ввімкнено «Надсилати чек покупцеві». Якщо вимкнути, магазин однаково видасть чек, лише не надішле його партнерові.»

• Увімкнено. Якщо каса магазину надсилає чеки покупцям, чек за замовленням партнера піде на пошту чи телефон контакту, якому видано ключ. Магазин бере їх із замовлення, куди вони потрапили з картки контакту під час оформлення.
• Вимкнено. Чек за замовленням магазин видає як завжди, але нікуди його не надсилає. Так роблять, коли партнер не хоче отримувати чеки за замовленнями своїх покупців.

Отримувачу, якого менеджер призначив у замовленні, чек не надходить ніколи. Налаштування стосується замовлень, які надійшли за цим ключем. Якщо ключ видалять, чеки за його попередніми замовленнями надсилатимуться так, ніби перемикач увімкнено. Докладніше про те, що магазин пише за замовленнями партнера, на сторінці «Замовлення партнера».

Повідомлення партнерові#

У виданого ключа у формі є блок «Повідомлення партнерові». У ньому власник вмикає повідомлення, які магазин сам надсилає на сайт партнера, коли змінився статус замовлення, менеджер змінив замовлення або змінилися ціни й залишки. Там само власник вписує адресу партнера, позначає події й бачить секрет підпису, а під блоком стоїть журнал надсилань. Усе це описано на сторінці «Повідомлення партнерові (вебхуки)».

Обмеження#

Запитів за хвилину#

Скільки запитів за хвилину магазин прийме за цим ключем, від 1 до 10 000. Якщо поле порожнє, ліміт — 120 запитів за хвилину. Лічильник у кожного ключа свій, тому часті запити одного партнера не забирають запити в іншого.

Поточний ліміт ключа приходить у полі rate_limit_per_minute відповіді /me і в заголовку X-RateLimit-Limit кожної відповіді, де ключ пройшов перевірку. Що відбувається в разі перевищення, описано на сторінці «Помилки та їхні коди».

Дозволені IP-адреси#

Впишіть адресу й натисніть Enter, щоб додати наступну. Підходить окрема адреса або підмережа, IPv4 чи IPv6:

203.0.113.7
203.0.113.0/24
2001:db8::/32

Можна вказати до 50 адрес і підмереж. Якщо список порожній, ключ працює з будь-якої адреси. Запит з адреси не зі списку отримує відповідь 403 з кодом ip_not_allowed.

Діє до#

Дата, після якої ключ перестає працювати. Ключ діє до кінця обраного дня за часовим поясом магазину, тому дата «сьогодні» означає «до опівночі сьогодні». Дату, ранішу за сьогоднішню, обрати не можна. Якщо поле порожнє, ключ безстроковий.

У відповіді /me термін приходить в UTC. Для магазину в Києві ключ «до 31 грудня» має вигляд "expires_at": "2026-12-31T21:59:59Z".

Коли термін минув, ключ отримує відповідь 401 з кодом key_revoked, а в списку ключів біля нього написано «Термін минув». Такий ключ можна перейменувати й зберегти, не змінюючи минулу дату. Щоб ключ знову запрацював, натисніть «Видати ключ знову». Магазин випустить новий ключ без терміну, а потрібний термін можна задати після цього.

Відкликати, видати новий, видалити#

Видати новий ключ. Кнопка в блоці «Ключ доступу». Попередній ключ одразу перестає працювати, а новий магазин один раз показує так само, як під час видачі. Назва, контакт, права й обмеження залишаються попередніми.

Відкликати. Кнопка в шапці ключа. Ключ одразу втрачає доступ до магазину, але залишається в списку з позначкою «Відкликано» разом зі своєю історією в журналі. Запит відкликаним ключем отримує відповідь 401 з кодом key_revoked, а в журналі такий запит записано під назвою ключа. Повернути доступ можна кнопкою «Видати ключ знову». Магазин випустить новий ключ, а відкликаний уже не працюватиме. Якщо на той час термін дії ключа минув, під час повторної видачі термін знімається й ключ стає безстроковим. Якщо термін потрібен, задайте нову дату.

Видалити. Ключ зникає зі списку й одразу перестає працювати. Його запити залишаються в журналі, але замість назви там написано «Ключ невідомий».

Якщо обрати інший контакт у полі «Кому видаєте ключ» і зберегти ключ, попередній ключ одразу перестає працювати, бо ціни й замовлення тепер рахуються за іншим контактом. Якщо ключ працював, магазин сам видасть новий і один раз покаже його так само, як під час видачі. У відкликаного ключа або ключа, термін дії якого минув, нового ключа після зміни контакту не буде. Щоб ключ знову запрацював, натисніть «Видати ключ знову». Назва, права й обмеження залишаються попередніми. Запит попереднім ключем отримує відповідь 401 з кодом unauthenticated і записується в журнал із позначкою «Ключ невідомий». Магазин вимкне повідомлення партнерові, якщо їх було ввімкнено, і видасть новий секрет підпису. Докладніше на сторінці «Повідомлення партнерові (вебхуки)».

Якщо видалити контакт, разом із ним видаляються й усі його ключі. Вони зникають зі списку, а запит таким ключем отримує відповідь 401 з кодом unauthenticated, ніби ключа ніколи не було. Попередні запити залишаються в журналі з позначкою «Ключ невідомий».

Ключ без контакту. Ключі, видані до того, як контакт став обов’язковим, можуть бути ні до кого не прив’язані. Такий ключ не працює, на запити він отримує відповідь 401 з кодом key_revoked, а в його стані написано «Контакт не вибрано», навіть якщо його до того ж відкликано. Кнопок «Видати новий ключ» і «Видати ключ знову» в нього немає. Оберіть контакт у полі «Кому видаєте ключ» і збережіть, тоді магазин сам видасть новий ключ. Якщо ключ до того ж відкликано або термін його дії минув, після збереження натисніть «Видати ключ знову».

Що видно в картці ключа#

Рядок	Що показує
Стан	«Працює», «Відкликано», «Термін минув» або, у старого ключа без контакту, «Контакт не вибрано»
Ключ починається з	перші знаки секрету, наприклад ctx_Hq4b…. Рядка немає, поки ключ не має чинного секрету. Так буває у відкликаного ключа або ключа з минулим терміном після зміни контакту
Останній запит	час останнього запиту та IP-адреса, з якої він надійшов. Магазин оновлює цей рядок не частіше ніж раз на хвилину
Видав	співробітник, який видав ключ

У списку ліворуч під назвою робочого ключа написано час останнього запиту або «Ще не підключалися». Під іншими написано, чому ключ не працює: «Відкликано», «Термін минув» або «Контакт не вибрано». Спочатку в списку стоять робочі ключі, за ними всі неробочі, і всередині кожної частини ключі йдуть за назвою.