SOAP-сервис на 1С: от объекта в конфигураторе до первого ответа клиенту

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

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

Как устроены веб-сервисы 1С: SOAP, HTTP-сервисы и OData

У платформы 8.3 есть три механизма, через которые внешняя программа может обратиться к базе по HTTP. Их часто путают, хотя задачи у них разные.

HTTP-сервисы появились в 8.3.5. До этого SOAP был единственным способом сделать в 1С свой программный интерфейс, поэтому в старых интеграциях его встречают чаще всего.

Сама схема работы веб-сервиса проста:

• 🌐 клиент шлёт XML-конверт SOAP на адрес публикации;
• 🔌 модуль расширения веб-сервера (wsisapi.dll для IIS, wsap24.dll для Apache 2.4) передаёт запрос платформе;
• ⚙️ платформа открывает сеанс в базе под пользователем из авторизации, вызывает процедуру из модуля веб-сервиса;
• 📦 результат превращается в XML по типам из WSDL и уходит обратно.

Создание веб-сервиса в конфигураторе: операции, параметры, модуль

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

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

1. Откройте конфигуратор, в дереве найдите Общие → Web-сервисы, добавьте новый элемент.
2. Задайте имя латиницей, например Exchange. Имя войдёт в WSDL, кириллица в нём потом мешает сторонним клиентам.
3. Заполните свойство «Пространство имен URI», например http://mycompany.ru/exchange. Это уникальный идентификатор контракта, по нему клиент отличает ваш сервис от чужих.
4. Проверьте «Имя файла публикации» — по умолчанию Exchange.1cws. Это последняя часть URL.
5. В свойстве «Пакеты XDTO» укажите пакеты с типами, которые сервис будет использовать. Для простых строк и чисел достаточно пакета http://www.w3.org/2001/XMLSchema.

Шаг 2. Операции и параметры

На закладке «Операции» добавьте метод, например GetStock. У операции задаются:

• 🔹 «Тип возвращаемого значения» — например, xs:string или тип из своего пакета XDTO;
• 🔹 «Возможно пустое значение» — можно ли вернуть Неопределено;
• 🔹 «В транзакции» — выполнять ли весь вызов в транзакции (имеет смысл для операций, которые записывают данные);
• 🔹 «Имя процедуры» — функция в модуле, которая обрабатывает вызов.

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

Шаг 3. Код модуля

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

Функция GetStock(Article)

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

	Выборка = Запрос.Выполнить().Выбрать();
	Выборка.Следующий();

	Возврат Формат(Выборка.Остаток, "ЧГ=0; ЧН=0");

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

Имя регистра в примере условное: в вашей конфигурации подставьте свой регистр остатков. Агрегатная функция СУММА гарантирует одну строку в результате, поэтому Следующий() без проверки здесь безопасен.

После правки сохраните конфигурацию и обновите конфигурацию базы данных (F7). Без этого опубликованный сервис не увидит новых операций.

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

Публиковать можно и файловую, и клиент-серверную базу . На машине с веб-сервером должны стоять модули расширения веб-сервера — это отдельный компонент в установщике платформы. Разрядность Apache и платформы 1С должна совпадать: 64-битный модуль не загрузится в 32-битный Apache, и наоборот.

Через конфигуратор

1. Запустите конфигуратор от имени администратора Windows — иначе он не сможет записать настройки IIS или httpd.conf.
2. Откройте Администрирование → Публикация на веб-сервере.
3. Укажите имя публикации (оно станет частью URL, например buh), тип веб-сервера и каталог.
4. На закладке «Web-сервисы» оставьте флаг «Публиковать Web-сервисы» и отметьте нужные сервисы в списке.
5. Нажмите «Опубликовать» и согласитесь на перезапуск веб-сервера.

Через webinst

Для сервера без графического конфигуратора есть утилита webinst из каталога bin платформы:

"C:\Program Files\1cv8\8.3.24.1548\bin\webinst.exe" -publish -apache24 -wsdir buh -dir "C:\Apache24\htdocs\buh" -connstr "Srvr=srv1c;Ref=buh;" -confPath "C:\Apache24\conf\httpd.conf"

Номер версии в пути подставьте свой. Для IIS вместо -apache24 указывают -iis, параметр -confPath тогда не нужен.

Что лежит в default.vrd

Публикация создаёт в каталоге файл default.vrd. В нём строка подключения к базе и список сервисов:

<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="/buh"
       ib="Srvr=&quot;srv1c&quot;;Ref=&quot;buh&quot;;">
  <ws pointEnableCommon="true">
    <point name="Exchange" alias="Exchange.1cws" enable="true"/>
  </ws>
</point>

Через default.vrd удобно включать и выключать отдельные сервисы, не переопубликовывая базу. После ручной правки файла веб-сервер нужно перезапустить.

