Интеграции — Администрирование¶

Документ описывает администрирование интеграций 1Формы: где хранится конфигурация, какие формы и API используются, ключевые настройки 1С и внешних сервисов, типовые ошибки и подробные параметры каждого сервиса. Администрирование сосредоточено в разделе system → подключения, в контуре sync1c и в единой форме AdminSPA «Сервисы» (v2.268+). Материал предназначен для администраторов и инженеров поддержки, настраивающих и диагностирующих интеграции.

Обзор¶

Для integrations администрирование в основном сосредоточено в разделе system → подключения и в отдельном контуре sync1c.

Ключевой принцип домена: конфигурация хранится в таблицах сервисов/интеграций, а эксплуатационное управление выполняется через Admin API (очереди, тесты соединения, повторная обработка).

Начиная с версии 2.268 в AdminSPA для управления сервисами доступна единая отдельная форма «Сервисы» (alias system-services): универсальный интерфейс с адаптивным набором полей под выбранный тип сервиса.

Механизмы администрирования¶

Автоадминка — сервисы подключений¶

Формы автоадминки для настройки сервисов подключений:

Alias формы	Название	Таблица БД	Что настраивается
`sync-1c`	Синхронизация с 1С	`dbo.SyncSettings1C`	Профили обмена 1С
`ews-service-settings`	Сервис ExchangeWebService	`dbo.EwsServiceSettings`	Подключение к Exchange
`diadoc-service-settings`	Сервис Diadoc	`dbo.DiadocServiceCredentials`	ЭДО Диадок
`sbis-service-settings`	Сервис Sbis	`dbo.SbisCredentials`	ЭДО СБИС
`dadata-service-settings`	Сервис Dadata	`dbo.DadataServiceCredentials`	Подсказки/обогащение данных
`paycontrol-service-settings`	Сервис PayControl	`dbo.PayControlServiceCredentials`	Мобильная подпись/СКЗИ
`tika-service-settings`	Сервис Tika	`dbo.TikaServiceSettings`	Извлечение текста из файлов
`azure-service-settings`	Сервис TranslateService	`dbo.AzureCognitiveServiceCredentials`	AI-перевод
`universalapi-service-settings`	Сервис UniversalApi	`dbo.UniversalApiServiceSettings`	Универсальные внешние вызовы
`vector-search-service-settings`	Сервис VectorSearch	`dbo.VectorSearchServiceSettings`	Поиск/индексация
`pt-sandbox-service-settings`	Сервис PT Sandbox	`dbo.PTSandboxServiceSettings`	Антивирусная проверка файлов (PT Sandbox)
`pt-sandbox-domain-settings`	Привязка доменов к сервису PT Sandbox	`dbo.PTSandboxDomainSettings`	Фильтрация доменов для проверки файлов
`system-services`	Сервисы	`dbo.ServicesSettings`	Глобальная карта сервисов
`file-providers`	Провайдеры файлов	`dbo.FileProviders`	Хранилища файлов (MSSQL/S3 и др.)

AdminSPA — единая форма «Сервисы» (v2.268+)¶

