Подсказки при заполнении реквизитов банка

Кроме подсказок по ЕГРЮЛ и ЕГРИП для реквизитов юридических лиц и индивидуальных предпринимателей Ахантер позволяет организовать быстрое заполнение форм с платёжными реквизитами кредитных организаций и участников платёжной системы ЦБ РФ (далее - банков). Кроме скорости заполнения, подсказки по реквизитам банков помогают вводить информацию без ошибок, а также определять, нет ли ограничений, наложенных регулятором на деятельность банка или на операции отдельно взятого корреспондентского счёта в настоящий момент. Эти данные Ахантер берёт из справочника БИК, публикуемого ЦБ РФ, а также на основе данных выписки из Книги государственной регистрации кредитных организаций ЦБ РФ.

При использовании подсказок предполагается, что приложение пользователя или веб-сайт содержит некоторую форму, в которой есть одно или несколько полей для ввода реквизитов банка. Основными сведениями, по которым выполняется поиск банков, являются название, ОГРН, код БИК, код СВИФТ (SWIFT), а также адрес регистрации. Полагается, что при вводе этих сведений, пользователь находит нужный банк среди предложенных подсказок, выбирает его, после чего получает расширенный набор сведений, имеющийся в БИК справочнике и Книге государственной регистрации кредитных организаций.

К таким сведениям относятся информация о корреспондентских счетах банка, информация об ограничениях, наложенных регулятором на банк или отдельные его счета, сведения о статусе и типе участника платёжной системы ЦБ РФ, информация о поддерживаемых услугах перевода, а также стандартизованный адрес банка с полными сведениями о нём.

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

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

Чем больше сведений о банке пользователь уже ввёл, тем более точные подсказки предлагает Ахантер. Быстрее всего Ахантер находит банки по кодам БИК, СВИФТ и ОГРН, поэтому если известен один из этих кодов, то можно сразу получить по нему реквизиты банка, чтобы не вводить их вручную при заполнении платёжных реквизитов.

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

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

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

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

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

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

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

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

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

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

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

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

• u-AhunterSuggestionSubValue – данный класс присваивается блоку, вложенному в основной блок с подсказкой, в который выводится дополнительная информация о подсказываемом банке. Дополнительная информация содержит адрес банка, ОГРН и код БИК. Чтобы визуально отделить эти сведения от названия, можно задать у данного класса дополнительное оформление. Мы на нашем сайте используем для этого уменьшенный размер шрифта, поэтому у нас этот класс описан так:

  .u-AhunterSuggestionSubValue 
  { 
    font-size: 11px;
    padding-top: 1px;
    padding-bottom: 2px; 
  }
  

• u-AhunterSpecialSuggestion – данный класс присваивается блоку с подсказкой, если подсказываемый банк имеет ограничения или находится в стадии аннулирования лицензии. Такие подсказки можно выделять особым фоном или цветом текста, чтобы пользователь обратил на это внимание. Мы на нашем сайте отображаем такие подсказки слегка прозрачными, поэтому у нас этот класс описан так:

  .u-AhunterSpecialSuggestion 
  { 
    opacity: 0.7 
  }
  

Подключение подсказок по банкам на сайте

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

<div>
  <input id="js-BankField" placeholder="Банк, ОГРН, БИК, СВИФТ, адрес">  
</div>

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

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

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

Здесь выполняется заполнение опций options, которые затем передаются модулю подсказок посредством вызова AhunterSuggest.Bank.Solid( options ). Этот вызов привяжет функционал подсказок к полю с идентификатором js-BankField, после чего ввод в этом поле будет приводить к отображению подсказок по банкам, из которых можно будет выбрать нужный для дальнейшего получения его платёжных реквизитов.

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

Опции модуля подсказок

Чуть выше было показано, что при запуске нашего модуля подсказок вам нужно подготовить и передать объект options с параметрами, влияющими на поведение модуля. Основные параметры можно посмотреть в подсказках по почтовым адресам здесь. Кроме них, в подсказках по банкам можно задействовать следующие:

• filter – массив, с помощью которого можно задать приоритеты некоторым адресным объектам (городам, населённым пунктам, улицам или целым регионам РФ) так, чтобы при выдаче подсказок предлагались банки, которые находятся по соответствующим адресам. Элементами данного массива являются строки, каждая из которых содержит уникальный АБР-код адресного объекта по нашему адресному классификатору. Узнать АБР-код для любого адресного объекта, будь то город или целый регион РФ, можно на Демо-странице Стандартизация адреса. Также эти коды возвращает наш сервис при стандартизации адресов с помощью API-команды cleanse/address в блоке codes.
• on_fetch – ваша колбэк-функция, которую будет вызывать наш модуль, после того как по выбранной пользователем подсказке будет получена дополнительная информация о банке. Если вы явно зададите данный колбэк, наш модуль будет асинхронно отправлять на сервис API-команду fetch/bank, чтобы получить полные сведения о выбранном банке (полный адрес банка, наличие ограничений, наложенных регулятором, корреспондентский счёт, БИК/СВИФТ и ОГРН коды). После получения этих сведений наш модуль вызовет ваш колбэк on_fetch и передаст ему следующие аргументы:
  • Suggestion - выбранная пользователем подсказка. Состав полей данного объекта описан ниже в данной статье в описании REST API.
  • Bank - соответствующий выбранной подсказке блок с полной информацией о банке. Состав полей данного объекта можно посмотреть в описании команды fetch/bank.
  Опцию on_fetch и соответствующий ей функционал целесообразно использовать совместно с параметром user, подтверждающим, что у вас есть действующий аккаунт на нашем сервисе. В противном случае сервис будет возвращать ограниченные сведения о банке.
