Документация 4 версии API-интерфейса для проверки кода банка и номера счета

Данный API-интерфейс является частью нашего сервиса SortWare

1. Что представляет собой 4 версия SortWare API?

SortWare API представляет собой автоматизированное решение для проверки кода банка и номера счета на территории Великобритании.

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

История изменения (от 3 к 4 версии):


Новая структура ответа
Новая версия SortWare API позволяет использовать более удобную структуру ответа в формате XML и JSON.
Мы разделили результат запроса на пять групп ( account_data, bank_data, payment_schemas, validations и errors )
Струкутра полностью соответствует аналогичной структуре API-интерфейса для проверки IBAN, что обеспечивает более простую интеграцию обоих решений. Подробное описание структуры ответа представлено в 4 части данной документации.

Коды ошибок
4-я версия SortWare использует коды ошибок, что позволяет быстрее толковать ответы, полученные от API.
Как и в случае с другими API-интерфейсами, коды ошибок позволяют понять, что именно пошло не так при использовании 4-й версии API.
Изучите 5-й раздел для получения подробной информации об ошибках, которые вы можете встретить при использовании системы.

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


2. Функционал

Интерфейс SortWare API предлагает следующие ключевые функции:

  • Получние информации о банке и отделении банка на основе кода банка.
  • Автоматический расчет IBAN на основе кода отделения и номера счета.
  • Определение возможности использования FPS и CHAPS платежей для выбранного банка и его отделений.
  • Отображение нескольких результатов в удобных форматах XML и JSON.

3. Использование API

Данный API-интерфейс позволяет автоматизировать процесс проверки кода банка и номера счета, используя единый запрос HTTP GET или POST.

Доступные параметры представлены в следующей таблице:

Название поля Длина Тип Описание
format 4 Строка Может иметь одно из двух значений: 'xml' или 'json'. Определяет формат ответа системы.
search 6 Строка Данный параметр используется для поиска кода банка в нашем каталоге.
sortcode 6 Строка Код банка, предоставленный одновременно со значением номера счета 'account'.
account 8 Строка Номер банковского счета, предоставленный одновременно с кодом банка 'sortcode'.
api_key 128 Строка Ваш личный API-ключ для доступа к системе.
Открыв ваш личный кабинет, и перейдя в раздел "Доступ к API", вы можете получить ваш API-ключ, который позволяет идентифицировать вас при создании API-запросов.

Ниже представлено несколько примеров использования POST-запросов для получения информации с помощью API:

curl "https://api.iban.com/clients/api/v4/sort/" \
    -X POST \
    -d format=json \
	-d api_key=[YOUR_API_KEY] \
	-d sortcode=200415 \
	-d account=38290008 
<?php
$curl = curl_init();

$post = [
    'format' => 'json',
    'api_key' => '[YOUR_API_KEY]',
    'sortcode'   => '200415',
	'account' => '38290008',
];

curl_setopt_array($curl, array(
    CURLOPT_URL => 'https://api.iban.com/clients/api/v4/sort/',
	CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POSTFIELDS => $post
));

$output = curl_exec($curl);
$result = json_decode($output);

print_r($result);

curl_close($curl);
?>
require 'net/http'

uri = URI('https://api.iban.com/clients/api/v4/sort/')

res = Net::HTTP.post_form(uri, "format" => "json", "api_key" => "[YOUR_API_KEY]","sortcode" => "200415","account" => "38290008")

puts res.body
import requests

post_data = {'format':'json', 'api_key':'[YOUR_API_KEY]','sortcode':'200415','account':'38290008'}

response = requests.post('https://api.iban.com/clients/api/v4/sort/',post_data)
print(response.text)
use LWP::UserAgent;

my $ua = LWP::UserAgent->new;
my $server_endpoint = "https://api.iban.com/clients/api/v4/sort/";

my $format = 'json';
my $api_key = '[YOUR_API_KEY]';
my $sortcode = '200415';
my $account = '38290008';


my $req = HTTP::Request->new( POST => $server_endpoint );
$req->content_type('application/x-www-form-urlencoded');

my $post_data = 'format=' . $format . '&api_key=' . $api_key . '&sortcode=' . $sortcode . '&account=' . $account;

