Как эффективно использовать веб-сервис 1С:Контрагент для поиска данных по ИНН: разбор WSПрокси, XDTO и пространств имен?

← На главную

При интеграции с различными внешними системами, в том числе с государственными реестрами и базами данных контрагентов, разработчики 1С часто сталкиваются с необходимостью работы с веб-сервисами. Сервис «1С:Контрагент» предоставляет удобный программный интерфейс для получения актуальных сведений о юридических лицах и индивидуальных предпринимателях по их идентификационному номеру налогоплательщика (ИНН). Давайте подробно рассмотрим, как правильно настроить взаимодействие с этим сервисом, понять его внутреннюю логику и эффективно использовать для решения своих задач.

Шаг 1: Инициализация WSПрокси и создание объектов XDTO

Первым шагом при работе с любым веб-сервисом в 1С является создание его программного представления, или, как его еще называют, «прокси-объекта». Этот объект позволяет нам обращаться к методам удаленного сервиса так, будто они являются обычными функциями нашей программы. Для создания прокси-объекта мы используем функцию ПроксиСервиса:

Прокси = ПроксиСервиса(ОписаниеОшибки);

Здесь ОписаниеОшибки – это переменная, в которую будет записана информация о возможных проблемах при создании прокси. После успешного создания объекта Прокси мы получаем доступ к его свойствам и методам, которые соответствуют операциям веб-сервиса и его структуре данных.

Одним из ключевых инструментов для работы с данными веб-сервисов в 1С является фабрика XDTO (XML Data Transfer Object). Эта фабрика позволяет нам программно создавать объекты, соответствующие типам данных, описанным в WSDL-схеме веб-сервиса. Когда мы видим строку:


ВходныеПараметры = Прокси.ФабрикаXDTO.Создать(Прокси.ФабрикаXDTO.Тип("findCorporationByInn"));

Мы выполняем две важные операции:

Прокси.ФабрикаXDTO.Тип("findCorporationByInn"): На этом этапе мы получаем описание типа данных, который соответствует входным параметрам операции веб-сервиса с именем findCorporationByInn. Это имя операции, которая предположительно используется для поиска данных юридического лица. Фабрика XDTO ищет в описании сервиса (WSDL) соответствующий тип, который описывает структуру входных данных для этой операции.
Прокси.ФабрикаXDTO.Создать(...): После получения описания типа, мы используем метод Создать фабрики XDTO, чтобы создать конкретный объект XDTO, соответствующий этому типу. Этот объект ВходныеПараметры затем будет использоваться для передачи данных в веб-сервис. Мы устанавливаем необходимые параметры поиска, такие как ИНН, в свойства этого XDTO-объекта.

Таким образом, мы не просто создаем фабрику XDTO "на основании типа", а создаем объект XDTO определенного типа, используя фабрику, которая знает, как эти типы данных структурированы согласно WSDL веб-сервиса. Именно в этот созданный объект мы потом помещаем все необходимые для запроса данные.

Шаг 2: Работа с пространствами имен в веб-сервисах 1С

Пространства имен (namespaces) являются фундаментальным концептом в мире XML и веб-сервисов. Они служат для уникальной идентификации элементов и атрибутов в XML-документах и WSDL-схемах, предотвращая конфликты имен, когда используются определения из разных источников. Представьте, что у вас есть два разных сервиса, и в каждом из них есть "Параметр". Без пространств имен было бы непонятно, какой именно "Параметр" вы имеете в виду. Пространство имен, часто выглядящее как URL (например, "http://www.example.com/services/myservice/types"), является уникальным идентификатором, а не ссылкой на реальный веб-ресурс.

В вашем коде мы видим, что для основной операции findCorporationByInn, тип данных, вероятно, находится в основном пространстве имен веб-сервиса "1С:Контрагент". Однако для дополнительных параметров используется другой подход:


ВходныеПараметры.additionalParameters = ДополнительныеПараметрыВызоваОперацииСервиса(Прокси.ФабрикаXDTO, "URIПространстваИмен");

