Управление установками

Установка — это экземпляр конкретной интеграции внутри вашего портала. У каждой интеграции может быть только одна активная установка на портал.

API установок

Все эндпоинты требуют роль tenant_admin или tenant_owner.

Список установок

GET /api/v1/integrations/installations

Возвращает все активные (не удалённые) установки текущего портала.

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "integrationSlug": "telegram-notify",
    "integrationName": "Telegram Уведомления",
    "type": "API_KEY",
    "status": "ACTIVE",
    "installedAt": "2026-03-15T10:00:00.000Z",
    "lastSyncAt": "2026-04-27T08:30:00.000Z",
    "lastErrorAt": null,
    "lastErrorMessage": null,
    "capabilities": [
      { "capability": "NOTIFY_ON_PROCUREMENT_STATUS_CHANGE", "isEnabled": true },
      { "capability": "NOTIFY_ON_INVOICE_CREATED", "isEnabled": false }
    ]
  }
]

Установить интеграцию

POST /api/v1/integrations/installations

{ "integrationSlug": "telegram-notify" }

Ответ — новая установка со статусом PENDING_CONFIG. Если интеграция была ранее удалена — восстанавливается с очисткой конфигурации.

Карточка установки

GET /api/v1/integrations/installations/:id

Возвращает детальную информацию, включая поля конфигурации (секреты маскируются символами ••••••••).

{
  "id": "550e8400-...",
  "integrationSlug": "telegram-notify",
  "status": "ACTIVE",
  "configView": {
    "fields": [
      { "key": "botToken", "isSecret": true, "isSet": true, "maskedValue": "••••••••" },
      { "key": "chatId", "isSecret": false, "isSet": true, "value": "-1001234567890" }
    ]
  },
  "capabilities": [ ... ],
  "metadata": null
}

Настройка конфигурации

PATCH /api/v1/integrations/installations/:id/config

Частичное обновление — незаполненные поля сохраняют предыдущие значения. Секреты при передаче null или отсутствии поля не затираются.

{
  "botToken": "7123456789:AAF...",
  "chatId": "-1001234567890"
}

Конфигурация хранится зашифрованной (AES-256-GCM). Секретные поля никогда не возвращаются в открытом виде.

После сохранения конфига статус переходит обратно в PENDING_CONFIG до явной активации.

Активация и деактивация

Включить интеграцию

POST /api/v1/integrations/installations/:id/enable

Переводит установку в статус ACTIVE. Требует заполненной конфигурации — без неё вернёт 400 Bad Request.

Выключить интеграцию

POST /api/v1/integrations/installations/:id/disable

Переводит в статус DISABLED. Все возможности (capabilities) деактивируются автоматически.

Удалить интеграцию

DELETE /api/v1/integrations/installations/:id

Помечает установку как UNINSTALLED, стирает конфигурацию и OAuth-токены. Повторная установка той же интеграции возможна.

Проверка соединения и синхронизация

Проверить соединение

POST /api/v1/integrations/installations/:id/test

Проверяет, что введённая конфигурация позволяет подключиться к внешнему сервису.

{ "ok": true, "message": "Connection successful" }

Запустить синхронизацию вручную

POST /api/v1/integrations/installations/:id/sync

Инициирует немедленную синхронизацию (для интеграций, поддерживающих sync).

{ "queued": true, "jobId": "sync_a3f1b2c4d5e6f7a8", "message": "Sync started" }

Журнал событий

GET /api/v1/integrations/installations/:id/logs

Параметр	Описание
direction	INBOUND или OUTBOUND
page	Номер страницы
limit	Размер страницы (максимум 50)

{
  "items": [
    {
      "id": "log-uuid",
      "direction": "INBOUND",
      "event": "order.created",
      "responseStatus": 200,
      "durationMs": 42,
      "createdAt": "2026-04-27T09:15:00.000Z",
      "hasPayload": true,
      "hasResponseBody": false
    }
  ],
  "total": 156
}