Маршрут: /administration/services (права администратора). SPA-форма для таблицы dbo.ServicesSettings — глобальная конфигурация всех интеграций (URL, порты, флаги, таймауты, сопоставление пользователей). Заменяет устаревшие формы автоадминки *-service-settings; серверная часть (таблицы *Credentials/*Settings) остаётся прежней.

Принципы:

Тип сервиса (ServiceType) выбирается в выпадающем списке. Для каждого типа зарегистрирован свой набор полей — после выбора типа форма перестраивается под нужный набор контролов.
Доступные типы контролов: text, password, number, checkbox, dropdown (с источником optionsKey — например, user-mapper-types, queues, queue-flows, перечислимые типы), textarea, users (с выбором групп), smart-filter, datetime (используется для readonly-полей сроков действия токенов — например в форме Passwork).
Поддерживаемые ServiceType (по состоянию на v2.268): PTSandbox, PythonExecutor, KonturCloud, KonturKEDO, Passwork и другие — точный список и набор полей по типу зависят от версии.

API:

Метод	Маршрут	Назначение
`GET`	`/api/admin/services`	Список сервисов (DataSourceGrid)
`POST`	`/api/services`	Создание сервиса
`DELETE`	`/api/services?settingsId={id}`	Удаление
`GET`	`/api/services/settings/{id}`	Чтение настроек
`POST`	`/api/services/settings`	Обновление настроек
`GET`	`/api/services/settings/user-mapper-types`	Справочник типов сопоставления пользователей
`GET`	`/api/admin/queues`	Очереди (для dropdown в формах)
`GET`	`/api/admin/queues/flows`	Потоки очередей

Не то же самое, что интерфейс секретов — /administration/services управляет конфигурацией сервиса (URL, порты, таймауты), /administration/secrets управляет учётными данными (логины, пароли, токены) (см. Интеграции — секреты). Связь между формами по типу: ServiceType в Сервисах соответствует префиксу serviceKey в Секретах (PTSandbox ↔ pt-sandbox-{id} и т.д.).

API администрирования и Редактор сущностей¶

Административные операции выполняются через маршруты API администрирования и схемы Редактора сущностей.

Редактор сущностей

Схема JSON	Таблица	Назначение
`fileProviders`	`dbo.FileProviders`	Расширенное управление файловыми провайдерами
`fileProviderDefault`	(виртуальная)	Провайдер файлов по умолчанию
`authenticationProviders`	`dbo.AuthenticationProviders`	Смежная интеграция авторизации в едином разделе подключений

API администрирования

Маршрут	Методы	Назначение
`/api/admin/sync1c/config*`	GET, POST, DELETE	CRUD конфигов 1С, тест соединения, отправка настроек
`/api/admin/sync1c/builder/*`	GET, POST	Конвейер-конструктор подготовки конфигурации
`/api/admin/sync1c/queue/*`	POST	Обработка/очистка очередей Sync1C
`/api/admin/sync1c/usermapping`	GET, POST, DELETE	Сопоставление пользователей 1С и 1Ф
`/api/admin/exchange/subscriptions`	GET	Активные подписки Exchange
`/api/admin/rebus/unsubscribe`	POST	Отписка от очередей шины сообщений
`/api/admin/fileproviders`	GET, POST, DELETE	Управление файловыми провайдерами
`/api/admin/services`	GET	Обзор зарегистрированных сервисов

Ключевые настройки¶

1. Профили интеграции 1С¶

Где настраивается: sync-1c, /api/admin/sync1c/*, страницы 1c_sync/1c_profile/1c_queue.

Таблицы БД:

dbo.SyncSettings1C
dbo.Sync1CEventQueues
dbo.Sync1CLog

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

Конвейер-конструктор: 4-шаговый мастер для автоматического создания категорий и ДП на основе метаданных 1С. Архитектура сопоставления, типы, виртуальные реквизиты/документы — в Сопоставление сущностей 1С.

Привилегированный режим (со стороны 1С). По умолчанию включён: операции с данными выполняются от лица пользователей-1С без проверки прав, что ускоряет обмен и обходит ограничения прав (RLS). Отключается флагом «Отключить привилегированный режим» в общих настройках обмена (раздел Sync1C → профиль). Отключать имеет смысл только если обмен явно должен соблюдать пользовательские ограничения 1С (редкий кейс — например, при выгрузке от имени конкретного оператора с ограниченным доступом).

2. Учётные данные внешних сервисов¶

Где настраивается: формы *-service-settings в system → подключения.

Таблицы БД:

dbo.EwsServiceSettings
dbo.DiadocServiceCredentials
dbo.SbisCredentials
dbo.DadataServiceCredentials
dbo.PayControlServiceCredentials
dbo.TikaServiceSettings
dbo.AzureCognitiveServiceCredentials
dbo.UniversalApiServiceSettings
dbo.VectorSearchServiceSettings
dbo.PTSandboxServiceSettings
dbo.PTSandboxDomainSettings

Что контролируется: URL, ключи, секреты, API-параметры и доступность интеграционного канала.

3–4. Файловые провайдеры, эксплуатация очередей и подписок¶

Файловые провайдеры и эксплуатация очередей настраиваются в разделе подключений и через Admin API.

Файловые провайдеры как инфраструктурная интеграция

Где настраивается: file-providers, /api/admin/fileproviders.

Таблицы БД:

dbo.FileProviders
таблицы настроек конкретного провайдера

Что контролируется: место физического хранения файлов, сжатие, тест подключения, переключение провайдера записи.

Эксплуатация очередей и подписок

Где настраивается: /api/admin/sync1c/queue/*, /api/admin/rebus/unsubscribe, /api/admin/exchange/subscriptions.

Таблицы БД:

dbo.MessageQueue
dbo.MessageQueueLog
dbo.MessageFlows

Что контролируется: повторные попытки, "зависшие" события, остановка/разблокировка потоков.

Административные формы очередей:

Форма	Alias	Таблица	Назначение
Журнал очередей	`message-queue-log`	`dbo.MessageQueueLog`	История обработанных событий. Колонки: дата, тип потока, событие, статус, исходный ключ очереди (`OriginalMessageId` — `ParentMessageId` из `MessageQueue`), параметры, текст ошибки.
Содержимое очереди	`queue-log`	`dbo.MessageQueue`	Активные записи в обработке: дата создания/обработки, тип потока, событие, статус, внутренний ID (`ContextId`), внешний ID (`ContextExternalId`), параметры (`Data`), текст ошибки, тип ошибки. Доступны массовые действия «Удалить события с ошибками» и «Обработать события с ошибками». Для каждой строки доступна кнопка «Выполнить повторно» — принудительно запускает обработку одного сообщения (v2.268+).

API повторного выполнения: POST /api/admin/queues/messages/{id}/execute — повторный запуск конкретного сообщения из очереди. Вызывается кнопкой «Выполнить повторно» в колонке формы queue-log (v2.268+).

Типичные ошибки настройки¶

Частые проблемы настройки интеграций и способы их диагностики:

Симптом	Причина	Где проверить	SQL-диагностика
Тест соединения 1С падает	Неверный адрес/учётные данные в профиле Sync1C	`sync-1c`, `/api/admin/sync1c/config/test-connection`	`select top (50) [Date], SettingsName, Message, TechData from dbo.Sync1CLog order by [Date] desc;`
Очередь Sync1C не разгребается	Превышен retry, события не очищены	`/api/admin/sync1c/queue/*`	`select Id, RetryCount, DateAdded, DateOfLastTry from dbo.Sync1CEventQueues order by RetryCount desc, DateAdded asc;`
Внешний сервис включён, но запросы не проходят	Неверные учётные данные/URL конкретного сервиса	соответствующая `*-service-settings` форма	`select * from dbo.UniversalApiServiceSettings; select * from dbo.DiadocServiceCredentials;`
Потоки очередей остановились после ошибки	`MessageFlows.HasErrors = 1` и ActionOnError=Stop	админка очередей	`select Id, FlowName, ActionOnError, HasErrors, FailedAttemptsCounter from dbo.MessageFlows;`
После смены FileProvider файлы недоступны	Некорректная конфигурация провайдера или fallback	`file-providers` + тест	`select ID, Name, TypeID, UseToWriteFiles, CompressContent from dbo.FileProviders;`

Сервисы внешних интеграций — подробные параметры¶

Параметры сервисов EWS, Диадок и СБИС¶

EWS, Диадок и СБИС — внешние сервисы, параметры которых задаются в формах подключений.

EWS (Exchange Web Services)

Связано. Параметры подключения EWS описаны в Календарь — администрирование. Там же: приоритет «имперсонализация» над «перевоплощением», правило «показывать только занятость», исключение для Робот 1Ф.

Диадок (ЭДО)

Версия: v2.256+.

Настройки сервиса Diadoc хранятся в dbo.DiadocServiceCredentials. Жизненный цикл: после создания сервиса → включить в sys_general_settings («Diadoc Service»); перед удалением → сначала убрать из sys_general_settings.

Параметр	Описание
Сервис	Предварительно созданный сервис с типом Diadoc (страница «Сервисы»)
Логин	Учётные данные в системе Диадок
Пароль	Пароль к аккаунту Диадок
`BoxId`	Идентификатор организации. Виден в веб-интерфейсе Диадока
`ClientId`	Уникальный строковый идентификатор клиента. Получается у `diadoc-api@skbkontur.ru` после заключения договора на API
API Url	Адрес API для онлайн-подписания

Доработка на JINT/SmartScript (с v2.267). Часть бизнес-логики ЭДО можно реализовать не через встроенные C#-смарт-действия, а через системные библиотеки SmartScript на JavaScript (JINT) — без пересборки ядра.

Библиотека	Назначение
`[edo] eds-common`	Базовая. Общие функции: HTTP-вызовы, SQL-хелперы, логирование, кэш токенов, загрузка файлов, работа с JSON. Подключается первой
`[edo] diadoc-api`	Обёртка над API Диадок: отправка/приём документов, статусы, подпись

Шаблон подключения в смарт-скрипте:

include("[edo] eds-common");
include("[edo] diadoc-api");

Прежние C#-смарт-действия продолжают работать и могут использоваться параллельно. Новые сценарии (маршрутизация, обработка ответов API, обмен документами) рекомендуется писать на JavaScript. Отладка — через стандартное логирование SmartScript. Большинство операций в JINT выполняются синхронно; очередь сообщений остаётся актуальной для синхронизации статусов и входящих документов.

СБИС (ЭДО)

Версия: v2.260+.

Настройки сервиса SBIS хранятся в dbo.SbisCredentials. Жизненный цикл аналогичен Диадоку: включение через sys_general_settings («Sbis Service»), удаление — только после отключения.

Параметр	Описание
Сервис	Предварительно созданный сервис с типом Sbis
Логин	Учётные данные в системе СБИС
Пароль	Пароль к аккаунту СБИС
API Url	Адрес API для подключения к СБИС
ИНН	ИНН компании
КПП	КПП компании
Уникальный ID	Идентификатор участника ЭДО (participantID) — из личного кабинета СБИС

CustomSettings ЭДО и интеграций¶

Глобальные ключи CustomSettings, относящиеся к ЭДО и интеграциям:

Ключ	Тип	Назначение
`DiadocLastEventsId`	JSON	Обязателен для интеграции. Курсор последних событий Диадок: `{"LastEvents":[{"BoxId":"...","ClientId":"...","Timestamp":1704067200}]}`. `Timestamp` — наносекунды от `01.01.0001`; `0` → автозаполнение датой первого подключения
`DiadocLogEnabled`	bool	Логирование ответов API Диадок (для диагностики)
`SbisLastEventsId`	JSON	Обязателен для интеграции. Курсор последних событий СБИС: `{"LastEvents":[{"EventId":N,"ServiceId":N}]}`
`Sync1CQueueMaxRetryCount`	int	Количество повторных попыток при неудачной синхронизации из 1Ф в 1С (превышение → событие висит с `HasErrors=1`)
`EnableCipherInUniversalApiCallbackUrls`	bool	Шифрование callback-URL в UniversalAPI (для повышения безопасности обратных вызовов)
`RedefiningIdentity`	bool	Механизм смещения автоинкремента строк таблиц сущностей. Работает в связке с `dbo.Settings.ServerIdKey` (используется при объединении инсталляций / миграциях с пересечением ID)
`TranslationService`	string	Управление сервисом автоматического перевода локализованных значений. По умолчанию используется AI-сервис (`UniversalApi` с типом TranslateService). Настройка позволяет вернуться к Azure Cognitive Services
`DadataAddressProviderAppendApiV2Path`	string	Управляет тем, дописывает ли `DadataAddressProvider` сегмент `/api/v2` к URL провайдера из поля «API Url». Только явное значение `"false"` отключает автодоп; отсутствие ключа, `null`, `"true"` и любое другое значение — включают. Подробнее: раздел DaData (подсказки)

DaData (подсказки)¶

Версия: v2.256+. Сервис используется для работы подсказок ДП «Текст» и ДП «Адрес».

Параметр	Описание
Сервис	Предварительно созданный сервис с типом Dadata
Token	API-ключ из личного кабинета dadata.ru
API Url	`https://suggestions.dadata.ru/suggestions/api/4_1/rs`

Поведение флага `DadataAddressProviderAppendApiV2Path`¶

DadataAddressProvider строит итоговый URL через new Uri(baseUri, "api/v2") — стандартный relative-URI resolution .NET.

Значение "true" (или ключ отсутствует) — автодоп включён:

К URL из поля «API Url» дописывается сегмент api/v2
https://suggestions.dadata.ru/ → https://suggestions.dadata.ru/api/v2 ✅
https://suggestions.dadata.ru/suggestions/api/4_1/rs → https://suggestions.dadata.ru/suggestions/api/4_1/api/v2 ❌ — последний сегмент заменяется, путь сломан; RestSharp получает 404/HTML, десериализует в пустой объект, подсказки и нормализация адресов молча возвращают пустоту, ошибок в логе нет

Значение "false" — автодоп отключён:

URL из настроек передаётся в SuggestClient без изменений
https://suggestions.dadata.ru/suggestions/api/4_1/rs → https://suggestions.dadata.ru/suggestions/api/4_1/rs ✅
Требуется при использовании актуального формата URL Dadata или корпоративного прокси (ЛИКАРД, ВСК), где URL уже содержит полный путь

Значение ключа	Итоговый URL (пример)	Когда использовать
отсутствует / `null` / `"true"`	`{URL}/api/v2` (relative resolution)	Старый формат URL: `https://suggestions.dadata.ru/`
`"false"`	`{URL}` без изменений	Актуальный формат URL или корпоративный прокси

PayControl (мобильная ЭП)¶

Версия: v2.256+.

⚠️ В системе может быть создан только один сервис PayControl.

Настройки хранятся в dbo.PayControlServiceCredentials. После создания — назначить группы через кнопку «Группа пользователей PC».

Параметр	Описание
Сервис	Предварительно созданный сервис с типом PayControl
`system_id`	Выдаётся при приобретении сервера PayControl
Адрес API	Адрес для подписания онлайн
Адрес Server Signer API	Адрес для подписания офлайн (если у ЭЦП включён признак «Серверное подписание»)
Расширенное свойство (`user_id`)	Название расширенного свойства пользователя, в котором хранится `user_id`
Расширенное свойство (серверная подпись)	Название свойства, хранящего признак серверной подписи PayControl
Расширенное свойство разрешения смены устройства	Название свойства, хранящего признак разрешения повторной регистрации (`true`/`false`; отсутствие = `false`)

Повторная регистрация требуется при перевыпуске сертификата, утере смартфона или переустановке приложения 1F Mobile.

Apache Tika (извлечение текста)¶

Версия: v2.260+. Сервис необходим для работы TikaJob — полнотекстового индексатора файлов (поиск по файлам). Управление: включение/выключение через sys_general_settings («Tika Service»).

⚠️ Файлы .md и .txt обрабатываются без обращения к Tika — содержимое читается напрямую с автоматическим определением кодировки.

Параметр	Описание	Рекомендация
Сервис	Предварительно созданный сервис с типом Tika
API Url	Адрес API Tika
Разрешённые типы файлов	Через запятую, без пробелов	`pdf,doc,docx,xls,xlsx,ppt,pptx,txt,xml,html,eml,sql,pgsql,json,md`
Максимальный размер (КБ)	Максимальный размер обрабатываемого файла	Рекомендуется 50000
Максимум параллельных запросов		Рекомендуется 10
Разрешённые языки	Формат: `rus+eng+fre+ger+ita+spa+uzb` (первые 3 буквы, через `+`)	По умолчанию: English, French, German, Italian, Spanish, Uzbek

Azure TranslateService (AI-перевод)¶

Версия: v2.256+. Используется для автоматического перевода комментариев на все поддерживаемые языки через AI-сервис (задание AzureCognitiveTranslateJob).

⚠️ Сценарий применения (логика, где применяется, лог) — см. Локализация — администрирование § 4. Здесь — только параметры (URL/Ключ/Регион).

⚠️ Для AI-перевода используются только поля URL и Ключ. Поля «Логин» и «Пароль» в AI-режиме не задействованы.

Параметр	Описание
Сервис	Предварительно созданный сервис с типом TranslateService
URL	`https://api.cognitive.microsofttranslator.com/translate?api-version=3.0`
Ключ	Azure Cognitive API key
Регион	Например, `westeurope`

Переключение на Azure: в SettingsCustom ключ TranslationService = azure.

UniversalApi (внешние AI-вызовы)¶

Версия: v2.264+. Асинхронное взаимодействие с внешними AI-сервисами через очередь — запрос отправляется, ответ приходит через callback.

Параметр	Описание
Сервис	Предварительно созданный сервис с типом UniversalApi
ApiUrl	Адрес API внешнего сервиса
ApiKey	Уникальный код для идентификации
Callback поток	Выбор из существующих потоков очереди
Callback очередь	Выбор из существующих произвольных событий очереди

Результат записывается в MessageQueue/MessageQueueLog: колонка textResult (текст), booleanResult (да/нет).

Для упрощённого формирования запросов доступно смарт-действие «Вызов внешнего сервиса».

VectorSearch (векторный поиск)¶

Внешний AI-сервис, обеспечивающий векторный (семантический) поиск по задачам. Настройки хранятся в dbo.VectorSearchServiceSettings, форма автоадминки — vector-search-service-settings.

Параметр	Описание
Сервис	Предварительно созданный сервис с типом VectorSearch (страница «Сервисы»)
ApiUrl	Адрес API внешнего сервиса векторного поиска

Серверная часть векторного поиска описана в домене «Поиск».

PT Sandbox (антивирусная проверка файлов)¶

Версия: v2.266+. Перехватывает загрузку файлов до записи в хранилище.

⚠️ Детальное описание всех 13 параметров конфигурации, архитектура, API PT Sandbox v5.7, фильтры, кеш вердиктов, таблицы БД — в PT Sandbox — интеграция.

В этом разделе — только краткая сводка для администратора.

Настройки: форма pt-sandbox-service-settings (таблица dbo.PTSandboxServiceSettings) + отдельная форма pt-sandbox-domain-settings (фильтрация по доменам, таблица dbo.PTSandboxDomainSettings). Включение — через sys_general_settings («PT Sandbox Service»).

Нет встроенного теста подключения — только реальная загрузка файла для проверки.

Контур.Облако (облачная УКЭП)¶

Версия: v2.266+. Облачная электронная подпись без локального токена. Используется для подписания на маршруте согласования, выбора сертификата из Контура, подтверждения SMS-кодом.

Параметр	Описание
Сервис	Предварительно созданный сервис с типом Контур.Облако
API Key	Для заголовка `X-KONTUR-APIKEY`
Адрес сервера	Адрес для операций подписания, загрузки файлов, получения статусов

Процесс подписания: пользователь выбирает сертификат → отправляется SMS-код → ввод кода → подписание.

При наличии сертификатов разных типов (НЭП, УКЭП) система автоматически фильтрует список, показывая только сертификаты нужного типа.

Контур.КЭДО (кадровый ЭДО)¶

Версия: v2.266+. Работает совместно с Контур.Облако: КЭДО предоставляет организационный контекст, Облако выполняет подписание.

Возможности: получение списка сотрудников из КЭДО, привязка логина КЭДО к пользователю 1Формы, получение действующих сертификатов, подписание кадровых документов (приём, увольнение, отпуска).

Параметр	Описание
Сервис	Предварительно созданный сервис с типом Контур.КЭДО
Адрес сервера	Адрес API Контур.КЭДО
Идентификатор клиента	ID приложения для OAuth-авторизации в Контуре
Идентификатор организации	OrgID для запроса сотрудников и сертификатов (CertificatesRequest.OrgId)
API Key	Для заголовка `X-KONTUR-APIKEY`
Логин	Сервисный логин для получения access token
Пароль	Пароль сервисной учётной записи

Matomo (веб-аналитика)¶

Версия: v2.256+.

⚠️ В Matomo аналитическая группа устанавливается для customDimension с id=1. Установка другого ID невозможна.

Настройка: ключ matomo в SettingsCustom.

Формат CustomSettings:

{
  "baseURL": "https://***/matomo.php",
  "serverAddress": "***.***.ru",
  "siteId": 5,
  "analyticGroups": [...]
}

