SOAP или REST в 1С 8.3: как выбрать тип сервиса под конкретную интеграцию

Главная разница между Web и HTTP сервисами 1С — в протоколе и строгости контракта. Web-сервис работает по SOAP: обмен идёт XML-конвертами, а описание методов и типов платформа сама отдаёт в виде WSDL. HTTP-сервис — это «голый» HTTP: вы сами задаёте адреса ресурсов, методы GET/POST/PUT/DELETE, формат тела (чаще JSON) и коды ответа.

Если коротко про выбор: внешняя система требует SOAP и WSDL (банк, госсервис, старая шина, другая 1С через WS-ссылку) — делайте Web-сервис. Сайт, мобильное приложение, интернет-магазин, микросервис на Python или JavaScript — делайте HTTP-сервис. Оба механизма есть в платформе 1С 8.3, публикуются на одном веб-сервере и могут жить в одной конфигурации одновременно.

Как устроен Web-сервис 1С на SOAP

Web-сервис — объект конфигурации в ветке Общие → Web-сервисы. У него есть операции (аналог процедур) с параметрами и возвращаемым значением. Типы параметров берутся из пакетов XDTO — это описание XML-схемы, по которой платформа проверяет и разбирает данные.

Что получает разработчик «бесплатно»:

• 📄 WSDL генерируется автоматически. После публикации описание доступно по адресу вида http://server/base/ws/имя.1cws?wsdl. Клиент на любом языке строит по нему заготовку кода.
• ✅ Проверка типов. Если клиент прислал строку там, где ждут число, ошибка случится ещё на этапе разбора конверта, до вашего кода.
• 🔁 Готовый клиент в самой 1С. Объект WS-ссылки импортирует чужой WSDL, а в коде вызов выглядит как вызов метода объекта.
• ⚠️ Ошибки в виде SOAP Fault. Исключение, вызванное в операции через ВызватьИсключение, клиент получает в стандартном формате Fault.

Цена этой строгости — конверт. Даже ответ «true» обёрнут в Envelope, Body и пространства имён. Любое изменение сигнатуры операции меняет WSDL, и клиентов приходится перегенерировать.

Пример вызова чужого SOAP-сервиса из 1С без WS-ссылки, через динамическое определение:

Определения = Новый WSОпределения("https://partner.example/service?wsdl", "user", "pass");
Прокси = Определения.СоздатьПрокси("http://partner.example/ns", "OrderService", "OrderServiceSoap");
Результат = Прокси.GetOrderStatus("A-1025");

Три последних параметра — пространство имён, имя сервиса и имя точки подключения. Их берут из самого WSDL: атрибут targetNamespace, элементы service и port.

Чем отличаются HTTP-сервисы и в чём их плюсы

HTTP-сервисы появились в платформе 8.3.5. Это объект Общие → HTTP-сервисы со своей иерархией:

1. Корневой URL — часть адреса, например api.
2. Шаблоны URL — путь ресурса с параметрами в фигурных скобках: /orders/{number}.
3. Методы — для каждого шаблона свой обработчик на GET, POST, PUT, DELETE и других HTTP-методах.

Опубликованный сервис отвечает по адресу http://server/base/hs/api/orders/A-1025. Обработчик получает объект HTTPСервисЗапрос и обязан вернуть HTTPСервисОтвет:

Функция OrdersGET(Запрос)

    Номер = Запрос.ПараметрыURL["number"];

    Данные = Новый Структура("number, status", Номер, "shipped");
    Запись = Новый ЗаписьJSON;
    Запись.УстановитьСтроку();
    ЗаписатьJSON(Запись, Данные);
    ТекстОтвета = Запись.Закрыть();

    Ответ = Новый HTTPСервисОтвет(200);
    Ответ.Заголовки.Вставить("Content-Type", "application/json; charset=utf-8");
    Ответ.УстановитьТелоИзСтроки(ТекстОтвета, КодировкаТекста.UTF8);
    Возврат Ответ;

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

Сильные стороны HTTP-сервиса:

• 🪶 Лёгкий трафик. JSON без конверта и пространств имён, тело можно сжать на веб-сервере.
• 🌐 Любой клиент. Браузерный fetch, curl, Postman, мобильное приложение — никаких генераторов кода не нужно.
• 🧩 Полный контроль. Вы сами ставите код ответа (200, 201, 400, 404, 409), заголовки, кэширование, отдаёте файлы и картинки как двоичные данные.
• 🔄 Свободная эволюция. Новое поле в JSON старые клиенты просто проигнорируют. Версию API можно вынести в шаблон: /v1/orders, /v2/orders.

Обратная сторона: контракта никто не проверяет. Валидацию входящих данных, разбор параметров запроса (Запрос.ПараметрыЗапроса) и формат ошибок пишет разработчик.

Сравнение Web и HTTP сервисов по ключевым параметрам

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

Производительность и накладные расходы: что реально тормозит

На простом методе разница в скорости между SOAP и REST в 1С заметна, но редко решает. Основные затраты — не в протоколе, а вокруг него.

Что добавляет SOAP:

• сериализация и разбор XML через XDTO — на больших пакетах (тысячи строк) это ощутимо по процессору и памяти;
• размер конверта: в обмене справочниками XML бывает в разы тяжелее аналогичного JSON;
• проверка по схеме при каждом вызове.

Что тормозит оба типа одинаково:

• 🐢 Старт сеанса на каждый вызов. Аутентификация, инициализация параметров сеанса, модуль сеанса — всё это выполняется при каждом новом сеансе. Если в модуле сеанса (УстановкаПараметровСеанса) тяжёлые запросы, каждый вызов API будет медленным.
• 🐢 Тяжёлый код обработчика. Запрос без индекса или чтение объекта целиком там, где хватило бы одного поля.
• 🐢 Синхронная длинная операция. Клиент ждёт, веб-сервер держит соединение, срабатывает таймаут.

Повторное использование сеансов снимает первый пункт. Режим задаётся при публикации и хранится в файле default.vrd атрибутом reuseSessions у конкретного сервиса. Значения:

Рядом задают sessionMaxAge (время жизни сеанса в пуле, секунды) и poolSize (размер пула). Для потока мелких запросов от сайта autouse обычно даёт самый заметный прирост.

Когда выбрать SOAP, а когда REST: сценарии

Несколько типовых ситуаций подробнее:

• 🏦 Банк, страховая, госинформсистема. Они почти всегда публикуют WSDL и требуют SOAP, часто с подписью сообщений. Выбора нет.
• 🛒 Сайт и 1С. Каталог, цены, остатки, заказы. REST и JSON — стандарт для веб-разработчиков. Дайте им /v1/products, /v1/stock, /v1/orders.
• 📱 Мобильное приложение торгового агента. Короткие частые запросы, слабый мобильный канал — лёгкий JSON и повторное использование сеансов.
• 🔗 Интеграционная шина. Если шина умеет оба протокола, решают договорённости. SOAP удобен там, где важна формальная схема и версии контракта согласуются документом.

Совмещать можно: один и тот же модуль с бизнес-логикой (общий модуль) вызывается и из операции Web-сервиса, и из метода HTTP-сервиса. Транспорт отдельно, логика отдельно.

Отладка и документирование сервисов

Отладка в Конфигураторе

Остановиться на точке останова внутри обработчика можно в обоих типах сервисов. Порядок:

1. Включите в Конфигураторе отладку по протоколу HTTP: Сервис → Параметры → Отладка.
2. При публикации на веб-сервере включите в публикации отладку — в default.vrd появится элемент debug с адресом сервера отладки.
3. В меню Отладка → Подключение откройте настройку автоматического подключения и отметьте «Web-сервис» и «HTTP-сервис».
4. Поставьте точку останова и вызовите сервис из Postman или curl.

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

Чем тестировать

• SoapUI — загружает WSDL и сам строит запросы ко всем операциям Web-сервиса.
• Postman, Insomnia, curl — для HTTP-сервисов. Простейшая проверка:

curl -u api_user:password -H "Accept: application/json" \
  "http://server/base/hs/api/orders/A-1025"

• Журнал регистрации — записывайте в него входящие параметры и ошибки через ЗаписьЖурналаРегистрации с отдельным событием, например «API.Заказы». Иначе после сбоя у партнёра вы не докажете, что именно пришло.

Документация

У Web-сервиса документация — это WSDL плюс короткое описание смысла операций. У HTTP-сервиса автоматического описания нет. Практика: вести файл в формате OpenAPI (Swagger) и показывать его внешним разработчикам. Без этого каждый новый подрядчик будет выяснять поля методом проб.

Минимум, который должен быть в описании REST-API 1С: адреса и методы, обязательные поля, пример запроса и ответа, перечень кодов ошибок и формат тела ошибки.

Публикация и внедрение: практические рекомендации

Оба типа сервисов публикуются одной процедурой: Администрирование → Публикация на веб-сервере в Конфигураторе. Нужен установленный веб-сервер (IIS или Apache) и модуль расширения веб-сервера из дистрибутива платформы той же версии, что и сервер 1С. В окне публикации на вкладках отмечают, какие Web-сервисы и HTTP-сервисы выставить наружу.

Рекомендации, которые сэкономят время после запуска:

1. Отдельный пользователь для API. Создайте пользователя информационной базы с ролью, где разрешено только нужное. Не публикуйте сервис под администратором.
2. Только HTTPS снаружи. Basic-аутентификация передаёт логин и пароль в каждом запросе; без шифрования их видно в канале.
3. Версия в адресе. /v1/ в шаблоне URL или отдельный Web-сервис OrdersV2 — и старые клиенты не ломаются при изменениях.
4. Единый формат ошибки. Для REST — JSON вида {"error": "код", "message": "текст"} и честный код HTTP. Не отдавайте 200 с текстом «Ошибка» внутри.
5. Идемпотентность записи. Если клиент повторил POST после таймаута, заказ не должен задвоиться. Принимайте внешний идентификатор и проверяйте, нет ли уже такого документа.
6. Ограничение объёма. Списки отдавайте страницами (?offset=0&limit=100), а не целиком.
7. Повторное использование сеансов — для частых коротких запросов, как описано выше.

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