Дискретные подсказки при вводе компаний по ЕГРЮЛ и ЕГРИП

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

Такой метод ввода весьма удобен, поскольку для уточнения поиска вместе с названием компании можно вводить дополнительную информацию в одно общее поле. Это ускоряет процесс заполнения форм с реквизитами организаций, однако у данного подхода есть один недостаток: при вводе в единое поле только названия компании в подсказки могут попадать организации, у которых введённые слова встречаются не в названиях, а, например, в составе адреса или ФИО руководителя.

Чтобы поменять такое поведение подсказок, можно использовать дискретные подсказки Ахантера, которые позволяют вводить название компании, её адрес и ФИО руководителя в разных полях, получая независимо подсказки при заполнении каждого из них.

Также в данном режиме целесообразно отделить друг от друга ввод данных по ЕГРЮЛ и по ЕГРИП, т.к. состав полей заполняемой формы в этих двух случаях будет отличаться. При заполнении данных о юридическом лице по ЕГРЮЛ есть возможность указать ФИО руководителя компании в отдельном поле, а при заполнении данных об индивидуальном предпринимателе такого поля нет, т.к. ФИО предпринимателя в случае с ИП является одновременно и названием компании.

Как работают дискретные подсказки по компаниям

В данном режиме подсказок для поиска нужной компании на форме требуется выделить три следующих поля:

1. Адрес компании
2. ФИО руководителя компании
3. Название компании

Первые два поля заполняются с помощью стандартных подсказок Ахантера по адресам и по ФИО. Когда пользователь заполнит их и переключится для заполнения третьего поля, вся информация, которую он укажет в нём, будет интерпретироваться как часть названия искомой компании. При этом подсказки, возвращаемые сервисом для данного поля, будут содержать только те компании, адреса которых соответствуют первому полю формы, и руководители которых имеют ФИО, соответствующее информации, указанной во втором поле формы. Кроме того, в третье поле формы можно ввести ОГРН или ИНН, чтобы быстро найти искомую компанию.

Если организуется ввод данных об индивидуальном предпринимателе по ЕГРИП, то поле формы с ФИО руководителя следует скрыть, т.к. у ИП руководителем является сам предприниматель, ФИО которого одновременно является и названием компании. Поэтому для ИП состав полей у формы будет таким:

1. Адрес компании
2. Название компании

Приведенная ниже форма демонстрирует работу данной функции. Для отображения подсказок достаточно начать вводить какие-нибудь сведения об искомой компании.

Здесь для отображения подсказок используется наш JavaScript-модуль ahunter_suggest.js, скачать его можно по следующей ссылке. Модуль использует библиотеку jQuery, поэтому, чтобы запустить подсказки у вас на сайте, в дополнение к ahunter_suggest.js нужно будет установить свежую версию jQuery.

Чтобы всё заработало, мы здесь использовали особую разметку и инициализирующий код для неё. Детальное описание этого кода, а также описание подготовки вашего сайта к использованию подсказок, приводится далее в этой статье.

В большинстве случаев для работы с подсказками бывает достаточно использовать модуль ahunter_suggest.js. Однако если вам нужно встроить подсказки в отдельное приложение, либо если у вас есть своё JavaScript решение, то для получения подсказок от Ахантера нужно будет использовать напрямую его REST API. Соответствующее описание приводится во второй части данной статьи.

Как добавить подсказки по компаниям на веб-сайт

Подготовка сайта для подключения подсказок

Для добавления дискретных подсказок на сайт, как и в случае с обычными подсказками для компаний, необходимо выполнить подготовку сайта. А именно, нужно установить jQuery, установить наш JavaScript-модуль ahunter_suggest.js, а также настроить таблицу стилей, чтобы подсказки отображались красиво.

Все эти процедуры детально описаны по следующей ссылке.

Подключение дискретных подсказок на сайте по ЕГРЮЛ

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

Каждому из этих полей вашей формы должен быть присвоен идентификатор, чтобы по нему наш модуль ahunter_suggest.js смог найти это поле на веб-странице и запустить для него подсказки. HTML-разметка такой формы может выглядеть следующим образом.