CustomDimension ID=1 (контекст — клиент):

Значение	Описание
`firstForm`	Все внутренние пользователи 1Формы (HD)
`firstFormOutstaff`	Внешние пользователи 1Формы

CustomDimension ID=2 (действия — тип страницы):

Значение	Описание
`tasksView`	Просмотр карточки задачи на любом синдикате
`tasksCreate`	Просмотр карточки создания новой задачи
`tasksList`	Просмотр списка задач категорий
`templatesView`	Просмотр шаблона МТФ (только для МП)
`templatesCreate`	Создание шаблона НТФ (только для МП)
`chatsList`	Список чатов
`chatsView`	Просмотр чатов
`chatsCreate`	Создание чата
`dashboardsView`	Портал (дашборд)
`contactsList`	Экран просмотра и поиска контактов
`profileView`	Просмотр профиля пользователя
`calendarsView`	Календарь
`feedsList`	Лента

Telegram-бот (двунаправленный чат)¶

Чат-бот позволяет дублировать сообщения между чатами Telegram и задачами-чатами 1Формы. Реализуется как публикация + Lua-скрипты, в которых проксируются обновления Telegram API в комментарии задачи (и наоборот).

Архитектура: интеграция целиком на конфигурации (Lua SmartScripts + публикации + пользовательские таблицы); платформенный код отвечает только за отправку 2FA-кодов.

