Получить объект по ссылке, провести и отменить проведение документа в 1С 8.3 программно

Чем ссылка отличается от объекта в 1С 8.3

В платформе 1С:Предприятие 8.3 важно разделять два типа данных: ссылочные типы (СправочникСсылка.<Имя>, ДокументСсылка.<Имя>) и объектные типы (СправочникОбъект.<Имя>, ДокументОбъект.<Имя>). Ссылка — это лёгкий указатель на запись в базе данных, который содержит уникальный идентификатор (УникальныйИдентификатор()) и тип таблицы.

Через точку от ссылки (например, СсылкаНаДокумент.Контрагент) можно только прочитать значения реквизитов, причём каждое такое обращение к первой некешированной ссылке приводит к считыванию всего объекта в кэш сеанса. Попытка присвоить новое значение свойству ссылки (СсылкаНаДокумент.Комментарий = "Исправлено") вызовет ошибку выполнения: свойства ссылки доступны исключительно для чтения. Кроме того, метод ПолучитьОбъект() существует только в серверном контексте (&НаСервере или &НаСервереБезКонтекста) — на тонком и веб-клиенте объектные типы данных недоступны.

Когда вы вызываете Ссылка.ПолучитьОбъект(), сервер 1С считывает из СУБД все реквизиты шапки и все строки табличных частей документа или справочника, размещая их в оперативной памяти рабочего процесса в виде изменяемого экземпляра ДокументОбъект или СправочникОбъект.

Как безопасно получить объект по ссылке программно

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

• Для пустой ссылки метод ПустаяСсылка.ПолучитьОбъект() вызовет исключение Нельзя получить объект для пустой ссылки.
• Для битой ссылки на удалённый элемент метод БитаяСсылка.ПолучитьОбъект() не выбросит исключение, но вернёт значение Неопределено.

&НаСервереБезКонтекста
Процедура ОбновитьКомментарийПоСсылке(СсылкаНаОбъект, НовыйКомментарий)
    
    // 1. Проверяем, что передана непустая ссылка, а не Null или Неопределено
    Если Не ЗначениеЗаполнено(СсылкаНаОбъект) Тогда
        Возврат;
    КонецЕсли;
    
    // 2. Получаем изменяемый объект в память сервера
    ОбъектБД = СсылкаНаОбъект.ПолучитьОбъект();
    
    // 3. Защита от битой ссылки (если запись удалена из СУБД)
    Если ОбъектБД = Неопределено Тогда
        ЗаписьЖурналаРегистрации("ОбновлениеРеквизитов",
            УровеньЖурналаРегистрации.Предупреждение, , СсылкаНаОбъект,
            "Объект не найден в информационной базе (битая ссылка).");
        Возврат;
    КонецЕсли;
    
    // 4. Блокируем объект от параллельного изменения в форме другим пользователем
    ОбъектБД.Заблокировать();
    
    ОбъектБД.Комментарий = НовыйКомментарий;
    ОбъектБД.Записать();
    
КонецПроцедуры

РежимЗаписиДокумента и проведение документа в 1С 8.3

В отличие от справочника, где метод СправочникОбъект.Записать() не принимает параметров, у объекта документа метод записи управляет как сохранением реквизитов, так и движениями по регистрам: ДокументОбъект.Записать(<РежимЗаписи>, <РежимПроведения>).

Первый параметр задаётся системным перечислением РежимЗаписиДокумента и принимает одно из трёх значений:

• РежимЗаписиДокумента.Запись (значение по умолчанию, если параметр не передан) — записывает реквизиты и табличные части документа. Если документ ранее не был проведён, он остаётся непроведённым. Если документ уже был проведён, обычный вызов Записать(РежимЗаписиДокумента.Запись) сохранит новые реквизиты шапки и табличных частей, но оставит пометку Проведен = Истина и старые движения в регистрах без пересчёта.
• РежимЗаписиДокумента.Проведение — записывает документ, устанавливает свойство Проведен = Истина и вызывает обработчик ОбработкаПроведения в модуле объекта для формирования движений по регистрам.
• РежимЗаписиДокумента.ОтменаПроведения — снимает признак проведения (Проведен = Ложь), вызывает ОбработкаУдаленияПроведения и очищает движения документа во всех подчинённых регистрах.

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

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

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

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

При таком вызове платформа открывает транзакцию, выполняет подписки на событие ПередЗаписью (где в параметре РежимЗаписи будет передано значение ОтменаПроведения), запускает процедуру ОбработкаУдаленияПроведения в модуле объекта, очищает наборы записей движений с признаком автоудаления и записывает саму шапку документа с Проведен = Ложь.