<div>
  <input id="js-AddressField1" placeholder="Адрес компании"/>  
  <input id="js-PersonField1" placeholder="ФИО руководителя"/>  
  <input id="js-CompanyField1" placeholder="Компания ..."/> 
</div>

Согласно этой форме, первое поле с идентификатором js-AddressField1 предназначено для адреса компании. В поле с идентификатором js-PersonField1 пользователи будут вводить ФИО руководителя компании. Поле с идентификатором js-CompanyField1 является основным, в него будет вводиться название компании.

Когда пользователь будет заполнять первые два поля, Ахантер будет предлагать стандартные подсказки по адресам и по ФИО. При заполнении третьего поля Ахантер будет возвращать подсказки для компаний, соответствующие всей информации, указанной в трёх полях формы.

Чтобы сообщить Ахантеру, какие именно подсказки он должен предлагать при заполнении этих полей, необходимо выполнить соответствующую инициализацию. Для этого где-нибудь на веб-странице нужно добавить следующий инициализирующий скрипт:

//опции для подсказок по адресу компании
var AddressOptions1 =
{
  fields: [ { id: 'js-AddressField1', 
              levels: ['Region','District','City'] } ] 
};
//будем показывать подсказки только для регионов и городов
AhunterSuggest.Address.Discrete( AddressOptions1 );

//опции для подсказок по ФИО руководителя компании
var PersonOptions1 = 
{
  id: 'js-PersonField1'
};
//запускаем подсказки по ФИО
AhunterSuggest.Person.Solid( PersonOptions1 );

//опции для подсказок по названию компании
var CompanyOptions1 = 
{ 
  id: 'js-CompanyField1', 
  company_address_id: 'js-AddressField1',
  company_person_id: 'js-PersonField1',
  egrul_enable: true,
  egrip_enable: false
};
//запускаем подсказки для компаний
AhunterSuggest.Company.Discrete( CompanyOptions1 );

Инициализация подсказок выполняется в три шага.

1. Сначала для поля с идентификатором js-AddressField1 настраиваются дискретные подсказки для почтовых адресов.

   //опции для подсказок по адресу компании
   var AddressOptions1 =
   {
     fields: [ { id: 'js-AddressField1', 
                 levels: ['Region','District','City'] } ] 
   };
   //будем показывать подсказки только для регионов и городов
   AhunterSuggest.Address.Discrete( AddressOptions1 );

   Здесь используются именно дискретные подсказки, т.к. этот механизм Ахантера позволяет ограничить выдаваемые в подсказках адреса заданным уровнем. В нашем примере, подсказки для адресов будут ограничиваться уровнем города. Поэтому пользователь сможет указать в этом поле регион, район и город, в котором располагается искомая компания. Ахантер позволяет искать адреса компаний в ЕГРЮЛ с детализацией до улицы, однако часто для эффективной фильтрации компаний бывает достаточно ограничиться городом. Подробнее об использовании и настройке дискретных подсказок для почтовых адресов можно посмотреть здесь.
2. Затем инициализируются и запускаются подсказки для второго поля с идентификатором js-PersonField1. Поскольку в этом поле будет указываться ФИО руководителя искомой компании, здесь подключаются подсказки по ФИО.

   //опции для подсказок по ФИО руководителя компании
   var PersonOptions1 = 
   {
     id: 'js-PersonField1'
   };
   //запускаем подсказки по ФИО
   AhunterSuggest.Person.Solid( PersonOptions1 );

   Тут используется типовой инициализирующий код, который просто включает стандартные подсказки Ахантера по ФИО для данного поля. Подробнее об использовании и настройке этих подсказок можно посмотреть здесь.
