דוקומנטציית API לאימות IBAN, גרסה 4

API זה הינו חלק משירות ה-IBAN Suite שלנו

1. מה חדש בגרסה 4 של ה-API לאימות IBAN?


אנו עובדים באופן קבוע על שיפור השירות שלנו למתן פתרונות אימות תשלום טובים יותר.
ייתכן ששמתם לב לכך שגרסת ה-API של IBAN SUITE קפצה מ-2 ל-4.
הסיבה לכך היא שאיחדנו API-ים אחרים, כגון SORTWARE גרסה 3, לגרסה אחת, והיא גרסה 4.

רשימת שינויים מגרסה 2 לגרסה 4


שיטת אימות חדשה נוספה (שגיאה 206 ואישור 006) - API גרסה 4 כעת בודק לקיום תווים בלתי-חוקיים ב-IBAN המוזן.
נוסף קוד שגיאה חדש - 206 (שגיאת אימות) עם הודעה: ה-IBAN מכיל תווים בלתי-חוקיים.
קוד האישור עבור בדיקה זו הוא 006 (אישור אימות) עם ההודעה: ה-IBAN אינו מכיל תווים בלתי חוקיים.
שגיאה זו תספק לכם מידע נוסף במקרה של שליחת IBAN המכיל תווים שאינם אלפאנומריים למערכת שלנו.
המהלך הקודם היה הסרה של כל התווים שאינם אלפאנומריים וביצוע הבדיקה.

שיטת אימות חדשה נוספה (שגיאה 207 ואישור 007) - בדיקת תמיכת המדינה ב-IBAN.
שכבת אימות זו תדווח האם קוד המדינה ב-IBAN שנשלח הינו קוד של מדינה שאינה תומכת ב-IBAN באופן רשמי.
לדוגמה, זה יכול לקרות כאשר אדם הפיק IBAN עבור חשבון בארצות הברית באמצעות תכנת צד שלישי בלתי-אמינה.
IBAN כזה ייראה כך: US64SVBKUS6S3300958879
שימו לב שספרת הביקורת הינה נכונה, ולכן, המספר יעבור את אימות המודולוס, אך בכל זאת - זהו אינו IBAN תקין, כיוון שארה"ב אינה תומכת בתשלומים באמצעות IBAN.


2. מאפיינים


גרסה 4 של ה-API לאימות IBAN תאפשר לכם לעשות את הפעולות הבאות:

  • אימות IBAN לפי ספרות ביקורת
  • אימות IBAN לקיום קוד בנק ומספר חשבון מקומיים לפי ספרות ביקורת *
  • אימות אורך IBAN בהתאם לכל מדינה ספציפית
  • אימות מבנה\פורמט IBAN לפי מדינה
  • אימות IBAN לקיום תווים שאינם אלפאנומריים
  • בדיקה האם המדינה שנתקבל קוד המדינה שלה תומכת בתקן IBAN

  • זיהוי הבנק שהנפיק את ה-IBAN
  • זיהוי המדינה וקוד המדינה לפי IBAN
  • איתור כתובת הבנק המנפיק את ה-IBAN
  • זיהוי קוד BIC של הבנק
  • זיהוי תמיכת SEPA של הבנק: B2B, COR1, SCC, SCT, SDD

* אימות קוד בנק ומספר חשבון נעשה עבור מדינות ובנקים ספציפיים בלבד.

3. פניות ב-API גרסה 4



ה-API מאפשר אוטומציה של אימות IBAN באמצעות פניות GET או POST בפרוטוקול HTTP.
הפרמטרים המקובלים מופיעים בטבלה מטה:

שם שדה אורך סוג תיאור
IBAN עד 100 מחרוזת The IBAN you want to validate.
api_key 128 מחרוזת מפתח ה-API האישי שלכם.
format 5 מחרוזת פורמט תשובת ה-API. פורמטים נתמכים - JSON ו-XML.

