Собственные модули, API и вебхуки

Вы можете подключить SelSup к своей учётной системе или добавить в кабинет собственную страницу. Способ подключения зависит от задачи.

Задача	Что использовать
Передавать товары, заказы или остатки между системами	Публичное API — запросы с вашего сервера в SelSup
Узнавать об изменениях без постоянного опроса	Вебхуки — уведомления от SelSup на ваш сервер
Показать собственный интерфейс в кабинете	Модуль — ваше веб-приложение внутри страницы или вкладки SelSup

Подключение через API

Откройте Интеграции → API, задайте понятное имя подключения и создайте токен. Для обмена только на чтение включите «Только чтение». Скопируйте и сохраните показанный токен. Для разных подключений создавайте отдельные токены — так одно из них можно отключить, не затрагивая остальные.

Запросы отправляются на https://api.selsup.ru/api/. Токен передаётся в заголовке Authorization без слова Bearer. Храните токен на своём сервере. Не добавляйте его в код веб-страницы или адрес модуля.

Программисту понадобятся первые шаги работы с API и справочник методов. Кнопка «Попробовать» в документации отправляет настоящий запрос с указанным токеном.

Получение уведомлений через вебхуки

Вебхук сообщает вашей системе об изменении данных. Например, SelSup может отправить уведомление о новом заказе или изменении доступного остатка. Разработчик создаёт подписку через API и указывает адрес обработчика на вашем сервере.

Для каждой подписки SelSup создаёт отдельный секрет. Обработчик использует его, чтобы проверить подпись уведомления, сохраняет сообщение и быстро отвечает SelSup. Передавать API-токен внутри модуля для этого не нужно.

Если принимающий сервер был недоступен, изменения нужно восстановить через API: гарантированная доставка всех пропущенных уведомлений здесь не предусмотрена. Форматы сообщений, проверка подписи и обработка повторов описаны в руководстве по вебхукам.

Добавление своего модуля

Управлять расширениями может администратор кабинета. Модуль размещается на вашем HTTPS-сайте и открывается в SelSup во встроенном окне — iframe. Его можно разработать на обычном HTML и JavaScript или с помощью привычного фреймворка.

1. Разработайте страницу и разместите её на отдельном от SelSup домене. Сайт должен разрешать открытие внутри iframe.
2. Откройте Интеграции → Мои расширения → Добавить расширение.
3. Заполните название, описание и адрес страницы, выберите иконку.
4. Выберите, где показывать расширение: отдельной страницей в меню, вкладкой товара или вкладкой заказа. Для страницы в меню дополнительно выберите раздел и позицию ссылки.
5. Отметьте данные, которые разрешено передавать модулю. Отдельно выберите доступные ему методы API.
6. Сохраните расширение и откройте его в выбранном месте. Вкладки товара и заказа доступны у сохранённых карточек.

Личное расширение можно использовать в своём кабинете без публикации в магазине. Чтобы предложить его другим клиентам, отправьте заявку на проверку SelSup. После изменения карточки и списка запрашиваемых методов нужна повторная проверка. Настройки и разрешения у других клиентов автоматически не обновляются.

Какие данные передаются в модуль

В настройках выбираются только нужные сведения: идентификатор сотрудника и язык, идентификатор кабинета, список доступных организаций, идентификатор открытой модели товара или заказа. Без разрешения соответствующего поля в сообщении не будет. Полная карточка товара или заказа, пароли, контакты и токены таким способом не передаются.

Данные приходят из SelSup в JavaScript-обработчик message через postMessage. В event.data находится объект с полями type, version и context. Внутри context — разрешённые сведения и список доступных методов apiMethods. Это объект JavaScript, поэтому вызывать для него JSON.parse не нужно.

Разрешения на данные и методы независимы. Например, передача идентификатора товара сама по себе не позволяет его изменить. Вызов разрешённого метода выполняется с правами сотрудника, который открыл панель, и не добавляет ему новых прав.

Руководство для разработчика

В подробном руководстве по созданию модуля есть:

• настройка сайта и подключение к кабинету;
• примеры данных для страницы меню, вкладки товара и вкладки заказа;
• порядок обмена сообщениями и проверки отправителя;
• готовые index.html и app.js для чтения меток;
• вызовы connection.callApi(method, params) с параметрами и результатами;
• обработка ошибок, ограничение частоты запросов и проверка после таймаута;
• архив примера с локальным учебным кабинетом.

Через модуль доступны чтение, создание, переименование и удаление меток, а также добавление модели товара в избранное и удаление из него. Каждый используемый метод нужно отдельно разрешить в настройках. Для фоновой работы, которая должна продолжаться после закрытия панели, используйте серверное приложение и публичное API.