• on_fetch_context – объект, который будет выступать в роли this-контекста при вызове колбэка on_fetch.

Пример запуска подсказок по банкам с разными опциями

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

//Готовим опции для модуля подсказок
var options = 
{ 
  //Наше поле, куда пользователи будут вводить информацию о банке
  id: "js-BankField",

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

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

  //Будем показывать только 5 топовых подсказок
  limit : 5,
  
  //Не будем показывать подсказки при возврате фокуса в поле ввода
  suggest_on_focus : false,
  
  //Фильтр с АБР-кодом города Владивостока
  //Будем возвращать подсказки для банков из этого города
  filter : ["25c1"],

  //При выборе подсказки будем выводить её в отладочную консоль
  on_fetch : function( Suggestion, Bank ) 
  {
    console.log( Suggestion, Bank );
  },
  
  //Указываем свой открытый API-токен, чтобы работал on_fetch
  user : "demotoken"
};

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

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

Пример подсказок по банкам с настраиваемым адресным фильтром

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

<div>
  <input id="js-AddressField" placeholder="Добавить адрес в фильтр"/>  
  <pre id="js-AddressFilter"></pre>
  <input id="js-BankField" placeholder="Банки..."/> 
</div>

В этой форме первое поле с идентификатором js-AddressField используется, чтобы с помощью подсказок получить АБР-код для города или региона РФ, чтобы добавить его в адресный фильтр банков. При редактировании этого поля Ахантер предлагает адресные подсказки, при выборе которых соответствующий АБР-код адресного объекта из подсказки захватывается и запоминается в адресном фильтре.

Элемент с идентификатором js-AddressFilter используется для отладки, в нём отображается весь массив адресного фильтра, сконструированный к настоящему моменту.

Поле с идентификатором js-BankField демонстрирует непосредственно подсказки по банкам, к которым применяется полученный фильтр.

Конфигурация для этой формы будет иметь следующий вид.

//Список с выбранными АБР-кодами адресов, включённых в фильтр
AddressFilter = [];
    
//Опции для подсказок по адресу
var AddressOptions = 
{
  //Будем подсказывать только города, районы и регионы
  fields: [ { 
              id: 'js-AddressField', 
              levels: ['Region','District','City']
            } ],

  //При выборе подсказки по адресу будем запоминать АБР-код адреса
  //в массиве адресного фильтра AddressFilter
  on_choose : function( _Suggestion ) 
  {
    //Запоминаем АБР-код в массиве фильтра
    AddressFilter.push( _Suggestion.sign );
    
    //Обновляем отладочный текст с содержимым фильтра
    $('#js-AddressFilter').text( 'filter = ' + 
                                 JSON.stringify(AddressFilter) );
  }
};
    
//Запускаем подсказки в поле с почтовым адресом
AhunterSuggest.Address.Discrete( AddressOptions );
    
//Запускаем подсказки в поле с банком, 
//В параметре filter передаём массив АБР-кодов адресного фильтра
var BankOptions = { id: 'js-BankField', filter : AddressFilter };
AhunterSuggest.Bank.Solid( BankOptions );

Ниже показан пример того, как это будет работать.

Чтобы заполнить фильтр, вводите адреса в поле сверху и выбирайте их.
Можно добавить не более 5 адресов.

REST API подсказок по банкам

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

Принципы использования API подсказок

Использование команды suggest/bank полагает, что пользователь в режиме реального времени заполняет какое-то одно поле вашей формы, соответствующее названию банка, для которого требуется получить полный набор сведений и реквизитов. В это поле пользователь может вводить как название, так и адрес банка, а также ОГРН, БИК или СВИФТ код. Каждый раз, когда пользователь вводит очередной символ, увеличивается количество информации, на основе которой сервис может сформировать подходящие подсказки.

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

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

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

После того, как пользователь выбрал подходящую подсказку, ваше приложение может запросить у Ахантера полную информацию об этом банке: сведения о банковских счетах, стандартизированный адрес, статусы и классификационные коды в рамках платёжной системы ЦБ РФ, а также информацию об ограничениях, наложенных на банк. Для этого каждая подсказка снабжается уникальным идентификатором-сигнатурой sign. Когда пользователь вашего приложения выбирает подсказку, ваше приложение может брать соответствующую ей сигнатуру и отсылать её с помощью команды fetch/bank. В качестве ответа сервис вернёт полный описатель со всей информацией о выбранном банке.

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

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

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

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

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

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

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

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

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

