SOAP-сервис на платформе 1С 8.3: от объекта метаданных до вызова из внешней системы
Содержание
Чтобы создать веб-сервис в 1С, откройте конфигуратор, в дереве метаданных разверните Общие → Web-сервисы и добавьте новый объект. Задайте ему пространство имён, опишите операции и их параметры, напишите в модуле сервиса функции-обработчики, затем опубликуйте базу на веб-сервере через Администрирование → Публикация на веб-сервере. После этого описание сервиса доступно по адресу вида http://сервер/база/ws/имя.1cws?wsdl.
Веб-сервис нужен, когда внешняя программа должна получать данные из 1С или передавать их в базу без участия пользователя: сайт спрашивает остатки, мобильное приложение создаёт заказ, другая учётная система забирает справочник. Механизм общий для платформы 8.3 и не зависит от конфигурации: одинаково работает в Бухгалтерии, УТ и собственных разработках.
Что такое веб-сервис в 1С и чем он отличается от HTTP-сервиса
Веб-сервис в 1С — это объект конфигурации, который принимает запросы по протоколу SOAP. Платформа сама формирует WSDL-описание, разбирает входящий XML и упаковывает ответ. Разработчик пишет только функции на встроенном языке.
У платформы есть два способа открыть базу наружу. Выбор зависит от того, кто будет клиентом.
| Механизм | Протокол | Когда выбирать |
|---|---|---|
| Web-сервис | SOAP, описание в WSDL | Клиент умеет работать с WSDL: другая 1С, .NET, Java, корпоративные шины |
| HTTP-сервис | Произвольный HTTP (обычно JSON) | Сайт, мобильное приложение, интеграции в стиле REST |
💡 SOAP-сервис удобен строгой схемой: клиент по WSDL сам генерирует классы, и ошибка в типе данных видна сразу. Если интегратор просит «просто JSON по URL», делайте HTTP-сервис, а не веб-сервис.
Типичные задачи, которые закрывает веб-сервис 1С:
- 📦 отдать остатки и цены интернет-магазину;
- 🧾 принять заказ или платёж из внешней системы и создать документ ;
- 🔄 обмениваться справочниками между базами без файлов обмена;
- 📊 отдавать агрегированные данные в BI-систему или корпоративный портал.
Подготовка к созданию веб-сервиса: что нужно до конфигуратора
Перед разработкой проверьте три вещи. Без них сервис либо не опубликуется, либо будет падать при первом вызове.
Платформа и модуль расширения веб-сервера
При установке платформы отметьте компонент «Модули расширения веб-сервера». Без него в каталоге платформы не будет библиотек wsisapi.dll (для IIS) и wsap24.dll (для Apache 2.4), и публикация закончится ошибкой.
Разрядность модуля должна совпадать с разрядностью веб-сервера. 64-битный Apache не загрузит 32-битную библиотеку, и наоборот.
Права на изменение конфигурации
Веб-сервис добавляется в основную конфигурацию или в расширение. В типовой конфигурации на поддержке удобнее расширение: обновления не придётся объединять вручную. Работайте на копии базы, а в рабочую переносите проверенный результат.
Пакет XDTO для сложных типов
Если сервис принимает и возвращает только строки и числа, пакет не нужен: хватит типов из пространства http://www.w3.org/2001/XMLSchema (string, decimal, boolean, dateTime).
Для структур — например, «товар: артикул, наименование, остаток» — создайте пакет в Общие → XDTO-пакеты:
- Добавьте пакет и задайте его URI пространства имён, например
http://example.ru/stock. - Внутри создайте тип объекта
StockItemсо свойствамиArticle,Name,Quantity. - Для списка создайте тип
StockListсо свойствомItemтипаStockItemи верхней границей-1(это значит «сколько угодно элементов»).
Как создать веб-сервис в конфигураторе: пошагово
Пример: сервис Stock с одной операцией — вернуть остаток товара по артикулу.
Шаг 1. Объект веб-сервиса
- В дереве метаданных:
Общие → Web-сервисы → Добавить. - Имя —
Stock. - URI пространства имён —
http://example.ru/stock. Это не адрес в интернете, а уникальный идентификатор. Главное — не менять его после того, как клиенты подключились. - На вкладке с пакетами XDTO добавьте созданный пакет, если используете свои типы.
- Имя файла публикации —
stock.1cws. Оно попадёт в адрес сервиса.
Шаг 2. Операция
- На закладке «Операции» добавьте операцию
GetStock. - Тип возвращаемого значения —
decimalиз пространства XMLSchema (илиStockListиз своего пакета). - Флаг «Возможно пустое» включайте, если сервис может вернуть «ничего».
- Флаг «В транзакции» нужен операциям, которые пишут данные. Для чтения его лучше снять.
- В поле «Имя процедуры» нажмите лупу — конфигуратор создаст заготовку функции в модуле.
Шаг 3. Параметры
Добавьте параметр Article, тип string, направление «Входной». Направления «Выходной» и «Входной-выходной» нужны, когда операция возвращает несколько значений, но для внешних клиентов проще отдать одну структуру XDTO.
Шаг 4. Модуль веб-сервиса
Код выполняется на сервере, поэтому в нём доступны запросы и объекты базы:
Функция GetStock(Article)
Запрос = Новый Запрос;
Запрос.Текст =
"ВЫБРАТЬ
| ЕСТЬNULL(СУММА(Остатки.КоличествоОстаток), 0) КАК Количество
|ИЗ
| РегистрНакопления.ТоварыНаСкладах.Остатки(
| ,
| Номенклатура.Артикул = &Артикул) КАК Остатки";
Запрос.УстановитьПараметр("Артикул", Article);
Выборка = Запрос.Выполнить().Выбрать();
Если Выборка.Следующий() Тогда
Возврат Выборка.Количество;
КонецЕсли;
Возврат 0;
КонецФункции
Имя регистра и его измерений подставьте из своей конфигурации — в примере условное.
Шаг 5. Возврат структуры через XDTO
Когда нужно отдать список товаров, соберите объект из типов пакета:
Функция GetStockList(Articles)
ТипСписок = ФабрикаXDTO.Тип("http://example.ru/stock", "StockList");
ТипТовар = ФабрикаXDTO.Тип("http://example.ru/stock", "StockItem");
Список = ФабрикаXDTO.Создать(ТипСписок);
// Выборка — результат запроса по остаткам
Пока Выборка.Следующий() Цикл
Товар = ФабрикаXDTO.Создать(ТипТовар);
Товар.Article = Выборка.Артикул;
Товар.Name = Выборка.Наименование;
Товар.Quantity = Выборка.Количество;
Список.Item.Добавить(Товар);
КонецЦикла;
Возврат Список;
КонецФункции
Обновите конфигурацию базы данных (F7) — без этого публикация не увидит новый сервис.
Публикация веб-сервиса 1С на Apache и IIS
Публикация связывает веб-сервер с информационной базой. Конфигуратор запускайте от имени администратора Windows: он правит файлы веб-сервера.
Публикация из конфигуратора
Администрирование → Публикация на веб-сервере.- Имя — короткое латинское, например
trade. Это первая часть адреса. - Веб-сервер — выберите из списка (Apache 2.4 или IIS).
- Каталог — папка, где появится файл
default.vrd. - Отметьте «Публиковать Web-сервисы» и галочку у сервиса
Stock. - Нажмите «Опубликовать» и согласитесь на перезапуск веб-сервера.
⚠️ Перезапуск веб-сервера обрывает текущие подключения через веб-клиент и уже опубликованные сервисы. Публикуйте рабочую базу в нерабочее время.
Чем отличаются Apache и IIS
| Apache 2.4 | IIS | |
|---|---|---|
| Модуль 1С | wsap24.dll подключается в httpd.conf | wsisapi.dll через сопоставление обработчиков |
| Что подготовить | Установить Apache как службу | Включить роль веб-сервера с расширениями ISAPI |
| Частая проблема | Нет прав у учётной записи службы на каталог файловой базы | Пул приложений с «Разрешить 32-разрядные приложения» при 64-битной платформе |
| Linux | Работает | Нет |
Публикация из командной строки
На сервере без конфигуратора используйте утилиту webinst из каталога bin платформы:
webinst -publish -apache24 -wsdir trade -dir "C:\Apache24\htdocs\trade" ^
-connstr "Srvr=srv1c;Ref=trade;" -confpath "C:\Apache24\conf\httpd.conf"
Для IIS вместо -apache24 и -confpath укажите -iis. Такую команду удобно держать в скрипте развёртывания.
После публикации откройте в браузере http://сервер/trade/ws/stock.1cws?wsdl. Если вернулся XML с описанием операций — сервис опубликован.
Как протестировать и отладить веб-сервис
Проверка без программирования
Возьмите SoapUI или аналог: создайте проект по адресу WSDL, инструмент сам сформирует шаблон запроса. Подставьте артикул, на вкладке авторизации укажите логин и пароль пользователя 1С (Basic). Ответ придёт в XML.
Проверка из другой базы 1С
Определения = Новый WSОпределения(
"http://srv/trade/ws/stock.1cws?wsdl", "ws_user", "пароль");
Прокси = Новый WSПрокси(Определения,
"http://example.ru/stock", "Stock", "StockSoap");
Прокси.Пользователь = "ws_user";
Прокси.Пароль = "пароль";
Остаток = Прокси.GetStock("A-100");
Имя точки подключения платформа формирует как имя сервиса плюс Soap (есть и вариант Soap12). Если не уверены, откройте WSDL и найдите элемент port.
Отладка кода сервиса
В конфигураторе откройте Отладка → Подключение, затем «Автоматическое подключение» и отметьте тип «Web-сервис». Поставьте точку останова в модуле и вызовите операцию из SoapUI — выполнение остановится на ней. Для клиент-серверной базы сервер 1С должен быть запущен в режиме отладки.
Проверить, что вызов вообще дошёл до базы, можно по журналу регистрации: сеансы веб-сервиса там видны отдельно от обычных пользователей.
Безопасность веб-сервиса: доступ, роли, шифрование
Веб-сервис открывает базу наружу. Ошибка в настройке доступа превращается в утечку данных.
Отдельный пользователь и роль
- Создайте роль, например
ИспользованиеВебСервисаОстатки. - В редакторе роли найдите ветку
Web-сервисыи дайте право «Использование» только нужным операциям. - Дайте роли права на чтение только тех объектов, которые читает код сервиса.
- Создайте пользователя
ws_userс этой ролью и сложным паролем. Права на запуск тонкого и веб-клиента этой роли не давайте.
⚠️ Не прописывайте логин и пароль в строке подключения файла default.vrd. Тогда сервис станет доступен без авторизации любому, кто знает адрес.
Шифрование канала
Basic-авторизация передаёт пароль в открытом виде, только в кодировке base64. Поэтому наружу публикуйте сервис только по HTTPS: сертификат ставится на веб-сервер, 1С тут ничего настраивать не нужно.
Дополнительные меры:
- 🔒 ограничьте доступ к каталогу публикации по IP-адресам клиентов на веб-сервере или межсетевом экране;
- 🧱 публикуйте наружу отдельную публикацию только с веб-сервисами, без веб-клиента;
- 🧪 проверяйте входные параметры в коде: длину строк, допустимые значения, существование объектов;
- 📝 пишите в журнал регистрации записи о попытках вызова с некорректными данными.
Интеграция веб-сервиса 1С с внешними системами
Вызов из других языков
Клиенты на .NET и Java генерируют прокси-классы по WSDL штатными средствами: в Visual Studio это «Добавить ссылку на службу», в Java — wsimport или генератор Apache CXF. После этого вызов выглядит как обычный метод.
Из Python удобна библиотека zeep:
from requests import Session
from requests.auth import HTTPBasicAuth
from zeep import Client
from zeep.transports import Transport
session = Session()
session.auth = HTTPBasicAuth("ws_user", "пароль")
client = Client("https://srv/trade/ws/stock.1cws?wsdl",
transport=Transport(session=session))
print(client.service.GetStock("A-100"))
Постоянная ссылка из 1С
Если другая база 1С вызывает сервис регулярно, не загружайте WSDL при каждом вызове. Добавьте в её конфигурацию объект Общие → WS-ссылки и импортируйте WSDL один раз. Прокси тогда создаётся без обращения к адресу ?wsdl, а это минус один сетевой запрос на каждый вызов.
Сопоставление полей
При интеграции большая часть ошибок возникает не в коде, а в договорённостях. Зафиксируйте с интегратором таблицу:
Оптимизация производительности веб-сервиса
Каждый вызов SOAP-сервиса без настроек открывает новый сеанс 1С. На частых запросах это главный источник задержек.
Повторное использование сеансов
В диалоге публикации у сервиса есть настройка повторного использования сеансов. Её же можно задать в default.vrd:
<ws>
<point name="Stock" alias="stock.1cws"
reuseSessions="autouse" sessionMaxAge="20" poolSize="10"/>
</ws>
Режим use держит сеансы всегда, autouse — только если клиент поддерживает cookies, dontuse отключает пул. Значение sessionMaxAge задаётся в секундах.
Что ещё ускоряет ответ
- ⚡ Используйте запросы вместо обращения через точку к реквизитам объектов.
- ⚡ Отдавайте только нужные поля и делайте постраничную выборку: параметры «с какой записи» и «сколько».
- ⚡ Снимайте флаг «В транзакции» у операций чтения.
- ⚡ Долгую операцию (формирование отчёта, массовая загрузка) запускайте фоновым заданием и отдавайте клиенту идентификатор. Вторая операция возвращает статус и результат.
- ⚡ Кэшируйте редко меняющиеся данные в модуле с повторным использованием возвращаемых значений.
💡 Перед оптимизацией замерьте время. Включите замер производительности в конфигураторе, вызовите операцию и посмотрите, какая строка модуля занимает больше всего времени.