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

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

Новый документ создают через менеджер конкретного вида, заполняют шапку и табличную часть, затем передают в Записать() режим проведения. Имена реквизитов зависят от конфигурации:

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

СтрокаТоваров = ДокументОбъект.Товары.Добавить();
СтрокаТоваров.Номенклатура = Номенклатура;
СтрокаТоваров.Количество = 2;
СтрокаТоваров.Цена = 1500;
СтрокаТоваров.Сумма = СтрокаТоваров.Количество * СтрокаТоваров.Цена;

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

Точная сигнатура метода объекта документа по синтакс-помощнику: Записать(<РежимЗаписи>, <РежимПроведения>). Оба параметра необязательные, но для программного проведения первый лучше указывать явно.

1С: записать документ программно без проведения

Если документ должен остаться непроведённым, передайте режим Запись. События записи выполнятся, но ОбработкаПроведения не будет вызвана и движения документа не появятся:

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

СсылкаНаДокумент = ДокументОбъект.Ссылка;

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

Провести существующий документ по ссылке

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

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

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

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

Для распроведения получите объект и запишите его в режиме ОтменаПроведения. Платформа удалит или деактивирует движения в соответствии с механизмом регистров и логикой конфигурации:

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

Не пытайтесь отменять проведение прямым изменением движений или реквизита состояния. Штатный режим запускает предусмотренные платформой проверки и обработчики записи документа.

Оперативное и неоперативное проведение

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

// Текущая хозяйственная операция
ДокументОбъект.Записать(
    РежимЗаписиДокумента.Проведение,
    РежимПроведенияДокумента.Оперативный);

// Перепроведение документа за прошлую дату
ДокументОбъект.Записать(
    РежимЗаписиДокумента.Проведение,
    РежимПроведенияДокумента.Неоперативный);

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

ОбработкаПроведения, параметр Отказ и ошибки записи

При проведении платформа вызывает ОбработкаПроведения(Отказ, РежимПроведения) в модуле объекта. Здесь формируют движения и выполняют бизнес-проверки. Если провести документ нельзя, обработчик устанавливает Отказ = Истина и обычно сообщает понятную причину.

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

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

Транзакции и блокировки при проведении

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

НачатьТранзакцию();
Попытка
    Блокировка = Новый БлокировкаДанных;
    ЭлементБлокировки = Блокировка.Добавить("Документ.РеализацияТоваровУслуг");
    ЭлементБлокировки.УстановитьЗначение("Ссылка", ДокументОбъект.Ссылка);
    Блокировка.Заблокировать();

    ДокументОбъект.Записать(РежимЗаписиДокумента.Проведение);
    ЗафиксироватьТранзакцию();
Исключение
    ОтменитьТранзакцию();
    ВызватьИсключение;
КонецПопытки;

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

Массовое проведение документов и обработка ошибок

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

Результаты = Новый ТаблицаЗначений;
Результаты.Колонки.Добавить("Ссылка");
Результаты.Колонки.Добавить("Успешно");
Результаты.Колонки.Добавить("Ошибка");

Пока Выборка.Следующий() Цикл
    СтрокаРезультата = Результаты.Добавить();
    СтрокаРезультата.Ссылка = Выборка.Ссылка;

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

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

Частые ошибки при программном проведении документа

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

Частые вопросы о проведении документов в 1С