3. На третьем шаге запускаются сами подсказки для компаний. Они привязываются к полю с идентификатором js-CompanyField1. Тут используется особый инициализирующий код, учитывающий тот факт, что адрес и ФИО руководителя компании вводятся в другие поля.

   //опции для подсказок по названию компании
   var CompanyOptions1 = 
   { 
     id: 'js-CompanyField1', 
     company_address_id: 'js-AddressField1',
     company_person_id: 'js-PersonField1',
     egrul_enable: true,
     egrip_enable: false
   };
   //запускаем подсказки для компаний
   AhunterSuggest.Company.Discrete( CompanyOptions1 );

   Кроме идентификатора поля, куда будет вводиться название компании, здесь в опциях CompanyOptions1 передаются дополнительные параметры company_address_id и company_person_id. С помощью них вы сообщаете нашему модулю идентификаторы полей вашей формы, в которых вводится адрес компании и ФИО её руководителя. Получая от вас эту информацию, Ахантер узнаёт, что данные из этих полей тоже нужно использовать при поиске компаний. Поэтому при формировании подсказок для основного поля js-CompanyField1 сервис будет фильтровать список найденных компаний по адресу и ФИО, которые пользователь указал в первых двух полях формы.

   Также здесь задаются два параметра egrul_enable и egrip_enable, первый устанавливается true, а второй - в false. Таким образом, мы сообщаем сервису, что для данной формы подсказки следует предлагать только для юридических лиц по ЕГРЮЛ, подсказки для индивидуальных предпринимателей при заполнении данной формы предлагаться не будут.

   Кроме этого, в рамках объекта CompanyOptions1 можно передавать любые другие параметры, предусмотренные в обычных подсказках по ЕГРЮЛ, описанные здесь.

Подключение дискретных подсказок по ЕГРИП

Дискретные подсказки по ЕГРИП для ввода индивидуальных предпринимателей настраиваются так же, как это описано выше для ЕГРЮЛ. Единственным отличием является отсутствие поля, куда вводится ФИО руководителя, поскольку для ИП руководителем является сам предприниматель, ФИО которого образует само название компании.

Таким образом, на форме для заполнения реквизитов ИП необходимо выделить не три, а два поля - с адресом регистрации ИП и названием ИП соответственно. Каждому из этих полей вашей формы должен быть присвоен идентификатор, чтобы по нему наш модуль ahunter_suggest.js смог найти это поле на веб-странице и запустить для него подсказки. HTML-разметка такой формы может выглядеть следующим образом.

<div>
  <input id="js-AddressField2" placeholder="Адрес регистрации ИП"/>  
  <input id="js-CompanyField2" placeholder="Название ИП"/> 
</div>

Согласно этой форме, первое поле с идентификатором js-AddressField2 предназначено для адреса регистрации ИП, а поле с идентификатором js-CompanyField2 является основным, в него будет вводиться название ИП.

Когда пользователь будет заполнять первое поле, Ахантер будет предлагать стандартные подсказки по адресам. При заполнении второго поля Ахантер будет возвращать подсказки для ИП, зарегистрированных по адресу, который указан в первом поле формы.

Чтобы сообщить Ахантеру, какие именно подсказки он должен предлагать при заполнении этих полей, необходимо выполнить соответствующую инициализацию. Для этого где-нибудь на веб-странице нужно добавить следующий инициализирующий скрипт:

//опции для подсказок по адресу ИП
var AddressOptions2 =
{
  fields: [ { id: 'js-AddressField2', 
              levels: ['Region','District','City'] } ] 
};
//будем показывать подсказки только для регионов и городов
AhunterSuggest.Address.Discrete( AddressOptions2 );

//опции для подсказок по названию ИП
var CompanyOptions2 = 
{ 
  id: 'js-CompanyField2', 
  company_address_id: 'js-AddressField2',
  egrul_enable: false,
  egrip_enable: true
};
//запускаем подсказки для ИП
AhunterSuggest.Company.Discrete( CompanyOptions2 );

Инициализация подсказок выполняется в два шага.

