Как устроено описание веб-сервиса 1С и что с ним делать

WSDL файл в 1С — это XML-описание веб-сервиса: какие операции он умеет, какие параметры принимает, что возвращает и по какому адресу его вызывать. Платформа 1С 8.3 строит его сама из объекта конфигурации «Web-сервис», а получить его можно по адресу публикации с добавкой ?wsdl, например http://srv/buh/ws/exchange.1cws?wsdl.

Типичная ситуация: интегратор маркетплейса или складской системы пишет «пришлите WSDL», а в базе есть только веб-сервис в конфигураторе. Файл отдельно хранить не нужно — он появляется в момент публикации. Ниже разобрано, из чего он состоит, как его получить, когда его правят руками и как отлаживать вызовы.

Зачем нужен WSDL и откуда он берётся в 1С

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

В 1С есть две роли, и в каждой WSDL работает по-своему:

• 📤 1С — сервер. Вы создаёте веб-сервис в ветке Общие → Web-сервисы, публикуете базу, и платформа отдаёт WSDL по запросу. Руками его не пишут.
• 📥 1С — клиент. Вы получаете чужой WSDL (банк, ФНС-сервис, сайт, другая база 1С) и вызываете его операции из встроенного языка через объекты WSОпределения и WSПрокси.

Структура WSDL файла: что значит каждый тег

Описание от 1С — это документ WSDL 1.1. Корневой элемент definitions, внутри пять крупных блоков. Порядок у них всегда один.

Укороченный пример того, что увидите в браузере для сервиса Exchange с одной операцией GetStock:

<definitions xmlns="http://schemas.xmlsoap.org/wsdl/"
             xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
             xmlns:tns="http://example.org/exchange"
             targetNamespace="http://example.org/exchange" name="Exchange">
  <types>
    <xs:schema targetNamespace="http://example.org/exchange"
               elementFormDefault="qualified">
      <xs:element name="GetStock">
        <xs:complexType><xs:sequence>
          <xs:element name="Article" type="xs:string"/>
        </xs:sequence></xs:complexType>
      </xs:element>
      <xs:element name="GetStockResponse">
        <xs:complexType><xs:sequence>
          <xs:element name="return" type="xs:decimal"/>
        </xs:sequence></xs:complexType>
      </xs:element>
    </xs:schema>
  </types>
  <message name="GetStockRequestMessage">
    <part name="parameters" element="tns:GetStock"/>
  </message>
  <message name="GetStockResponseMessage">
    <part name="parameters" element="tns:GetStockResponse"/>
  </message>
  <portType name="ExchangePortType">
    <operation name="GetStock">
      <input message="tns:GetStockRequestMessage"/>
      <output message="tns:GetStockResponseMessage"/>
    </operation>
  </portType>
  <!-- binding ExchangeSoapBinding и ExchangeSoap12Binding -->
  <service name="Exchange">
    <port name="ExchangeSoap" binding="tns:ExchangeSoapBinding">
      <soap:address location="http://srv/buh/ws/exchange.1cws"/>
    </port>
  </service>
</definitions>

Что важно в этом тексте

• 🏷️ targetNamespace — это свойство «URI пространства имён» веб-сервиса. Клиенту оно нужно точно, до символа. Поменяли его в конфигураторе — все внешние клиенты придётся перегенерировать.
• 🔁 Две точки подключения (...Soap и ...Soap12) — одна и та же логика по двум версиям протокола. Внешней системе обычно годится любая.
• 📍 location подставляется из адреса запроса. Если WSDL открыли как http://localhost/..., в описании будет localhost, и партнёр получит нерабочий адрес.

Публикация веб-сервиса и получение WSDL из 1С

Сначала нужен сам веб-сервис в конфигурации, потом публикация на веб-сервере (Apache или IIS) с установленными модулями расширения веб-сервера из дистрибутива платформы.

Шаг 1. Создайте веб-сервис

1. В конфигураторе откройте ветку Общие → Web-сервисы и добавьте объект.
2. Заполните «URI пространства имён» — уникальная строка вида http://company.ru/exchange. Это не адрес сайта, а идентификатор, его никто не открывает.
3. В свойстве «Пакеты XDTO» укажите пакеты с вашими типами (если операции работают только с xs:string, xs:decimal и подобными, хватит стандартного пространства XML-схемы).
4. Проверьте «Имя файла публикации» — по умолчанию оно вида exchange.1cws.
5. Добавьте операции. У каждой задайте тип возвращаемого значения, имя процедуры в модуле и параметры с типом и направлением.
6. Откройте модуль веб-сервиса и напишите функцию для каждой операции.

