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

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

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

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

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

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

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

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

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

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

Чтобы всё это заработало, мы использовали здесь следующий JavaScript-код.

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

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

//опции для подсказок по названию компании
var CompanyOptions = 
{ 
  id: 'js-CompanyField', 
  company_address_id: 'js-AddressField',
  company_person_id: 'js-PersonField'
};
//запускаем подсказки для компаний
AhunterSuggest.Company.Discrete( CompanyOptions );

Детальное описание этого кода, а также описание подготовки вашего сайта к использованию подсказок, приводится далее в этой статье.

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

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

Подготовка сайта для подключения подсказок по ЕГРЮЛ

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

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

Подключение дискретных подсказок на сайте

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

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

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

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

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

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

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

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

//опции для подсказок по названию компании
var CompanyOptions = 
{ 
  id: 'js-CompanyField', 
  company_address_id: 'js-AddressField',
  company_person_id: 'js-PersonField'
};
//запускаем подсказки для компаний
AhunterSuggest.Company.Discrete( CompanyOptions );

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

  1. Сначала для поля с идентификатором js-AddressField настраиваются дискретные подсказки для почтовых адресов.
    //опции для подсказок по адресу компании
    var AddressOptions =
    {
      fields: [ { id: 'js-AddressField', 
                  levels: ['Region','District','City'] } ] 
    };
    //будем показывать подсказки только для регионов и городов
    AhunterSuggest.Address.Discrete( AddressOptions );
    Здесь используются именно дискретные подсказки, т.к. этот механизм Ахантера позволяет ограничить выдаваемые в подсказках адреса заданным уровнем. В нашем примере, подсказки для адресов будут ограничиваться уровнем города. Поэтому пользователь сможет указать в этом поле регион, район и город, в котором располагается искомая компания. Ахантер позволяет искать адреса компаний в ЕГРЮЛ с детализацией до улицы, однако часто для эффективной фильтрации компаний бывает достаточно ограничиться городом. Подробнее об использовании и настройке дискретных подсказок для почтовых адресов можно посмотреть здесь.
  2. Затем инициализируются и запускаются подсказки для второго поля с идентификатором js-PersonField. Поскольку в этом поле будет указываться ФИО руководителя искомой компании, здесь подключаются подсказки по ФИО.
    //опции для подсказок по ФИО руководителя компании
    var PersonOptions = 
    {
      id: 'js-PersonField'
    };
    //запускаем подсказки по ФИО
    AhunterSuggest.Person.Solid( PersonOptions );
    Тут используется типовой инициализирующий код, который просто включает стандартные подсказки Ахантера по ФИО для данного поля. Подробнее об использовании и настройке этих подсказок можно посмотреть здесь.
  3. На третьем шаге запускаются сами подсказки для компаний. Они привязываются к полю с идентификатором js-CompanyField. Тут используется особый инициализирующий код, учитывающий тот факт, что адрес и ФИО руководителя компании вводятся в другие поля.
    //опции для подсказок по названию компании
    var CompanyOptions = 
    { 
      id: 'js-CompanyField', 
      company_address_id: 'js-AddressField',
      company_person_id: 'js-PersonField'
    };
    //запускаем подсказки для компаний
    AhunterSuggest.Company.Discrete( CompanyOptions );

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Поле формы
Тэг
Фрагмент запроса для этого поля
a
a[обл Омская, г Омск]
p
p[Иванов]
n
n[ООО Тех]

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

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

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

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

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

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

http://ahunter.ru/site/suggest/company?output=json;mode=discrete;query=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-массива, содержащая адресный фильтр. Адресный фильтр задаёт перечень адресных объектов (например, городов и населённых пунктов), которым должны принадлежать компании, чтобы попасть в выдачу. Каждый адресный объект фильтра задаётся его АБР-кодом. Такие коды используются в адресной базе Ахантера для уникальной идентификации объектов. Для любого адресного объекта можно узнать его АБР-код, например, здесь, если ввести и обработать его адрес.

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

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

http://ahunter.ru/site/suggest/company?output=json|pretty;mode=discrete;companylim=3;query=a[ул Малышева]n[Техн];afilter=["66c1"]

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

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

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

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

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

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

версия сервиса:
© ixLab, 2007-2020, e-mail: info@ixlab.ru
обработано за 1 (мс)