&НаСервереБезКонтекста
Процедура ОтменитьПроведениеДокумента(СсылкаНаДокумент, ПометитьНаУдаление = Ложь)
    
    Если Не ЗначениеЗаполнено(СсылкаНаДокумент) Тогда
        Возврат;
    КонецЕсли;
    
    ДокОбъект = СсылкаНаДокумент.ПолучитьОбъект();
    Если ДокОбъект = Неопределено Тогда
        Возврат;
    КонецЕсли;
    
    Если ПометитьНаУдаление Тогда
        // Сам снимет проведение и установит ПометкаУдаления = Истина за один вызов
        ДокОбъект.УстановитьПометкуУдаления(Истина);
    ИначеЕсли ДокОбъект.Проведен Тогда
        // Снимет проведение и очистит движения, оставив документ черновиком
        ДокОбъект.Записать(РежимЗаписиДокумента.ОтменаПроведения);
    КонецЕсли;
    
КонецПроцедуры

Когда использовать ОбменДанными.Загрузка = Истина

У любого экземпляра СправочникОбъект и ДокументОбъект есть системное свойство ОбменДанными типа ПараметрыОбменаДанными с булевым флагом Загрузка (по умолчанию Ложь). В типовых конфигурациях 1С (ERP, КА, УТ 11, БП 3.0, ЗУП 3.1) в начале всех обработчиков ПередЗаписью, ПриЗаписи и в подписках на события стоит стандартная проверка:

Если ОбменДанными.Загрузка Тогда
    Возврат;
КонецЕсли;

Если перед вызовом Объект.Записать() установить Объект.ОбменДанными.Загрузка = Истина, платформа запишет объект в режиме загрузки данных:

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

Поэтому режим ОбменДанными.Загрузка = Истина применяют тогда, когда нужно быстро обновить технический реквизит (например, комментарий, статус синхронизации или номер входящего документа) в тысячах проведённых документов прошлых периодов, не затрагивая их бухгалтерские и складские движения. Если же вы меняете сумму, количество, склад или цену и хотите пересчитать движения по регистрам, включать ОбменДанными.Загрузка = Истина категорически нельзя.

Сводная таблица режимов записи и методов объекта

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

Частые ошибки при получении объекта и записи документов

• Вызов Ссылка.ПолучитьОбъект() внутри цикла по выборке запроса. Каждое обращение к ПолучитьОбъект() выполняет отдельные SQL-запросы к таблицам шапки и всех табличных частей объекта. Если нужно только прочитать реквизиты, выбирайте их прямо в запросе (ВЫБРАТЬ Док.Контрагент, Док.СуммаДокумента), а ПолучитьОбъект() вызывайте исключительно для тех ссылок, которые действительно требуют перезаписи.
• Попытка изменить реквизит напрямую через ссылку. Код вида Выборка.Ссылка.Комментарий = "Ок"; Выборка.Ссылка.Записать(); завершится ошибкой, так как у ДокументСсылка нет метода Записать(), а все её свойства доступны только для чтения.
• Отсутствие проверки Объект <> Неопределено после ПолучитьОбъект(). Если в регистре или реквизите сохранилась битая ссылка на удалённый элемент, ПолучитьОбъект() вернёт Неопределено, и следующая строка Объект.Записать() упадёт с исключением Значение не является значением объектного типа (Записать).
• Запись уже проведённого документа в режиме РежимЗаписиДокумента.Запись после изменения табличной части. Если в проведённом документе поменять количество или сумму и вызвать ДокОбъект.Записать() без параметров, новые цифры сохранятся в документе, но в регистрах останутся старые движения — возникнет расхождение между первичным документом и отчётами.
• Проведение документов задним числом в режиме РежимПроведенияДокумента.Оперативный. Если не передать второй параметр в ДокОбъект.Записать(РежимЗаписиДокумента.Проведение), по умолчанию используется Неоперативный, но при явной передаче Оперативный для документа прошлой датой платформа сдвинет его дату на текущий день или откажет в проведении.
• Снятие проведения через ДокОбъект.Проведен = Ложь или с флагом ОбменДанными.Загрузка = Истина. Если вручную сбросить свойство Проведен = Ложь при включённом ОбменДанными.Загрузка = Истина и вызвать Записать(), в журнале документ станет непроведённым, но все его движения в регистрах останутся в базе.

Частые вопросы о получении объекта и режимах записи в 1С