Как работать с веб-сервисом в 1С: вызов внешних API и публикация своих сервисов

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

Для вызова внешних SOAP-сервисов используется объект «WS-ссылка» (WSReference), который строит прокси по WSDL-описанию. Для REST-сервисов и произвольных API применяется объект HTTPСоединение с запросами GET, POST, PUT. Для публикации своих сервисов платформа предлагает два объекта метаданных: «Web-сервисы» (SOAP) и «HTTP-сервисы» (REST-подобные), оба требуют настройки публикации на веб-сервере.

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

Разбираемся в терминах: SOAP, REST, WSDL и JSON

Прежде чем писать код, важно различать форматы взаимодействия. SOAP — это протокол обмена XML-сообщениями со строгим контрактом, описанным в WSDL-файле. REST — не протокол, а стиль: обычные HTTP-запросы к адресам (ресурсам), данные чаще всего передаются в формате JSON. В 1С поддерживаются оба подхода, но инструменты различаются.

Практический признак выбора прост: если поставщик сервиса дал вам ссылку вида https://example.com/service?wsdl — это SOAP, и вы работаете через WS-ссылку. Если дали документацию с адресами вида GET /api/v1/orders и примерами JSON — это REST, и нужен HTTPСоединение. Смешивать подходы не получится: SOAP-сервис нельзя вызвать простым POST с JSON, а REST-сервис не имеет WSDL.

Вызываем внешний SOAP-сервис через WS-ссылку

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

1. 1
   Создайте WS-ссылку в конфигураторе, указав URL WSDL-файла
2. 2
   В коде сформируйте WSПрокси через WSСсылки.ИмяСсылки.СоздатьWSПрокси с указанием URI пространства имен и имени сервиса
3. 3
   При необходимости задайте логин и пароль в параметрах создания прокси
4. 4
   Вызовите нужную операцию, передав параметры платформенных XDTO-типов
5. 5
   Обработайте результат и возможные исключения через Попытка/Исключение

Типичный код вызова выглядит так:

Прокси = WSСсылки.СервисКурсов.СоздатьWSПрокси(
"http://example.org/namespace", "RateService", "RateServiceSoap");
Прокси.Пользователь = "user";
Прокси.Пароль = "password";
Результат = Прокси.GetRate("USD", ТекущаяДатаСеанса());

Параметры операций SOAP-сервиса часто являются сложными объектами XDTO, а не примитивами. Если метод требует объект-запрос, создайте его через Прокси.ФабрикаXDTO.Создать() с указанием типа из WSDL, заполните свойства и только потом передавайте в вызов. Попытка передать строку туда, где ожидается объект, вызовет ошибку сериализации ещё до отправки запроса.

Работаем с REST API через HTTPСоединение

HTTPСоединение — универсальный механизм для любых веб-запросов. Вы создаёте соединение с сервером, формируете HTTPЗапрос с нужным ресурсом, заголовками и телом, выполняете метод (Получить, ОтправитьДляОбработки и т.д.) и читаете ответ. Это основной способ интеграции с современными API: сайтами, CRM, службами доставки, банками.

Соединение = Новый HTTPСоединение("api.example.com", 443, , , , ,
Новый ЗащищенноеСоединениеOpenSSL());
Запрос = Новый HTTPЗапрос("/v1/orders?status=new");
Запрос.Заголовки.Вставить("Authorization", "Bearer " + Токен);
Ответ = Соединение.Получить(Запрос);
Если Ответ.КодСостояния = 200 Тогда
Данные = ПрочитатьJSONИзСтроки(Ответ.ПолучитьТелоКакСтроку());
КонецЕсли;

Для чтения JSON используйте объект ЧтениеJSON с методом ПрочитатьJSON — он преобразует данные в структуру или соответствие. Для отправки данных в теле запроса сформируйте JSON через ЗаписьJSON и установите заголовок Content-Type: application/json. Без этого заголовка многие серверы не распарсят тело и вернут ошибку 400.

Публикуем собственный HTTP-сервис из 1С

Чтобы внешние системы могли обращаться к базе 1С, создайте в конфигураторе объект «HTTP-сервисы» в ветке «Общие». Внутри сервиса настраиваются шаблоны URL (например, /orders/{id}) и для каждого шаблона — методы GET, POST и другие с обработчиками на встроенном языке. Обработчик получает объект HTTPСервисЗапрос и должен вернуть HTTPСервисОтвет с кодом состояния и телом.

