SelSup Developers

Платформа SelSup · Руководства

Расширения и собственные интеграции

Выбор между внешним backend-сервисом, React-расширением кабинета и серверным модулем интеграции с маркетплейсом или доставкой.

5 разделовПрактическое руководство
→

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

Разработчики приложений и технологические партнёры

01

Выбрать тип интеграции

  1. 1

    Внешний backend-сервис

    Подходит для синхронизации ERP, сайта, WMS, BI и других систем. Токен хранится только на вашем сервере, обмен выполняется через API и вебхуки.

  2. 2

    React-расширение

    Выбирайте для пользовательского интерфейса, который должен открываться внутри кабинета SelSup и использовать привычные компоненты продукта.

  3. 3

    Backend-модуль SelSup

    Нужен для глубокой интеграции нового маркетплейса или службы доставки, когда требуется участие в общих фоновых процессах SelSup.

i
Начинайте с минимального контура

Сначала реализуйте один сквозной сценарий и наблюдаемость. Массовые импорты, UI и дополнительные события подключайте после стабильной сверки.

02

Архитектура внешнего приложения

Разместите токен в менеджере секретов и обращайтесь к SelSup только из backend. Браузер вашего приложения должен работать с вашим API, а не получать токен SelSup.

Разделите адаптер SelSup, очередь задач и вашу доменную модель. Это позволит обновлять контракт API без распространения деталей SelSup по всему приложению.

Для входящих событий используйте inbox, для исходящих изменений — outbox. Оба журнала должны поддерживать повторную обработку и аудит.

Поток данных · Text
SelSup webhook → inbox → domain worker → ERP/WMS
ERP/WMS change → outbox → SelSup API → reconciliation

Связанные методы API

GET/api/product/findПример чтения справочникаGET/api/order/findПример инкрементальной синхронизации

03

React-расширение кабинета

Компонент встраивается в интерфейс SelSup. Внешний домен должен разрешать запросы из selsup.ru и корректно обрабатывать ограничения браузера.

Не помещайте постоянный API-токен в bundle. Для привилегированных операций используйте свой backend и короткоживущий контекст пользователя, предусмотренный архитектурой расширения.

Сохраняйте визуальную совместимость, доступность и обработку пустых, загрузочных и ошибочных состояний.

!
CORS не является авторизацией

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

Демо-компонент · URL
https://github.com/SelSup/component

04

Серверный модуль интеграции

Интеграция маркетплейса обычно охватывает токены, карточки, цены, остатки, заказы и фоновые обновления статусов. Служба доставки добавляет расчёт, создание отправления, этикетки и отслеживание.

Такой модуль изменяет основной backend SelSup и проходит общий процесс ревью, тестирования, локализации и выпуска. Согласуйте интерфейс и границы данных до реализации.

Ошибки внешнего API преобразуйте в стабильные ApplicationError, а недействительный или отозванный внешний токен — в AccessException согласно правилам backend-проекта.

i
Совместимость данных

Не добавляйте поля конкретного маркетплейса в общие сущности. Храните сырой контракт в DTO интеграции и преобразуйте его на границе.

05

Выпуск и сопровождение

  1. 1

    Добавьте тестовый аккаунт

    Отделите тестовые токены, склады, товары и заказы от production-данных клиентов.

  2. 2

    Настройте наблюдаемость

    Метрики должны показывать задержку очереди, частоту ошибок по коду, число повторов и расхождения сверки.

  3. 3

    Подготовьте миграцию контракта

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

  4. 4

    Опишите отключение

    Пользователь должен понимать, как отозвать токен, удалить вебхук и остановить синхронизацию без потери данных.