Подсказки при заполнении поля "Кем выдан паспорт"

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

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

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

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

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

Чем больше сведений пользователь уже ввёл в такое поле, тем более точные подсказки предлагает Ахантер. Быстрее всего Ахантер находит подразделения по их кодам, поэтому если код заранее известен, то можно сразу получить по нему все альтернативные названия этого подразделения в именительном и творительном падежах. Творительный падеж обычно используется, если при заполнении паспортных данных необходимо ответить на вопрос Кем выдан паспорт. Именительный падеж отвечает на вопрос Кто выдал паспорт.

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

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

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

//готовим опции модуля
var options = { id : 'js-FMSField', limit : 6 };

//запускаем модуль
AhunterSuggest.FMS.Solid( options );

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

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

Как добавить подсказки по подразделениям ФМС на веб-сайт

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

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

Все эти процедуры детально описаны в подсказках для почтовых адресов по следующей ссылке: suggest/address.

Подключение подсказок по отделениям ФМС на сайте

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

<div>
  <input id="js-FMSField" placeholder="Подразделение, выдавшее паспорт">  
</div>

Теперь, чтобы запустить подсказки, достаточно где-нибудь на странице добавить следующий инициализирующий скрипт:

<script>
  
  //готовим настройки модуля
  var options = { id : 'js-FMSField' };

  //запускаем модуль подсказок
  AhunterSuggest.FMS.Solid( options );
  
</script>

Здесь выполняется заполнение опций options, которые затем передаются модулю подсказок посредством вызова AhunterSuggest.FMS.Solid( options ). Этот вызов привяжет функционал подсказок к полю с идентификатором js-FMSField, после чего частичное заполнение этого поля будет приводить к отображению подсказок с названиями паспортных столов, отделений МВД и подразделений ФМС, выдающих паспорта. Из этих подсказок пользователь вашего приложения или веб-сайта сможет выбрать нужный вариант для дальнейшего получения полной информации о данном подразделении.

Объект options позволяет указать и другие опции, влияющие на поведение и внешний вид подсказок. Все они подробно рассмотрены по следующей ссылке.

Подсказки для поля "Кем выдан паспорт" с разными опциями

Ниже приведён пример инициализации модуля подсказок по паспортным столам и подразделениям ФМС, вводимым в одно поле, с помощью дополнительных параметров.

//Готовим опции для модуля подсказок
var options = 
{ 
  //Поле, куда вводится информация о подразделении
  id: "js-FMSField",

  //Веб-адрес облачной версии сервиса
  ahunter_url : "https://ahunter.ru/",

  //Не будем показывать предупреждающее сообщение, когда подсказок нет
  empty_msg : "",

  //Будем показывать только 5 топовых подсказок
  limit : 5,
  
  //Не будем показывать подсказки при возврате фокуса в поле ввода
  suggest_on_focus : false,
  
  //При выборе подсказки будем выводить её в отладочную консоль
  on_choose : function( Suggestion ) 
  {
    console.log( Suggestion );
  }
};

//Запускаем модуль подсказок
AhunterSuggest.FMS.Solid( options );

После выполнения этой инициализации всякий раз, когда пользователи будут редактировать поле js-FMSField, на экране будут появляться подсказки с информацией о подходящих подразделениях ФМС.

REST API подсказок по подразделениям ФМС

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

Принципы использования API подсказок по отделениям ФМС

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

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

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

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

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

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

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

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

• output=json - сообщает сервису о том, что необходимо вернуть ответ в формате JSON.
• query=%D0%B0%D1%80%D0%B1 - закодированный с использованием URL-encoding фрагмент введенного названия подразделения арб в кодировке UTF-8, для которого необходимо получить подсказки.

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

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

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

• https://ahunter.ru/site/suggest/fms - URL-команды.
• output=json или output=xml - формат, в котором требуется вернуть результат выполнения команды.
• query=строка запроса - строка, содержащая фрагмент некоторой информации об искомом подразделении, по которой требуется выполнить поиск и вернуть релевантные подсказки.

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