Шаги настройки¶

В Telegram:

Через @BotFather командой /newbot создать бота. Username должен заканчиваться на bot (например, Chat1FBot); если занят — будет ошибка «Sorry, this username is invalid».
Сохранить токен HTTP API (bot token) и ID бота — потребуются в Lua-скрипте.
Добавить бота как участника в нужный чат Telegram.

В 1Форме:

Создать служебного пользователя для роли чат-бота (его ID подставляется в скрипт).
Создать таблицы и представление БД:
cm_Telegram_ChatToTask — связь TelegramChatID ↔ TaskID.
cm_tlg_tasks — связь TelegramMessageID ↔ CommentID (нужна для последующих edit / delete).
View cm_vw_ChatToTask — производная от cm_Telegram_ChatToTask (через JOIN с cm_tlg_tasks); используется во всех smart-фильтрах правил.
Заполнить в профилях пользователей:
Users.ICQ — числовой Telegram-ID (для поиска @id в chat_id/user_id).
Users.TelegramUserName — @username (для упоминаний; если не задан, в entities используется text_mention с firstName).
Системные категории в разделе Системный:
«Общение» — личные чаты (только два участника: пользователь + бот).
«Группы» — групповые чаты Telegram. Бот один на площадку (на все категории и чаты).
Создать публикацию с Lua-скриптом — обработчик входящего webhook (точка входа: dbo.1fSynkChat_webhook_telegram @Mode = @json).
В смарт-действиях системных категорий настроить отправку комментариев из 1Ф обратно в Telegram (см. ниже).

