Как в УНФ 3 организовать отправку документов через Telegram и интеграцию бота?

Для УНФ 3 это лучше реализовать отдельным расширением, не изменяя типовые объекты конфигурации. Функциональность целесообразно разделить на два блока:

1. Отправка документов из 1С в Telegram.
2. Клиентский Telegram-бот для прайса, взаиморасчетов и оформления заказов.

## 1. Отправка документов в Telegram

По механике это будет аналогично отправке по электронной почте, но вместо SMTP используется Telegram Bot API.

### Что должен уметь пользователь 1С

В документах УНФ добавить команду, например:

— «Отправить в Telegram»;
— «Отправить печатную форму в Telegram»;
— «Отправить клиенту в Telegram».

Команду можно добавить в формы документов:

— Заказ покупателя;
— Реализация товаров и услуг;
— Счет на оплату;
— Акт выполненных работ;
— УПД или накладная, если используются;
— Заказ поставщику, если требуется отправка поставщикам;
— другие документы с печатными формами.

В меню команды нужно дать возможность выбрать:

— конкретную печатную форму;
— несколько печатных форм;
— PDF-файл из присоединенных файлов;
— текстовое сообщение;
— получателя из карточки контрагента;
— получателя из списка пользователей Telegram.

Пример сообщения клиенту:

После текста отправляется файл через метод Telegram sendDocument.

## 2. Какие данные добавить в УНФ

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

### Справочник «Получатели Telegram»

Рекомендуемые реквизиты:

— Контрагент;
— Партнер;
— Физическое лицо;
— Пользователь 1С;
— ChatID;
— UserID;
— Имя пользователя Telegram;
— Имя;
— Фамилия;
— Номер телефона;
— Статус авторизации;
— Дата авторизации;
— Разрешены уведомления;
— Разрешены документы;
— Разрешены прайс-листы;
— Разрешены взаиморасчеты;
— Разрешено оформление заказов;
— Дата последнего сообщения;
— Дата последней ошибки отправки.

Связь с контрагентом должна быть отдельной, а не только по номеру телефона. Один контрагент может иметь несколько Telegram-получателей, например:

— директор;
— бухгалтер;
— менеджер;
— несколько сотрудников клиента.

Также желательно предусмотреть отдельный регистр сведений «Связи Telegram»:

— TelegramUserID;
— TelegramChatID;
— Контрагент;
— Партнер;
— Пользователь 1С;
— Дата начала действия;
— Дата окончания действия;
— Статус;
— Способ подтверждения.

### Почему нужно хранить именно ChatID

Для отправки сообщения Telegram необходим идентификатор чата. Имя пользователя Telegram не является надежным идентификатором:

— пользователь может изменить username;
— у пользователя может не быть username;
— username может быть неуникальным в бизнес-логике конкретной базы;
— бот не может найти пользователя только по номеру телефона без его предварительного взаимодействия с ботом.

## 3. Авторизация клиента в боте

Автоматически отправлять сообщения человеку, который ни разу не запускал бота, нельзя. Клиент должен сначала открыть бота и нажать /start.

Для УНФ лучше использовать авторизацию по одноразовому коду.

### Рекомендуемый вариант

1. В карточке контрагента или партнера в 1С пользователь нажимает «Подключить Telegram».
2. 1С формирует одноразовый код, например:

3. Клиент открывает бота по ссылке:

4. Telegram передает боту команду /start TG-7F4K92.
5. Бот передает в 1С:
— Telegram UserID;
— ChatID;
— имя;
— фамилию;
— username;
— код авторизации.
6. 1С находит созданный код и связывает Telegram-пользователя с нужным контрагентом.
7. Одноразовый код блокируется.

Это безопаснее, чем сопоставление только по ФИО или имени пользователя Telegram.

### Дополнительный способ

Можно использовать отправку номера телефона через кнопку Telegram «Поделиться контактом». Но номер телефона нужно обязательно проверять:

— номер должен принадлежать именно пользователю, который его отправил;
— нужно сравнивать contact.user_id и from.id;
— номер необходимо нормализовать к единому формату;
— желательно требовать дополнительное подтверждение.

Одной проверки номера телефона недостаточно для доступа к финансовой информации. Для взаиморасчетов лучше использовать код авторизации.

## 4. Интеграция с Telegram

Варианты получения сообщений от бота:

### Webhook

Предпочтительный вариант для рабочей системы.

Нужно:

— опубликовать HTTP-сервис 1С;
— обеспечить HTTPS;
— установить webhook Telegram;
— принимать POST-запросы от Telegram;
— быстро возвращать ответ HTTP 200;
— тяжелую обработку передавать в фоновые задания.

Схема:

Webhook удобнее для:

— быстрых ответов;
— большого количества пользователей;
— inline-кнопок;
— оформления заказов;
— получения callback-запросов.

### Long polling

Можно использовать, если нет возможности публиковать базу УНФ в Интернет.

В этом случае регламентное задание 1С периодически вызывает getUpdates. Для нормальной работы нужно использовать именно long polling с таймаутом, а не частый короткий опрос.