1. Сначала для поля с идентификатором js-AddressField2 настраиваются дискретные подсказки для почтовых адресов.

   //опции для подсказок по адресу ИП
   var AddressOptions2 =
   {
     fields: [ { id: 'js-AddressField2', 
                 levels: ['Region','District','City'] } ] 
   };
   //будем показывать подсказки только для регионов и городов
   AhunterSuggest.Address.Discrete( AddressOptions2 );

   Здесь используются именно дискретные подсказки, т.к. этот механизм Ахантера позволяет ограничить выдаваемые в подсказках адреса заданным уровнем. В нашем примере, подсказки для адресов будут ограничиваться уровнем города. Поэтому пользователь сможет указать в этом поле регион, район и город, в котором зарегистрирован предприниматель. Это важно, т.к. в ЕГРИП адреса для всех индивидуальных предпринимателей детализированы только до уровня города. Подробнее об использовании и настройке дискретных подсказок для почтовых адресов можно посмотреть здесь.
2. На втором шаге запускаются сами подсказки для ИП. Они привязываются к полю с идентификатором js-CompanyField2. Тут используется особый инициализирующий код, учитывающий тот факт, что адрес регистрации ИП вводится в другое поле.

   //опции для подсказок по названию ИП
   var CompanyOptions2 = 
   { 
     id: 'js-CompanyField2', 
     company_address_id: 'js-AddressField2',
     egrul_enable: false,
     egrip_enable: true
   };
   //запускаем подсказки для компаний
   AhunterSuggest.Company.Discrete( CompanyOptions2 );

   Кроме идентификатора поля, куда будет вводиться название компании, здесь в опциях CompanyOptions2 передаётся дополнительный параметр company_address_id. С помощью него вы сообщаете нашему модулю идентификатор поля вашей формы, в котором вводится адрес регистрации ИП. Получая от вас эту информацию, Ахантер узнаёт, что данные из этого поля тоже нужно использовать при поиске ИП. Поэтому при формировании подсказок для основного поля js-CompanyField2 сервис будет фильтровать список найденных ИП по адресу, который пользователь указал в первом поле формы.

   Также здесь задаются два параметра egrul_enable и egrip_enable, первый устанавливается false, а второй - в true. Таким образом, мы сообщаем сервису, что для данной формы подсказки следует предлагать только для индивидуальных предпринимателей по ЕГРИП, подсказки для юридических лиц при заполнении данной формы предлагаться не будут.

   Дополнительно в рамках объекта CompanyOptions2 можно передавать любые другие параметры, предусмотренные в обычных подсказках по ЕГРИП, описанные здесь.

REST API дискретных подсказок по ЕГРЮЛ и ЕГРИП для компаний

Если вам нужно встроить подсказки для компаний не на веб-сайте, а в ваше приложение, либо если вы по каким-то причинам не можете подключить наш JavaScript-модуль подсказок ahunter_suggest.js, то в этом случае вам следует использовать API-команду suggest/company для получения подсказок напрямую от Ахантера по заданному запросу. Использование данной команды в режиме дискретных подсказок несколько отличается от стандартного режима, изложенного здесь.

Принципы использования API подсказок по ЕГРЮЛ при дискретном вводе

Дискретный режим команды suggest/company подразумевает, что информация об адресе и ФИО руководителя компании может вводиться отдельно от её названия. Заполнение поля с адресом компании и ФИО руководителя можно организовать с помощью команд Ахантера suggest/address и suggest/person соответственно. Поэтому при отправке запросов suggest/company в дискретном режиме полагается, что в настоящий момент заполняется поле с названием компании. Всякий раз, когда пользователь вводит очередной символ в это поле, увеличивается количество информации, на основе которой Ахантер может предложить новые, более точные, подсказки. При этом информация об адресе и ФИО руководителя компании, уже введённая в других полях, тоже должна учитываться.

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

Для реализации такого сценария ваше приложение должно отслеживать события, возникающие, когда происходят изменения в поле с названием компании. При возникновении такого события приложение должно отсылать текст, введенный к настоящему моменту во всех полях формы, в виде специально оформленного запроса сервису.

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