Маршруты Bot API¶

Используются в смарт-действии «Отправить HTTP-запрос» (Url — токен бота + маршрут):

Маршрут	Используется на событии
`https://api.telegram.org/bot{token}/sendMessage`	После написания комментария (создание сообщения в Telegram)
`https://api.telegram.org/bot{token}/editMessageText`	После редактирования комментария (правка текста по `message_id`)
`https://api.telegram.org/bot{token}/deleteMessage`	Перед удалением комментария / После удаления подписчика

После sendMessage ответ парсится: $.HttpResponse.ResponseContent.result.chat.id и $.HttpResponse.ResponseContent.result.message_id записываются в cm_tlg_tasks для последующих editMessageText / deleteMessage.

События-триггеры (исходящие из 1Ф в Telegram)¶

Исходящие события и отправляемые при них запросы в Telegram:

Событие	Назначение
После написания комментария (комментарий не пустой, не ответ, без адресатов)	Отправка обычного сообщения
После написания комментария (есть адресаты)	Отправка с `entities` (упоминания)
После написания комментария (является ответом)	Отправка с `reply_to_message_id`
После редактирования комментария	`editMessageText` по сохранённому `message_id`
Перед удалением комментария	`deleteMessage` по `message_id`
После удаления подписчика	Удаление пользователя из чата (через Telegram-API)
Перед удалением задачи	Очистка чата / связей
После перехода / После смены текста задачи	Уведомления в чат

