WS-ссылка в 1С: что это и как с ней работать

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

Термин «WS-ссылка» (Web Service Reference) чаще всего встречается у разработчиков и интеграторов, когда нужно подключить 1С к внешней системе: банку, транспортной компании, сервису проверки контрагентов, CRM или другой базе 1С, опубликованной как веб-сервис. Без WS-ссылки пришлось бы вручную формировать SOAP-конверты через HTTP-соединение, разбирать ответы и следить за структурой данных — платформа делает всё это автоматически.

Важно не путать WS-ссылку с публикацией собственного веб-сервиса 1С. WS-ссылка — это потребление чужого сервиса (1С выступает клиентом), а публикация — предоставление своих данных наружу (1С выступает сервером). Ниже разберём, как создать ссылку, как вызвать методы, какие ошибки встречаются чаще всего и когда WS-ссылку лучше заменить альтернативой.

Что такое WS-ссылка и как она устроена

WS-ссылка находится в ветке «Общие → WS-ссылки» дерева конфигурации. Единственный обязательный параметр объекта — URL файла WSDL (Web Services Description Language). Этот файл описывает, какие операции предоставляет сервис, какие параметры они принимают и какие типы данных возвращают.

При первом обращении к WS-ссылке платформа скачивает WSDL, строит по нему внутреннюю модель сервиса — так называемый WS-прокси — и кэширует её. Дальше все вызовы идут через этот прокси: вы пишете Прокси.ПолучитьОстатки(Склад), а платформа сама упаковывает параметры в SOAP-конверт, отправляет HTTP-запрос и превращает XML-ответ в объекты XDTO, с которыми удобно работать в коде.

С точки зрения администратора важно понимать: WS-ссылка — это не «живое» соединение, а декларация. Соединение устанавливается только в момент вызова операции, поэтому недоступность сервиса проявится не при открытии базы, а при конкретном обращении к методу — с ошибкой таймаута или отказа в соединении.

Когда WS-ссылка нужна, а когда лучше обойтись без неё

WS-ссылка оправдана, когда внешняя система предоставляет именно SOAP-сервис с WSDL-описанием. Это типично для корпоративных интеграций: обмен с банками, сервисы проверки контрагентов по ИНН, интеграция с учётными системами, обмен между двумя базами 1С через опубликованный веб-сервис.

Если же внешняя система работает по REST (JSON через HTTP), WS-ссылка бесполезна — она не умеет ничего, кроме SOAP. В этом случае используют объекты HTTPСоединение и HTTPЗапрос, а разбор JSON выполняют штатными средствами платформы. Пытаться «натянуть» WS-ссылку на REST-API — частая ошибка новичков.

Способы обращения к внешним сервисам из 1С

WS-ссылка

Подходит для SOAP-сервисов с WSDL. Платформа сама валидирует типы, код получается коротким. Ограничение: только SOAP, зависимость от доступности WSDL.

HTTPСоединение вручную

Универсальный вариант для REST и любых нестандартных протоколов. Требует ручной сборки запросов и разбора ответов, больше кода и тестирования.

WS-определение в коде (WSОпределения)

Динамическое создание прокси без объекта конфигурации. Удобно, когда адрес сервиса меняется, но WSDL скачивается при каждом создании — нужно кэшировать.

Как создать и настроить WS-ссылку

Создание выполняется в конфигураторе и занимает несколько минут, если WSDL-документ доступен. Понадобится сам URL WSDL — его предоставляет разработчик внешнего сервиса или он указан в документации интеграции. Обычно адрес выглядит как http://сервер/путь/сервис?wsdl или заканчивается на .wsdl.

Перед добавлением ссылки в конфигурацию проверьте доступность WSDL из браузера с того компьютера, где работает сервер 1С (или клиент, если вызовы будут идти с клиента). Если браузер не открывает документ — платформа тоже не сможет, и дальнейшая настройка бессмысленна до решения сетевой проблемы.

1. 1
   Откройте конфигуратор, в дереве конфигурации перейдите в «Общие → WS-ссылки» и добавьте новый элемент.
2. 2
   Задайте понятное имя, например СервисПроверкиКонтрагентов — оно станет частью кода.
3. 3
   В свойстве «URL» укажите полный адрес WSDL-документа.
4. 4
   Обновите конфигурацию базы данных (F7), чтобы объект стал доступен в коде.
5. 5
   Проверьте работу: выполните тестовый вызов операции через консоль кода или отладку.

Если конфигурацию нельзя изменять (типовая на поддержке, нет прав), WS-ссылку можно заменить программным созданием определения: WSОпределения создаётся прямо в коде из URL, затем из него строится прокси. Это тот же механизм, но без объекта метаданных — удобно для внешних обработок.

Как вызвать операции сервиса из кода

Работа с WS-ссылкой в коде строится в три шага: получить определение, создать прокси, вызвать операцию. Типовой фрагмент выглядит так:

Определение = WSСсылки.СервисПроверкиКонтрагентов.ПолучитьWSОпределение();
Прокси = Определение.ПолучитьWSПрокси(
"http://example.org/service",   // пространство имён
"CheckService",                  // имя сервиса
"CheckServiceSoap");             // имя точки подключения
Прокси.Пользователь = "user";
Прокси.Пароль = "password";
Результат = Прокси.CheckByINN("7707083893");

Точные значения пространства имён, имени сервиса и точки подключения берутся из WSDL-документа — они указаны в его элементах definitions и service. Ошибка в любом из трёх параметров приводит к исключению «сервис не найден», хотя сам WSDL загрузился успешно.

Возвращаемые значения приходят как объекты XDTO. Если операция возвращает сложную структуру (список документов, вложенные объекты), обращайтесь к полям по именам из WSDL. Учтите, что необязательные поля могут отсутствовать — перед чтением проверяйте их на Неопределено, иначе получите ошибку «Поле объекта не обнаружено».

Типичные ошибки и их диагностика

Большинство проблем с WS-ссылками делится на три группы: сеть, аутентификация и несовпадение схемы данных. Диагностику всегда начинайте с самого простого — доступности WSDL, и двигайтесь дальше по цепочке вызова.

Ошибка вида «Ошибка при вызове конструктора WSОпределения» означает, что платформа не смогла скачать или разобрать WSDL. Причины: недоступный адрес, блокировка прокси-сервером или файрволом, самоподписанный SSL-сертификат при HTTPS, битый XML в самом документе. Проверка — открыть тот же URL в браузере с сервера 1С.

Ошибка «Операция не найдена» или исключение при вызове метода обычно говорит о том, что сервис обновился, а схема в кэше устарела, либо неверно указаны пространство имён или имя сервиса. Ошибки SOAP-уровня (Fault) приходят от самого сервиса — читайте текст FaultString, там обычно прямо написано, что не так: неверный логин, просрочен ключ, некорректный параметр.

Безопасность и ограничения

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

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

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

Проверка результата и обслуживание интеграции

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

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

Как проверить, что интеграция работает

Доступность WSDL

Норма

Документ открывается в браузере с сервера 1С за секунды

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

Таймаут, ошибка сертификата или 404 — интеграция не заработает

Вызов операции

Норма

Метод возвращает объект XDTO с ожидаемыми полями

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

Исключение, Fault от сервиса или пустой результат

Поведение при сбое

Норма

Код перехватывает ошибку, пишет в журнал регистрации, пользователь видит понятное сообщение

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

Необработанное исключение и «зависание» формы

Нагрузка

Норма

Вызовы выполняются в фоне или пакетно

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

Сервис дёргается в цикле по каждой строке документа

Для постоянно работающих интеграций полезно логировать вызовы: время выполнения, результат, текст ошибки. Журнал регистрации подходит для технических деталей, а для бизнес-контроля — отдельный регистр сведений. Когда внешний сервис обновляется, первым признаком проблемы обычно становится рост ошибок в таком журнале — и вы узнаёте об этом раньше пользователей.

Частые вопросы о WS-ссылках в 1С

Чем WS-ссылка отличается от веб-сервиса 1С?

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

Можно ли использовать WS-ссылку без изменения конфигурации?

Да. Вместо объекта метаданных создайте определение программно: конструктор WSОпределения принимает URL WSDL прямо в коде. Это подходит для внешних обработок и типовых конфигураций на поддержке. Минус — WSDL скачивается при каждом создании, поэтому определение стоит кэшировать в рамках сеанса.

Почему возникает ошибка «Ошибка при вызове конструктора WSОпределения»?

Платформа не смогла получить или разобрать WSDL. Проверьте по порядку: открывается ли URL в браузере с того же компьютера, не блокирует ли прокси или файрвол, корректен ли SSL-сертификат при HTTPS, не требует ли доступ к WSDL авторизации. Часто причина в том, что указан адрес HTML-страницы сервиса вместо самого WSDL.

Как задать таймаут для вызова веб-сервиса?

У объекта WS-прокси есть свойство «Таймаут» — задайте его в секундах перед вызовом операции. Без явного таймаута при недоступном сервисе вызов может ждать очень долго, блокируя сеанс пользователя. Для интерактивных операций разумно ограничивать ожидание секундами, длительные обмены выносить в фоновые задания.

Что делать, если внешний сервис обновился и вызовы перестали работать?

Обновите определение: для WS-ссылки в конфигураторе заново укажите или перепроверьте URL, при программном создании — очистите кэш определений. Затем сверьте имена операций и структуру параметров с новым WSDL: переименованные поля и операции — типичная причина ошибок после обновления сервиса.

Подходит ли WS-ссылка для обмена между двумя базами 1С?

Да, это рабочий сценарий: одна база публикует веб-сервис, другая подключается к нему через WS-ссылку. Однако для регулярного обмена между своими базами чаще выбирают HTTP-сервисы, файловый обмен через планы обмена или шину — они проще в сопровождении и устойчивее к различиям версий платформы.