Как обратиться к веб-сервису из 1С

Обращение к веб-сервису из 1С — стандартная задача интеграции: получение курсов валют, обмен данными с сайтом, проверка контрагентов, отправка заказов во внешнюю систему. Платформа 1С:Предприятие предлагает два основных механизма: WS-ссылки для SOAP-сервисов и объект HTTPСоединение для REST и произвольных HTTP-запросов. Выбор зависит от того, какой интерфейс предоставляет внешняя система.

Если сервис публикует WSDL-описание (SOAP), удобнее всего использовать WS-ссылку: платформа сама сформирует прокси-объект с типизированными методами. Если сервис работает по REST и отдаёт JSON или XML, потребуется HTTPСоединение, HTTPЗапрос и ручная разборка ответа через ЧтениеJSON или ЧтениеXML. Оба подхода работают и на клиенте, и на сервере, но для прикладных решений вызывать внешние сервисы следует на сервере — это безопаснее и не зависит от сетевых настроек рабочего места пользователя.

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

Какой способ выбрать: WS-ссылка или HTTPСоединение

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

Если внешняя система описана в документации как REST API, принимает JSON в теле запроса и возвращает JSON в ответе, WS-ссылка не подойдёт — используйте HTTPСоединение. Этот же вариант выбирайте, когда нужно просто скачать файл, отправить POST-запрос с произвольным телом или обратиться к сервису, у которого нет WSDL.

Сравнение вариантов

WS-ссылка (WSПрокси)

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

HTTPСоединение

Универсальный вариант для REST, JSON, XML, скачивания файлов. Полный контроль над заголовками и телом. Ограничение: сериализацию и разбор ответа пишете вручную.

WS-определение динамически

WSОпределения создаётся из URL WSDL в коде без добавления ссылки в конфигурацию. Подходит, когда адрес сервиса меняется, но требует обработки ошибок недоступности описания.

Обращение к SOAP-сервису через WS-ссылку

WS-ссылка добавляется в конфигураторе: в дереве конфигурации откройте ветку «Общие» → «WS-ссылки», создайте новый элемент и укажите URL WSDL-описания. После сохранения платформа загрузит описание сервиса, и в коде станет доступен прокси-объект. Имя ссылки используется при создании объекта WSПрокси.

Типовой код вызова выглядит так: создаётся объект WSПрокси с указанием имени ссылки, URI пространства имён сервиса, имени сервиса и точки подключения, затем вызывается метод с параметрами. Данные для параметров сложных типов создаются через фабрику XDTO прокси-объекта.

Прокси = WSСсылки.КурсыВалют.СоздатьWSПрокси(
"http://example.org/webservices",
"CurrencyService",
"CurrencyServiceSoap");

Результат = Прокси.GetExchangeRate("USD", ТекущаяДатаСеанса());
Курс = Результат.Rate;

Если адрес сервиса заранее неизвестен или хранится в настройках, создайте определение динамически: объект WSОпределения принимает URL WSDL, логин и пароль, после чего из него получают WSПрокси. Учтите, что при каждом вызове будет выполняться загрузка WSDL — для частых обращений лучше кэшировать прокси или использовать статическую ссылку.

Обращение к REST-сервису через HTTPСоединение

Для REST API работа строится из трёх объектов: HTTPСоединение описывает сервер (хост, порт, защищённое соединение, таймаут), HTTPЗапрос описывает конкретный запрос (адрес ресурса, заголовки, тело), а ответ возвращается как HTTPОтвет с кодом состояния и телом. Соединение создавайте с явным таймаутом — по умолчанию ожидание может оказаться слишком долгим, и при недоступном сервере сеанс «зависнет».

Пример POST-запроса с JSON-телом и авторизацией по токену:

Соединение = Новый HTTPСоединение("api.example.ru", 443, , , , 30,
Новый ЗащищенноеСоединениеOpenSSL);

Запрос = Новый HTTPЗапрос("/v1/orders");
Запрос.Заголовки.Вставить("Content-Type", "application/json");
Запрос.Заголовки.Вставить("Authorization", "Bearer " + Токен);

Данные = Новый Структура("НомерЗаказа, Сумма", "А-00125", 15000);
Запись = Новый ЗаписьJSON;
Запись.УстановитьСтроку();
ЗаписатьJSON(Запись, Данные);
Запрос.УстановитьТелоИзСтроки(Запись.Закрыть());

Ответ = Соединение.ОтправитьДляОбработки(Запрос);

Если Ответ.КодСостояния = 200 Тогда
Чтение = Новый ЧтениеJSON;
Чтение.УстановитьСтроку(Ответ.ПолучитьТелоКакСтроку());
Результат = ПрочитатьJSON(Чтение);
КонецЕсли;