Все правила используют smart-фильтр вида:

select 1 from cm_vw_ChatToTask v where v.TaskID = @ContextID
-- + опционально для edit/delete:
join [custom].cm_tlg_tasks t on v.chatid = t.tlg_chat_id
where t.task_id = @eventParam0

Параметр `entities` (упоминания)¶

Для упоминаний (@username или text_mention пользователя без публичного username) формируется JSON-массив с полями offset, length, type, и опциональным user.id:

type = "mention" — если у пользователя задан TelegramUserName (@…).
type = "text_mention" — если только ICQ (числовой ID); в user.id подставляется ICQ.

Список адресатов берётся из dbo.CommentParticipants через JOIN с Users.

Распознавание автора при публикации сообщения из Telegram в 1Ф:

Условие	Поведение
У пользователя в профиле 1Ф указан Telegram ID (`Users.ICQ`)	Сообщение публикуется от его имени
ID не указан, но есть подходящая учётная запись	Используется она
Нет учётной записи	Создаётся новый пользователь или используется служебный бот-пользователь (зависит от настроек скрипта)

WhatsApp (мессенджер)¶

Версия: v2.256+. Интеграция через чат-бота — пользователь пишет ключевое слово или числовой код. Сценарии общения задаются администраторами.

В отличие от Telegram, WhatsApp-бот может самостоятельно инициировать диалог (для этого нужен список контактов в 1Форме).

3 способа интеграции

Способ	Преимущества	Недостатки
Бизнес-аккаунт WhatsApp	Безопаснее; может сам инициировать диалог	Долгая процедура оформления; сложная документация
Chat API (платная подписка)	Быстрое оформление; подробная документация	Платная; ниже уровень безопасности
WAZZUP	Быстрая настройка; множество номеров	Требует прогрев аккаунта

WAZZUP — 6 шагов настройки

Зарегистрироваться на wazzup24.ru
Добавить канал WhatsApp → сканировать QR-код
Скопировать ключ API (раздел «Интеграция с CRM» → API → «Подключить»)

⚠️ Прогрев аккаунта (критично): - Новый аккаунт: переписываться с 10–15 людьми в течение суток - Для стабильной работы: открывать WhatsApp раз в пару недель - При нарушении: WhatsApp разлогинивает из WAZZUP → переподключение канала

Отправка сообщений (POST):

POST https://api.wazzup24.com/v3/message
Authorization: Bearer {key}
Content-Type: application/json

{
  "channelId": "...",       // uuidv4 канала
  "chatType": "whatsapp",   // или "whatsgroup"
  "chatId": "...",
  "text": "...",
  "crmMessageId": "..."
}

Webhooks (PATCH):

PATCH https://api.wazzup24.com/v3/webhooks
{
  "webhooksUri": "https://...",
  "subscriptions": {
    "messagesAndStatuses": true,
    "contactsAndDealsCreation": true,
    "channelsUpdates": true,
    "tepmplateStatus": true
  }
}

Webhook-URL получает тестовый POST {test: true} — должен вернуть 200.

Lua-примеры (отправка ответа, получение входящих, обработка файлов) реализуются отдельным Lua-скриптом.

PHP-интеграция (вызовы из PHP)¶

Версия: v2.184+ (токены); до v2.184 — только cookie.

Связано. Заголовок 1FormaAuth и схема аутентификации описаны в Авторизация — администрирование. Специфика PHP: json_decode для токена и особенности curl.

Метод 1: токены (v2.184+)¶

Пример получения токена и запроса к API на PHP:

// Получение токена
$authUrl = $formaUrl . "/app/v1.0/api/auth/token?login=" . $formaUser . "&password=" . $formaPwd;
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $authUrl);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "GET");
curl_setopt($ch, CURLOPT_HTTPHEADER, ["Accept: application/json"]);
$result = curl_exec($ch);
curl_close($ch);

// ВАЖНО: json_decode ОБЯЗАТЕЛЕН — токен возвращается как JSON-строка в кавычках
$token = json_decode($result);

// Запрос к API
$url = $formaUrl . "/app/v1.0/api/info";
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["1FormaAuth: " . $token]);  // НЕ "Authorization: Bearer"
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "GET");
$result = curl_exec($ch);
curl_close($ch);

⚠️ Authorization: Bearer {token} → всегда 401. Только заголовок 1FormaAuth.

Авторизация по cookie (для версий до 2.184):

$authUrl = $formaUrl . "/iOSClientServices/Auth.ashx";
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $authUrl);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_HEADER, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, "UserName=" . $formaUser . "&Pass=" . $formaPwd . "&IsDebug=1");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
$result = curl_exec($ch);
preg_match_all('/^Set-Cookie:\s*([^;]*)/mi', $result, $matches);
$cookies = [];
foreach ($matches[1] as $item) {
    parse_str($item, $cookie);
    $cookies = array_merge($cookies, $cookie);
}
curl_close($ch);

Онлайн-редакторы: MS Office Online и OnlyOffice CE¶

MS Office Online и OnlyOffice CE — два варианта онлайн-редакторов, параметры которых задаются в OfficeOnlineEditor.

MS Office Online (webApps) — устаревший

