Настройка системы

#1145: Встраивание и авторизация веб-виджета в собственном приложении

Отредактирована: 12 дней назад

Интеграция внешней системы и быстрый логин

Пожалуйста, сначала прочитайте обзор логики интеграции описанной в статье.

ВАЖНО: В данном документе даны примеры OTP_CODE_KEY  и API ключа. 

При переходе в production будет необходимо поменять шифр (OTP_CODE_KEY) и API ключ, используемые при интеграции.

Настройка системы (единоразово/по необходимости)

Настройка системы, как Swarmica, так и внешняя интегрируемая система (ваше приложение), настраиваются один раз (либо перенастраиваются при необходимости)

На стороне Swarmica:

  1. На сервере:Необходимо настроить секретный ключ для шифра и максимально допустимое отклонение времени в timestamp и подключить провайдер авторизации code:Для этого нужно выставить переменные в /root/swarmica/.env:
root@swarmica# grep -i code .env
AUTH_PROVIDERS=email,code
OTP_CODE_KEY=E655633B-2FAB-4661-9637-DADBE53E9633
OTP_CODE_TIMESTAMP_DELTA=120

Параметр OTP_CODE_TIMESTAMP_DELTA - это срок жизни сгенерированной ссылки для авторизации пользователя в секундах. Для примера и тестов данный параметр выставлен в 120 секунд, для продакшена рекомендуется выставить его в несколько секунд (5-10).

Параметр OTP_CODE_KEY - это секретный ключ, который используется для шифровки/дешифровки данных авторизации. После завершения разработки рекомендуется заменить ключ.

Перезагрузить систему:

cd /root/swarmica
docker compose down
docker compose up -d
  1. В приложении Swarmica (требуются права Администратора):Создать API ключ, который будет использоваться бэкендом интегрируемой системы в Настройки>API интеграцииВыглядеть он будет вот так:
    8932368e-cdc6-4be4-a31d-1cf0aa129b99

На стороне интегрируемой системы (биллинга или панели):

1. Подготовить код для работы с API Swarmica.

2. Записать в настраиваемые переменные:

- Код для шифра (то же, что указано в OTP_CODE_KEY выше): E655633B-2FAB-4661-9637-DADBE53E9633

- API ключ: 8932368e-cdc6-4be4-a31d-1cf0aa129b99

-Шаблон HTML кода вставки виджета с настройкой OTP https://support.swarmica.com/article/ru/599-vstraivaemyj-veb-vidzhet.html 

Пример кода виджета:

  <!-- start embedded Swarmica widget script -->
  <iframe src="https://helpdesk.ispmanager.tech/widgets/index.html?id=veNilW0QFQhTq2hg&locale=en&otpdata=URLENCODED_ДАННЫЕ_СМ_ДАЛЕЕ" id="veNilW0QFQhTq2hg" style="position: fixed; right: 12px; bottom: 12px; width: 56px; height: 56px; overflow: hidden; "
    allowTransparency="true"
    frameborder="0"
    allowTransparency="true" frameborder="0"></iframe>
  <script src="https://help.solar-start.ru/widgets/render.js"></script>
  <script>
    const iframe = document.getElementById("veNilW0QFQhTq2hg")
    iframe.onload = () => {
      renderWidget("veNilW0QFQhTq2hg")
    }
  </script>
  <!-- end embedded Swarmica widget scripts -->

Получение code для пользователя (при регистрации / авторизации пользователя в вашем приложении)

В случае, когда пользователь авторизуется в в вашем приложении, его бэкенд  должен проверять наличие code и если его нет, то выполнять запрос на получение code для пользователя:

https://support.yourdomain.tld/api/schema/doc/#post-/api/auth/otp/code/request

где support.yourdomain.tld - адрес вашей инсталляции Swarmica

Для удобства, в запросе можно передавать не только email искомого пользователя, но и другие поля - если такой учетной записи не будет, то Swarmica автоматически создаст пользователя и сразу выпишет ему код. Параметры объекта user идентичны вызову https://support,swarmica.com/api/schema/doc/#post-/api/users/ . Так же, см. ниже Параметры создания пользователя

ВАЖНО: Этот API запрос выполняется только от учетной записи с правами Администратор (то есть, нужен API токен, который был создан при настройке системы)

Пример такого вызова:

curl -X POST "https://support.yourdoamin.tld/api/auth/otp/code/request" \
 -H "accept: application/json"\
 -H "authorization: Token 8932368e-cdc6-4be4-a31d-1cf0aa129b99"\
 -H "content-type: application/json" \
 -d '{"user":{"name":"Joe Sudyin","email":"joedoe@swarmica.com","role":"CUSTOMER","ext_id":"fake_user_id","locale":"en","custom_fields":[{"uid":"OGRcFb1U8XFHM2r1","value":"freelancer"},{"uid":"IHZAwFQD3bBJSmAM","value":"+1234567890"}]}}' \

Ответ системы:

{
  "code": "c44f3108-76fd-4797-a61e-658aeda5876b",
  "user": {
    "uid": "6zndSQzdagK8WLfK",
    "name": "Max Sudyin",
    "email": "joedoe@swarmica.com",
    "date_joined": "2025-06-18T07:17:30.564278Z",
    "role": "CUSTOMER",
    "image_path": null,
    "signatures": null,
    "ext_id": "fake_user_id",
    "custom_fields": [],
    "schedule": null,
    "locale": "en",
    "tz_offset_minutes": 0,
    "timezone": "UTC",
    "organization": "s5cN_OBc_U5MXosr",
    "source": "api",
    "kcs_role": "CANDIDATE",
    "created_at": "2025-06-18T07:17:30.857456Z",
    "updated_at": "2025-06-18T07:17:30.857463Z",
    "groups": [],
    "is_system": false,
    "is_employee": false,
    "anonymous": false,
    "identities": [
      {
        "uid": "8ipu8ZpttthVGJIa",
        "user": "6zndSQzdagK8WLfK",
        "source": "EMAIL",
        "ext_id": "joedoe@swarmica.com",
        "ext_id_type": null,
        "data": null,
        "confirmed": true,
        "default": true
      }
    ],
    "merged_into": null,
    "last_login": null
  }
}

