Маркет интеграций

Маркет интеграций в /app/settings/integrations помогает быстро понять, какие сервисы можно подключить к закупочному контуру SNABZHENETS+, какие данные они передают, сколько стоят и как ими управлять после установки.

Интерфейс рассчитан на B2B-сценарии: администратор видит разработчика, цену, способ подключения, права доступа, статусы синхронизации, логи и документацию до установки.

Витрина

Верхняя часть маркета содержит:

название раздела «Маркет SNABZHENETS+»;
поиск по интеграциям, поставщикам, API и 1С;
кнопки + Webhooks и Предложить интеграцию;
горизонтальные категории;
промо-баннеры для 1С/ERP, ЭДО и API/Webhooks;
секции «Рекомендации дня», «Популярно для закупок», «Быстрый старт», «Автоматизация документов», «Интеграции для аналитики» и «Инструменты разработчика».

Карточка интеграции показывает название, разработчика, категорию, короткое описание, рейтинг, количество установок, цену, тип подключения, бейджи и действие: Установить бесплатно, Подключить, Подробнее или Настроить.

Первая базовая карточка для проверки маркета — Email:

категория: Уведомления;
разработчик: AI TRINITY;
цена: Бесплатно;
тип подключения: SMTP/IMAP;
назначение: отправка системных писем и уведомлений через корпоративный SMTP-сервер клиента;
базовый сценарий: администратор указывает SMTP host, порт, SSL/TLS, логин, пароль, email отправителя и имя отправителя, затем отправляет тестовое письмо и включает интеграцию.

Категории и фильтры

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

Slug	Категория
`accounting-erp`	1С и ERP
`edo-documents`	ЭДО и документы
`banks-payments`	Банки и счета
`suppliers-catalogs`	Поставщики и каталоги
`warehouse-logistics`	Склад и логистика
`crm-sales`	CRM и продажи
`analytics-bi`	BI и аналитика
`notifications`	Уведомления
`webhooks-api`	API и Webhooks

Фильтры в категории:

цена: Бесплатно, Внешняя оплата, По запросу;
статус или бейдж: Проверено, Beta, Built by SNABZHENETS+;
тип подключения: OAuth, API-key, Webhook, Файл CSV/XLSX;
данные: поставщики, PO, счета, номенклатура, статусы;
минимальный рейтинг;
сортировка: популярные, новые, рейтинг, недавно обновлены.

Карточка интеграции

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

Справа находятся:

hero-preview или скриншоты;
описание интеграции;
список возможностей;
таблица «Какие данные передаются»;
сценарии использования;
инструкция подключения;
отзывы;
блок «Логи и безопасность».

Таблица передаваемых данных показывает сущность и направление доступа, например Поставщики — Чтение/запись или Статусы оплат — Чтение.

Установленные интеграции

Вкладка «Установленные» показывает подключенные интеграции списком. В строке отображаются:

название и категория;
статус: Установлено, Требуется настройка, Ошибка синхронизации, Отключено;
дата установки;
последняя синхронизация;
подключенная организация или аккаунт;
разработчик;
действия Настроить, Логи, Отключить.

Статусы и даты берутся из установки интеграции текущего портала.

API и Webhooks

Категория API и Webhooks содержит отдельный developer-блок:

карточки REST API, Webhooks, Импорт CSV/XLSX, Песочница разработчика;
список событий purchase_request.created, po.status_changed, invoice.created, supplier.updated, item.price_changed, payment.status_changed;
пример webhook-карточки с URL, статусом доставки, успешными и ошибочными вызовами.

API каталога

Список интеграций

Эндпоинт: GET /api/v1/integrations/marketplace

Возвращает пагинированный список опубликованных интеграций с marketplace metadata и информацией об установке для текущего портала.

Параметр	Тип	Описание
`search`	`string`	Поиск по названию, описанию, тегам и категории
`category`	`string`	Slug категории, например `accounting-erp`
`type`	`string`	Тип интеграции: `OAUTH2`, `API_KEY`, `WEBHOOK_OUTBOUND` и др.
`status`	`string`	Статус интеграции: `ACTIVE`, `BETA`, `DEPRECATED`, `COMING_SOON`
`installed`	`boolean`	`true` — только установленные, `false` — только неустановленные
`price`	`string`	Модель оплаты: `FREE`, `EXTERNAL`, `REQUEST`
`badge`	`string`	Фильтр по бейджу или тегу
`connectionType`	`string`	Тип подключения из metadata
`data`	`string`	Сущность данных из таблицы синхронизации
`ratingMin`	`number`	Минимальный рейтинг от `0` до `5`
`sort`	`string`	`popular`, `new`, `rating`, `updated`
`page`	`number`	Номер страницы, по умолчанию `1`
`limit`	`number`	Размер страницы, максимум `100`, по умолчанию `24`

Пример ответа

json