Здесь URIПространстваИмен передается как отдельный аргумент функции ДополнительныеПараметрыВызоваОперацииСервиса. Это может указывать на то, что типы AdditionalParameters и AdditionalParameter (которые создаются внутри этой функции) определены в отдельном, возможно, общем или вспомогательном пространстве имен. Такая практика является распространенной: основные операции и их специфические типы данных могут находиться в одном пространстве имен, тогда как общие, повторно используемые структуры (например, для передачи служебной информации, ошибок или, как здесь, дополнительных параметров) могут быть вынесены в другое, стандартизированное пространство имен.

Давайте подробно рассмотрим, как функция ДополнительныеПараметрыВызоваОперацииСервиса работает с пространствами имен и создает эти параметры:


Функция ДополнительныеПараметрыВызоваОперацииСервиса(ФабрикаXDTOСервиса, URIПространстваИмен)
    ИмяКонфигурации = Метаданные.Имя;
    // Получаем описание типа для контейнера дополнительных параметров
    ТипДополнительныеПараметрыXDTO = ФабрикаXDTOСервиса.Тип(URIПространстваИмен, "AdditionalParameters");
    // Получаем описание типа для одиночного дополнительного параметра
    ТипДополнительныйПараметрXDTO = ФабрикаXDTOСервиса.Тип(URIПространстваИмен, "AdditionalParameter");
    
    // Создаем объект-контейнер для всех дополнительных параметров
    Результат = ФабрикаXDTOСервиса.Создать(ТипДополнительныеПараметрыXDTO);
    
    // Создаем первый дополнительный параметр: ИмяКонфигурации
    ДополнительныйПараметрXDTO = ФабрикаXDTOСервиса.Создать(ТипДополнительныйПараметрXDTO);
    ДополнительныйПараметрXDTO.name = "ConfigurationName";
    ДополнительныйПараметрXDTO.value = ИмяКонфигурации; // Передаем имя текущей конфигурации 1С
    Результат.Parameter.Добавить(ДополнительныйПараметрXDTO);
    
    // Создаем второй дополнительный параметр: SupportsCustomAddressElements
    ДополнительныйПараметрXDTO = ФабрикаXDTOСервиса.Создать(ТипДополнительныйПараметрXDTO);
    ДополнительныйПараметрXDTO.name = "SupportsCustomAddressElements";
    ДополнительныйПараметрXDTO.value = "true"; // Устанавливаем значение "true"
    Результат.Parameter.Добавить(ДополнительныйПараметрXDTO);
    
    Возврат Результат;
КонецФункции

Из этого кода становится очевидно, что и "контейнер" AdditionalParameters, и сами "параметры" AdditionalParameter принадлежат одному и тому же пространству имен, URI которого передается в функцию. Это демонстрирует гибкость и модульность использования пространств имен в веб-сервисах.

Шаг 3: Назначение дополнительного параметра SupportsCustomAddressElements

Параметр SupportsCustomAddressElements, устанавливаемый в "true", является важным аспектом при работе с адресными данными через сервис "1С:Контрагент". Этот параметр, по всей видимости, сигнализирует веб-сервису о том, что клиентская система (ваша конфигурация 1С) поддерживает работу с расширенными или кастомными элементами адресов, которые могут быть предоставлены сервисом. В контексте 1С и сервиса "1С:Контрагент" это напрямую связано с Федеральной информационной адресной системой (ФИАС).

Интеграция с ФИАС: Сервис "1С:Контрагент" активно использует данные ФИАС для предоставления актуальной и точной информации об адресах. Это позволяет избежать ручной загрузки и обновления адресных классификаторов в каждую конфигурацию 1С.
Проверка и нормализация адресов: При установке SupportsCustomAddressElements в "true", сервис может предложить более глубокую проверку и нормализацию вводимых адресов, а также возвращать адресные элементы в соответствии со структурой ФИАС. Это особенно важно для обеспечения корректности адресных данных, что влияет на документооборот, отчетность и взаимодействие с государственными органами.
Расширенные возможности: Данный параметр, вероятно, активирует или подтверждает для сервиса готовность клиента к обработке таких адресных элементов, которые могут быть более детализированными или специфичными, чем стандартный набор полей "город", "улица", "дом". Это может включать идентификаторы ФИАС, коды ОКАТО/ОКТМО для адресных объектов и другие подробности, которые позволяют более точно локализовать адрес.

