Вызов внешнего SOAP- и REST-сервиса из кода 1С 8.3

Подключиться к веб-сервису из 1С можно двумя путями. Если у сервиса есть WSDL (это SOAP), создайте WSПрокси — статически через WS-ссылку в Конфигураторе или динамически через Новый WSОпределения(АдресWSDL). Если сервис REST и обменивается JSON, используйте HTTPСоединение и HTTPЗапрос: они есть в платформе 8.3 без всяких внешних компонент.

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

Что выяснить до интеграции и где взять WSDL

Начните не с кода, а с документации сервиса. От неё зависит весь дальнейший путь.

Соберите у владельца сервиса:

• 🌐 Адрес — полный URL точки подключения или адрес WSDL;
• 📄 Протокол — SOAP (есть WSDL, сообщения в XML) или REST (запросы GET/POST, обычно JSON);
• 🔑 Авторизация — логин и пароль (Basic), токен в заголовке, ключ API в параметре адреса или клиентский сертификат;
• 🔒 Защищённость — http или https, нужен ли свой корневой сертификат;
• 🧪 Тестовый контур — отдельный адрес «песочницы», чтобы не слать пробные заказы в бой.

Как получить WSDL

У SOAP-сервиса описание обычно открывается по адресу точки подключения с суффиксом ?wsdl. Если сервис опубликован на другой базе 1С, адрес выглядит так:

http://server/basename/ws/ИмяСервиса?wsdl

Откройте этот адрес в браузере. Если пришёл XML с тегами definitions, types, service — WSDL доступен. Если браузер просит пароль, тот же пароль понадобится и в 1С.

SOAP или REST: что выбрать в 1С

Если сервис отдаёт и WSDL, и REST-API, для новой разработки чаще удобнее REST: меньше слоёв между кодом и данными.

Настраиваем WS-ссылку в Конфигураторе

Статическая WS-ссылка — это объект конфигурации, в котором платформа хранит импортированный WSDL. После неё в коде доступны типы сервиса и подсказки.

Порядок действий:

1. Откройте базу в режиме Конфигуратора и включите возможность изменения конфигурации, если она на поддержке.
2. В дереве метаданных разверните Общие → WS-ссылки.
3. Добавьте новую WS-ссылку. Платформа спросит адрес WSDL — укажите URL или путь к сохранённому файлу.
4. Если сервис закрыт паролем, введите логин и пароль в окне импорта.
5. Задайте понятное имя, например СлужбаДоставки.
6. Сохраните конфигурацию и выполните Обновить конфигурацию базы данных (F7).

После импорта в свойствах WS-ссылки видно пространство имён, имена сервисов, точки подключения и список операций. Эти три строки — URI пространства имён, имя сервиса и имя точки подключения — понадобятся в коде.

Когда сервис меняет WSDL (добавили операцию или поле), статическая ссылка сама не обновится. WSDL нужно импортировать заново и снова обновить конфигурацию базы.

Вызываем сервис через WS-прокси

WS-прокси — это объект, через который 1С вызывает операции SOAP-сервиса как обычные методы. Создать его можно двумя способами.

Из статической WS-ссылки

Прокси = WSСсылки.СлужбаДоставки.СоздатьWSПрокси(
    "http://example.com/delivery",   // URI пространства имён
    "DeliveryService",               // имя сервиса
    "DeliveryServiceSoap");          // имя точки подключения

Прокси.Пользователь = "api_user";
Прокси.Пароль = ПарольИзХранилища;

Результат = Прокси.GetStatus("TRK123456");

Динамически, без изменения конфигурации

Определения = Новый WSОпределения(
    "https://example.com/delivery?wsdl",
    "api_user", ПарольИзХранилища, , 30);

Прокси = Новый WSПрокси(Определения,
    "http://example.com/delivery",
    "DeliveryService",
    "DeliveryServiceSoap", , 30);

Прокси.Пользователь = "api_user";
Прокси.Пароль = ПарольИзХранилища;