* לקבלת מפתח ה-API, אנא צרו איתנו קשר באימייל contact@iban.com, או רכשו מנוי בעמוד ההזמנות

דוגמה - אימות IBAN
הנכם מוזמנים להשתמש בקוד לדוגמה המסופק מטה על-מנת לבדוק את ה-API עם שפות התכנות הנפוצות ביותר.

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

$post = [
    'format' => 'json',
    'api_key' => '[YOUR_API_KEY]',
    'iban'   => 'DE46500700100927353010',
];

curl_setopt_array($curl, array(
    CURLOPT_URL => 'https://api.iban.com/clients/api/v4/iban/',
	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/iban/')

res = Net::HTTP.post_form(uri, "format" => "json", "api_key" => "[YOUR_API_KEY]","iban" => "DE46500700100927353010")

puts res.body
import requests

post_data = {'format':'json', 'api_key':'[YOUR_API_KEY]','iban':'DE46500700100927353010'}

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

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

my $format = 'json';
my $api_key = '[YOUR_API_KEY]';
my $iban = 'DE02100500000024290661';


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 . '&iban=' . $iban;

$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/iban/";
		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&iban=DE02100500000024290661";

		// 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/iban/");
 
			var postData = "api_key=[YOUR_API_KEY]";
			 postData += "&format=json";
			 postData += "&iban=DE02100500000024290661";
			 
			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/iban/',
    method: 'POST',
    headers: headers,
    form: {'api_key': '[YOUR_API_KEY]', 'format': 'json', 'iban': 'GB04BARC20474473160944'}
}

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 FAX: " + data.bank_data.fax);
		console.log("Bank www: " + data.bank_data.www);
		console.log("Bank email: " + data.bank_data.email);
		console.log("Bank Country Name: " + data.bank_data.country);
		console.log("Bank Country Code: " + data.bank_data.country_iso);
		console.log("Domestic Account Number: " + data.bank_data.account);
		
    }
})


דוגמת שימות ב-API לאימות IBAN עם פניית GET נמצאת מטה:

https://api.iban.com/clients/api/v4/iban/?api_key=key&format=xml&iban=IBAN

ובה:
  • KEY הינה מפתח ה-API שלכם.
  • מס' ה-IBAמ שנשלח לאימות על-ידי ה-API.
  • התשובה מגיעה בפורמט XML. כמו כן, ניתן להוסיף את מילת המפתח JSON על מנת לקבל תשובת JSON..

לאחר שפניית GET או POST נשלחת, בצירוף מפתח ה-API הנכון, המערכת תחזיר תשובה בפורמט המבוקש. אתם יכולים למצוא תשובה לדוגמה במדור הבא: "מבנה תשובת API".

4. תשובת API גרסה 4

סכימת XSD של תשובת ה-API נמצאת מטה:




	 
		   
				 
					   
							 
							 
							 
							 
							 
							 
							 
							 
							 
							 
							 
							 
							 
							 
							 
							 
					   
				 
		   
		   
				 
					   
							 
							 
							 
							 
							 
					   
				 
		   
		   
				 
					   
							 
								   
										 
											   
											   
										 
								   
							 
							 
								   
										 
											   
											   
										 
								   
							 
							 
								   
										 
											   
											   
										 
								   
							 
							 
								   
										 
											   
											   
										 
								   
							 
							 
								   
										 
											   
											   
										 
								   
							 
							 
								   
										 
											   
											   
										 
								   
							 
					   
				 
		   
		   
	 



תיאור מפורט של שדות האובייקט BANK_DATA שמוחזרים מופיעים בטבלה מטה:

שם שדה אורך סוג תיאור
BIC עד 11 מחרוזת קוד ה-BIC של הבנק או המוסד.
BANK עד 256 מחרוזת שם הבנק\המוסד שהנפיק את ה-IBAN
BRANCH עד 256 מחרוזת שם הסניף הספציפי, אם קיים.
COUNTRY עד 32 מחרוזת שם מלא שמדינת המקור, דוגמת "ארצות הברית"
COUNTRY_ISO 2 מחרוזת קוד מדינה בן שני תווים, דוגמת: US, UK, AU, FR, וכו'.
CITY עד 128 מחרוזת שם העיר בה נמצא הבנק המנפיק.
STATE עד 128 מחרוזת שם המדינה\המחוז בו נמצא הבנק\הסניף.
ZIP עד 11 מחרוזת מיקוד של הבנק\סניף\מוסד.
ADDRESS עד 128 מחרוזת כתובת הבנק המנפיק.
ACCOUNT עד 128 מחרוזת מספר החשבון המקומי מתוך ה-IBAN.
תיאור מפורט של שדות האובייקט SEPA_DATA שמוחזרים מופיעים בטבלה מטה:

שם שדה אורך סוג תיאור
SCT עד 3 מחרוזת האם הבנק תומך בהעברת אשראי של SEPA.
SDD עד 3 מחרוזת האם הבנק תומך בחיוב ישיר של SEPA.
COR1 עד 3 מחרוזת האם הבנק תומך ב-SEPA COR1.
B2B עד 3 מחרוזת האם הבנק תומך בסכימת עסק-לעסק של SEPA.
SCC עד 3 מחרוזת האם הבנק תומך בסליקת כרטיסים של SEPA.


תשובת XML לדוגמה מה-API לשאילתת אימות IBAN תיראה כך:

	
		BARCGB22
		INTERNATIONAL BANKING 2
		BARCLAYS BANK UK PLC
		
PO Box 69999 1 Churchill Place Canary Wharf
London E14 1QE 020 71147000 GB 73160944
YES YES YES YES NO 006 ה-IBAN אינו מכיל תווים לא-חוקיים 001 ספרת ביקורת של IBAN תקינה 002 ספרת ביקורת של מספר חשבון תמיכה 005 מבנה IBAN תקין 003 אורך IBAN תקין 007 המדינה תומכת IBAN

5. קודי סטטוס ב-API גרסה 4

תוצאות בדיקת ספרת ביקורת ופורמט מוחזרות באובייקט VALIDATIONS.
בגרסה 4 של ה-API, הפרדנו כל בדיקה לאובייקט משלו על-מנת להקל על הגישה לקוד הספציפי של כל בדיקה.
המשמעות היא שבמקום יצירת לולאה דרך אובייקט VALIDATIONS, תוכלו פשוט לקשר לאובייקט ה-VALIDATION הספציפי בשמו באופן הבא - $validations->structure;

קוד סטטוס סוג תיאור
301 שגיאת חשבון מפתח API לא תקין
302 שגיאת חשבון מנוי פג תוקף
303 שגיאת חשבון אין שאילתות זמינות
304 שגיאת חשבון אין לכם גישה ל-API זה
305 שגיאת חשבון כתובת IP לא מורשת
201 שגיאת אימות ספרת ביקורת בחשבון אינה נכונה
202 שגיאת אימות ספרת ביקרות ב-IBAN אינה תקינה
203 שגיאת אימות אורך IBAN לא תקין
205 שגיאת אימות מבנה IBAN לא תקין
206 שגיאת אימות IBAN מכיל תווים לא חוקיים
207 שגיאת אימות מדינה אינה תומכת בתקן IBAN
001 אישור אימות ספרת ביקורת IBAN תקינה
002 אישור אימות ספרת ביקורת חשבון תקינה
003 אישור אימות אורך IBAN תקין
004 אישור אימות בדיקת ספרת ביקורת אינה נעשית עבור בנק או סניף זה
005 אישור אימות מבנה IBAN תקין
006 אישור אימות IBAN אינו מכיל תווים לא חוקיים
007 אישור אימות המדינה תומכת בתקן IBAN