Кратко говоря, установка SupportsCustomAddressElements в "true" помогает получить от сервиса более полную и структурированную информацию об адресах, соответствующую стандартам ФИАС, и обеспечивает поддержку расширенных возможностей по работе с адресными данными.

Шаг 4: Получение реквизитов юридического лица (ЮЛ) и индивидуального предпринимателя (ИП)

Сервис "1С:Контрагент" предоставляет отдельные операции для получения данных о юридических лицах и индивидуальных предпринимателях, поскольку структура их реквизитов существенно различается. Мы должны использовать соответствующий метод веб-сервиса в зависимости от того, кого мы ищем.

Поиск юридического лица:
Для поиска данных о юридическом лице используется операция, схожая с findCorporationByInn (или аналогичная по смыслу). После выполнения запроса к сервису, ответ будет содержать объект, в котором мы ожидаем найти реквизиты юридического лица. Как правило, это свойство имеет имя РеквизитыЮрЛица или аналогичное:
```
Ответ = Прокси.findCorporationByInn(ВходныеПараметры);
ОбъектXDTO = Ответ.РеквизитыЮрЛица;
```
Объект РеквизитыЮрЛица будет содержать такие поля, как:
- Основной государственный регистрационный номер юридического лица (ОГРН)
- ИНН юридического лица
- КПП юридического лица
- Наименование, адрес, руководитель и другие актуальные сведения.
Эти данные соответствуют актуальным сведениям из ЕГРЮЛ.
Поиск индивидуального предпринимателя:
Для индивидуальных предпринимателей существует отдельная операция, например, findEntrepreneurByInn (как упоминается в сообщениях). Важно отметить, что для работы с ИП может потребоваться использование специфического имени сервиса и точки подключения, как указано в сообщении: ИмяСервиса = EntrWsImplService, точкаПодключения = EntrWsImplPort. Это означает, что для ИП может использоваться отдельный WSDL-файл или секция WSDL, описывающая операции именно для ИП.

После вызова операции для ИП, ответ сервиса также будет содержать объект с реквизитами. В данном случае мы ожидаем свойство РеквизитыИП:
```
Ответ = Прокси.findEntrepreneurByInn(ВходныеПараметры);
ОбъектXDTO = Ответ.РеквизитыИП;
```
Объект РеквизитыИП будет включать следующие поля:
- Основной государственный регистрационный номер индивидуального предпринимателя (ОГРНИП)
- Дата присвоения ОГРНИП
- ИНН физического лица (сам ИНН индивидуального предпринимателя)
- Код вида предпринимательства (например, 1 – индивидуальный предприниматель; 2 – глава крестьянского фермерского хозяйства)
- Наименование вида предпринимательства (например, "индивидуальный предприниматель")
- Другие сведения, относящиеся к ИП.
Эти данные соответствуют актуальным сведениям из ЕГРИП.

Важно всегда обращаться к WSDL-описанию конкретного веб-сервиса, чтобы точно знать названия операций, типы входных и выходных параметров, а также структуру возвращаемых данных. Использование правильных имен свойств (например, РеквизитыЮрЛица или РеквизитыИП) является критичным для успешного получения и обработки информации.

Шаг 5: Анализ функций и атрибутов веб-сервиса (WSDL-описание)

Для глубокого анализа функциональности и структуры данных веб-сервиса "1С:Контрагент" (или любого другого веб-сервиса), основным и наиболее надежным источником информации является его WSDL-описание (Web Services Description Language). WSDL-файл представляет собой XML-документ, который формально, в машиночитаемом виде, описывает веб-сервис. Он содержит всю необходимую информацию для взаимодействия с сервисом, включая:

Операции (operations): Список доступных методов веб-сервиса (например, findCorporationByInn, findEntrepreneurByInn).
Входные и выходные сообщения (input/output messages): Описание структур данных, которые должны быть переданы в качестве параметров и которые будут возвращены сервисом.
Типы данных (types): Определение всех сложных типов данных (структур, объектов), используемых в сообщениях сервиса. Эти типы описываются с использованием XML Schema Definition (XSD).
Местоположение сервиса (endpoint): URL, по которому доступен веб-сервис.

