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

Ключ открывает доступ к 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-адрес, с которого он пришёл. Магазин обновляет эту строку не чаще раза в минуту
Выдал	сотрудник, который выдал ключ

В списке слева под названием работающего ключа написано время последнего запроса или «Ещё не подключались». Под остальными написано, почему ключ не работает: «Отозван», «Срок истёк» или «Контакт не выбран». Сначала в списке стоят работающие ключи, за ними все неработающие, и внутри каждой части ключи идут по названию.