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

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

1. отправка печатных форм документов;
2. отправка текущей задолженности;
3. отправка прайс-листа;
4. прием заказа от клиента через Telegram;
5. создание заказа покупателя в УНФ;
6. уведомление клиента о статусе заказа и оплате.

Полностью штатной настройки «подключить Telegram аналогично электронной почте» в УНФ обычно нет. Потребуется разработка интеграции с Telegram Bot API.

## 1. Как клиент будет связываться с Telegram

Главный идентификатор клиента в Telegram, это не номер телефона и не ФИО, а chat_id.

Рекомендуемый способ привязки:

1. В УНФ у клиента создается персональная ссылка, например:

2. Ссылка отправляется клиенту по электронной почте, SMS или передается менеджером.
3. Клиент нажимает ссылку и запускает бота.
4. Бот получает chat_id клиента и код привязки.
5. В УНФ сохраняется связь:

Не следует определять клиента только по имени пользователя Telegram. Оно может отсутствовать или измениться.

Лучше добавить в расширение регистр сведений, например:

Измерения:

— Клиент;
— Организация, если в базе используется несколько организаций;
— TelegramChatID.

Ресурсы и реквизиты:

— ДатаПривязки;
— ИмяПользователяTelegram;
— Активна;
— ДатаПоследнегоСообщения;
— КодПривязки;
— Комментарий.

У одного клиента может быть несколько Telegram-чатов, например у директора, бухгалтера и менеджера. Поэтому не обязательно ограничивать связь одним chat_id.

## 2. Отправка документов клиенту

В карточке клиента или в списке документов необходимо добавить команду:

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

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

Логика должна быть аналогичной отправке по электронной почте:

1. пользователь открывает документ;
2. нажимает «Отправить в Telegram»;
3. система проверяет наличие привязанного Telegram-клиента;
4. формирует печатную форму;
5. преобразует ее в PDF;
6. отправляет файл через Telegram Bot API;
7. записывает результат отправки в журнал.

Дополнительно можно добавить флажки:

Например, при отправке реализации клиенту можно автоматически отправлять:

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

Пример сообщения:

### Как получать печатную форму

В расширении не нужно заново разрабатывать печатные формы. Желательно использовать существующие типовые механизмы УНФ:

1. получить табличный документ штатной печатной формы;
2. сохранить его во временный файл PDF;
3. передать файл в Telegram;
4. удалить временный файл после отправки.

Если типовая печатная форма не поддерживает прямое формирование PDF, можно использовать один из вариантов:

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

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

## 3. Отправка задолженности

Задолженность лучше реализовать двумя способами.

### Вариант 1. Отправка текстовой информации

Самый простой вариант, не требующий формирования отчета:

Точные показатели зависят от того, какие данные ведутся в конкретной базе:

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

Нужно выбрать один вариант как основной, чтобы данные Telegram совпадали с отчетами УНФ.

### Вариант 2. Отправка отчета в PDF

Можно формировать и отправлять клиенту PDF-отчет:

В отчет можно включить:

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

Наиболее практичный вариант: отправлять короткую сводку текстом, а при необходимости прикладывать подробный PDF.

Кнопки в Telegram:

При нажатии «Моя задолженность» бот выполняет запрос к УНФ и возвращает актуальные данные.

## 4. Автоматическая отправка задолженности вместе с документом

В настройках расширения можно добавить параметры:

Также желательно сделать настройку по клиентам или группам клиентов:

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

Пример правила:

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

В Telegram можно реализовать несколько вариантов прайс-листа.

### Простой вариант, единый файл

В УНФ формируется стандартный прайс-лист в PDF или Excel. Клиент нажимает:

Бот отправляет актуальный файл.

Файл можно формировать:

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

В настройках интеграции следует указать:

### Более удобный вариант, каталог в боте

Бот показывает разделы:

Клиент выбирает:

1. группу товаров;
2. товар;
3. характеристику;
4. количество;
5. добавляет товар в корзину.

В карточке товара можно показывать:

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

Для большого ассортимента не рекомендуется отправлять весь каталог в виде длинного списка сообщений. Лучше использовать:

— постраничную навигацию;
— поиск по артикулу;
— поиск по наименованию;
— Telegram Web App;
— ссылку на веб-каталог.

## 6. Оформление заказа через Telegram