• output=pretty - опция, требует, чтобы сервис выполнил "красивое" форматирование возвращаемого JSON или XML текста, расставив в нем переносы строк и отступы. Опция может быть полезна при отладке взаимодействия пользовательского приложения с сервисом.
• fmslim=число - лимит на число возвращаемых подсказок. Если данное значение превышает установленный администратором сервиса порог, равный 10 подсказкам, то данное значение будет принудительно уменьшено до этого допустимого порога. Если в запросе данный параметр не указан, то в качестве лимита будет выступать установленное администратором сервиса умолчальное значение, равное 6 подсказкам.

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

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

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

• output=json|pretty - сообщает сервису о том, что необходимо вернуть ответ в формате JSON, отформатировав его "красиво".
• fmslim=3 - сообщает сервису, что следует вернуть только три наиболее подходящие подсказки для вводимого подразделения ФМС.
• query=%D0%B0%D1%80%D0%B1 - закодированный с использованием URL-encoding исходный фрагмент искомого подразделения арб, по которому сервис должен сформировать подсказки.

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

Ниже приведен ответ сервиса с результатом формирования подсказок по запросу 161-001. Полагается, что пользователь хочет получить подходящее название отделения УВД в Казани с соответствующим кодом.

Результирующий JSON-ответ получен с использованием опции output=json|pretty, позволяющей выполнить "красивое" форматирование JSON-текста.

{
  "query" : "161-001",
  "request_process_time" : 1,
  "suggestions" : [
    {
      "ablative_name" : "ДЧ УВД Г. КАЗАНИ",
      "canon_name" : "ДЧ УВД Г. КАЗАНИ",
      "code" : "161-001",
      "sign" : "c[161-001]n[ДЧ УВД Г. КАЗАНИ]"
    },
    {
      "ablative_name" : "МВД РЕСПУБЛИКИ ТАТАРСТАН",
      "canon_name" : "МВД РЕСПУБЛИКИ ТАТАРСТАН",
      "code" : "161-001",
      "sign" : "c[161-001]n[МВД РЕСПУБЛИКИ ТАТАРСТАН]"
    },
    {
      "ablative_name" : "ДЧ МВД РЕСПУБЛИКИ ТАТАРСТАН",
      "canon_name" : "ДЧ МВД РЕСПУБЛИКИ ТАТАРСТАН",
      "code" : "161-001",
      "sign" : "c[161-001]n[ДЧ МВД РЕСПУБЛИКИ ТАТАРСТАН]"
    }
  ]
}

Результатом формирования подсказок для вводимого подразделения является JSON-объект со следующими элементами.

• suggestions - массив с вариантами подсказок для обработанного запроса.
• query - строка, содержащая исходный обработанный запрос.
• request_process_time - время обработки всего запроса в целом в миллисекундах.

Ниже приведено детальное описание этих элементов.

JSON-массив suggestions: подсказки с отделениями ФМС

Поскольку при формировании подсказок полагается, что информация о подразделении ФМС введена не полностью, то вариантов с подсказками в общем случае может быть несколько. Также подсказок может быть несколько, даже если код подразделения, выдавшего паспорт, введён полностью. Это связано с тем, что в разное время подразделение, оформлявшее паспорта, называлось по-разному. Каждому предлагаемому сервисом варианту соответствует отдельный элемент suggestions[i] JSON-массива suggestions. Количество предлагаемых вариантов может лимитироваться с помощью опционального параметра fmslim, передаваемого в рамках запроса.

Пример JSON-объекта, соответствующего одному варианту подсказок suggestions[i] приведен ниже.

{
  "ablative_name" : "ФРУНЗЕНСКОЕ РУВД Г. ВЛАДИВОСТОКА",
  "canon_name" : "ФРУНЗЕНСКИМ РУВД Г. ВЛАДИВОСТОКА",
  "code" : "252-005",
  "sign" : "c[252-005]n[ФРУНЗЕНСКОЕ РУВД Г. ВЛАДИВОСТОКА]",
}