$req->content($post_data);

my $resp = $ua->request($req);

if ( $resp->is_success ) {
    my $message = $resp->decoded_content;
	print $message;
}

JAVA

import java.io.BufferedReader;
import java.io.DataOutputStream;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;
import javax.net.ssl.HttpsURLConnection;
import org.json.simple.JSONObject;
import org.json.simple.JSONArray;
import org.json.simple.parser.ParseException;
import org.json.simple.parser.JSONParser;


public class ibanapi {

	private final String USER_AGENT = "API Client/1.0";

	public static void main(String[] args) throws Exception {

		ibanapi http = new ibanapi();

		
		System.out.println("\nTesting API - Send API POST request");
		http.sendPost();

	}

	// HTTP POST request
	private void sendPost() throws Exception {

		String url = "https://api.iban.com/clients/api/v4/sort/";
		URL obj = new URL(url);
		HttpsURLConnection con = (HttpsURLConnection) obj.openConnection();

		//add reuqest header
		con.setRequestMethod("POST");
		con.setRequestProperty("User-Agent", USER_AGENT);
		con.setRequestProperty("Accept-Language", "en-US,en;q=0.5");

		String urlParameters = "api_key=[YOUR_API_KEY]&format=json&sortcode=200415&account=38290002";

		// Send post request
		con.setDoOutput(true);
		DataOutputStream wr = new DataOutputStream(con.getOutputStream());
		wr.writeBytes(urlParameters);
		wr.flush();
		wr.close();

		int responseCode = con.getResponseCode();
		System.out.println("\nSending 'POST' request to URL : " + url);
		System.out.println("Post parameters : " + urlParameters);
		System.out.println("Response Code : " + responseCode);

		BufferedReader in = new BufferedReader(
		new InputStreamReader(con.getInputStream()));
		String inputLine;
		StringBuffer response = new StringBuffer();

		while ((inputLine = in.readLine()) != null) {
			response.append(inputLine);
		}
		in.close();

		//print result
		System.out.println(response.toString());

	}

}

.NET

public static void Main(string[] args)
		{						
			var request = (HttpWebRequest)WebRequest.Create("https://api.iban.com/clients/api/v4/sort/");
 
			var postData = "api_key=[YOUR_API_KEY]";
			 postData += "&format=json";
			 postData += "&sortcode=200415";
			 postData += "&account=38290002";
			 
			var data = Encoding.ASCII.GetBytes(postData);
			 
			request.Method = "POST";
			request.ContentType = "application/x-www-form-urlencoded";
			request.ContentLength = data.Length;
			 
			using (var stream = request.GetRequestStream())
			{
			 stream.Write(data, 0, data.Length);
			}
			 
			var response = (HttpWebResponse)request.GetResponse();
			 
			var responseString = new StreamReader(response.GetResponseStream()).ReadToEnd();
			
			Console.WriteLine(responseString);
			
			Console.Write("Press any key to continue . . . ");
			Console.ReadKey(true);
		}

NODE

var request = require('request');

var headers = {
    'User-Agent':       'IBAN API Client/0.0.1',
    'Content-Type':     'application/x-www-form-urlencoded'
}

var options = {
    url: 'https://api.iban.com/clients/api/v4/sort/',
    method: 'POST',
    headers: headers,
    form: {'api_key': '[YOUR_API_KEY]', 'format': 'json', 'sortcode': '200415', 'account': '38290002'}
}


request(options, function (error, response, body) {
    if (!error && response.statusCode == 200) {
     
		var data = JSON.parse(body);

		console.log(data.errors);
		
		console.log("Bank Name: " + data.bank_data.bank);
		console.log("Bank BIC: " + data.bank_data.bic);
		console.log("Bank City: " + data.bank_data.city);
		console.log("Bank Address: " + data.bank_data.address);
		console.log("Bank Zip: " + data.bank_data.zip);
		console.log("Bank Phone: " + data.bank_data.phone);
		console.log("Bank Country Name: " + data.bank_data.country);
		console.log("IBAN: " + data.account_data.iban);
		
    }
})



4. Структура ответа API

