SOAP-интеграция с 1С: от объекта в конфигураторе до работающего WSDL

Web-сервис 1С — это объект конфигурации из ветки Общие → Web-сервисы, который отдаёт наружу операции по протоколу SOAP. После публикации на веб-сервере (IIS или Apache) у сервиса появляется адрес вида http://сервер/база/ws/имя.1cws?wsdl. По этому WSDL любая внешняя система — сайт, складская программа, другая база 1С — узнаёт, какие методы можно вызвать и какие данные передать.

Типичная ситуация: интернет-магазину нужны остатки и цены из 1С каждые 10 минут, а выгрузка файлами постоянно ломается. Настройка web-сервиса в 1С занимает час-два: объект в конфигураторе, функция в модуле, публикация и права. Дальше разберём каждый шаг с примерами использования и типичными сбоями.

Web-сервисы и HTTP-сервисы в 1С: в чём разница

В платформе 8.3 есть два способа принять входящий запрос: web-сервисы (SOAP) и HTTP-сервисы (REST-подобные, появились в 8.3.5). Оба публикуются одной командой, но устроены по-разному.

Главный плюс SOAP — контракт. Внешний разработчик скачивает WSDL, его среда сама строит классы и типы. Ошибиться в имени поля или типе почти нельзя: запрос не пройдёт проверку схемы.

Минус — тяжеловесность. Каждый вызов обёрнут в XML-конверт, а сайту на PHP или JavaScript проще работать с JSON. Поэтому новые интеграции с сайтами чаще делают на HTTP-сервисах, а web-сервисы остаются там, где нужен строгий формат.

Как создать web-сервис в конфигураторе 1С

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

Объект и пространство имён

1. Откройте Конфигурация → Открыть конфигурацию.
2. В дереве раскройте Общие → Web-сервисы, нажмите «Добавить».
3. Задайте имя латиницей, например Stock. Латиница избавит внешних разработчиков от проблем с кодировкой в именах классов.
4. Заполните «Пространство имен URI» — уникальную строку вида http://example.ru/stock. Это не реальный адрес, а идентификатор, но он должен быть уникален в конфигурации.
5. В свойстве «Имя файла публикации» оставьте или задайте имя, например stock.1cws. Оно попадёт в адрес сервиса.

Пакеты XDTO и типы

На вкладке «Пакеты XDTO» отмечают пакеты, типы из которых сервис использует. Для простых значений хватает базовых типов из пространства http://www.w3.org/2001/XMLSchema: string, int, decimal, boolean, dateTime.

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

Операции и параметры

1. На вкладке «Операции» добавьте операцию, например GetStock.
2. Укажите «Тип возвращаемого значения» и при необходимости «Возможно пустое».
3. Свойство «В транзакции» включайте, если операция записывает данные и всё должно откатиться при ошибке.
4. Внутри операции добавьте параметры: имя, тип значения и направление передачи (входной, выходной, входной-выходной).
5. Нажмите на лупу у свойства «Имя процедуры» — платформа создаст функцию в модуле сервиса.

Код операции

Пример функции, которая возвращает остаток по артикулу. Имена регистров и реквизитов замените на свои:

Функция GetStock(Article)

	Запрос = Новый Запрос;
	Запрос.Текст =
	"ВЫБРАТЬ
	|	ЕСТЬNULL(СУММА(Остатки.КоличествоОстаток), 0) КАК Количество
	|ИЗ
	|	РегистрНакопления.ТоварыНаСкладах.Остатки(
	|			,
	|			Номенклатура.Артикул = &Артикул) КАК Остатки";
	Запрос.УстановитьПараметр("Артикул", Article);

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

	Возврат 0;

КонецФункции

Модуль выполняется на сервере в сеансе того пользователя, под которым пришёл запрос. Исключение, вызванное через ВызватьИсключение, вернётся клиенту как SOAP Fault с текстом ошибки.

Права на сервис

Без этого шага сервис не заработает ни у кого, кроме полноправного пользователя:

1. Создайте роль или откройте существующую.
2. Найдите в ней ветку Web-сервисов и дайте право «Использование» на ваш сервис.
3. Дайте роли права на чтение тех справочников и регистров, к которым обращается код.
4. В базе заведите отдельного пользователя для интеграции, например ws_shop, с паролем и только этой ролью.

После сохранения выполните Конфигурация → Обновить конфигурацию базы данных (F7).

Публикация web-сервисов 1С на веб-сервере

Публикацию делают из конфигуратора командой Администрирование → Публикация на веб-сервере. Перед этим на компьютере с веб-сервером должна стоять платформа 1С того же номера, что и сервер 1С, с компонентом «Модули расширения веб-сервера».

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

В окне публикации:

• 🔹 «Имя» — часть адреса после сервера, например trade. Латиница, без пробелов.
• 🔹 «Веб-сервер» — выбор из найденных: Internet Information Services или Apache нужной версии.
• 🔹 «Каталог» — папка, куда ляжет файл default.vrd.
• 🔹 Вкладка «Web-сервисы» — флаг публикации web-сервисов по умолчанию и список сервисов с галочками и адресами.

Галочку в списке ставьте только у тех сервисов, которые реально нужны снаружи. Каждый лишний опубликованный сервис — лишняя точка входа в базу.

После нажатия «Опубликовать» в каталоге появится default.vrd. Это обычный XML, и иногда его удобнее поправить руками:

<?xml version="1.0" encoding="UTF-8"?>
<point xmlns="http://v8.1c.ru/8.2/virtual-resource-system"
       xmlns:xs="http://www.w3.org/2001/XMLSchema"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       base="/trade"
       ib="Srvr=&quot;srv1c&quot;;Ref=&quot;trade&quot;;">
  <ws pointEnableCommon="true">
    <point name="Stock" alias="stock.1cws" enable="true"
           reuseSessions="autouse" sessionMaxAge="20"
           poolSize="10" poolTimeout="5"/>
  </ws>