Каждый элемент suggestions[i] представляет собой JSON-объект со следующими элементами.

• canon_name – строка с названием подразделения ФМС в именительном падеже. Данное название отвечает на вопрос Кто выдал паспорт;
• ablative_name - строка с названием подразделения ФМС в творительном падеже. Данное название отвечает на вопрос Кем выдан паспорт;
• code - строка с числовым кодом данного подразделения;
• sign - уникальная сигнатура данного подразделения, позволяющая идентифицировать подразделения в БД сервиса;

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

Назначение возвращаемых в XML-ответе элементов аналогично JSON-элементам, которые мы рассмотрели выше. Для получения ответа в формате XML необходимо в исходном запросе использовать значение параметра output=xml.

XML-ответ сервиса c подсказками по запросу 161-001 имеет следующий вид.

<ProcessSuggestResult>
  <Suggestion code="161-001" 
              canon_name="ДЧ УВД Г. КАЗАНИ" 
              ablative_name="ДЧ УВД Г. КАЗАНИ" 
              sign="c[161-001]n[ДЧ УВД Г. КАЗАНИ]"/>
  <Suggestion code="161-001" 
              canon_name="МВД РЕСПУБЛИКИ ТАТАРСТАН" 
              ablative_name="МВД РЕСПУБЛИКИ ТАТАРСТАН" 
              sign="c[161-001]n[МВД РЕСПУБЛИКИ ТАТАРСТАН]"/>
  <Suggestion code="161-001" 
              canon_name="ДЧ МВД РЕСПУБЛИКИ ТАТАРСТАН" 
              ablative_name="ДЧ МВД РЕСПУБЛИКИ ТАТАРСТАН" 
              sign="c[161-001]n[ДЧ МВД РЕСПУБЛИКИ ТАТАРСТАН]"/>
  <Query val="161-001"/>
</ProcessSuggestResult>

Ответ с подсказками представляет собой XML-документ со следующими дочерними элементами.

• Suggestion - данный XML-элемент соответствует одной подсказке, предложенной сервисом. Поскольку в результате формирования подсказок, как правило, возникает несколько вариантов, в XML-ответе может присутствовать несколько элементов Suggestion, каждый из которых соответствует одному из предложенных сервисом вариантов. Список из всех XML-элементов Suggestion является аналогом JSON-массива suggestions, возвращаемого в JSON-ответе сервиса.
• Query - данный XML-элемент содержит обработанную строку запроса. Эта строка передается с помощью атрибута val этого XML-элемента. Данный элемент является аналогом JSON-элемента query, возвращаемого в JSON-ответе сервиса.

Ниже приведено детальное описание этих XML-элементов.

XML-элемент Suggestion: подсказка одного подразделения ФМС

Элемент Suggestion содержит информацию об одной подсказке из предложенного сервисом перечня подсказок по вводимому подразделению ФМС. Пример данного элемента приведен ниже.

  <Suggestion code="252-005" 
              canon_name="ФРУНЗЕНСКОЕ РУВД Г. ВЛАДИВОСТОКА" 
              ablative_name="ФРУНЗЕНСКИМ РУВД Г. ВЛАДИВОСТОКА" 
              sign="c[252-005]n[ФРУНЗЕНСКОЕ РУВД Г. ВЛАДИВОСТОКА]"/>

Данный элемент содержит следующие атрибуты.

• code - код отделения УВД или подразделения ФМС.
• canon_name - строка с названием подразделения ФМС в именительном падеже. Данное название отвечает на вопрос Кто выдал паспорт;
• ablative_name - строка с названием подразделения ФМС в творительном падеже. Данное название отвечает на вопрос Кем выдан паспорт;
• sign – уникальная сигнатура данного подразделения, позволяющая идентифицировать подразделения в БД сервиса.