Для файловой базы этот вариант менее удобен, поскольку постоянно работающее задание может мешать другим регламентным заданиям. В таком случае применяют отдельный внешний сервис или промежуточный сервер.

## 5. Отправка печатной формы как PDF

Алгоритм отправки документа:

1. Получить объект документа.
2. Сформировать нужную печатную форму.
3. Вывести печатную форму во временный табличный документ.
4. Сохранить табличный документ во временный PDF-файл.
5. Сформировать подпись и описание файла.
6. Передать файл в Telegram методом sendDocument.
7. Записать результат отправки в журнал.

В журнале отправок нужно хранить:

— дату и время;
— документ 1С;
— контрагента;
— ChatID;
— название файла;
— размер файла;
— статус;
— текст ошибки Telegram;
— идентификатор сообщения Telegram;
— количество попыток отправки.

Статусы можно сделать такими:

— Подготовлено;
— Отправляется;
— Отправлено;
— Ошибка;
— Повторная отправка;
— Заблокировано пользователем.

### Важный технический момент

Для отправки файла нельзя использовать обычный GET-запрос с URL, как для простого сообщения. Метод sendDocument требует multipart-запрос с передачей файла.

В 1С это обычно реализуется через:

— HTTPСоединение;
— HTTPЗапрос;
— ДвоичныеДанные;
— временный файл;
— multipart-форму.

Также нужно учитывать ограничение размера файла и таймаут HTTP-соединения.

## 6. Отправка документов автоматически

Кроме ручной команды в форме документа можно реализовать автоматические уведомления.

Например:

— при записи заказа покупателя отправить заказ клиенту;
— после проведения реализации отправить накладную;
— после формирования счета отправить счет на оплату;
— при изменении статуса заказа уведомить клиента;
— при поступлении оплаты отправить уведомление;
— при просрочке оплаты отправить напоминание;
— при готовности заказа отправить сообщение;
— при отгрузке отправить транспортные документы.

Для этого в расширении создается справочник «Правила уведомлений Telegram».

Реквизиты правила:

— Вид события;
— Вид документа;
— Статус документа;
— Получатель;
— Шаблон сообщения;
— Печатная форма;
— Отправлять автоматически;
— Использовать фоновую отправку;
— Количество повторов;
— Интервал между повторами.

Не рекомендуется отправлять файл непосредственно из обработчика проведения документа. Правильнее:

1. При проведении записать задание на отправку.
2. Регламентное или фоновое задание обработает очередь.
3. После отправки записать результат.

Иначе медленный ответ Telegram может увеличить время проведения документа.

## 7. Получение прайс-листа через бота

Прайс-лист лучше не отправлять одной огромной таблицей. В Telegram удобнее сделать меню:

### Возможности клиента

Клиент может:

— выбрать вид цены;
— выбрать группу номенклатуры;
— указать склад;
— выбрать характеристику;
— показать только товары в наличии;
— найти товар по строке;
— открыть карточку товара;
— получить цену;
— получить остаток;
— добавить товар в корзину;
— скачать полный прайс-лист в Excel или PDF.

### Как определяется цена

Цена должна определяться не из произвольного регистра, а тем же механизмом, который используется в УНФ при продаже:

— вид цены партнера;
— соглашение с клиентом;
— валюта;
— дата действия цены;
— характеристики;
— единица измерения;
— условия отгрузки;
— индивидуальные цены клиента.

Для разных клиентов бот должен показывать разные цены. Нельзя просто выводить последний найденный вид цены без проверки соглашения и прав клиента.

### Пагинация

Telegram имеет ограничения на размер callback-данных и количество кнопок. Поэтому список товаров следует выдавать страницами:

Для каждой inline-кнопки передается не наименование товара, а короткий идентификатор:

По этому идентификатору 1С однозначно определяет номенклатуру.

## 8. Проверка взаиморасчетов

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

В меню бота можно сделать:

### Что можно показывать

Например:

### Рекомендуемые ограничения

Для каждого получателя хранить разрешения:

— видеть только свой контрагент;
— видеть все организации или только одну;
— видеть сумму долга;
— видеть документы;
— получать акт сверки;
— видеть себестоимость;
— видеть закупочные цены.

Сотруднику клиента нельзя показывать информацию только потому, что он знает ChatID. Связь с контрагентом и права должны проверяться при каждом запросе.

## 9. Получение акта сверки

Пункт «Скачать акт сверки» может работать так:

1. Клиент выбирает период.
2. Выбирает организацию, если доступно несколько организаций.
3. 1С формирует отчет или печатную форму акта сверки.
4. Формирует PDF.
5. Отправляет PDF в Telegram.
6. Записывает операцию в журнал.

Формирование отчета лучше выполнять в фоне, особенно если период большой или в базе много документов.

## 10. Оформление заказа через бота

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

### Сценарий для клиента

### Что хранить по корзине

Создается регистр сведений или отдельный временный объект:

