Присоединённые файлы в 1С: как организовать интеграцию

Присоединённые файлы в 1С — это механизм Библиотеки стандартных подсистем (БСП), который позволяет хранить произвольные файлы (сканы договоров, изображения товаров, акты, вложения писем) с привязкой к объектам базы: документам, элементам справочников, задачам. Когда возникает задача интеграции — передать файл во внешнюю систему, получить вложение из почты, синхронизировать картинки с сайтом, — работа с этой подсистемой становится ключевой частью обмена.

Интеграция с присоединёнными файлами сводится к трём практическим задачам: программно добавить файл к объекту, программно прочитать файл (получить двоичные данные или ссылку) и передать его наружу — через HTTP-сервис, веб-сервис, COM-соединение или регламентное задание обмена. Каждый сценарий имеет свои ограничения по правам, объёму и производительности.

Ниже разобраны устройство хранения, готовые программные интерфейсы БСП, варианты интеграционных каналов, типовые ошибки и способы проверки результата. Материал ориентирован на конфигурации, где подсистема «Работа с файлами» внедрена стандартно (УТ, ERP, БП, Документооборот и подобные).

Как устроено хранение присоединённых файлов

Механизм построен на связке «владелец файла — справочник файлов — хранилище данных». Для каждого типа владельца (например, документ «Реализация товаров и услуг» или справочник «Номенклатура») создаётся свой справочник присоединённых файлов вида «<ИмяОбъекта>ПрисоединенныеФайлы». Элемент такого справочника содержит метаданные файла: имя, расширение, размер, дату создания, автора, признак подписания и шифрования.

Сами двоичные данные хранятся в одном из двух мест в зависимости от настройки «Хранить файлы в томах на диске» в параметрах работы с файлами. При хранении в информационной базе данные лежат в регистре сведений «ДвоичныеДанныеФайлов» (в старых версиях БСП — «ПрисоединенныеФайлы»). При хранении в томах в базе остаётся только путь к файлу в томе, а сами файлы лежат в сетевом каталоге.

Для интеграции это принципиально: если файлы в томах, внешняя система при наличии доступа к каталогу может читать их напрямую, минуя 1С, но при этом легко нарушить целостность связей. Если файлы в базе — единственный корректный путь получения данных идёт через программный интерфейс 1С.

Программный интерфейс: добавление и чтение файлов

Основная точка входа — общий модуль «РаботаСФайлами». Для добавления файла к объекту используется функция «ДобавитьФайл», которой передаются параметры через структуру, формируемую конструктором «ПараметрыДобавленияФайла», и адрес двоичных данных во временном хранилище. Типичный сценарий: получить двоичные данные (из HTTP-запроса, с диска, из почты), поместить во временное хранилище, вызвать добавление.

ПараметрыФайла = РаботаСФайлами.ПараметрыДобавленияФайла();
ПараметрыФайла.ВладелецФайлов = СсылкаНаДокумент;
ПараметрыФайла.ИмяБезРасширения = "Акт_сверки";
ПараметрыФайла.РасширениеБезТочки = "pdf";
ПараметрыФайла.Автор = Пользователи.ТекущийПользователь();

НовыйФайл = РаботаСФайлами.ДобавитьФайл(ПараметрыФайла, АдресВХранилище);

Для чтения применяются функции «ДвоичныеДанныеФайла» (возвращает данные для передачи наружу), «ДанныеФайла» (метаданные плюс навигационная ссылка) и «ПрисоединенныеФайлыКОбъекту» (список файлов владельца). В новых версиях БСП часть функций объявлена устаревшими и перенесена в служебные модули — ориентируйтесь на комментарии в коде вашей конфигурации, а не на примеры из старых публикаций.

1. 1
   Получите двоичные данные файла (из запроса, каталога, почты)
2. 2
   Поместите данные во временное хранилище через ПоместитьВоВременноеХранилище
3. 3
   Сформируйте параметры через РаботаСФайлами.ПараметрыДобавленияФайла
4. 4
   Вызовите РаботаСФайлами.ДобавитьФайл и сохраните возвращённую ссылку
5. 5
   Проверьте, что файл виден в карточке объекта в режиме предприятия

Варианты интеграционных каналов

HTTP-сервис внутри 1С

Самый гибкий способ отдать файлы наружу — опубликовать собственный HTTP-сервис. В обработчике по идентификатору объекта находите присоединённые файлы, получаете двоичные данные и возвращаете их в теле ответа с нужным Content-Type. Для загрузки файлов в 1С сервис принимает тело запроса, помещает его во временное хранилище и вызывает добавление. Обязательно настройте аутентификацию на уровне публикации и отдельного пользователя с минимально необходимыми правами.

OData и стандартный интерфейс

Автоматический REST-интерфейс (OData) позволяет обращаться к справочникам присоединённых файлов как к обычным объектам, если их состав включён в публикацию. Это быстрый вариант для чтения метаданных и списков файлов, но передача больших двоичных данных через OData менее удобна и производительна, чем через специализированный HTTP-сервис. Подходит для интеграций малого объёма и прототипов.

Регламентные задания и файловый обмен

Если внешняя система не умеет работать с API, применяют обмен через каталог: регламентное задание выгружает новые присоединённые файлы в сетевую папку с именами по шаблону (GUID объекта + имя файла), а загрузку выполняет обратное задание, сканирующее каталог входящих. Это надёжный, но медленный канал с задержкой на период задания и без гарантий мгновенной доставки.

Сравнение каналов интеграции

Свой HTTP-сервис

Полный контроль формата и прав; требует разработки и публикации на веб-сервере