• output=pretty - опция, требует, чтобы сервис выполнил "красивое" форматирование возвращаемого JSON или XML текста, расставив в нем переносы строк и отступы. Опция может быть полезна при отладке взаимодействия пользовательского приложения с сервисом.
• banklim=число - лимит на число возвращаемых подсказок. Если данное значение превышает установленный администратором сервиса порог, равный 10 подсказкам, то данное значение будет принудительно уменьшено до этого допустимого порога. Если в запросе данный параметр не указан, то в качестве лимита будет выступать установленное администратором сервиса умолчальное значение, равное 6 подсказкам.
• afilter - строка в формате JSON-массива, содержащая адресный фильтр. Адресный фильтр задаёт перечень адресных объектов (например, городов и населённых пунктов), которым должны принадлежать банки, чтобы попасть в выдачу. Каждый адресный объект фильтра задаётся его АБР-кодом. Такие коды используются в адресной базе Ахантера для уникальной идентификации объектов. Для любого адресного объекта можно узнать его АБР-код, например, здесь, если ввести и обработать его адрес.

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

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

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

• output=json|pretty - сообщает сервису о том, что необходимо вернуть ответ в формате JSON, отформатировав его "красиво".
• banklim=3 - сообщает сервису, что следует вернуть только три наиболее подходящие подсказки для вводимого банка.
• query=%D1%81%D0%B1%D0%B5 - закодированный с использованием URL-encoding исходный фрагмент искомого банка "сбе", по которому сервис должен сформировать подсказки.
• afilter=["66c1"] - адресный фильтр, требующий, чтобы в выдачу подсказок в первую очередь попадали банки из Екатеринбурга, т.к. АБР-код этого города - 66c1.

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

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

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

{
  "query" : "москва сб",
  "request_process_time" : 0,
  "status" : { "egrul": 0, "egrip": 1 },
  "suggestions" : [
    {
      "address" : "г Москва, ул Вавилова, дом 19",
      "bic" : "044525225",
      "name" : "ПАО Сбербанк",
      "ogrn" : "1027700132195",
      "sign" : "044525225",
      "state" : 0
    },
    {
      "address" : "г Москва, ул Высоцкого, дом 4",
      "bic" : "044525921",
      "name" : "КУ СБ БАНК (ООО) - ГК \"АСВ\"",
      "ogrn" : "1027739177091",
      "sign" : "044525921",
      "state" : 1
    }
  ]
}

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

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

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

JSON-массив suggestions: подсказки с банками

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

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

{
  "address" : "г Москва, ул Вавилова, дом 19",
  "bic" : "044525225",
  "name" : "ПАО Сбербанк",
  "ogrn" : "1027700132195",
  "sign" : "044525225",
  "state" : 0
}

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

• name – строка с кратким названием банка в том виде, в котором оно приводится в справочнике БИК.
• address - юридический адрес банка;
• ogrn - ОГРН банка;
• bic - БИК код банка;
• state - числовое значение, отражающее текущее состояние банка. Значение 0 указывает на то, что на банк в настоящий момент не наложены никакие ограничения. Значение 1 указывает на то, что у банка есть ограничения, наложенные на какой-то из его счетов, либо приостановлена лицензия, либо он находится в состоянии ликвидации.
• sign – строка, содержащая сигнатуру банка. Сигнатуру следует рассматривать как уникальный идентификатор, по которому можно получить полную информацию с помощью команды fetch/bank.

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

Чтобы получить исчерпывающую информацию по выбранному пользователем банку, вашему приложению следует использовать команду fetch/bank, которая позволяет получить полные сведения по сигнатуре подсказки sign.

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

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

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

<ProcessSuggestResult>
  <Suggestion address="г Москва, ул Вавилова, дом 19" 
              bic="044525225" 
              name="ПАО Сбербанк" 
              ogrn="1027700132195" 
              sign="044525225" 
              state="0"/>
  <Suggestion address="г Москва, ул Высоцкого, дом 4" 
              bic="044525921" 
              name="КУ СБ БАНК (ООО) - ГК "АСВ"" 
              ogrn="1027739177091" 
              sign="044525921" 
              state="1"/>
  <Query val="Москва сб"/>
</ProcessSuggestResult>

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

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

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

XML-элемент Suggestion: подсказка одного банка

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

  <Suggestion address="г Москва, ул Вавилова, дом 19" 
              bic="044525225" 
              name="ПАО Сбербанк" 
              ogrn="1027700132195" 
              sign="044525225" 
              state="0"/>

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

• name - краткое название банка в том виде, в котором оно представлено в справочнике БИК.
• address - юридический адрес банка;
• ogrn - ОГРН банка;
• bic - БИК код банка;
• state - числовое значение, отражающее текущее состояние банка. Значение 0 указывает на то, что банк в настоящий момент действует без ограничений. Значение 1, указывает на то, что на банк наложены ограничения, либо идёт процедура его ликвидации.
• sign – строка, содержащая сигнатуру банка. Сигнатуру следует рассматривать как уникальный идентификатор банка, по которому можно получить полную информацию с помощью команды fetch/bank.