Платформа интеграций
Интеграция — это дополнение, которое расширяет систему, не меняя её код. Она может добавить свою страницу, вклиниться в существующий раздел, синхронизироваться с внешним сервисом, зарегистрировать способ оплаты или свой отчёт.
Компания ставит интеграции из маркетплейса поштучно: установленная интеграция получает ровно те возможности, которые заявила, и ничего сверх.
Манифест
Каждая интеграция описывается манифестом — это её паспорт и одновременно граница дозволенного.
| Поле | Что задаёт |
|---|---|
alias | Уникальный идентификатор в kebab-case |
version, sdkVersion | Версия интеграции и требуемая версия SDK |
name, description | Локализованные название и описание для маркетплейса |
category | Раздел маркетплейса |
developer | Кто разработал и с каким уровнем доверия |
entry | Точка входа |
capabilities | Что интеграции разрешено делать |
scopes | К каким доменным данным она обращается |
worker | Нужен ли фоновый исполнитель |
billing | Платная ли она |
Манифест проверяется дважды: в CI при сборке монорепозитория и на сервере при установке. Интеграция с невалидным манифестом не поедет дальше.
Возможности
Возможность (capability) — это разрешённая операция. Список закрытый: всё, чего в нём нет, недоступно.
| Возможность | Что даёт |
|---|---|
module.slot.render | Вставить свой UI в слот существующего модуля |
module.addons.menu | Добавить пункт в меню дополнений раздела |
ui.page | Свои страницы в /integrations/<alias>/* |
ui.modal | Регистрировать и открывать модалки |
storage.read / storage.write | Собственное key-value хранилище |
api.call | Вызывать доменное API ядра в пределах scopes |
api.proxy.request | Ходить на внешние хосты через прокси-шлюз |
socket.connect | Свои realtime-каналы |
reports.form.register | Свои формы и показатели в отчётах |
payments.method.register | Свой способ оплаты на кассе |
backend.connector | Серверный коннектор: синхронизация, проверка, вебхуки |
events.subscribe / events.emit | Подписка на доменные события и собственные события |
Области доступа
Возможность api.call сама по себе ничего не открывает — нужно ещё объявить область (scope): что именно интеграция читает и меняет.
Области заданы попарно чтение/запись по доменам: каталог, заказы, клиенты, продажи (только чтение), склад, сделки, планирование, отчёты (только чтение). Интеграция, объявившая catalog.read, не сможет записать в каталог, даже если очень захочет: проверка идёт на стороне ядра.
Где выполняется код
Интеграции запрещено делать бизнес-логику в главном потоке интерфейса. Точка входа только регистрирует: вот моя страница, вот пункт меню, вот обработчик.
Сама работа идёт либо в воркере — изолированном фоновом исполнителе, либо на сервере — в коннекторе. Воркер не имеет прямого доступа ни к сети, ни к данным: он ходит через host-протокол, а тот сверяется с манифестом.
Внешние запросы
Наружу интеграция ходит только через прокси-шлюз платформы. Это не формальность: прямые запросы позволили бы обратиться к внутренним адресам инфраструктуры. Прокси проверяет адрес назначения и не даёт этого сделать.
Установка
Установка ведёт журнал: кто поставил, какие возможности подтвердил, когда обновил, когда удалил. Статус установки видно в разделе интеграций, а проблемные интеграции можно отключить, не удаляя.
Типы разработчиков
В маркетплейсе видно, кто автор: сама платформа, вендор интегрируемого сервиса, сторонний интегратор или собственная разработка компании. Собственная разработка видна только той компании, которая её заказала.
Что дальше
Как написать свою интеграцию — в разделе SDK интеграций.