Шаг 2. Опубликуйте базу

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

Шаг 3. Откройте описание

Адрес собирается так: http://<сервер>/<имя публикации>/ws/<имя файла публикации>?wsdl. Для примера выше — http://srv/buh/ws/exchange.1cws?wsdl. В актуальных версиях платформы сервис доступен и по его имени: .../ws/Exchange?wsdl.

Браузер спросит логин и пароль — это пользователь информационной базы. Ему нужна роль с правом «Использование» на этот веб-сервис. Чтобы отдать файл партнёру, сохраните страницу как .xml или .wsdl.

Типы данных и сериализация: как 1С превращает значения в XML

Всё, что идёт в WSDL, — XML-типы. Платформа сама переводит значения встроенного языка в XML и обратно. Связка простая:

Как передавать сложные данные

Для структуры «документ с табличной частью» создайте пакет XDTO в ветке Общие → XDTO-пакеты. Опишите тип объекта с нужными свойствами и вложенный тип для строк, у которого «Максимальное количество» больше 1 или -1 (без ограничения). В операции укажите этот тип — и он попадёт в блок types.

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

ТипСтроки = ФабрикаXDTO.Тип("http://company.ru/exchange", "StockRow");
Строка = ФабрикаXDTO.Создать(ТипСтроки);
Строка.Article = "A-100";
Строка.Quantity = 12;

Если у операции или свойства включено «Возможно пустое значение», в схеме появится nillable="true". Без этого флага ответ с Неопределено клиент примет за ошибку.

WSDL на стороне клиента: WS-ссылки и WSОпределения

Когда 1С сама вызывает чужой сервис, WSDL подключают одним из двух способов.

Динамический вызов к сервису из примера:

Определения = Новый WSОпределения("http://srv/buh/ws/exchange.1cws?wsdl", "Обмен", "Пароль");
Прокси = Новый WSПрокси(Определения, "http://example.org/exchange", "Exchange", "ExchangeSoap");
Прокси.Пользователь = "Обмен";
Прокси.Пароль = "Пароль";
Остаток = Прокси.GetStock("A-100");

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

Первым параметром WSОпределения можно передать путь к локальному файлу, например C:\Exchange\exchange.wsdl. Это и есть путь к ручной правке.

Ручная правка и расширение описания

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

Правка копии файла оправдана в четырёх случаях:

1. 📍 Неверный адрес в location. Сервис стоит за обратным прокси или NAT, и в описании внутренний адрес. Замените значение soap:address на внешний URL и отдайте исправленный файл партнёру.
2. 🧩 Внешние схемы через xs:import. Чужой WSDL ссылается на отдельные .xsd по schemaLocation, а сервер с ними недоступен. Скачайте схемы рядом и пропишите локальные пути или вставьте их содержимое в types.
3. ✂️ Лишние точки подключения. Описание содержит десятки сервисов, а нужен один. Удалите ненужные service и связанные binding — импорт в WS-ссылку пройдёт быстрее.
4. 🔐 Сервис отдаёт WSDL только после авторизации, которую не поддерживает ваш клиент. Сохраните описание один раз вручную и подключайте из файла.

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

Отладка и проверка WSDL описания

Проверку проводят в три слоя: доступность описания, корректность схемы, логика операции.

Слой 1. Открывается ли описание

Откройте адрес с ?wsdl в браузере на той машине, откуда будет обращаться клиент. Так сразу видно, что мешает: DNS, файрвол, авторизация или публикация.

Слой 2. Валидна ли схема

Загрузите WSDL в SoapUI (New SOAP Project, поле Initial WSDL). Программа разберёт описание, построит шаблоны запросов для каждой операции и покажет ошибки схемы. Отправьте тестовый запрос с заполненными полями — это лучший способ проверить сериализацию до того, как подключится интегратор.

Для быстрой проверки XML-синтаксиса подойдёт xmllint:

xmllint --noout exchange.wsdl

Слой 3. Что происходит внутри операции

Отладка модуля веб-сервиса включается в публикации: в файле default.vrd в каталоге публикации добавляют элемент debug с адресом сервера отладки. Затем в конфигураторе подключают отладчик к предмету «Web-сервис» и ставят точку останова в функции операции. Запрос из SoapUI остановится на ней.

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