После того, как пользователь выбрал подходящую подсказку, ваше приложение может запросить у Ахантера полную информацию об этом юридическом лице: сведения о регистрации в ФНС, ПФР и ФСС, коды ОКВЭД, информацию о лицензиях компании, сведения о ликвидации, структуре уставного капитала, учредителях и руководителях. Для этого каждая подсказка снабжается уникальным идентификатором-сигнатурой sign. Когда пользователь вашего приложения выбирает подсказку, ваше приложение может брать соответствующую ей сигнатуру и отсылать её с помощью команды fetch/company. В качестве ответа сервис вернёт полный описатель со всей информацией о компании, извлечённой из ЕГРЮЛ.

Принципы использования API подсказок по ЕГРИП при дискретном вводе

Для организации дискретного ввода реквизитов индивидуальных предпринимателей по ЕГРИП следует руководствоваться принципами, изложенными выше для получения подсказок по ЕГРЮЛ. Разница заключается лишь в том, что форма ввода для ИП не должна содержать отдельного поля с ФИО руководителя, т.к. руководителем ИП является сам предприниматель, ФИО которого одновременно является и названием компании.

Подготовка запроса для получения дискретных подсказок

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

• Для адреса компании следует использовать тэг a,
• Для ФИО руководителя - тэг p,
• Для названия компании - тэг n.

Следующий пример формы демонстрирует, формирование такого запроса.

Здесь в первом поле вводится адрес компании, во втором поле - ФИО руководителя, а в третьем - название компании. Если объединить все фрагменты запроса этой формы в одну общую строку, то получим следующий запрос.

a[обл Омская, г Омск]p[Иванов]n[ООО Тех]

Именно в таком виде он и должен быть отправлен Ахантеру, чтобы получить подсказки для последнего поля формы, куда пользователь вводит название.

При получении такого запроса в режиме поиска подсказок только по ЕГРИП компонент запроса p[Иванов] будет игнорироваться сервисом, т.к. в ЕГРИП у индивидуальных предпринимателей нет обособленного поля, в котором отдельно был бы указан руководитель компании. Чтобы реализовать единую форму, с помощью которой можно было бы одновременно заполнять данные по юридическим лицам и индивидуальным предпринимателям, нужно объединить название компании и ФИО руководителя в единое поле. В этом случае следует использовать объединённый тэг np для данного поля. Пример запроса в этом случае будет выглядеть так:

a[обл Омская, г Омск]np[Иванов ООО Тех]

Компоненты запроса, соответствующие адресу и ФИО руководителя могут быть опущены, в этом случае Ахантер не будет выполнять фильтрацию найденных компаний по адресу и ФИО руководителя, а просто будет выполнять поиск компаний по их названию, в соответствии с фрагментом запроса в блоке n[ООО Тех].

Есть ещё одно правило, которое следует учитывать при формировании таких запросов. Символы квадратных скобок являются служебными, поэтому если пользователь введёт их в само поле вашей формы то, перед формированием запроса их следует экранировать обратным слэшем. Аналогично следует поступать с символом самого обратного слэша, в случае, если пользователь ввёл его в каком-то поле вашей формы. Например, если в приведённой выше форме в последнем поле пользователь ввёл ООО \Тех, то соответствующий этому полю фрагмент запроса будет выглядеть так n[ООО \\Тех].

Пример простого запроса

В приведенном ниже примере сервису отсылается запрос дискретных подсказок a[Москва]n[ООО Тех]. Полагается, что пользователь хочет ограничить выдачу компаний теми, которые находятся в Москве. Кроме этого пользователь частично заполнил название компании, введя слова ООО Тех.

В данном запросе используются следующие параметры.

• output=json - сообщает сервису о том, что необходимо вернуть ответ в формате JSON.
• mode=discrete - указывает на то, что запрашиваются дискретные подсказки, а не обычные.
• query=a[Москва]n[ООО Тех] - строка с запросом дискретных подсказок, которая должна быть представлена в кодировке UTF-8 и закодирована с использованием URL-encoding.

Рассмотрим более подробно все параметры, которые сервис может получать в рамках данной команды в режиме выдачи дискретных подсказок.

Параметры команды