{
  "items": [
    {
      "slug": "1c-erp-ut-bp",
      "name": "1С:ERP / УТ / БП",
      "shortDescription": "Синхронизация PO, счетов, номенклатуры и поставщиков с 1С",
      "categorySlug": "accounting-erp",
      "type": "HYBRID",
      "status": "ACTIVE",
      "logoUrl": null,
      "isPaid": false,
      "requiredPlanTier": "BUSINESS",
      "rating": "4.90",
      "installCount": 0,
      "marketplaceMetadata": {
        "developer": { "name": "SNABZHENETS+", "type": "SNABZHENETS_PLUS" },
        "pricing": { "model": "FREE", "label": "Бесплатно" },
        "badges": ["Проверено", "Built by SNABZHENETS+", "Популярное"],
        "connectionTypes": ["API-key", "Файл CSV/XLSX", "Webhook"],
        "syncData": [
          { "entity": "Поставщики", "direction": "Чтение/запись" },
          { "entity": "PO", "direction": "Чтение/запись" }
        ]
      },
      "isInstalledForTenant": true,
      "installationStatus": "ACTIVE",
      "installationSummary": {
        "id": "5f3f0f7c-0000-0000-0000-000000000000",
        "status": "ACTIVE",
        "installedAt": "2026-05-07T10:00:00.000Z",
        "lastSyncAt": "2026-05-07T10:05:00.000Z",
        "lastErrorAt": null,
        "lastErrorMessage": null,
        "accountLabel": "ООО Снабжение"
      },
      "canInstall": false,
      "unavailableReason": "ALREADY_INSTALLED"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 24
}

Карточка интеграции API

Эндпоинт: GET /api/v1/integrations/marketplace/:slug

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

Ключевые поля:

Поле	Описание
`marketplaceMetadata.developer`	Разработчик и тип разработчика
`marketplaceMetadata.pricing`	Модель оплаты и текстовая цена
`marketplaceMetadata.badges`	Бейджи карточки
`marketplaceMetadata.trustBadges`	Блок доверия в модалке
`marketplaceMetadata.connectionTypes`	Способы подключения
`marketplaceMetadata.syncData`	Таблица передаваемых данных
`marketplaceMetadata.useCases`	Сценарии использования
`marketplaceMetadata.installSteps`	Инструкция подключения
`marketplaceMetadata.reviews`	Короткие отзывы
`installation.accountLabel`	Подключенная организация или аккаунт

Правила добавления новой интеграции

Новая карточка маркета должна добавляться через данные интеграции, а не через hardcode во frontend.

Минимальный checklist:

Выберите существующую категорию из IA маркета или добавьте новую категорию в seed и migration-data.
Создайте или обновите IntegrationDefinition со стабильным slug, названием, коротким описанием, полным описанием, setupInstructions, requirementsText, type, status, isPaid, requiredPlanTier, configSchema, capabilitiesSchema, tags, rating и publishedAt.
Заполните marketplaceMetadata: developer, pricing, badges, trustBadges, connectionTypes, syncData, useCases, installSteps, permissions, promoSections, gallery.
Если интеграция должна появиться в пустом production-каталоге без ручного seed, добавьте data migration с INSERT ... ON CONFLICT DO UPDATE для категории и integration_definitions.
Если интеграция имеет реальный сценарий установки, slug должен совпадать со slug backend handler. Например, карточка Email использует smtp-email, потому что SMTP handler работает с этим slug.
В shortDescription пишите не рекламный слоган, а практическую пользу и первый шаг подключения. Подробные шаги храните в setupInstructions и marketplaceMetadata.installSteps.
Не добавляйте юридические сертификаты, SLA или гарантийные бейджи, если они не подтверждены продуктом и договором.
После добавления обновите публичную и внутреннюю документацию, если появляются новые правила, поля metadata или особые ограничения.

Для тестовой карточки Email источником правды являются seed и data migration. Frontend только отображает данные API и поддерживает соответствующие фильтры Built by AI TRINITY, SMTP/IMAP, Email и Уведомления.

Категории API

Эндпоинт: GET /api/v1/integrations/marketplace/categories

Возвращает список активных категорий с количеством опубликованных интеграций.

json

[
  {
    "slug": "accounting-erp",
    "nameRu": "1С и ERP",
    "nameEn": "1C & ERP",
    "icon": "Calculator",
    "description": "1С, ERP, справочники, PO, счета, остатки и статусы заказов",
    "count": 1
  }
]

Ограничения

Маркет показывает только опубликованные интеграции.
Бейджи доверия описывают реализованные продуктовые свойства и не являются юридическими сертификатами.
Цена Внешняя оплата означает, что платежные отношения могут находиться вне SNABZHENETS+.
Для фактических параметров конфигурации источником правды остается configSchema конкретной интеграции.

Маркет интеграций ​

Витрина ​

Категории и фильтры ​

Карточка интеграции ​

Установленные интеграции ​

API и Webhooks ​

API каталога ​

Список интеграций ​

Пример ответа ​

Карточка интеграции API ​

Правила добавления новой интеграции ​

Категории API ​

Ограничения ​