В процессе разработки на платформе 1С:Предприятие 8.3 одной из наиболее частотных задач является программное создание документов. Это необходимо для реализации механизмов интеграции, автоматизации загрузки данных из внешних систем или создания сложных обработок. В рамках данной статьи мы подробно разберем, как правильно инициализировать новый объект конфигурации, заполнить его реквизиты, обработать табличные части и обеспечить корректную запись в базу данных с соблюдением транзакционной логики.
Проанализируем процесс создания нового документа. Первым шагом всегда является обращение к менеджеру соответствующего документа. Для этого используется метод СоздатьДокумент(). Важно понимать, что на данном этапе объект создается только в оперативной памяти сервера, и в базе данных он еще не существует. Рассмотрим пример кода для создания документа типа ПоступлениеТоваровУслуг.
НовыйДокумент = Документы.ПоступлениеТоваровУслуг.СоздатьДокумент();
НовыйДокумент.Дата = ТекущаяДата();
НовыйДокумент.УстановитьНовыйНомер();
Обратим внимание на метод УстановитьНовыйНомер(). Мы рекомендуем вызывать его сразу после инициализации или перед финальной записью, чтобы платформа автоматически назначила следующий порядковый номер в соответствии с установленным префиксом организации или узла распределенной информационной базы (РИБ).
Рассмотрим подробнее заполнение реквизитов «шапки». К ним относятся ссылки на справочники (Организация, Контрагент, Склад), числовые значения, даты и строки. Выясним причину, по которой важно проверять заполнение ссылочных типов. Если передать в реквизит пустую ссылку неправильного типа, платформа может выдать ошибку при записи или проведении. Разберем по шагам заполнение стандартных полей:
Организации.Контрагенты.Посмотрим на пример заполнения:
НовыйДокумент.Организация = Справочники.Организации.НайтиПоРеквизиту("ИНН", "7701010101");
НовыйДокумент.Контрагент = Справочники.Контрагенты.НайтиПоНаименованию("ООО Поставщик");
НовыйДокумент.Склад = Справочники.Склады.НайтиПоНаименованию("Основной склад");
НовыйДокумент.Комментарий = "Документ создан программно на основании данных из внешней системы.";
Важный момент: при поиске ссылок (например, через НайтиПоНаименованию) всегда следует проверять результат на Пустая(). Если объект не найден, создание документа может потерять смысл или привести к некорректному учету.
Проанализируем ситуацию, когда документ содержит список товаров или услуг. Для работы с табличной частью используется метод Добавить(), который создает новую строку и возвращает ссылку на нее. После этого мы можем обращаться к реквизитам этой строки.
Разберем пример заполнения табличной части Товары:
НоваяСтрока = НовыйДокумент.Товары.Добавить();
НоваяСтрока.Номенклатура = Справочники.Номенклатура.НайтиПоКоду("00001");
НоваяСтрока.Количество = 10;
НоваяСтрока.Цена = 1500;
НоваяСтрока.Сумма = НоваяСтрока.Количество * НоваяСтрока.Цена;
Если табличная часть большая, мы рекомендуем использовать метод Загрузить(), который позволяет вставить сразу всю таблицу значений. Это значительно ускоряет работу, если данные предварительно были подготовлены в объекте типа ТаблицаЗначений. Выясним преимущества этого подхода: он минимизирует количество обращений к контексту объекта в цикле.
В типовых конфигурациях (таких как 1C:ERP или 1С:Бухгалтерия) часто используется механизм ОбработкаЗаполнения. Если мы хотим, чтобы при создании документа сработали все стандартные алгоритмы (например, подстановка счетов учета или ответственных лиц), следует использовать метод Заполнить().
// Создание документа на основании другого объекта (например, Заказа)
Основание = Документы.ЗаказПоставщику.НайтиПоНомеру("123");
НовыйДокумент = Документы.ПоступлениеТоваровУслуг.СоздатьДокумент();
НовыйДокумент.Заполнить(Основание);
При вызове Заполнить(Основание) платформа обращается к модулю менеджера или модуля объекта, выполняя предопределенную логику. Это позволяет избежать дублирования кода и гарантирует, что программно созданный документ не будет отличаться от созданного вручную пользователем.
После заполнения всех необходимых полей документ необходимо сохранить в базе данных. Для этого используется метод Записать(). У данного метода есть параметр РежимЗаписиДокумента, который определяет, будет ли документ просто сохранен (как черновик) или сразу проведен.
Рассмотрим варианты записи:
РежимЗаписиДокумента.Запись — документ сохраняется, но не делает движений по регистрам.РежимЗаписиДокумента.Проведение — документ сохраняется и формирует проводки/движения.РежимЗаписиДокумента.ОтменаПроведения — снимает документ с проведения.Пример кода с обработкой исключений:
Попытка
НовыйДокумент.Записать(РежимЗаписиДокумента.Проведение);
Сообщить("Документ успешно проведен: " + НовыйДокумент.Ссылка);
Исключение
Инфо = ИнформацияОбОшибке();
Сообщить("Не удалось записать документ. Причина: " + Инфо.Описание);
КонецПопытки;
Важный момент: Всегда используйте конструкцию Попытка ... Исключение при записи объектов. Это предотвратит аварийное завершение работы системы в случае нарушения бизнес-логики (например, при нехватке остатков на складе или отсутствии прав доступа).
Если нам требуется создать группу документов (например, при импорте 1000 накладных), мы должны рассмотреть вопрос транзакционной целостности. Платформа 1С автоматически оборачивает вызов Записать() в транзакцию. Однако, если документы логически связаны, имеет смысл использовать явное управление транзакциями через НачатьТранзакцию() и ЗафиксироватьТранзакцию().
Проанализируем преимущества:
НачатьТранзакцию();
Попытка
// Цикл создания документов
// ...
ЗафиксироватьТранзакцию();
Исключение
ОтменитьТранзакцию();
ВызватьИсключение "Ошибка при массовой загрузке: " + ОписаниеОшибки();
КонецПопытки;
Выясним основные причины, по которым программное создание документов может не работать или работать некорректно:
Записать() выдаст ошибку блокировки. Мы рекомендуем использовать метод Заблокировать() перед началом изменения существующего объекта.Записать() в режиме проведения вернет ошибку, если поле пустое.Иногда требуется передать в обработчики проведения информацию, которая не хранится в реквизитах самого документа. Для этого используйте коллекцию ДополнительныеСвойства. Это структура, которая «живет» в памяти объекта до конца транзакции записи.
НовыйДокумент.ДополнительныеСвойства.Вставить("ЭтоЗагрузкаИзExcel", Истина);
НовыйДокумент.Записать(РежимЗаписиДокумента.Проведение);
Затем в модуле документа, например, в процедуре ПередЗаписью, мы можем проанализировать это свойство и изменить поведение системы (например, отключить лишние проверки для ускорения загрузки).
Мы рассмотрели полный цикл программной работы с документами в среде 1С:Предприятие 8.3. Правильное использование методов СоздатьДокумент(), Заполнить() и корректное управление транзакциями позволяет создавать надежные и производительные решения. Помните о важности обработки исключений и проверки ссылочных данных перед их записью в объект. Этот фундамент позволит вам успешно решать задачи любой сложности по автоматизации учета.