Полезно сохранить UID пользователя и необходимо сохранить code - первое нужно для того, чтобы впоследствии было проще сопоставлять учетные записи в других интеграциях, а code необходим для генерации данных otpdata для авторизации виджета.

Генерация параметра otpdata для авторизации виджета

Когда необходимо сделать ссылку для входа (например, при нажатии на ссылку “Мои заявки”), тогда бэкенд вашего приложения должен сделать следующее:

  1. Сформировать JSON данные вида:{"email": "joedoe@swarmica.com", "code": "c44f3108-76fd-4797-a61e-658aeda5876b", "timestamp": int(time.time())}
  2. Зашифровать их алгоритмом шифрования (см. далее) 
  3. В коде инициализации виджета подставить в значение параметра otpdata в URLEncoded виде.Например, если функция encrypt вернула вот такие данные:
GPQi9F26yw/MaNUWvmSYrShqK+n9IdtcbUraB5/WfNNdjEJqZbWk1Qifn1BF3iV4phT0tt5GtH51Ks6DMCz6hZk4NxfNnHnfpCrM+P0y8BlTK2v6nGjN+KoP/1x1OptMN+at2ZNTlPn7nVrmxfMeJdu7pruLTDo62snxHQymWiPLKvhOdgCfFAKHyWWwmxIQ

То в ссылке нужно будет указать:

&otpdata=GPQi9F26yw%2FMaNUWvmSYrShqK%2Bn9IdtcbUraB5%2FWfNNdjEJqZbWk1Qifn1BF3iV4phT0tt5GtH51Ks6DMCz6hZk4NxfNnHnfpCrM%2BP0y8BlTK2v6nGjN%2BKoP%2F1x1OptMN%2Bat2ZNTlPn7nVrmxfMeJdu7pruLTDo62snxHQymWiPLKvhOdgCfFAKHyWWwmxIQ

При тестировании “от клиента” рекомендуется открывать код страницы с виджетом в другом браузере или в инкогнито режиме или выйдя из Swarmica, если вдруг был выполнен вход от имени привилегированного пользователя.

Параметры создания пользователя

При создании пользователя через https://support,yourdomain.tld/api/schema/doc/#post-/api/auth/otp/code/request или напрямую через https://support.yourdomain.tld/api/schema/doc/#post-/api/users/ можно указывать следующие данные (ниже вариант примера):

{
  "user": {
    "name": "Joe Doe",
    "email": joedoe@swarmica.com",
    "role": "CUSTOMER",
    "ext_id": "fake_user_id",
    "locale": "en",
    "custom_fields": [
       {"uid": "OGRcFb1U8XFHM2r1", "value": "freelancer"},
       {"uid": "IHZAwFQD3bBJSmAM", "value": "+1234567890"}
    ]
  }
}

Обязательные поля:

name - имя пользователя, строка

email - email пользователя, который будет использоваться для его идентификации

role - роль в Swarmica, для клиентов это может быть CUSTOMER (имеет привилегии клиента, может работать только со своими заявками/чатами) или CUSTOMER_ADMIN (имеет привилегии клиента, но может работать не только со своими заявками/чатами, но и заявками/чатами других пользователей из своей Организации).

Необязательные поля:

ext_id -  строка, ID пользователя во внешней системе (например, в личном кабинете Solar, можно использовать для сопоставления учетных записей и поиска через API и интерфейс)

locale - язык интерфейса Swarmica для этого пользователя (ru или en)

custom_fields - массив значений для кастомных полей. Все кастомные поля пользователя можно посмотреть в API custom_fields с фильтром model = user

Значения кастомных полей:

Значения кастомных полей указываются в виде объекта:

{
  “uid”: “УИД КАСТОМНОГО ПОЛЯ”,
  “value”: “ЗНАЧЕНИЕ КАСТОМНОГО ПОЛЯ В ФОРМАТЕ ЕГО ТИПА”
}

Например, для поля Телефон (uid = “IHZAwFQD3bBJSmAM”) это текстовое значение.

А для поля Тип клиента (uid = “OGRcFb1U8XFHM2r1”) указывается ключ из словаря choices, соответствующий нужному параметру:

{
  "uid": "OGRcFb1U8XFHM2r1",
  "name": {
    "en": "User type",
    "ru": "Тип пользователя"
  },
  "field_type": "DROPDOWN",
  "applicable_to": [
    "user"
  ],
  "mandatory_for": [],
  "permissions": "INTERNAL",
  "default_value": null,
  "properties": {
    "choices": {
      "customer": {
        "en": "Customer",
        "ru": "Заказчик"
      },
      "freelancer": {
        "en": "Freelancer",
        "ru": "Фрилансер"
      }
    }
  }
}

Например, для значения Фрилансер/Freelancer нужно указать freelancer, а для Заказчик/Customer - customer.

Все значения и ключи настраиваются через графический интерфейс 

© 2023 - 2026 ООО «Свормика». Swarmica - Платформа управления знаниями и ресурсами техподдержки. Версия: 5.12.1