Обязательные параметры для выполнения запроса

• http://ahunter.ru/site/suggest/company - URL-команды.
• output=json или output=xml - формат, в котором требуется вернуть результат выполнения команды.
• mode=discrete – включает режим дискретных подсказок, без этого параметра сервис будет пытаться формировать обычные подсказки.
• query=строка запроса – строка, содержащая запрос дискретных подсказок, синтаксис которого описан выше в данной статье. Ваше приложение должно автоматически формировать такой запрос на основе данных, введённых пользователем в полях вашей формы. Данная строка должна быть закодирована с помощью URL-encoding и изначально всегда должна быть представлена в UTF-8.

Опциональные параметры

• output=pretty - опция, требует, чтобы сервис выполнил "красивое" форматирование возвращаемого JSON или XML текста, расставив в нем переносы строк и отступы. Опция может быть полезна при отладке взаимодействия пользовательского приложения с сервисом.
• output=cp1251 - опция применима только в случае использования XML формата ответа сервиса. Данная опция требует, чтобы сервис вернул XML-ответ в кодировке windows-1251.
• companylim=число - лимит на число возвращаемых подсказок. Если данное значение превышает установленный администратором сервиса порог, равный 10 подсказкам, то данное значение будет принудительно уменьшено до этого допустимого порога. Если в запросе данный параметр не указан, то в качестве лимита будет выступать установленное администратором сервиса умолчальное значение, равное 6 подсказкам.
• afilter - строка в формате JSON-массива, содержащая адресный фильтр. Адресный фильтр задаёт перечень адресных объектов (например, городов и населённых пунктов), которым должны принадлежать компании, чтобы попасть в выдачу. Каждый адресный объект фильтра задаётся его АБР-кодом. Такие коды используются в адресной базе Ахантера для уникальной идентификации объектов. Для любого адресного объекта можно узнать его АБР-код, например, здесь, если ввести и обработать его адрес.
• mode=egrul|egrip - опции, позволяющие выбирать в каком именно государственном реестре выполнять поиск подсказок. Можно указать одну или сразу обе опций, разделив их вертикальной чертой. При отсутствии данной опции сервис будет выполнять поиск в обоих государственных реестрах. Опции имеют следующее назначение.
  • mode=egrul - разрешает искать подсказки в ЕГРЮЛ.
  • mode=egrip - разрешает искать подсказки в ЕГРИП.

Пример запроса с дополнительными опциями

Приведенный ниже запрос отсылает сервису на обработку фрагмент информации о компании a[ул Малышева]n[Техн] с дополнительными параметрами.

В данном запросе используются следующие параметры.

• output=json|pretty - сообщает сервису о том, что необходимо вернуть ответ в формате JSON, отформатировав его "красиво".
• mode=discrete|egrul - включает режим дискретных подсказок, без этого параметра сервис будет пытаться формировать обычные подсказки. Также здесь требуется выполнять поиск только по ЕГРЮЛ.
• companylim=3 - сообщает сервису, что следует вернуть только три наиболее подходящие подсказки для вводимой компании.
• query=a[ул Малышева]n[Техн] - запрос дискретных подсказок, требует, чтобы все компании в подсказках находились на улице Малышева, а также, чтобы в их названии встречалось слово Техн.
• afilter=["66c1"] - адресный фильтр, требующий, чтобы в выдачу подсказок в первую очередь попадали компании из Екатеринбурга, т.к. АБР-код этого города - 66c1.

Результат запроса: подсказки для компании в формате JSON

Ответ Ахантера в формате JSON на запрос дискретных подсказок имеет точно такую же структуру и вид, как и ответ в формате JSON на запрос обычных (не дискретных) подсказок. Описание этого ответа можно посмотреть здесь.

Результат запроса: подсказки для компании в формате XML

Также как и с JSON-форматом, ответ Ахантера на запрос дискретных подсказок в формате XML аналогичен ответу, который сервис возвращает при запросе обычных (не дискретных) подсказок. Посмотреть описание этого ответа можно по следующей ссылке.