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

← На главную

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

Основные этапы программного создания документа

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

Разберем пример создания документа РеализацияТоваровУслуг. Рассмотрим следующий код:


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

Использование метода СоздатьДокумент() возвращает объект типа ДокументОбъект. Важно помнить, что на данном этапе документ существует только в оперативной памяти и еще не записан в базу данных. Метод УстановитьНовыйНомер() позволяет системе автоматически присвоить номер в соответствии с заданной периодичностью нумерации.

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

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

Посмотрим на пример заполнения данных:


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

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

Работа с табличными частями

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

Рассмотрим подробнее процесс заполнения табличной части Товары:


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

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

Запись и проведение документа

Когда все данные заполнены, документ необходимо сохранить в базе данных. В 1С существует три режима записи:

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

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


Попытка
    // Сначала записываем объект
    НовыйДокумент.Записать(РежимЗаписиДокумента.Проведение);
    Сообщить("Документ успешно создан и проведен: " + НовыйДокумент.Ссылка);
Исключение
    // В случае ошибки выводим описание
    Сообщить("Не удалось провести документ! Причина: " + ОписаниеОшибки());
    
    // Если проведение не удалось, можно просто записать документ в режиме "Запись"
    НовыйДокумент.Записать(РежимЗаписиДокумента.Запись);
КонецПопытки;

Использование транзакций для обеспечения целостности

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

Разберем пример с использованием НачатьТранзакцию() и ЗафиксироватьТранзакцию():


НачатьТранзакцию();
Попытка
    // Создаем первый документ
    Док1 = Документы.РеализацияТоваровУслуг.СоздатьДокумент();
    // ... заполнение ...
    Док1.Записать(РежимЗаписиДокумента.Проведение);
    
    // Создаем связанный документ (например, Счет-фактура)
    Док2 = Документы.СчетФактураВыданный.СоздатьДокумент();
    // ... заполнение на основании Док1 ...
    Док2.Записать(РежимЗаписиДокумента.Запись);
    
    ЗафиксироватьТранзакцию();
Исключение
    ОтменитьТранзакцию();
    Сообщить("Ошибка транзакции: " + ОписаниеОшибки());
КонецПопытки;

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

Оптимизация и привилегированный режим

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

Посмотрим на пример переключения режима на сервере:


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

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

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

Разберем типичные проблемы, с которыми сталкиваются разработчики:

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

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