Удалено в актуальных версиях. Ключ OfficeOnlineEditor.editor=webApps в актуальной сборке не работает: интеграция с Office Web Apps Server убрана, серверные настройки и WOPI-discovery не используются. Для онлайн-просмотра и редактирования документов используйте Р7-Офис (editor=r7) или OnlyOffice CE (editor=OnlyOffice, см. ниже). Информация ниже сохранена как историческая.

CustomSettings ключ OfficeOnlineEditor:

{"editor": "webApps"}

⚠️ Обязательное условие (исторически): в корневой папке веб-сервера должен существовать файл discovery: C:\inetpub\wwwroot\DevTC\wopi

Без этого файла редактор не открывался. В актуальной сборке файл больше не учитывается.

Параметры Web Apps задавались в sys_general_settings#webapps.

OnlyOffice CE (ограничения)

Версия: v2.257+.

Связано. Версионирование ключа r7 → onlyOffice с v2.265 описано в Файлы — онлайн-просмотр (диагностика). CustomSettings формат и персонализация — там же.

CustomSettings ключ OfficeOnlineEditor:

{"editor": "OnlyOffice", "settings": {"serverAddress": "https://domain/office", "allowedIPs": []}}

Параметр	Описание
`editor`	`OnlyOffice` (v2.265+); `r7` (v2.264 и ниже — только для Р7-Офис)
`serverAddress`	Адрес сервера OnlyOffice (например, `https://domain/office/`)
`allowedIPs`	Список разрешённых IP или подсетей (может быть пустым)

appsettings.json R7.SecretKey — ключ для подписи запросов к Р7-серверу (минимум 32 символа). Требуется при OfficeOnlineEditor.editor=r7 или OnlyOffice для совместимых развёртываний:

"R7": { "SecretKey": "yourSecretKey" }

Ограничения OnlyOffice CE (критично)

⚠️ Лимит 20 одновременных сессий. При превышении все последующие подключения открываются только в режиме readonly.

⚠️ Кластеризация не поддерживается. Для кластеризации/отказоустойчивости/большой нагрузки — OnlyOffice Enterprise или Р7-Офис.

Требования к ресурсам (OnlyOffice CE)

Пользователей	vCPU	RAM	Storage
< 100	1	4 GB	40 GB
100–200	2	4 GB	80 GB
200–400	4	4 GB	160 GB

1С — справочник XML-тегов¶

Справочник XML-тегов синхронизации с 1С описывает структуру настроек, реквизитов, файлов и событий.

Теги начинаются с 1C (настройки 1С:Предприятие) или TC (настройки 1Формы).

SyncSettings — общие настройки синхронизации¶

Атрибуты корневого тега синхронизации:

Атрибут	Описание
`Name`	Имя настроек (отображается в списке)
`OneCAddress`	Адрес сервиса 1С:Предприятие
`OneCUserName` / `OneCPassword`	Учётные данные 1С
`TCAddress`	Адрес сервиса 1Формы
`TCUserName` / `TCPassword`	Учётные данные 1Формы
`TCSommentOnEpChange`	Публиковать комментарии об изменении ДП (`true`/`false`). ⚠️ Только в общих настройках, не в категориях
`GUIDExtParamID`	ID ДП типа «Текст» для хранения GUID записей 1С. ⚠️ При нескольких задачах в категории с одинаковым GUID обновляется только последняя по `TaskID`; новые не создаются
`UsersDic`	Название справочника пользователей в 1С
`UsersFilter`	Имя булева реквизита 1С для фильтрации пользователей. Если не указан, но указан `UsersDic` — синхронизируются все
`UsersFilterIn1Forma`	Если `true` — фильтрация на стороне 1Ф (позволяет фильтровать по виртуальным реквизитам), но значительно медленнее физических реквизитов 1С
`QueryRepeatTime`	Интервал проверки очереди (формат `HH:mm:ss`, например `00:05:00`)
`TC1C_SyncLog`	Логирование первичной выгрузки: `0` — выкл., `1` — полные (по умолчанию), `2` — только ошибки
`UpdateLookupsByGuids`	Синхронизация Lookup ДП по GUID (`true`/`false`)
`SendErrorCommentToTask`	Записывать комментарий в задаче и сообщение в лог при ошибке. По умолчанию: `true` (если опция не указана или пустая)
`ImportStrategy`	`0` — только создание, `1` — только обновление, `2` — создание+обновление (по умолчанию)

SyncRecords / Record — настройки справочника¶

Атрибуты тега SyncRecords / Record:

Атрибут	Описание
`OneCDocName`	Системное имя справочника/документа в 1С
`OneCSynonym`	Псевдоним справочника/документа в 1С
`TCSubcatID` / `TCSubcatName`	ID/название категории в 1Ф
`SyncSource`	Источник данных (только источник может создавать задачи/документы): `_1C` / `_TC` / `Both`
`SyncDirections`	Направление: `TwoSided` / `From1CtoTC` / `FromTCto1C`
`DefaultActionOnError`	При ошибке входящего события: `NotAssigned` (игнорировать) / `Ignore` (только уведомить) / `ForceAddToQuery` (сразу в очередь) / `AddToQuery` (в очередь после первой ошибки) / `Cancel` (отклонить)
`DefaultNotificationOnError`	Способ уведомления при ошибке: `NotAssigned` / `Comment` (комментарий к задаче) / `Alert` (предупреждение) / `Both`
`DefaultErrorMessage` / `DefaultSuccessMessage`	Сообщения об ошибке/успехе по умолчанию (используются, если не указаны для конкретного события)
`SmartFilterID`	ID смарт-фильтра для отбора задач, отправляемых из 1Ф в 1С. `0` — фильтрация выключена
`DisableTaskTextSync`	`true` — тексты задач 1Ф не заменяются на тексты из 1С (по умолчанию `false`)
`InboxQueueFlowId`	Опциональный flow для входящих документов (`None` по умолчанию). Подробнее — в Сопоставление сущностей 1С