Число 30 — таймаут в секундах. Динамический вариант каждый раз читает WSDL по сети, поэтому на частых вызовах создавайте прокси один раз и переиспользуйте его в пределах одной обработки.

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

Если операция принимает не строку, а структуру (например, заказ с адресом), объект создают через фабрику XDTO прокси:

Фабрика = Прокси.ФабрикаXDTO;
ТипЗаказа = Фабрика.Тип("http://example.com/delivery", "Order");
Заказ = Фабрика.Создать(ТипЗаказа);
Заказ.Number = "А-000125";
Заказ.Weight = 2.5;

Ответ = Прокси.CreateOrder(Заказ);

Имена типов и свойств берите ровно из WSDL, с учётом регистра. Ошибка в имени свойства даёт исключение XDTO уже на этапе заполнения объекта.

Отправляем запросы через HTTPЗапрос: JSON и «ручной» SOAP

Для REST-сервисов нужны два объекта. HTTPСоединение описывает сервер, HTTPЗапрос — конкретный адрес ресурса, заголовки и тело.

Соединение с https и таймаутом

SSL = Новый ЗащищенноеСоединениеOpenSSL(, Новый СертификатыУдостоверяющихЦентровОС);

Соединение = Новый HTTPСоединение(
    "api.example.com",   // только имя сервера, без https:// и пути
    443, , , , 30, SSL);

Объект СертификатыУдостоверяющихЦентровОС заставляет платформу проверять сертификат сервера по хранилищу Windows или Linux. Без него на части серверов запрос падает на проверке сертификата.

Сервер указывается без протокола и без пути. Частая ошибка — передать https://api.example.com/v1 целиком: платформа не разберёт такую строку как имя хоста.

GET с токеном в заголовке

Заголовки = Новый Соответствие;
Заголовки.Вставить("Authorization", "Bearer " + Токен);
Заголовки.Вставить("Accept", "application/json");

Запрос = Новый HTTPЗапрос("/v1/orders/TRK123456", Заголовки);
Ответ = Соединение.Получить(Запрос);

POST с телом JSON

Данные = Новый Структура;
Данные.Вставить("number", "А-000125");
Данные.Вставить("weight", 2.5);

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

Заголовки = Новый Соответствие;
Заголовки.Вставить("Content-Type", "application/json; charset=utf-8");
Заголовки.Вставить("Authorization", "Bearer " + Токен);

Запрос = Новый HTTPЗапрос("/v1/orders", Заголовки);
Запрос.УстановитьТелоИзСтроки(ТекстJSON, КодировкаТекста.UTF8,
    ИспользованиеByteOrderMark.НеИспользовать);

Ответ = Соединение.ОтправитьДляОбработки(Запрос);

Отключайте BOM при отправке JSON. Многие сервисы на Node.js и Go не понимают невидимый маркер в начале тела и отвечают 400 Bad Request при внешне правильном JSON.

Для методов PUT, PATCH, DELETE используйте универсальный вызов: Соединение.ВызватьHTTPМетод("PATCH", Запрос).

SOAP без WSDL

Иногда WSDL недоступен, а пример XML-конверта в документации есть. Тогда конверт можно отправить как обычный POST:

Заголовки = Новый Соответствие;
Заголовки.Вставить("Content-Type", "text/xml; charset=utf-8");
Заголовки.Вставить("SOAPAction", """http://example.com/delivery/GetStatus""");

Запрос = Новый HTTPЗапрос("/delivery", Заголовки);
Запрос.УстановитьТелоИзСтроки(ТекстКонверта, КодировкаТекста.UTF8,
    ИспользованиеByteOrderMark.НеИспользовать);
Ответ = Соединение.ОтправитьДляОбработки(Запрос);

Ответ придёт XML-строкой, разбирать её придётся через ЧтениеXML или DOM. Это работает, но при изменении сервиса всю разметку правят вручную.

Разбираем ответ и ошибки соединения

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

Шаблон обработки

Попытка
    Ответ = Соединение.ОтправитьДляОбработки(Запрос);