Как анализировать WSDL:

Чтение WSDL-файла: Мы можем открыть WSDL-файл в любом текстовом редакторе или браузере, чтобы изучить его структуру. Хотя он может быть сложным для ручного анализа, понимание основных секций (<types>, <message>, <portType>, <binding>, <service>) поможет ориентироваться.
Использование 1С и XDTO: В 1С механизм XDTO создан специально для работы с WSDL. После того как мы создаем WSПрокси, мы можем программно исследовать его структуру:
- Прокси.ФабрикаXDTO: Через фабрику мы можем получать описания типов данных, которые представлены в WSDL. Например, Прокси.ФабрикаXDTO.Типы содержит коллекцию всех известных типов.
- Изучение свойств типа: Если мы получили описание типа (например, ТипДополнительныеПараметрыXDTO), мы можем посмотреть его свойства, такие как ТипДополнительныеПараметрыXDTO.Свойства. Это покажет нам, какие атрибуты и элементы входят в этот тип и каков их собственный тип.
- Метаданные WSПрокси: Сам объект WSПрокси часто предоставляет методы или свойства для доступа к его метаданным, которые являются интерпретацией WSDL 1С.
Онлайн-валидаторы и анализаторы WSDL: Существуют веб-инструменты и программы, которые могут парсить WSDL-файлы и представлять их в более удобном для чтения виде, например, в виде дерева операций и типов данных. Это может значительно упростить анализ сложной схемы.

Для сервиса "1С:Контрагент" WSDL-описание обычно доступно по адресу, например, https://api.orgregister.1c.ru/orgregister/v7?wsdl. Изучение этого файла позволит нам точно определить имена операций, необходимые входные параметры и ожидаемую структуру возвращаемых данных, например, наличие свойств РеквизитыЮрЛица или РеквизитыИП, и их внутренний состав.

Шаг 6: Получение файлов выписок или устава

Важно понимать разницу между получением структурированных данных (реквизитов) и получением целых документов (файлов выписок или уставов). Веб-сервис "1С:Контрагент" в своих основных операциях findCorporationByInn и findEntrepreneurByInn предназначен для предоставления актуальных реквизитов контрагента в структурированном виде (то есть, как набор полей: ИНН, ОГРН, КПП, наименование и т.д.). Эти операции не возвращают файлы документов, таких как выписки из ЕГРЮЛ/ЕГРИП или уставные документы.

Если нам требуется получить юридически значимые файлы выписок из Единого государственного реестра юридических лиц (ЕГРЮЛ) или Единого государственного реестра индивидуальных предпринимателей (ЕГРИП), то для этих целей в экосистеме 1С предусмотрен другой сервис – "1С-Отчетность".

Как получить выписки через "1С-Отчетность":

Сервис "1С-Отчетность" позволяет напрямую отправлять запросы в Федеральную налоговую службу (ФНС) для получения выписок.
Выписки предоставляются в формате PDF и подписываются усиленной квалифицированной электронной подписью ФНС, что придает им полную юридическую силу.
В программе "1С", интегрированной с "1С-Отчетность", обычно имеется специализированный раздел, например, "Отчеты" -> "ЕГРЮЛ" или аналогичный, где мы можем запросить выписку, указав ИНН или ОГРН нужного контрагента.

Таким образом, для получения файлов документов (выписок) мы должны использовать специализированные функции сервиса "1С-Отчетность", а не операции веб-сервиса "1С:Контрагент", который ориентирован на получение текущих реквизитов в формате данных.

В целом, эффективная работа с веб-сервисом "1С:Контрагент" требует понимания механизмов WSПрокси, умения работать с XDTO-фабрикой и осознания роли пространств имен. Детальный анализ WSDL-описания сервиса всегда будет нашим лучшим помощником в освоении его функционала. А для получения файлов юридически значимых документов мы всегда можем обратиться к сервису "1С-Отчетность", который интегрирован в нашу систему 1С.