WSDL опубликованного веб-сервиса и описание методов

Откройте в браузере адрес публикации с параметром ?wsdl:

http://webserver/buh/ws/Exchange.1cws?wsdl

Браузер запросит логин и пароль пользователя 1С. Если в ответ пришёл XML — сервис опубликован правильно.

Что внутри WSDL и зачем это знать:

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

Передача данных через веб-сервис: типы 1С и XDTO

SOAP знает только XML-типы. Ссылку на справочник, таблицу значений или структуру 1С напрямую в ответ не положить — их нужно привести к типам XML-схемы.

Простые типы

Сложные типы через пакет XDTO

Для ответа со структурой (например, заказ с шапкой и строками) создайте в Общие → XDTO-пакеты свой пакет. В нём опишите тип объекта Order со свойствами Number, Date и списком Lines. Затем укажите пакет в свойстве веб-сервиса и выберите тип как возвращаемое значение.

В модуле объект создаётся через фабрику:

Функция GetOrder(Number)

	ТипЗаказа = ФабрикаXDTO.Тип("http://mycompany.ru/exchange", "Order");
	Заказ = ФабрикаXDTO.Создать(ТипЗаказа);
	Заказ.Number = Number;
	Заказ.Date = ТекущаяДатаСеанса();

	Возврат Заказ;

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

Строка с JSON или XML

Практичный компромисс — передавать одну строку, а внутри JSON. Контракт WSDL остаётся простым, структуру можно расширять без переопубликации. Минус: клиент не видит схему данных, её придётся описать отдельно.

Вызов внешнего веб-сервиса из 1С

Обратная задача — когда 1С сама обращается к чужому SOAP-сервису. Для этого есть два варианта.

Статическая WS-ссылка. В Общие → WS-ссылки добавляют ссылку и указывают адрес WSDL. Конфигуратор загрузит описание в конфигурацию. Удобно, когда контракт стабилен.

Динамический вызов. WSDL читается в момент вызова. Гибче, но каждый раз тратит время на загрузку описания:

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

Прокси = Новый WSПрокси(Определения,
	"http://mycompany.ru/exchange", "Exchange", "ExchangeSoap");
Прокси.Пользователь = "ws_user";
Прокси.Пароль = "Пароль";

Остаток = Прокси.GetStock("А-1024");

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

Права, авторизация и безопасность веб-сервисов

Веб-сервис открывает базу наружу. Ошибка в настройке прав здесь стоит дороже, чем в обычном интерфейсе.

Отдельный пользователь и роль

1. Создайте роль, например ВебСервисОбмен. Дайте в ней право «Использование» на нужный веб-сервис.
2. В той же роли дайте минимальные права на объекты, которые читает или пишет модуль. Только чтение регистра остатков — значит, только чтение.
3. Заведите пользователя ws_user только с этой ролью и аутентификацией 1С:Предприятия.
4. Отключите ему «Показывать в списке выбора»: интерактивно под ним никто работать не должен.

Если в модуле нужен доступ к данным шире, чем у роли, используйте привилегированный режим точечно: УстановитьПривилегированныйРежим(Истина) и обратно сразу после нужной операции.

Чек-лист защиты публикации

HTTPS настраивается на стороне веб-сервера, не в 1С. Сама платформа принимает запрос уже расшифрованным от IIS или Apache.

Тестирование и диагностика интеграции через веб-сервисы

Проверяйте по слоям: сначала веб-сервер, потом WSDL, потом вызов метода.

1. Браузер. Открыть ...Exchange.1cws?wsdl. Пришёл XML — публикация живая.
2. SoapUI или Postman. Создать проект по адресу WSDL. SoapUI сам построит конверты для каждой операции, останется подставить значения и авторизацию Basic.
3. curl — когда на сервере нет графики:

curl -u ws_user:Пароль -H "Content-Type: text/xml; charset=utf-8" --data-binary @request.xml http://webserver/buh/ws/Exchange.1cws

Файл request.xml с конвертом SOAP 1.1:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
               xmlns:ex="http://mycompany.ru/exchange">
  <soap:Body>
    <ex:GetStock>
      <ex:Article>А-1024</ex:Article>
    </ex:GetStock>
  </soap:Body>
</soap:Envelope>

4. Отладка модуля. В конфигураторе в настройках автоматического подключения отладки (Отладка → Подключение) включите отладку сеансов веб-сервисов. В default.vrd для публикации должна быть разрешена отладка. Тогда точка останова в модуле сработает при внешнем вызове.
5. Журнал регистрации. Исключения из модуля фиксируются там с текстом ошибки. Отбор по приложению «Web-сервис» быстро отсекает события пользователей.

Расшифровка типичных ответов:

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