Ответ SortWare API 4 версии содержит в себе несколько объектов, которые позволяют более точно толковать полученные результаты.
Ниже представлена подробная XSD-схема XML-ответа системы:

  
    
      
        
          
            
              
              
              
            
          
        
        
          
            
              
              
              
              
              
              
              
              
            
          
        
        
          
            
              
              
              
              
              
            
          
        
        
          
            
              
                
                  
                    
                    
                  
                
              
            
          
        
        
      
    
  

Ниже представлено подробное описание каждого из значений, которые являются частью XML-ответа:

Описание объекта 'account_data'
Название поля Длина Тип Описание
SORTCODE 6 Целое число Информация о коде банка, который клиент указал в своем запросе (для справки).
ACCOUNT 8 Целое число Информация о номере счета, который клиент указал в своем запросе (для справки).
IBAN 125 Строка Информация о рассчитанном номере IBAN, который был получен на основе кода банка и номера счета.


Описание объекта 'bank_data', в котором содержится информация о банке и банковском отделении:
Название поля Длина Тип Описание
BIC 8 или 11 Строка БИК выбранного банка или его отделения.
BANK 256 Строка Наименование банка, которому принадлежит указанный код.
BRANCH 256 Строка Наименование отделения банка, которому принадлежит указанный код.
ADDRESS 256 Строка Адрес отделения банка, которому принадлежит указанный код.
CITY 11 Строка Город отделения банка, которому принадлежит указанный код.
ZIP 11 Строка Индекс отделения банка, которому принадлежит указанный код.
PHONE 20 Строка Номер телефона отделения банка, которому принадлежит указанный код.
COUNTRY 2 Строка Двухзначный ISO-код страны отделения банка, которому принадлежит указанный код.


Описание объекта 'payment_schemes', в котором содержится информация о доступных способах оплаты:
Название поля Длина Тип Описание
DD 3 Строка Возможность прямого зачисления средств на счет выбранного банка. Может иметь значение 'YES' или 'NO'
FPS_PAYMENTS 3 Строка Возможность прямого зачисления FPS-платежей на счет выбранного банка. Может иметь значение 'YES' или 'NO'
CHAPS 3 Строка Возможность прямого зачисления CHAPS-платежей на счет выбранного банка. Может иметь значение 'YES' или 'NO'
BACS 3 Строка Возможность прямого зачисления BACS-платежей на счет выбранного банка. Может иметь значение 'YES' или 'NO'
CCC_PAYMENTS 3 Строка Возможность прямого использования чеков и CCC-платежей на счет выбранного банка. Может иметь значение 'YES' или 'NO'


Описание объекта 'validations':
Название поля Длина Тип Описание
CODE 3 Целое число Отображает код, полученный в результате проверки кода банка и номера счета. См. раздел 5 для получения подробной информации о возможных вариантах.
MESSAGE 256 Строка Содержит текстовое описание результатов запроса. См. раздел 5 для получения подробной информации о возможных вариантах.


Описание объекта 'errors':
Название поля Длина Тип Описание
CODE 3 Целое число Отображает код ошибка, полученный в результате проверки кода банка и номера счета. См. раздел 5 для получения подробной информации о возможных вариантах.
MESSAGE 256 Строка Содержит текстовое описание ошибки при обработке запроса. См. раздел 5 для получения подробной информации о возможных вариантах.


5. Коды ошибок и состояния в 4 версии SortWare API

Существует два типа кодов, которые могут быть отправлены API-интерфейсом.
Успешность проверки кода содержится в объекте 'validations'.
Ошибки, возникшие при обработке запроса, содержатся в объекте 'errors'.

Код состояния Тип Описание
301 Ошибка учетной записи Неправильный API-ключ
302 Ошибка учетной записи Истек срок действия подписка
303 Ошибка учетной записи Нет доступных запросов
304 Ошибка учетной записи У вас нет доступа к данному API
201 Ошибка проверки Ошибка проверки номера счета
202 Ошибка проверки Ошибка проверки кода банка
001 Успешная проверка Номер счета является действительным

Если вам требуется документация к 3 версии SortWare API, вы можете скачать ее здесь: Legacy SortWare API V3 Documentation