Заказ можно оформлять непосредственно в чате.

Пример сценария:

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

Бот запрашивает:

1. организацию или покупателя;
2. договор, если он используется;
3. склад;
4. способ доставки;
5. адрес доставки;
6. желаемую дату;
7. комментарий;
8. контактное лицо;
9. подтверждение заказа.

Перед подтверждением выводится итог:

После подтверждения в УНФ создается документ:

Заполняются:

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

В документ можно записывать дополнительные реквизиты:

Если в УНФ используется заказ клиента другого типа, необходимо использовать именно тот объект, который уже является основным документом продаж в данной конфигурации. Название и состав реквизитов нужно проверить по конкретному релизу УНФ 3.

После создания заказа бот отправляет клиенту:

## 7. Согласование заказа менеджером

Создавать заказ сразу проведенным документом не рекомендуется.

Безопаснее использовать следующий порядок:

1. Telegram создает заказ в УНФ;
2. заказ записывается без проведения или с отдельным статусом;
3. менеджер проверяет цены и наличие;
4. менеджер корректирует заказ при необходимости;
5. клиент получает подтверждение;
6. заказ переводится в рабочий статус.

Это особенно важно, если:

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

Можно сделать автоматическую блокировку создания заказа при превышении задолженности:

Либо полностью запретить оформление заказа через Telegram для клиентов с просрочкой.

## 8. Уведомления клиенту

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

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

Пример:

Для этого можно использовать регламентное задание, которое периодически проверяет изменения документов. Если используется платформа 8.3.26 или новее, уведомления клиентского приложения 1С можно применять для внутренних уведомлений пользователей, но для Telegram все равно потребуется обращение к Telegram Bot API.

## 9. Способы подключения Telegram к 1С

Есть три основных варианта.

### Вариант 1. Прямая интеграция из 1С

УНФ напрямую обращается к Telegram Bot API.

Плюсы:

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

Минусы:

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

Подходит для отправки документов, прайс-листов и уведомлений.

### Вариант 2. Промежуточный Telegram-сервис

Создается небольшой сервис, например на Python, Node.js или другом серверном языке.

Схема:

Сервис отвечает за:

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

1С передает сервису команды:

Плюсы:

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

Минусы:

— появляется отдельный сервер;
— необходимо защищать API;
— возникает дополнительный компонент, который нужно сопровождать.

Для полноценного каталога и оформления заказов этот вариант обычно наиболее надежный.

### Вариант 3. Готовый сервис интеграции

Можно использовать готовую платформу, которая уже умеет работать с Telegram, а в УНФ подключить API.

При выборе нужно проверить:

— есть ли интеграция именно с УНФ 3;
— создаются ли реальные документы в УНФ;
— поддерживаются ли печатные формы;
— передается ли задолженность;
— где хранятся данные клиентов;
— можно ли выгрузить историю;
— есть ли API и документация;
— кто имеет доступ к документам и персональным данным.

## 10. Передача файлов в Telegram

Для документов используется метод Telegram Bot API sendDocument.

Обычно отправляются:

— PDF;
— XLSX;
— ZIP, если нужно передать несколько документов;
— изображения, если документ формируется как изображение.

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

Нужно предусмотреть обработку ошибок:

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

Результат каждой отправки следует записывать в журнал:

## 11. Необходимые настройки в УНФ

В расширении желательно сделать отдельную форму:

Параметры:

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

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

## 12. Права и безопасность

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

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

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

## 13. Рекомендуемая структура расширения

В расширении можно предусмотреть следующие объекты:

### Общие модули

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

### Регистр сведений для очереди

В очереди можно хранить:

— получателя;
— тип сообщения;
— документ;
— файл;
— текст;
— количество попыток;
— дату следующей попытки;
— статус;
— ошибку.

Это позволит не задерживать работу пользователя УНФ, пока отправляется большой PDF-файл.

### Регламентные задания

Для отправки документов достаточно очереди. Для интерактивного бота потребуется либо webhook, либо регулярный опрос Telegram методом getUpdates.

## 14. Что включить в техническое задание

В ТЗ стоит зафиксировать следующие функции.

### Работа с клиентом

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

### Документы

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

### Задолженность

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

### Прайс-лист

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

### Заказы

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

### Администрирование

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

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