</point>

Атрибут reuseSessions управляет повторным использованием сеансов. При dontuse каждый вызов открывает и закрывает сеанс 1С, это надёжно, но медленно. При autouse платформа держит пул сеансов, и частые вызовы проходят заметно быстрее.

Настройка IIS для web-сервисов 1С

IIS — штатный вариант на Windows Server 2016 и новее. Последовательность:

1. В «Диспетчере серверов» добавьте роль «Веб-сервер (IIS)».
2. В компонентах роли отметьте «Расширения ISAPI» и «Фильтры ISAPI» (раздел «Разработка приложений»), а также «Обычная проверка подлинности», если будете использовать Basic-авторизацию.
3. Установите платформу 1С с компонентом «Модули расширения веб-сервера». Разрядность платформы должна совпадать с режимом пула приложений.
4. Опубликуйте базу из конфигуратора, запущенного от имени администратора.
5. Выдайте права на папку bin платформы и на каталог публикации группе IIS_IUSRS (чтение и выполнение). Для файловой базы этой же группе нужны права на изменение каталога базы.

Если стоит 32-разрядная платформа, в дополнительных параметрах пула приложений включите «Разрешить 32-разрядные приложения». Для 64-разрядной платформы этот флаг должен быть выключен.

Настройка Apache для 1С

На Linux 1С публикуют только через Apache, на Windows он бывает альтернативой IIS. Конфигуратор сам дописывает нужные строки в httpd.conf, но их полезно знать на случай ручной правки или переноса:

LoadModule _1cws_module "C:/Program Files/1cv8/8.3.24.1342/bin/wsap24.dll"

# 1c publication
Alias "/trade" "C:/Apache24/htdocs/trade/"
<Directory "C:/Apache24/htdocs/trade/">
    AllowOverride All
    Options None
    Require all granted
    SetHandler 1c-application
    ManagedApplicationDescriptor "C:/Apache24/htdocs/trade/default.vrd"
</Directory>

Номер версии в пути подставьте свой. На Linux модуль называется wsap24.so и лежит в каталоге установленной платформы.

Что проверить:

• 📌 Строка LoadModule в конфиге одна. После обновления платформы старый путь часто остаётся, и Apache грузит модуль от прежней версии.
• 📌 Разрядность Apache и платформы одинаковая: 64-битный Apache не загрузит 32-битный wsap24.dll.
• 📌 Пользователь, от которого работает служба Apache, имеет права на каталог публикации и, для файловой базы, на каталог базы.

После правки конфига проверьте синтаксис командой httpd -t (на Linux — apachectl configtest) и только потом перезапускайте службу. Перезапуск разорвёт текущие вызовы.

Вызов web-сервиса 1С: WSDL, SOAP и WSПрокси

Первая проверка — открыть в браузере адрес http://сервер/trade/ws/stock.1cws?wsdl. Браузер спросит логин и пароль пользователя 1С, а затем покажет XML с описанием сервиса. Если XML появился, публикация и права работают.

Вызов из другой базы 1С

Динамический вариант — сервис подключается в момент выполнения кода:

Определения = Новый WSОпределения(
	"http://srv/trade/ws/stock.1cws?wsdl", "ws_shop", "Пароль");

Прокси = Новый WSПрокси(Определения,
	"http://example.ru/stock",  // Пространство имен URI сервиса
	"Stock",                     // имя сервиса
	"StockSoap");                // точка подключения
Прокси.Пользователь = "ws_shop";
Прокси.Пароль = "Пароль";

Остаток = Прокси.GetStock("A-1024");
Сообщить("Остаток: " + Формат(Остаток, "ЧГ=0"));

Пространство имён, имя сервиса и точку подключения берите из WSDL: элементы service и port. Для сервисов 1С точки подключения обычно две — с суффиксами Soap и Soap12.

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

Вызов из внешней системы

Внешний разработчик скармливает WSDL своему инструменту: в .NET — «Add Service Reference», в Java — генератор клиентских классов. Для ручной проверки удобен SoapUI: создайте проект по адресу WSDL, и он сам соберёт шаблон запроса.

Сам SOAP-запрос выглядит так:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
               xmlns:st="http://example.ru/stock">
  <soap:Body>
    <st:GetStock>
      <st:Article>A-1024</st:Article>
    </st:GetStock>
  </soap:Body>
</soap:Envelope>

Отправляется он методом POST на адрес без ?wsdl, с Basic-авторизацией пользователя 1С. Для доступа из интернета обязательно настройте HTTPS на веб-сервере: при Basic-авторизации пароль иначе идёт по сети почти открытым текстом.

Ошибки интеграции и отладка web-сервиса

Большинство сбоев видно по коду HTTP-ответа. Начинайте диагностику с него, а не с кода модуля.

Как отлаживать код операции

Ставить точку останова в модуле сервиса можно, но отладчик сам к сеансу web-сервиса не подключится. В конфигураторе откройте Отладка → Подключение, перейдите к автоматическому подключению и отметьте сеансы web-сервисов. После этого вызов из SoapUI остановится на точке останова, как обычный серверный код.

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

Если не помогло

• 🔍 Откройте журнал регистрации с отбором по пользователю интеграции: видно, доходят ли вызовы до базы вообще.
• 🔍 Посмотрите журнал ошибок веб-сервера: в IIS — журналы сайта и «Просмотр событий» Windows, в Apache — файл error.log.
• 🔍 Проверьте сервис простейшей операцией без параметров, которая возвращает строку ok. Работает — проблема в типах или коде, нет — в публикации.

Частые вопросы о web-сервисах 1С