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

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

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

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

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

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

Через ссылку можно обращаться к реквизитам документа «через точку» — платформа неявно выполнит чтение из базы. Но изменить данные через ссылку нельзя: для записи нужно получить объект методом ПолучитьОбъект(), изменить его и вызвать Записать().

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

Получение ссылки из существующего объекта

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

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

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

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

Поиск ссылки по номеру и дате

Когда известны номер и период документа, используется метод НайтиПоНомеру менеджера документа:

Ссылка = Документы.ПоступлениеТоваровУслуг.НайтиПоНомеру("000000123", Дата(2026, 5, 15));
Если Ссылка.Пустая() Тогда
Сообщить("Документ не найден");
КонецЕсли;

Метод ищет документ в пределах периодичности нумерации: второй параметр задаёт дату, определяющую период (обычно год). Если указать дату из другого года, документ с тем же номером, но из другого периода, найден не будет. Это частая причина «не находит документ, который точно есть».

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

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

При обмене данными между базами документы идентифицируются не номерами, а GUID — уникальными идентификаторами. Если у вас есть строка с GUID, ссылка восстанавливается так:

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

Критически важное отличие: ПолучитьСсылку не проверяет, существует ли документ в базе. Он просто конструирует ссылку из идентификатора. Если документа с таким GUID нет, вы получите «битую» ссылку, которая выглядит заполненной. Проверка существования делается отдельно — например, запросом или проверкой на равенство полученного объекта:

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

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

Предварительное получение ссылки для нового документа

Иногда ссылка нужна до записи документа: например, чтобы заполнить реквизит «Основание» в другом объекте или установить связь между двумя создаваемыми документами. Для этого ссылка генерируется заранее и назначается объекту:

НоваяСсылка = Документы.СчетНаОплатуПокупателю.ПолучитьСсылку(Новый УникальныйИдентификатор);

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

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

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

1. 1
   Определите, что известно: объект, номер с датой или GUID
2. 2
   Для объекта — прочитайте свойство Ссылка после записи
3. 3
   Для номера — вызовите НайтиПоНомеру с датой нужного периода
4. 4
   Для GUID — вызовите ПолучитьСсылку и проверьте существование запросом
5. 5
   Для нового документа — сгенерируйте ссылку и назначьте через УстановитьСсылкуНового
6. 6
   Проверьте результат: Ссылка.Пустая() и существование записи в базе

Получение ссылки через запрос

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

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

Запрос предпочтительнее перебора выборки методом Выбрать() менеджера документов, когда условия сложные или нужно ограничить количество результатов. Конструкция «ВЫБРАТЬ ПЕРВЫЕ 1» с сортировкой — стандартный способ найти последний документ по условию.

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

Маршрут решения

Как выбрать действие

Есть открытый объект документаЧитайте свойство Ссылка после записи объекта

Известны номер и датаИспользуйте НайтиПоНомеру с датой нужного периода нумерации

Известен GUID из обмена или внешней системыПолучитьСсылку(УИД) плюс проверка существования запросом

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

Ссылка нужна до записи документаПолучитьСсылку(Новый УникальныйИдентификатор) и УстановитьСсылкуНового

Проверка результата и типичные ошибки

После получения ссылки всегда проверяйте два независимых условия: заполненность и существование. Заполненность проверяется через Пустая() или ЗначениеЗаполнено(). Существование — запросом или попыткой обращения к реквизиту с обработкой исключения. Пустая ссылка и «битая» ссылка — разные проблемы с разными причинами.

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

Ещё одна ловушка — составные типы реквизитов. Если реквизит имеет тип «ДокументСсылка» по нескольким видам документов, перед вызовом методов вроде НайтиПоНомеру нужно явно определить конкретный вид через ТипЗнч(Ссылка) — иначе логика поиска будет работать непредсказуемо.

Ограничения и безопасная работа со ссылками

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

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

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

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

Чем отличается ПолучитьСсылку от НайтиПоНомеру?

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

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

Выполните запрос вида «ВЫБРАТЬ Ссылка ИЗ Документ.Вид ГДЕ Ссылка = &Ссылка» — если результат пустой, а сама ссылка не пустая, она битая. Альтернатива — сравнить Ссылка.ПолучитьОбъект() с Неопределено: для несуществующей записи метод вернёт Неопределено.

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

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

Почему НайтиПоНомеру не находит документ, который виден в списке?

Чаще всего дата, переданная вторым параметром, попадает в другой период нумерации (другой год). Также проверьте точное совпадение номера с учётом префиксов и лидирующих нулей и отсутствие ограничений доступа к данным.

Можно ли изменить документ, имея только ссылку?

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

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

Когда ссылка нужна до записи: для заполнения реквизитов связанных объектов, для синхронизации с внешней системой по заданному GUID или при загрузке данных из обмена, где связи между объектами строятся по идентификаторам.