Как программно заполнить документ в 1С

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

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

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

Создание нового документа через объектную модель

Точка входа — метод менеджера документа СоздатьДокумент(). Он возвращает объект типа ДокументОбъект, ещё не записанный в базу. Пока не вызван метод Записать(), данных в информационной базе нет, и объект существует только в памяти.

НовыйДок = Документы.РеализацияТоваровУслуг.СоздатьДокумент();
НовыйДок.Дата = ТекущаяДатаСеанса();
НовыйДок.Организация = Организация;
НовыйДок.Контрагент = Контрагент;
НовыйДок.Записать();

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

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

Заполнение реквизитов шапки

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

Если исходные данные приходят в виде строк (например, из файла или веб-сервиса), ссылку сначала ищут по наименованию, коду или ИНН через методы НайтиПоНаименованию(), НайтиПоКоду() менеджера справочника. Если элемент не найден — либо создают новый, либо фиксируют ошибку загрузки, но не оставляют реквизит пустым молча.

КонтрагентСсылка = Справочники.Контрагенты.НайтиПоНаименованию(ИмяКонтрагента);
Если КонтрагентСсылка.Пустая() Тогда
ВызватьИсключение "Контрагент не найден: " + ИмяКонтрагента;
КонецЕсли;
НовыйДок.Контрагент = КонтрагентСсылка;

Многие типовые документы имеют процедуру Заполнить() или обработчик заполнения, который подтягивает связанные данные — договор по контрагенту, счета учёта, ставки НДС. Вызов НовыйДок.Заполнить(ДанныеЗаполнения) после установки ключевых реквизитов избавляет от ручного заполнения десятка полей и повторяет логику интерактивного ввода.

Заполнение табличной части

Табличные части заполняются добавлением строк через метод Добавить() коллекции табличной части. Каждая строка — объект со своими реквизитами: номенклатура, количество, цена, сумма, ставка НДС и так далее.

Для Каждого СтрокаДанных Из ДанныеТоваров Цикл
НоваяСтрока = НовыйДок.Товары.Добавить();
НоваяСтрока.Номенклатура = СтрокаДанных.Номенклатура;
НоваяСтрока.Количество = СтрокаДанных.Количество;
НоваяСтрока.Цена = СтрокаДанных.Цена;
НоваяСтрока.Сумма = СтрокаДанных.Количество * СтрокаДанных.Цена;
КонецЦикла;

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

Перед записью имеет смысл сверить итог по табличной части с ожидаемой суммой документа, если она известна из источника. Расхождение — признак ошибки в данных или в алгоритме расчёта, и такой документ лучше не проводить автоматически.

НовыйДок = Документы.ПоступлениеТоваровУслуг.СоздатьДокумент();
НовыйДок.Дата = ТекущаяДатаСеанса();
НовыйДок.Организация = Организация;
НовыйДок.Контрагент = Контрагент;
СтрокаТовара = НовыйДок.Товары.Добавить();
СтрокаТовара.Номенклатура = Номенклатура;
СтрокаТовара.Количество = 10;
СтрокаТовара.Цена = 500;
СтрокаТовара.Сумма = 5000;
НовыйДок.Записать(РежимЗаписиДокумента.Проведение);

Поиск и изменение существующего документа

Если требуется дополнить уже созданный документ, сначала получают ссылку — по номеру и дате через НайтиПоНомеру(), по уникальному идентификатору или запросом. Затем через ПолучитьОбъект() загружают объект, изменяют реквизиты и записывают.

ДокСсылка = Документы.ЗаказПокупателя.НайтиПоНомеру(Номер, Дата);
Если Не ДокСсылка.Пустая() Тогда
ДокОбъект = ДокСсылка.ПолучитьОбъект();
ДокОбъект.Комментарий = "Изменён загрузкой";
ДокОбъект.Записать();
КонецЕсли;

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

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

Запись, проведение и контроль результата

Метод Записать() принимает параметр режима: РежимЗаписиДокумента.Запись — просто сохранить, РежимЗаписиДокумента.Проведение — провести с формированием движений, РежимЗаписиДокумента.ОтменаПроведения — снять с проведения. Без параметра выполняется обычная запись.

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

Попытка
НовыйДок.Записать(РежимЗаписиДокумента.Проведение);
Исключение
ЗаписьЖурналаРегистрации("ЗагрузкаДокументов",
УровеньЖурналаРегистрации.Ошибка, , ,
ОписаниеОшибки());
НовыйДок.Записать(); // сохранить хотя бы без проведения
КонецПопытки;

Результат проверяют по ссылке: НовыйДок.Ссылка.Проведен должен быть истинным, сумма документа — совпадать с ожидаемой, движения по регистрам — присутствовать. Для массовых загрузок полезен сводный контроль: количество созданных документов и их общая сумма сверяются с исходным файлом.

Типичные ошибки и ограничения

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

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

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

FAQ