Публикация выполняется через диалог «Администрирование» → «Публикация на веб-сервере». Требуется установленный веб-сервер (IIS или Apache) с модулем расширения 1С. В диалоге укажите имя публикации, каталог и отметьте флажок публикации HTTP-сервисов. После публикации сервис станет доступен по адресу вида http://server/base/hs/orders/123, где hs — стандартный префикс HTTP-сервисов.

В обработчике метода важно явно формировать код ответа: 200 при успехе, 400 при неверных параметрах, 404 если объект не найден, 500 при внутренней ошибке. Это позволит вызывающей системе корректно реагировать на сбои. Тело ответа формируйте в JSON через ЗаписьJSON — это де-факто стандарт для таких интеграций.

Публикуем SOAP Web-сервис: когда это оправдано

Объект «Web-сервисы» работает по SOAP: вы описываете операции и их параметры, платформа автоматически генерирует WSDL по адресу http://server/base/ws/ИмяСервиса?wsdl. Этот вариант выбирайте, если вызывающая система требует именно SOAP — например, устаревшие корпоративные шины или системы, где контракт строго фиксируется через WSDL.

Для параметров сложных типов в Web-сервисах используются пакеты XDTO. Простые параметры (строка, число, дата, булево) объявляются прямо в свойствах операции. Учтите ограничение: SOAP в 1С тяжелее в отладке — для проверки понадобится внешний клиент вроде SoapUI, а текст ошибки часто скрыт за общим сообщением о сбое сериализации.

Что выбрать для своей интеграции

HTTP-сервис (REST/JSON)

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

Web-сервис (SOAP)

Подходит, когда внешняя система требует WSDL и строгий контракт типов. Ограничение — больше накладных расходов, сложнее диагностика ошибок.

Планы обмена + файлы

Альтернатива при нестабильном канале: данные передаются пакетами по расписанию. Не подходит, когда нужен ответ в реальном времени.

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

Основной инструмент диагностики вызовов внешних сервисов — журнал регистрации и анализ кода состояния HTTP. Коды 4xx означают проблему на вашей стороне (неверный адрес, параметры, авторизация), коды 5xx — сбой на стороне сервиса. Таймауты и ошибки соединения чаще всего связаны с сетью: прокси, файрволом, недоступностью DNS с сервера 1С.

Для отладки собственных HTTP-сервисов удобно сначала вызвать их браузером или утилитой curl с тестовыми параметрами — так вы отделите ошибки публикации от ошибок кода. Если сервис возвращает ошибку 404, проверьте, что публикация выполнена, флажок публикации HTTP-сервисов установлен, а шаблон URL в конфигураторе совпадает с вызываемым адресом с точностью до регистра и слэшей.

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

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

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

Вызов внешнего сервиса

Норма

Код ответа 200, тело читается как JSON/XML, данные совпадают с ожидаемыми

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

Код 4xx/5xx, пустое тело или HTML-страница ошибки вместо данных

Публикация HTTP-сервиса

Норма

Запрос по адресу /hs/... возвращает ожидаемый ответ, в журнале регистрации нет ошибок

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

404 (сервис не опубликован или неверный шаблон URL), 401/403 (проблема с правами)

Производительность

Норма

Разовый вызов занимает секунды, массовый обмен идёт фоновым заданием

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

Форма зависает при записи, пользователи жалуются на ожидание

Безопасность

Норма

Сервис требует аутентификацию, пароли хранятся в защищённом хранилище

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

Сервис отвечает без авторизации, пароли видны в коде модулей

FAQ: частые вопросы о веб-сервисах в 1С

Чем WS-ссылка отличается от объекта WSПрокси?

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

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

Передайте объект ИнтернетПрокси в конструктор HTTPСоединение или в параметры создания WSПрокси. В объекте прокси укажите сервер, порт, при необходимости логин и пароль. Если прокси настроен системно, можно использовать вариант с автоматическим определением настроек, но на сервере 1С надёжнее задавать параметры явно.

Что делать, если WSDL не загружается в конфигураторе?

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

Можно ли вызывать веб-сервис из тонкого или веб-клиента?

Да, но вызов выполняется на сервере 1С: код с HTTPСоединение или WSПрокси должен находиться в серверном контексте (серверная процедура общего модуля или серверный метод формы). Прямое обращение к внешним адресам из клиентского контекста платформа не выполняет — это сделано в том числе из соображений безопасности.

Как ограничить нагрузку от опубликованного HTTP-сервиса?

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

Где хранить токены и пароли для внешних сервисов?

Не в коде и не в открытых константах. Используйте защищённое хранилище (в БСП — общий модуль работы с безопасным хранилищем данных) либо константу с ограничением прав доступа. Доступ к настройкам давайте только администраторам интеграций, а при смене пароля обновляйте его в одном месте, не переписывая код.