OData

Быстрый старт без кода; ограничен при больших файлах и нестандартной логике

Файловый обмен по расписанию

Прост и отказоустойчив; задержка на интервал задания, нужен контроль дублей

COM/V83.COMConnector

Подходит для связки 1С-1С на Windows; не масштабируется и привязан к платформе

Ограничения и риски

Главный риск при интеграции — прямая запись в таблицы присоединённых файлов или регистр двоичных данных в обход API. Такая запись не заполняет служебные поля (хеш, размер, путь в томе), ломает подсистему версионирования и может привести к ошибкам при открытии файлов в интерфейсе. Все изменения выполняйте только через экспортные процедуры БСП.

Второй блок ограничений касается объёма. Передача файлов десятков мегабайт через HTTP-сервис требует настройки лимитов веб-сервера (максимальный размер запроса, таймауты), а хранение крупных файлов в базе ускоряет рост размера данных и усложняет резервное копирование. Для массовых вложений рассмотрите тома на диске с последующей выдачей файлов веб-сервером напрямую.

Третий момент — права и безопасность. Пользователь, под которым работает интеграция, получает доступ ко всем файлам объектов, на которые у него есть права. Не используйте для интеграции учётную запись администратора; создайте отдельного пользователя с ролями только на нужные типы объектов и на работу с файлами.

Типовые ошибки при интеграции

Частая проблема — файлы добавляются, но «не видны» в карточке объекта. Причины: указан неверный владелец (например, ссылка на другой тип объекта), у пользователя нет прав на справочник присоединённых файлов, либо в конфигурации для этого объекта используется нестандартный справочник файлов. Проверяйте состав подсистемы и тип справочника в метаданных.

Вторая типичная ошибка — потеря расширения или имени при передаче. Если при добавлении не заполнить «РасширениеБезТочки», файл сохранится, но при открытии система не сможет сопоставить его приложению. При выгрузке наружу всегда передавайте имя файла и расширение отдельными полями, а не только двоичные данные.

Третья группа ошибок связана с томами: после переноса базы или изменения путей к томам интеграция продолжает отдавать старые пути, и внешняя система получает ошибки доступа. После любого переноса проверяйте константу путей к томам для каждой рабочей станции или сервера.

Проверка результата интеграции

После настройки обмена проверку выполняйте в три этапа. Сначала — внутри 1С: файл, добавленный программно, должен открываться из карточки объекта, иметь корректные имя, размер и автора. Затем — на транспортном уровне: HTTP-сервис должен возвращать ожидаемый код ответа и корректный Content-Type, а при ошибках — осмысленное описание, а не пустой ответ.

Наконец, проверьте полный цикл на стороне приёмника: внешняя система должна получить файл, открыть его без повреждений (сверьте размер и, при необходимости, контрольную сумму до и после передачи). Для регламентных обменов добавьте журналирование: фиксируйте идентификатор объекта, имя файла, результат и время каждой операции — это сильно упрощает расследование сбоев.

Контрольные точки

Как проверить результат

Файл в карточке объекта

Норма

Открывается, верные имя и размер

Тревожный признак

Файл есть в списке, но не открывается или пустой

Ответ HTTP-сервиса

Норма

Код 200, корректный Content-Type и тело

Тревожный признак

Код 500, пустое тело или HTML-страница ошибки веб-сервера

Целостность данных

Норма

Размер и хеш совпадают на стороне отправителя и приёмника

Тревожный признак

Размер отличается — обрыв передачи или неверная кодировка

Журнал обмена

Норма

Каждая операция зафиксирована с результатом

Тревожный признак

Записей нет либо массовые ошибки прав доступа

FAQ

Можно ли интегрировать присоединённые файлы без доработки конфигурации?

Частично да: через публикацию OData доступны чтение и запись объектов стандартным способом, а для файлового обмена достаточно внешней обработки, запускаемой регламентным заданием. Полноценный HTTP API с нестандартной логикой потребует добавления HTTP-сервиса — это уже доработка, которую можно вынести в расширение конфигурации, не снимая основную конфигурацию с поддержки.

Где лучше хранить файлы при активной интеграции — в базе или в томах?

При небольших объёмах и редких обменах проще хранить в базе: не нужно управлять каталогами и правами на файловую систему. При больших вложениях и частой выгрузке тома на диске выгоднее: база растёт медленнее, а файлы может отдавать веб-сервер напрямую, разгружая 1С.

Почему HTTP-сервис обрывает передачу больших файлов?

Чаще всего срабатывают ограничения веб-сервера: максимальный размер тела запроса и таймауты соединения. Проверьте настройки публикации (для IIS — maxAllowedContentLength, для Apache — LimitRequestBody и директивы прокси), а также таймауты на стороне клиента. Для очень больших файлов передавайте данные частями или через файловый обмен.

Как передать файл вместе с подписью (ЭЦП)?

Подписи хранятся отдельно — в табличной части «ЭлектронныеПодписи» элемента справочника файлов. При выгрузке получайте их вместе с данными файла и передавайте отдельным полем или файлом подписи. При загрузке в другую базу добавляйте подпись через программный интерфейс подсистемы электронной подписи, иначе проверка подлинности на приёмной стороне будет невозможна.

Чем интеграция через расширение лучше изменения конфигурации?

Расширение позволяет добавить HTTP-сервисы, общие модули и обработчики без снятия конфигурации с поддержки, что упрощает обновления. Ограничение: в расширениях есть рамки по изменению ролей и некоторых объектов, поэтому сложные схемы прав иногда всё же требуют доработки основной конфигурации.