# Встраивание и авторизация веб-виджета в собственном приложении
# **Интеграция внешней системы и быстрый логин**
Пожалуйста, сначала прочитайте [обзор логики интеграции описанной в статье](https://support.swarmica.com/article/ru/557-ru.html).
:::caution
ВАЖНО: В данном документе даны примеры OTP\_CODE\_KEY и API ключа.
При переходе в production будет необходимо поменять шифр (OTP\_CODE\_KEY) и API ключ, используемые при интеграции.
:::
## **Настройка системы (единоразово/по необходимости)**
Настройка системы, как Swarmica, так и внешняя интегрируемая система (ваше приложение), настраиваются один раз (либо перенастраиваются при необходимости)
### На стороне Swarmica:
1. **На сервере**:Необходимо настроить секретный ключ для шифра и максимально допустимое отклонение времени в timestamp и подключить провайдер авторизации code:Для этого нужно выставить переменные в `/root/swarmica/.env`:
```txt
root@swarmica# grep -i code .env
AUTH_PROVIDERS=email,code
OTP_CODE_KEY=E655633B-2FAB-4661-9637-EXAMPLE
OTP_CODE_TIMESTAMP_DELTA=120
```
Параметр *OTP\_CODE\_TIMESTAMP\_DELTA* - это срок жизни сгенерированной ссылки для авторизации пользователя в секундах. Для примера и тестов данный параметр выставлен в 120 секунд, для продакшена рекомендуется выставить его в несколько секунд (5-10).
Параметр *OTP\_CODE\_KEY* - это секретный ключ, который используется для шифровки/дешифровки данных авторизации. После завершения разработки рекомендуется заменить ключ.
Перезагрузить систему:
```txt
cd /root/swarmica
docker compose down
docker compose up -d
```
1. **В приложении Swarmica (требуются права Администратора)**: Создать API ключ, который будет использоваться бэкендом интегрируемой системы в **Настройки>API интеграции**
Выглядеть он будет вот так: `EXAMPLE-cdc6-4be4-a31d-1cf0aa129b99`
На стороне интегрируемой системы (биллинга или панели):
1\. Подготовить код для работы с API Swarmica.
2\. Записать в настраиваемые переменные:
\- Код для шифра (то же, что указано в OTP\_CODE\_KEY выше): E655633B-2FAB-4661-9637-EXAMPLE
\- API ключ: `EXAMPLE-cdc6-4be4-a31d-1cf0aa129b99`
-Шаблон HTML кода вставки виджета с настройкой OTP [https://support.swarmica.com/article/ru/599-vstraivaemyj-veb-vidzhet.html](https://support.swarmica.com/article/ru/599-vstraivaemyj-veb-vidzhet.html)
Пример кода виджета:
```html
```
## **Получение code для пользователя (при регистрации / авторизации пользователя в вашем приложении)**
В случае, когда пользователь авторизуется в в вашем приложении, его бэкенд должен проверять наличие code и если его нет, то выполнять запрос на получение code для пользователя:
[https://support.yourdomain.tld/api/schema/doc/#post-/api/auth/otp/code/request](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/](https://support.swarmica.com/api/schema/doc/#post-/api/users/). Так же, см. ниже **Параметры создания пользователя**
**ВАЖНО: Этот API запрос выполняется только от учетной записи с правами Администратор (то есть, нужен API токен, который был создан при настройке системы)**
Пример такого вызова:
```bash
curl -X POST "https://support.yourdomаin.tld/api/auth/otp/code/request" \
-H "accept: application/json"\
-H "authorization: Token EXAMPLE-cdc6-4be4-a31d-1cf0aa129b99"\
-H "content-type: application/json" \
-d '{"user":{"name":"Joe Doe","email":"joedoe@swarmica.tld","role":"CUSTOMER","ext_id":"fake_user_id","locale":"en","custom_fields":[{"uid":"OGRcFb1U8XFHM2r1","value":"freelancer"},{"uid":"IHZAwFQD3bBJSmAM","value":"+1234567890"}]}}' \
```
Ответ системы:
```json
{
"code": "EXAMPLE-76fd-4797-a61e-658aeda5876b",
"user": {
"uid": "6zndSQzdagK8WLfK",
"name": "Joe Doe",
"email": "joedoe@swarmica.tld",
"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.tld",
"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": "EXAMPLE-76fd-4797-a61e-658aeda5876b", "timestamp": int(time.time())}`
2. Зашифровать их алгоритмом шифрования, вызвав encrypt метод: [https://support.yourdomаin.tld//api/schema/doc/#post-/api/auth/otp/code/encrypt](https://support.yourdomаin.tld//api/schema/doc/#post-/api/auth/otp/code/encrypt)
3. В коде инициализации виджета подставить в значение параметра otpdata в URLEncoded виде.Например, если функция encrypt вернула вот такие данные:
```txt
GPQi9F26yw/MaNUWvmSYrShqK+n9IdtcbUraB5/WfNNdjEJqZbWk1Qifn1BF3iV4phT0tt5GtH51Ks6DMCz6hZk4NxfNnHnfpCrM+P0y8BlTK2v6nGjN+KoP/1x1OptMN+at2ZNTlPn7nVrmxfMeJdu7pruLTDo62snxHQymWiPLKvhOdgCfFAKHyWWwmxIQ
```
То в ссылке нужно будет указать:
```bash
&otpdata=GPQi9F26yw%2FMaNUWvmSYrShqK%2Bn9IdtcbUraB5%2FWfNNdjEJqZbWk1Qifn1BF3iV4phT0tt5GtH51Ks6DMCz6hZk4NxfNnHnfpCrM%2BP0y8BlTK2v6nGjN%2BKoP%2F1x1OptMN%2Bat2ZNTlPn7nVrmxfMeJdu7pruLTDo62snxHQymWiPLKvhOdgCfFAKHyWWwmxIQ
```
При тестировании “от клиента” рекомендуется открывать код страницы с виджетом в другом браузере или в инкогнито режиме или выйдя из Swarmica, если вдруг был выполнен вход от имени привилегированного пользователя.
## **Параметры создания пользователя**
:::cut{title="Развернуть"}
При создании пользователя через [https://support,yourdomain.tld/api/schema/doc/#post-/api/auth/otp/code/request](https://support,yourdomain.tld/api/schema/doc/#post-/api/auth/otp/code/request) или напрямую через [https://support.yourdomain.tld/api/schema/doc/#post-/api/users/](https://support.yourdomain.tld/api/schema/doc/#post-/api/users/) можно указывать следующие данные (ниже вариант примера):
```json
{
"user": {
"name": "Joe Doe",
"email": "joedoe@swarmica.tld",
"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](https://support.swarmica.com/api/schema/doc/#get-/api/custom_fields/) с фильтром model \= user
**Значения кастомных полей**:
Значения кастомных полей указываются в виде объекта:
```json
{
“uid”: “УИД КАСТОМНОГО ПОЛЯ”,
“value”: “ЗНАЧЕНИЕ КАСТОМНОГО ПОЛЯ В ФОРМАТЕ ЕГО ТИПА”
}
```
Например, для поля Телефон (uid \= “IHZAwFQD3bBJSmAM”) это текстовое значение.
А для поля Тип клиента (uid \= “OGRcFb1U8XFHM2r1”) указывается ключ из словаря choices, соответствующий нужному параметру:
```json
{
"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.
Все значения и ключи[ настраиваются через графический интерфейс ](https://support.swarmica.com/article/ru/124-sozdanie-kastomnyh-polej.html)
:::