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

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

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

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

Получение объекта документа для изменения

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

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

Метод ПолучитьОбъект() загружает документ из базы целиком, включая все табличные части. Это затратная операция, поэтому в циклах не следует получать объект раньше, чем он реально понадобится, и не следует держать его «про запас» для тысяч документов одновременно.

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

Изменение реквизитов шапки и табличных частей

Реквизиты шапки изменяются обычным присваиванием: ДокументОбъект.Склад = НовыйСклад;. Типы должны совпадать — присвоение строки в реквизит типа «Число» вызовет ошибку преобразования. Для ссылочных реквизитов присваивайте именно ссылки, а не строковые представления.

Табличные части представляют собой коллекции строк. Типовые операции выглядят так:

// Изменить существующую строку
Для Каждого СтрокаТовары Из ДокументОбъект.Товары Цикл
СтрокаТовары.Цена = СтрокаТовары.Цена * 1.1;
КонецЦикла;

// Добавить строку
НоваяСтрока = ДокументОбъект.Товары.Добавить();
НоваяСтрока.Номенклатура = НайденнаяНоменклатура;
НоваяСтрока.Количество = 1;

// Удалить строку
ДокументОбъект.Товары.Удалить(0);

// Очистить всю табличную часть
ДокументОбъект.Товары.Очистить();

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

Запись, проведение и отмена проведения

Метод Записать() принимает режим записи, который определяет, что произойдёт с движениями документа. Для проводимого документа доступны три основных варианта.

Пример перепроведения после изменения:

ДокументОбъект = ДокументСсылка.ПолучитьОбъект();
ДокументОбъект.Организация = НоваяОрганизация;
ДокументОбъект.Записать(РежимЗаписиДокумента.Проведение);

Если документ не проводится из-за контроля остатков или заполненности, Записать(РежимЗаписиДокумента.Проведение) вызовет исключение — и данные шапки тоже не сохранятся. Когда нужно гарантированно сохранить изменения даже при невозможности проведения, сначала записывайте в режиме Запись, а проведение выполняйте отдельным вызовом внутри попытки.

Дополнительный параметр РежимПроведенияДокумента.Оперативный / Неоперативный влияет на контроль остатков для оперативных документов. Оперативное проведение возможно только «текущей датой»; при программной обработке старых документов используйте неоперативный режим.

Пакетное изменение документов и транзакции

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

Запрос = Новый Запрос("ВЫБРАТЬ Ссылка ИЗ Документ.РеализацияТоваровУслуг ГДЕ Дата МЕЖДУ &Начало И &Конец");
Выборка = Запрос.Выполнить().Выбрать();
Пока Выборка.Следующий() Цикл
	НачатьТранзакцию();
	Попытка
		Объект = Выборка.Ссылка.ПолучитьОбъект();
		Объект.Комментарий = "Обработано";
		Объект.Записать();
		ЗафиксироватьТранзакцию();
	Исключение
		ОтменитьТранзакцию();
		ЗаписьЖурналаРегистрации("ПакетнаяОбработка", УровеньЖурналаРегистрации.Ошибка,,, ОписаниеОшибки());
	КонецПопытки;
КонецЦикла;

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

Для очень больших объёмов разбивайте выборку на порции и выполняйте обработку фоновым заданием через ДлительныеОперации — иначе синхронный вызов с клиента завершится по таймауту, а пользователи получат длительные блокировки таблиц.

Изменение без нарушения обменов, прав и блокировок

При программной записи могут сработать подписки на события, регистрация изменений для обмена, бизнес-процессы и проверки прав. Часто это желательно, но в служебных сценариях (миграция, загрузка из внешнего источника) требуется записать данные «тихо». Для этого используется параметр ОбменДанными:

ДокументОбъект.ОбменДанными.Загрузка = Истина;
ДокументОбъект.Записать();

Режим ОбменДанными.Загрузка = Истина отключает большинство проверок заполнения и бизнес-логики. Это мощный и опасный инструмент: документ запишется даже с некорректными данными, а контроль ссылочной целостности ложится на вас. Используйте его только для загрузки данных, где источник уже гарантирует корректность.

Учитывайте и права: код на сервере выполняется в контексте текущего пользователя, и Записать() завершится ошибкой «Нарушение прав доступа», если у него нет права изменения документа. В регламентных заданиях код обычно выполняется от имени служебного пользователя — проверьте его роли заранее. Для обхода проверок прав внутри транзакции можно использовать УстановитьПривилегированныйРежим(Истина), но делать это следует осознанно и только в серверных процедурах.

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

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

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

Частые вопросы