Аутентификация по логину и паролю (Basic) задаётся прямо в конструкторе HTTPСоединение третьим и четвёртым параметрами. Для токенов и подписи запросов заголовки формируются вручную — порядок и формат смотрите в документации конкретного API.

1. 1
   Изучите документацию API: метод (GET/POST), адрес ресурса, формат тела и авторизации.
2. 2
   Проверьте запрос во внешнем инструменте (Postman, curl) с реальными учётными данными.
3. 3
   Напишите серверную процедуру: HTTPСоединение с таймаутом, HTTPЗапрос с заголовками и телом.
4. 4
   Обработайте код ответа: 2xx — успех, 4xx — ошибка в данных запроса, 5xx — проблема на стороне сервиса.
5. 5
   Разберите тело ответа через ЧтениеJSON или ЧтениеXML и проверьте обязательные поля.
6. 6
   Запишите результат в базу и залогируйте вызов в журнале регистрации.

Настройка прокси-сервера и аутентификации

Во многих организациях выход в интернет возможен только через прокси. В этом случае передайте объект ИнтернетПрокси в конструктор HTTPСоединение: у объекта задаются адрес, порт, пользователь и пароль прокси, а также флаг использования системных настроек. Для защищённых соединений HTTPS дополнительно передаётся объект ЗащищенноеСоединениеOpenSSL.

Прокси = Новый ИнтернетПрокси(Истина);
Прокси.Установить("https", "proxy.company.local", 3128, "user", "pass");

Соединение = Новый HTTPСоединение("api.example.ru", 443, , , Прокси, 30,
Новый ЗащищенноеСоединениеOpenSSL);

Учётные данные внешних сервисов не храните в коде и в открытом виде в справочниках. Используйте безопасное хранилище (в типовых конфигурациях — механизмы подсистемы интернет-поддержки или защищённые константы), а для файловых баз — как минимум ограничьте доступ к настройкам правами ролей.

Обработка ошибок и таймаутов

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

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

Отдельно проверяйте код состояния ответа. Код 200 не гарантирует, что в теле нет ошибки бизнес-логики — многие API возвращают описание ошибки в JSON с успешным HTTP-кодом. Коды 401 и 403 указывают на проблемы авторизации, 404 — на неверный адрес ресурса, 429 — на превышение лимита запросов, 5xx — на сбой на стороне сервиса, при котором имеет смысл повторить вызов через паузу.

Проверка результата и отладка

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

При отладке SOAP полезно сравнить XML-конверт, который формирует платформа, с примером из документации сервиса. Частая причина ошибок — несовпадение пространств имён и регистра имён элементов: SOAP чувствителен к регистру, и элемент OrderNumber не равен orderNumber. Для HTTP-запросов проверяйте заголовок Content-Type и кодировку: JSON по стандарту передаётся в UTF-8.

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

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

Код состояния ответа

Норма

200–299, тело содержит ожидаемые поля

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

4xx/5xx или пустое тело при успешном коде

Структура ответа

Норма

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

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

Поля отсутствуют, значения Неопределено, изменились имена

Данные в базе

Норма

Записанные значения совпадают с ответом сервиса

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

Пустые значения, обрезанные строки, неверные даты

Журнал регистрации

Норма

Есть запись об успешном вызове с ключевыми параметрами

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

Ошибки таймаута, авторизации или сериализации

Повторный вызов

Норма

Повтор не создаёт дублей и не ломает данные

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

Каждый вызов создаёт дублирующие записи

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

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

Чем WS-ссылка отличается от WSОпределения?

WS-ссылка — объект конфигурации, созданный в конфигураторе на основе WSDL; прокси из неё получают через WSСсылки. WSОпределение создаётся программно в коде из URL WSDL, что удобно при динамических адресах, но требует загрузки описания при каждом вызове и усложняет обработку ошибок.

Как передать файл в веб-сервис из 1С?

Для REST используйте метод УстановитьИмяФайлаТела у HTTPЗапрос — файл будет отправлен в теле запроса. Для SOAP файл обычно передаётся как base64-строка внутри XML или как вложение MTOM, если сервис это поддерживает; конкретный формат определяется документацией сервиса.

Почему вызов работает на компьютере разработчика, но не на сервере?

Чаще всего на сервере закрыт исходящий доступ в интернет или требуется прокси, который настроен только на рабочей станции. Проверьте сетевые правила для сервера 1С, передайте объект ИнтернетПрокси в HTTPСоединение и убедитесь, что вызов выполняется в серверной процедуре.

Как обратиться к сервису с самоподписанным сертификатом?

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

Можно ли вызывать веб-сервис асинхронно, не блокируя пользователя?

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

Что делать, если сервис ограничивает число запросов?

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