Files — синхронизация вложенных файлов¶

Дочерний для Record тег. Управляет синхронизацией файлов между задачами 1Ф и реквизитами 1С.

Атрибут	Описание
`CatalogName`	Имя справочника 1С, в котором хранятся вложенные файлы
`BinFileProperty`	Имя реквизита 1С с двоичными данными файла
`FileNameProperty`	Имя реквизита 1С с именем файла
`OwnerProperty`	Имя реквизита 1С со ссылкой на документ-владелец
`SyncDirections`	Направление синхронизации файлов: `TwoSided` / `From1CtoTC` / `FromTCto1C`
`ExtParamIds`	Список ID ДП «Файл» в 1Ф, для которых выполняется обмен. Если в категории два ДП «Файл», но указан только один — обмен происходит только при работе с этим ДП; вложения в другие ДП и в общие вложения задачи не синхронизируются

Сопоставление реквизитов и события синхронизации¶

SyncExtParams / Property — сопоставление реквизитов

Атрибут	Описание
`RequisiteName` / `Synonym`	Системное имя и имя реквизита в 1С
`ExtParamID` / `ExtParamName`	ID/название ДП в 1Ф
`Type`	Тип ДП: `Checkbox`, `Combobox`, `Date`, `DateTime`, `LookUpField`, `Money`, `Numerator`, `NumericValue`, `Select`, `Table`, `Text`, `TextArea`, `TextAreaWOFormat`, `URL`
`RepresentAsReadonlyText`	`true` — передавать как текст, без выгрузки подчинённого справочника

Event1C — события из 1С (7 типов)

Событие	Описание	Action
`Create`	Создание документа	`ChangeTask` / `ChangeToStatus` / `DeleteTask`
`Modify`	Изменение	`ChangeTask` / `ChangeToStatus` / `DeleteTask`
`Post`	Проведение	`ChangeTask` / `ChangeToStatus` / `DeleteTask`
`ClearPost`	Отмена проведения	`ChangeTask` / `ChangeToStatus` / `DeleteTask`
`Repost`	Перепроведение	`ChangeTask` / `ChangeToStatus` / `DeleteTask`
`MarkDelete`	Пометка на удаление	`ChangeTask` / `ChangeToStatus` / `DeleteTask`
`UnmarkDelete`	Снятие пометки на удаление	`ChangeTask` / `ChangeToStatus` / `DeleteTask`

EventTC — события из 1Ф

Событие	Описание
`CreateTask`	Создание задачи
`ChangeTask`	Изменение ДП
`ChangeToStatus`	Переход в статус
`MakeStep`	Переход по маршруту
`DeleteTask`	Удаление задачи
`FileUpload` / `FileDelete`	Вложение/удаление файла
`EPFileUpload`	Загрузка файла в ДП
`CustomEvent`	Произвольное событие

EventTC → действия в 1С

Action	Описание
`Create` / `Modify`	Создать/изменить документ
`Post` / `ClearPost` / `Repost`	Провести/отменить проведение/перепровести
`Lock` / `Unlock`	Заблокировать/разблокировать
`MarkDelete` / `UnmarkDelete`	Пометить на удаление / снять пометку

Связанные документы¶

См. также:

PT Sandbox — интеграция
Календарь — администрирование — EWS
Локализация — администрирование — Azure TranslateService (сценарий)
Файлы — онлайн-просмотр (диагностика) — OnlyOffice CE, версионирование ключа r7→onlyOffice
Авторизация — администрирование — PHP-интеграция, заголовок 1FormaAuth
Системные настройки
Почта — администрирование

Интеграции — Администрирование¶

Обзор¶

Механизмы администрирования¶

Автоадминка — сервисы подключений¶

AdminSPA — единая форма «Сервисы» (v2.268+)¶

API администрирования и Редактор сущностей¶

Ключевые настройки¶

1. Профили интеграции 1С¶

2. Учётные данные внешних сервисов¶

3–4. Файловые провайдеры, эксплуатация очередей и подписок¶

Типичные ошибки настройки¶

Сервисы внешних интеграций — подробные параметры¶

Параметры сервисов EWS, Диадок и СБИС¶

CustomSettings ЭДО и интеграций¶

DaData (подсказки)¶

Поведение флага DadataAddressProviderAppendApiV2Path¶

PayControl (мобильная ЭП)¶

Apache Tika (извлечение текста)¶

Azure TranslateService (AI-перевод)¶

UniversalApi (внешние AI-вызовы)¶

VectorSearch (векторный поиск)¶

PT Sandbox (антивирусная проверка файлов)¶

Контур.Облако (облачная УКЭП)¶

Контур.КЭДО (кадровый ЭДО)¶

Matomo (веб-аналитика)¶

Telegram-бот (двунаправленный чат)¶

Шаги настройки¶

Маршруты Bot API¶

События-триггеры (исходящие из 1Ф в Telegram)¶

Параметр entities (упоминания)¶

WhatsApp (мессенджер)¶

PHP-интеграция (вызовы из PHP)¶

Метод 1: токены (v2.184+)¶

Метод 2: cookie (устаревший, до v2.184)¶

Онлайн-редакторы: MS Office Online и OnlyOffice CE¶

1С — справочник XML-тегов¶

SyncSettings — общие настройки синхронизации¶

SyncRecords / Record — настройки справочника¶

Files — синхронизация вложенных файлов¶

Сопоставление реквизитов и события синхронизации¶

Связанные документы¶

Поведение флага `DadataAddressProviderAppendApiV2Path`¶

Параметр `entities` (упоминания)¶