Исключение
    ЗаписьЖурналаРегистрации("Интеграция.СлужбаДоставки",
        УровеньЖурналаРегистрации.Ошибка, , ,
        ПодробноеПредставлениеОшибки(ИнформацияОбОшибке()));
    Возврат Неопределено;
КонецПопытки;

ТелоОтвета = Ответ.ПолучитьТелоКакСтроку("UTF-8");

Если Ответ.КодСостояния < 200 Или Ответ.КодСостояния > 299 Тогда
    ЗаписьЖурналаРегистрации("Интеграция.СлужбаДоставки",
        УровеньЖурналаРегистрации.Предупреждение, , ,
        СтрШаблон("Код %1: %2", Формат(Ответ.КодСостояния, "ЧГ=0"), ТелоОтвета));
    Возврат Неопределено;
КонецЕсли;

Чтение = Новый ЧтениеJSON;
Чтение.УстановитьСтроку(ТелоОтвета);
Результат = ПрочитатьJSON(Чтение, Истина);   // Истина — вернуть Соответствие
Чтение.Закрыть();

С параметром Истина функция ПрочитатьJSON возвращает Соответствие. Это надёжнее структуры: ключи JSON вроде order-id или 1st не могут быть именами свойств структуры и дадут ошибку.

Что означают частые коды

• 🚫 401 — неверный логин, пароль или токен; проверьте и срок действия токена;
• ⛔ 403 — учётка есть, но прав на этот метод нет;
• ❓ 404 — ошибка в адресе ресурса или объект с таким номером не найден;
• 🐢 429 — превышен лимит запросов, нужна пауза между вызовами;
• 💥 500, 502, 503 — проблема на стороне сервиса, повторите позже.

Ошибки WS-прокси приходят исключением с текстом SOAP Fault. Достаньте его через ПодробноеПредставлениеОшибки и пишите в журнал регистрации целиком: в нём обычно есть код и описание от сервиса.

Безопасность и быстродействие обмена

Рабочая интеграция должна не только работать, но и не мешать пользователям.

Где выполнять вызов

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

Если используется прокси-сервер организации, передайте в соединение объект ИнтернетПрокси с его адресом и портом.

Где хранить пароли и токены

• ❌ Не пишите пароль строкой в модуле: его увидит любой, у кого есть доступ к Конфигуратору или к выгрузке конфигурации.
• ✅ В конфигурациях на БСП (БП 3.0, ЗУП 3.1, УТ 11) есть безопасное хранилище: процедуры ОбщегоНазначения.ЗаписатьДанныеВБезопасноеХранилище и ОбщегоНазначения.ПрочитатьДанныеИзБезопасногоХранилища. Доступ к нему — только в привилегированном режиме на сервере.
• ✅ В собственной конфигурации храните секреты в отдельном регистре сведений, доступ к которому есть только у роли администратора.

Всегда используйте https, если сервис его поддерживает. Basic-авторизация по http передаёт логин и пароль почти открытым текстом.

Чтобы обмен не тормозил работу

• ⏱️ Ставьте таймаут 15–60 секунд. Без него зависший сервис может держать форму пользователя очень долго.
• 🔁 Переиспользуйте соединение. Один объект HTTPСоединение для серии запросов к одному серверу быстрее, чем новое соединение на каждый вызов.
• 📦 Отправляйте пакетами. Если API принимает массив, 100 заказов одним запросом лучше 100 отдельных вызовов.
• 🌙 Выносите массовый обмен в фон. Регламентное задание раз в 10–15 минут или фоновое задание не блокирует пользователя.
• 📝 Логируйте адрес, код ответа и время вызова, но не пароли и не токены.

Как проверить подключение до запуска в работу

Перед тем как дать обмен пользователям, пройдите короткую проверку на тестовом контуре.

Отдельно проверьте поведение при недоступном сервисе: временно укажите неверный адрес. Пользователь должен увидеть понятное сообщение, а документ — сохраниться без сбоя.

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