Документ из Telegram в CRM: карантин вместо ссылки с токеном
Схема приёма клиентских документов: серверная загрузка, закрытое хранение, проверка содержимого и прав перед передачей менеджеру.
Документ из Telegram в CRM: карантин вместо ссылки с токеном
Не записывайте ссылку загрузки Telegram в карточку CRM. В документированном адресе загрузки есть токен бота, а доступность самой ссылки не делает файл безопасным. Для собственной интеграции нужен другой маршрут: принять событие, получить документ серверным исполнителем, сохранить его в закрытый карантин и разрешить вложение только после проверки содержимого и прав на обращение.
Этот разбор предназначен для разработчика и владельца процесса, принимающего документы от клиентов через обычный hosted Telegram Bot API. Нужны разрешённый доступ к интеграции, отдельное хранилище и тестовая CRM. Здесь нет готового загрузчика, отчёта о проверке действующего бота или описания подтверждённой функции 24go.site. Рассматривается message.document; фотографии, альбомы, локальный Bot API server и автоматическая распаковка архивов требуют отдельных решений.
Разделите четыре разные ссылки на файл
В объекте Document есть file_id, пригодный для получения или повторного использования файла, и file_unique_id. Последний предназначен для идентификации файла, но документация прямо запрещает использовать его для загрузки или повторной отправки. Ни один из этих идентификаторов не подтверждает, что документ принадлежит текущему обращению или разрешён для просмотра менеджеру.
Следующая сущность - file_path из объекта File. Он используется сервером для получения байтов через документированный адрес, содержащий токен. Это транспортная деталь, а не адрес вложения для пользователя. Не отправляйте такой URL в CRM, аналитику, уведомления или браузер менеджера. Проверьте также журналирование HTTP-клиента: исключение с полным адресом может раскрыть токен даже без явной записи в вашем коде.
После загрузки создайте собственный идентификатор объекта хранения. Именно он должен связывать карантинную копию с внутренней записью вложения. Отдельно существует адрес выдачи вашему сотруднику: приложение проверяет пользователя и обращение перед чтением объекта. Если используются временные подписанные адреса собственного хранилища, они тоже требуют защиты от распространения и ограниченного срока действия. Это не основание раскрывать Telegram URL.
Сохраните связь между входным событием, документом и внутренним объектом, но не смешивайте её с правами доступа. Один и тот же файл может быть прислан в разные обращения. Совпадение file_unique_id не разрешает показать документ другому клиенту или арендатору. Даже при физическом устранении одинаковых копий разрешения на каждое вложение остаются самостоятельными.
Что сохранить до вызова getFile
При приёме события запишите арендатора, бота, идентификатор обновления, контекст сообщения и внутреннее обращение, к которому разрешено добавление. Сохраните доступные file_id, file_unique_id, исходное имя, заявленный MIME-тип и заявленный размер. Не создавайте отсутствующие метаданные: в документации имя, тип и размер необязательны. Отсутствующий размер - неизвестное значение, а не пустой файл.
Исходное имя и MIME-тип в Document определены отправителем. Поэтому подпись invoice.pdf и тип application/pdf полезны для интерфейса и предварительного отбора, но не подтверждают содержимое. Контракт getFile отдельно предупреждает, что вызов может не сохранить исходные имя и тип. Сохраните их из входного объекта, когда они доступны, с явной пометкой о недоверенном происхождении.
Не используйте имя отправителя как путь на диске или ключ объекта. Генерируйте внутреннее имя, а исходное держите только как ограниченные по длине отображаемые данные с безопасным экранированием. Не подставляйте его в shell-команду сканера. Имена с путями, управляющими символами или необычными расширениями должны попадать под согласованную политику, а не управлять размещением файла.
Приём документа начинается после проверки подлинности запроса. Для этой границы есть отдельная инструкция по webhook secret. Повтор доставки не должен создавать новую задачу загрузки или второе вложение; используйте устойчивую идентичность события по руководству об идемпотентности. Эти меры не заменяют проверку самих байтов.
Определите политику до первой загрузки
Согласуйте с владельцем процесса, какие документы вообще нужны. Если для обращения достаточно PDF, не принимайте архивы и исполняемые файлы ради универсальности. OWASP File Upload Cheat Sheet рекомендует список разрешённых расширений, проверку типа, генерируемые имена, ограничения размера и изолированное хранение. Это многослойная защита: ни расширение, ни MIME, ни сигнатура по отдельности не дают достаточной проверки.
Для учебного протокола ниже выбрана политика: только PDF и максимум 5000000 загруженных байтов. Это произвольный предел приложения, а не расшифровка лимита Telegram. Документация hosted getFile на день проверки говорит о загрузке файлов до 20 MB. Не путайте этот предел с возможностями отправки файлов или отдельного локального Bot API server. Владелец может выбрать меньший предел по потребностям и доступным ресурсам.
Ограничьте также время одной попытки, суммарное число повторов, объём карантина и число одновременных задач. Маленький файл может быть дорогим для обработчика, поэтому размер входного потока не заменяет ограничения памяти, времени и числа процессов проверки. Без такой границы несколько разрешённых загрузок способны занять ресурсы остальных обращений.
Решите, кто разбирает отказ и что увидит пользователь. Статусы «получен», «проверяется», «отклонён» и «доступен» должны означать разные подтверждённые этапы. Сообщение «документ прикреплён» недопустимо сразу после получения file_id. Вместо молчаливого пропуска оставляйте понятную причину: неподдерживаемый тип, превышение размера, ошибка загрузки или незавершённая проверка.
Получите байты, не открывая их менеджеру
Выполняйте getFile серверным worker через существующий защищённый клиент бота. Проверяйте успешность ответа и наличие пригодного file_path: поле необязательно. Не собирайте рабочую ссылку в пользовательском JavaScript и не вставляйте токен в задания очереди. Секрет должен оставаться в штатном серверном контуре; очередь хранит ссылку на разрешённую операцию, а не секретный адрес.
Telegram гарантирует действительность ссылки минимум один час. Это не означает точное истечение через час и не обещает вечного доступа. Если ссылка больше не работает, документация предлагает снова вызвать getFile. Повтор должен сохранять исходную идентичность задачи и соблюдать общий бюджет попыток. Ошибку прав, неподдерживаемый размер и обрыв потока нельзя объединять в бесконечную ветку «обновить ссылку».
Загружайте во временный закрытый объект, считая реально полученные байты. Заявленный размер помогает отказать раньше, но решение о фактическом пределе должно опираться на поток. Остановите чтение при превышении лимита; частичная копия не является успешной загрузкой. Не полагайтесь только на HTTP-заголовок длины. При сетевом обрыве пометьте попытку незавершённой и удалите или изолируйте её остаток по правилам очистки.
Адрес получения формируется только доверенным серверным кодом для согласованного Telegram endpoint. Не позволяйте присланному в сообщении URL подменить источник, а клиенту - автоматически перенести секретный запрос на произвольный адрес перенаправления. Это предлагаемая граница реализации, которую нужно проверить у используемой библиотеки. Она не доказывается одним успешным скачиванием.
Карантин должен закрывать доступ, а не только обозначать папку
Карантин - состояние, при котором непроверенные байты нельзя выдать обычному сотруднику или передать в автоматический разбор CRM. Храните их вне публичного webroot, в отдельном закрытом хранилище с минимальными правами. Непредсказуемое имя публичного объекта не заменяет авторизацию. Превью и генераторы миниатюр тоже обрабатывают содержимое, поэтому не запускайте их раньше предназначенной для этого изолированной проверки.
Сначала сверяйте политику типа и фактический формат, затем выполняйте согласованную проверку содержимого в ограниченной среде. Сигнатура PDF сама по себе не доказывает, что документ безопасен. Если нужен антивирус или обезвреживание содержимого, назначьте владельца сервиса и определите, какой результат считается допустимым. Недоступный сканер означает «проверка не завершена», а не «угроз не найдено».
Не отправляйте клиентские документы в публичный сервис проверки без отдельно согласованного основания. OWASP предупреждает о риске утечки данных через такие сервисы. Договорённости о хранении, доступе, сроках удаления и резервных копиях должны соответствовать вашему процессу и применимым требованиям. Общая техническая статья не устанавливает правовое основание обработки за владельца.
Привяжите результат проверки к точной версии объекта, например к неизменяемому объекту и измеренному хешу байтов. Если содержимое заменилось после проверки, старый положительный вердикт больше не подходит. При преобразовании документа результат преобразования становится отдельной версией со своей проверкой. Не считайте статус строки «проверено» свойством любого файла, который позднее оказался по тому же адресу.
Разрешите вложение только для нужного обращения
Перед передачей в CRM повторно проверьте арендатора, обращение и полномочия действующего пользователя или сервисной операции. Между приёмом и окончанием сканирования обращение могли закрыть, переместить или лишить доступа. file_id и успешное скачивание не дают права проигнорировать это изменение.
| Наблюдение | Решение приложения | Что не делать |
|---|---|---|
| Нет допустимого file_path | Оставить ошибку получения с причиной | Объявлять пустой файл готовым |
| Заявленный или фактический размер выше политики | Отказать, очистить частичную копию | Увеличивать предел ради одного запроса без согласования |
| Имя и MIME допустимы, содержимое ещё не проверено | Оставить карантин | Давать менеджеру ссылку «для ручного просмотра» |
| Сканер недоступен или ответ не относится к текущим байтам | Ожидание либо ограниченная повторная проверка | Считать отсутствие ответа положительным вердиктом |
| Проверки пройдены, доступ к обращению отозван | Не выпускать вложение | Наследовать старые права из задачи |
| Проверки и права подтверждены | Создать разрешённую связь CRM с внутренним объектом | Записывать секретный Telegram URL |
Запись в удалённую CRM тоже может завершиться неопределённо: сервер сохранил вложение, но ответ потерялся. Применяйте подтверждённый механизм идемпотентности этой CRM или сверку по стабильной операции. Не создавайте новую операцию только из-за timeout. Отдельно сохраните квитанцию связи: внутреннее вложение, обращение, версия объекта и полученный CRM identifier.
Как проверить маршрут в тестовой среде
Подготовьте искусственные несекретные документы и тестовое обращение без продаж и уведомлений реальным клиентам. Ниже протокол для вашей реализации, а не отчёт о сетевом испытании. Используйте подменённые ответы Telegram и сканера для отказов, чтобы не искать вредоносный файл и не создавать нагрузку на настоящий API.
- Передайте допустимый небольшой PDF. До вердикта сканера пользовательский маршрут выдачи должен отказать, после положительного вердикта и проверки прав - вернуть только разрешённый объект.
- Уберите заявленный размер. Загрузка должна оставаться ограниченной по фактическим байтам, а не получать нулевой размер по умолчанию. Затем передайте поток, который превышает учебный предел: готовой копии и связи CRM быть не должно.
- Дайте допустимые имя и MIME, но несовместимое содержимое. Убедитесь, что решение не основано только на метаданных и документ не попал в превью менеджера.
- Верните отсутствие
file_path, затем обрыв загрузки. Сохраните различные причины отказа; проверьте отсутствие выдаваемых частичных файлов и уборку остатка. - Задержите сканер и замените тестовый объект другой версией. Старый положительный результат не должен выпускать новые байты. Отдельно проверьте недоступный сканер: автоматического пропуска быть не должно.
- После загрузки отзовите доступ к тестовому обращению. Файл остаётся недоступным, даже если проверка содержимого завершилась успешно. Повторите запрос от другого арендатора.
- Повторите входное событие и имитируйте потерянный ответ CRM. Сверьте число задач, внутренних объектов и удалённых связей, а не только текст успешного ответа worker.
- Проверьте логи и трассировку через все слои на тестовом окружении. Там не должно быть токена, полного адреса загрузки или содержимого документа. Сохраните обезличенные причины и идентификаторы для расследования.
Критерий завершения - не факт скачивания. Нужны наблюдаемые доказательства, что непроверенная версия не выдавалась, превышение размера остановило поток, чужое обращение осталось закрытым, а повтор не добавил второе вложение. Эти проверки зависят от вашего хранилища, scanner и CRM; таблица решений сама их не выполняет.
Что оставить в эксплуатационном отчёте
Записывайте переходы состояний, длительность ожидания, причину отказа, измеренный размер и версию политики. Для проблемной задачи должно быть понятно, закончилась ли загрузка, что проверял scanner, к каким байтам относился результат и была ли подтверждена связь CRM. Не собирайте полные документы в технические журналы ради удобства отладки.
Назначьте очистку временных объектов и карантина, срок хранения принятых документов и порядок удаления производных копий. Очистка не должна превращать старую запись CRM в незаметно пустую ссылку: интерфейс обязан различать удаление по политике и временную ошибку получения. При удалении учитывайте собственные копии, результаты преобразований и согласованный цикл резервных копий; удаление локальной копии не является обещанием стереть исходник из Telegram.
Если у команды пока нет закрытого хранилища, проверки содержимого или механизма авторизованной выдачи, остановитесь на локальном review проекта интеграции. Не заменяйте отсутствующий этап прямой ссылкой на Telegram. Безопасный следующий шаг - реализовать и проверить недостающую границу, а не расширять список форматов или автоматически принимать все присланные файлы.