1С: тип ДокументСсылка — как получить ссылку на документ

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

Получить ссылку можно несколькими способами: через менеджер документа, из объекта документа, запросом к базе, по номеру и дате или по строковому представлению уникального идентификатора. Выбор способа зависит от того, что у вас есть на входе: объект, номер документа, GUID или условия отбора.

Ниже разобраны все рабочие варианты с примерами кода, особенностями управляемых и обычных форм, а также типичные ошибки, которые приводят к пустым или «битым» ссылкам.

Что такое ДокументСсылка и чем она отличается от ДокументОбъект

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

Когда вы обращаетесь к реквизиту через точку от ссылки (например, Ссылка.Номер), платформа неявно выполняет обращение к базе и подгружает данные. Такие «разыменования» удобны для одиночных обращений, но в циклах по тысячам документов дают серьёзную нагрузку — тогда правильнее использовать запрос.

Получение новой ссылки через ПолучитьСсылку()

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

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

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

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

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

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

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

СсылкаНаДокумент = ДокОбъект.Ссылка;
Сообщить("Создан документ: " + СсылкаНаДокумент);

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

Поиск существующего документа и получение его ссылки

Поиск по номеру

Метод НайтиПоНомеру(Номер, Дата) возвращает ссылку на документ с указанным номером. Второй параметр — дата — сужает поиск и особенно важен, когда нумерация периодическая (например, обнуляется каждый год). Если документ не найден, метод вернёт пустую ссылку.

НайденнаяСсылка = Документы.СчетФактура.НайтиПоНомеру("000000125", Дата(2026, 12, 31));

Если НайденнаяСсылка.Пустая() Тогда
Сообщить("Документ не найден");
Иначе
Сообщить("Найден: " + НайденнаяСсылка);
КонецЕсли;

Поиск через запрос

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

Запрос = Новый Запрос;
Запрос.Текст =
"ВЫБРАТЬ ПЕРВЫЕ 1
|    Реализация.Ссылка КАК Ссылка
|ИЗ
|    Документ.РеализацияТоваровУслуг КАК Реализация
|ГДЕ
|    Реализация.Контрагент = &Контрагент
|    И Реализация.Проведен";
Запрос.УстановитьПараметр("Контрагент", Контрагент);

Выборка = Запрос.Выполнить().Выбрать();
Если Выборка.Следующий() Тогда
СсылкаНаДокумент = Выборка.Ссылка;
КонецЕсли;

1. 1
   Определите вид документа и период, в котором он мог быть создан
2. 2
   Вызовите Документы.ИмяДокумента.НайтиПоНомеру(Номер, Дата)
3. 3
   Проверьте результат методом Пустая()
4. 4
   Если ссылка пустая — расширьте диапазон дат или проверьте формат номера (лидирующие нули)
5. 5
   При массовом поиске замените цикл с НайтиПоНомеру на один запрос

Получение ссылки по уникальному идентификатору (GUID)

Если известен GUID документа — например, он пришёл из внешней системы при обмене — ссылку восстанавливают методом ПолучитьСсылку() с параметром-идентификатором. Это стандартный приём при интеграциях и при разборе «битых ссылок».

Идентификатор = Новый УникальныйИдентификатор("a1b2c3d4-e5f6-7890-abcd-ef1234567890");
СсылкаПоGUID = Документы.РеализацияТоваровУслуг.ПолучитьСсылку(Идентификатор);

// Проверка существования документа в базе
Запрос = Новый Запрос;
Запрос.Текст = "ВЫБРАТЬ 1 ИЗ Документ.РеализацияТоваровУслуг ГДЕ Ссылка = &Ссылка";
Запрос.УстановитьПараметр("Ссылка", СсылкаПоGUID);
ДокументСуществует = Не Запрос.Выполнить().Пустой();

Обратная задача — получить GUID из ссылки — решается через XMLСтрока(Ссылка) или Ссылка.УникальныйИдентификатор(). Второй вариант проще и доступен на тонком клиенте.

Особенности в формах и на клиенте

В форме документа ссылка доступна через Объект.Ссылка (для основного реквизита формы типа ДанныеФормыСтруктура). В обычных формах — через Ссылка или ЭтотОбъект.Ссылка в модуле объекта. На тонком и веб-клиенте методы ПолучитьОбъект() и СоздатьДокумент() недоступны — любая работа с объектами выполняется только в серверных процедурах.

Если нужно открыть форму существующего документа по ссылке, используйте ОткрытьЗначение(Ссылка) или ПоказатьЗначение(, Ссылка). Для получения навигационной ссылки (строки вида e1cib/data/...) применяется функция ПолучитьНавигационнуюСсылку(Ссылка) — она удобна для передачи в письма и внешние системы.

Сравнение способов получения ссылки

Объект.Ссылка

Когда объект уже в памяти. Самый простой вариант, но требует загруженного объекта

НайтиПоНомеру()

Поиск одного документа по номеру и дате. Не подходит для массовой обработки

Запрос с выборкой Ссылка

Поиск по любым условиям и массовая выборка. Оптимален по производительности

ПолучитьСсылку(GUID)

Восстановление ссылки по идентификатору при обменах. Требует отдельной проверки существования

Проверка и типичные ошибки

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

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

Контрольные точки

Как проверить результат

Ссылка получена

Норма

Ссылка.Пустая() возвращает Ложь

Тревожный признак

Пустая ссылка — документ не найден, проверьте номер и дату

Документ существует в базе

Норма

Запрос по ссылке возвращает строку, ПолучитьОбъект() не равен Неопределено

Тревожный признак

Объект не найден — ссылка битая или документ удалён

Тип ссылки

Норма

ТипЗнч(Ссылка) = Тип("ДокументСсылка.ИмяДокумента")

Тревожный признак

Другой тип — значение пришло из составного реквизита с неожиданным содержимым

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

Как получить ссылку на документ, если известен только его номер?

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

Чем отличается ПолучитьСсылку() без параметров от ПолучитьСсылку(GUID)?

Без параметров метод генерирует новую ссылку, которой ещё нет в базе — она предназначена для установки новому объекту через УстановитьСсылкуНового(). С параметром GUID метод формирует ссылку на конкретный идентификатор, который может как существовать в базе, так и отсутствовать.

Как проверить, не «битая» ли ссылка?

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

Можно ли получить ссылку на тонком клиенте?

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

Как из ссылки получить строку GUID для передачи во внешнюю систему?

Вызовите Ссылка.УникальныйИдентификатор() — вернётся значение типа УникальныйИдентификатор, которое автоматически преобразуется в строку при конкатенации или сериализации. Альтернатива — XMLСтрока(Ссылка).

Почему НайтиПоНомеру возвращает пустую ссылку, хотя документ точно есть?

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