— ChatID;
— Контрагент;
— Партнер;
— Организация;
— Склад;
— Номенклатура;
— Характеристика;
— Единица измерения;
— Количество;
— Цена;
— Сумма;
— Вид цены;
— Дата добавления;
— Идентификатор корзины;
— Статус.

Корзину нельзя хранить только в памяти сеанса. При перезапуске сервера или повторной обработке webhook данные должны сохраниться.

### Что создавать в УНФ

После подтверждения создается документ «Заказ покупателя» с заполнением:

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

Документ лучше создавать непроведенным. Проведение заказа через Telegram имеет риски:

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

Поэтому оптимальный вариант:

1. Создать заказ покупателя в статусе «Черновик» или «Не согласован».
2. Уведомить менеджера.
3. Проверить остатки, цены и задолженность.
4. После подтверждения менеджером перевести заказ в рабочий статус.
5. Отправить клиенту номер заказа.

### Защита от двойного заказа

Telegram может повторно отправить webhook, а пользователь может несколько раз нажать кнопку. Поэтому для каждой операции нужно хранить:

— update_id;
— уникальный идентификатор команды;
— статус обработки;
— дату обработки.

Если update_id уже обработан, повторно создавать заказ нельзя.

## 11. Меню бота

Пример структуры меню для клиента:

Для сотрудника компании можно сделать другое меню:

Меню должно формироваться с учетом роли пользователя и привязанного объекта 1С.

## 12. Команды и кнопки

### Обычные кнопки

Подходят для постоянного меню:

— Каталог;
— Мои заказы;
— Взаиморасчеты;
— Помощь;
— Настройки.

### Inline-кнопки

Подходят для конкретного сообщения:

— выбрать товар;
— согласовать заказ;
— отменить заказ;
— выбрать склад;
— выбрать вид цены;
— открыть заказ;
— скачать документ;
— следующая страница.

В callback нельзя передавать длинный JSON или полное представление объекта. Лучше передавать короткий ключ, например:

Сам ключ и его срок действия можно хранить в регистре сведений «Сессии Telegram».

## 13. Объекты расширения

Минимальный состав расширения:

### Справочники

— Получатели Telegram;
— Настройки Telegram;
— Шаблоны сообщений;
— Сценарии бота;
— Разрешения Telegram.

### Регистры сведений

— Связи Telegram;
— Очередь отправки;
— История отправки;
— Входящие сообщения;
— Обработанные обновления;
— Сессии Telegram;
— Корзины Telegram;
— Одноразовые коды авторизации.

### Документы или задания

— Задание на отправку Telegram;
— Заказ из Telegram, если требуется отдельный журнал обмена;
— Запрос на авторизацию клиента.

Отдельный документ «Заказ из Telegram» имеет смысл, если требуется:

— контроль ошибок;
— повторное создание заказа;
— ручное подтверждение;
— история действий клиента;
— журнал обмена между Telegram и УНФ.

## 14. Безопасность

Обязательно предусмотреть:

— хранение токена бота не в коде;
— хранение токена в настройках с ограничением доступа;
— HTTPS для webhook;
— проверку секретного пути webhook;
— проверку структуры входящего JSON;
— ограничение частоты запросов;
— проверку ChatID при каждой операции;
— запрет просмотра чужих заказов;
— проверку принадлежности товара и цены;
— журналирование операций;
— повторную авторизацию после изменения связи;
— возможность заблокировать пользователя;
— возможность отозвать доступ к Telegram.

Токен Telegram нельзя хранить в общем модуле или передавать в клиент. Его следует получать только на сервере из защищенного хранилища настроек.

## 15. Что сделать в первой версии

Для практического внедрения лучше идти по этапам.

### Первый этап

— справочник получателей Telegram;
— авторизация клиента по одноразовой ссылке;
— отправка текстовых сообщений;
— ручная отправка печатных форм из документов;
— отправка PDF;
— журнал отправок;
— повторная отправка при ошибке.

### Второй этап

— автоматическая отправка заказа;
— отправка счета и реализации;
— уведомления об оплате;
— уведомления о готовности и отгрузке;
— карточка клиента;
— меню бота.

### Третий этап

— прайс-лист;
— поиск товаров;
— остатки;
— карточки товаров;
— скачивание полного прайса;
— индивидуальные цены.

### Четвертый этап

— взаиморасчеты;
— акт сверки;
— история оплат;
— уведомления о задолженности;
— ограничения по ролям и организациям.

### Пятый этап

— корзина;
— оформление заказа;
— создание заказа покупателя;
— согласование заказа менеджером;
— контроль остатков и кредитного лимита;
— статус заказа и доставки.

Для УНФ 3 оптимальная архитектура будет такой: расширение конфигурации, webhook через HTTP-сервис, очередь исходящих сообщений, фоновые задания для формирования PDF и отчетов, справочник связей Telegram с партнерами и строгая авторизация по одноразовому коду. Такой вариант позволит сохранить типовую конфигурацию на поддержке и обновлять УНФ без потери доработок.