Dokumentácia pre IBAN API V4 Validáciu

Toto API je súčasťou našich služieb IBAN Balíčka

1. Čo je nové vo validačnom rozhraní API V4 pre IBAN?


Neustále sa snažíme zlepšovať naše služby a poskytovať lepšie riešenia na overovanie platieb.
Možno ste si všimli, že IBAN Balíček API preskočil iteráciu verzie z V2 na V4.
Toto sa vykonalo preto, lebo sme zjednotili ostatné API, ako napríklad SortWare v3, do jednej iterácie verzií, napr. v4.

Zoznam zmien ( z v2 na v4 ):


Bola pridaná nová validácia (chyba 206 a úspešnosť 006) - API V4 teraz kontroluje, či sa vo vstupnom IBAN nenachádzajú nepovolené znaky.
Nový kód chyby - 206 (Overenie zlyhalo) so správou: IBAN obsahuje neplatné znaky.
Úspešný kód pre túto kontrolu je - 006 (Overenie úspešnosti) so správou: IBAN neobsahuje ilegálne znaky.
Tento kód chyby vám poskytne viac informácií v prípade, že do nášho systému odošlete IBAN s nealfanumerickými znakmi.
Predchádzajúce správanie bolo odstrániť všetky nealfanumerické znaky a vykonať validáciu.

Pridaná nová validácia (chyba 207 a úspešnosť 007) - Krajina nepodporuje IBAN
Táto overovacia vrstva oznámi, či kód krajiny predloženého IBAN nie je súčasťou oficiálnych krajín podporujúcich platby IBAN.
Osoba môže napríklad vygenerovať IBAN pre Spojené štáty pomocou nespoľahlivého softvéru tretej strany
Takýto IBAN môže vyzerať ako US64SVBKUS6S3300958879
Všimnite si, že kontrolná číslica je správna a dokáže prejsť validáciou modulu, ale nie je platným IBAN, pretože Spojené štáty nepoužívajú IBAN pre bankové platby.


2. Vlastnosti


IBAN API V4 validácia vám umožňuje vykonávať nasledujúce činnosti:

  • Overenie, či je IBAN platný pomocou kontrolných číslic
  • Overenie, či má IBAN platný kód domácej banky a kontrolné číslo účtu *
  • Overiť dĺžku IBAN pre konkrétnu krajinu
  • Overenie štruktúry / formátovania IBAN pre konkrétnu krajinu
  • Overenie znakov IBAN (kontrola nealfanumerických znakov)
  • Overenie, či kód krajiny podporuje štandard IBAN

  • Identifikuje banku, ktorá vydala IBAN
  • Identifikuje kód krajiny a krajiny pre IBAN
  • Identifikuje adresu banky, ktorá vydala IBAN
  • Identifikuje bankový kód banky BIC
  • Identifikuje bankovú podporu SEPA: B2B, COR1, SCC, SCT, SDD

* Pre niektoré banky a krajiny sa vykonávajú overenia bankového kódu a čísla účtu.

3. API V4 Požiadavky



Systém API vám umožňuje automatizovať validáciu IBAN prostredníctvom jednoduchej požiadavky HTTP GET alebo POST.
Prijaté parametre sú uvedené v nasledujúcej tabuľke:

Názov Poľa Dĺžka Typ Popis
IBAN Max 100 String IBAN, ktorý chcete overiť.
api_key 128 String Váš osobný kľúč API.
format 5 String Formát odpovede XML a JSON podporované.

* Ak chcete získať kľúč API, kontaktujte nás na adrese contact@iban.com alebo si kúpite predplatné na našej objednávacej stránke

PRÍKLADY – Validácie IBAN
Použite nižšie uvedený vzorový kód na testovanie rozhrania API v najbežnejších programovacích jazykoch.

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);
		
    }
})


Príklad použitia API validácie IBAN s požiadavkou GET nájdete nižšie:

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

Kde:
  • kľúč je kľúč API
  • IBAN odoslaný na overenie modulom API.
  • xml je formát odpovede. Pre odpoveď vo formáte json možno zadať aj kľúčové slovo json.

Keď je požiadavka HTTP GET alebo POST vykonaná so správnym kľúčom API, systém vráti výsledky v zadanom formáte. Vzorovú odpoveď môžete nájsť v nasledujúcej časti “Štruktúra odpovedí API”

4. API V4 Odpovede

Schému XSD odozvy rozhrania API nájdete nižšie:




	 
		   
				 
					   
							 
							 
							 
							 
							 
							 
							 
							 
							 
							 
							 
							 
							 
							 
							 
							 
					   
				 
		   
		   
				 
					   
							 
							 
							 
							 
							 
					   
				 
		   
		   
				 
					   
							 
								   
										 
											   
											   
										 
								   
							 
							 
								   
										 
											   
											   
										 
								   
							 
							 
								   
										 
											   
											   
										 
								   
							 
							 
								   
										 
											   
											   
										 
								   
							 
							 
								   
										 
											   
											   
										 
								   
							 
							 
								   
										 
											   
											   
										 
								   
							 
					   
				 
		   
		   
	 



Podrobný popis vrátených polí objektov bank_data môžete vidieť v tabuľke nižšie:

Názov Poľa Dĺžka Typ Popis
BIC Max 11 String Kód BIC vydávajúcej banky / pobočky alebo inštitúcie.
BANK Max 256 String Názov banky / inštitúcie, ktorá IBAN vydala
BRANCH Max 256 String Názov konkrétnej pobočky banky, ak je k dispozícii
COUNTRY Max 32 String Úplný názov krajiny pôvodu, napr. “Spojené Štáty”
COUNTRY_ISO Max 2 String Dvojpísmenová skratka kódu krajiny, napr. USA, UK, AU, FR… atď.
CITY Max 128 String Názov mesta, v ktorom sa nachádza vydávajúca banka.
STATE Max 128 String Názov štátu, v ktorom sa banka / pobočka nachádza.
ZIP Max 11 String PSČ alebo smerovacie číslo mesta.
ADDRESS Max 128 String Adresa vystavujúcej banky.
ACCOUNT Max 128 String Číslo domáceho bankového účtu extrahované z IBAN.
Podrobný popis vrátených polí sepa_data objektov je možné vidieť v tabuľke nižšie:

Názov Poľa Dĺžka Typ Popis
SCT Max 3 String Či táto banka podporuje SEPA Kreditný Transfer.
SDD Max 3 String Či táto banka podporuje SEPA inkaso.
COR1 Max 3 String Či táto banka podporuje SEPA COR1.
B2B Max 3 String Či táto banka podporuje SEPA Business to Business.
SCC Max 3 String Či táto banka podporuje zúčtovanie SEPA karty.


Vzorová odpoveď XML z API pre dotaz na overenie IBAN by bola:

	
		BARCGB22
		INTERNATIONAL BANKING 2
		BARCLAYS BANK UK PLC
		
PO Box 69999 1 Churchill Place Canary Wharf
Londýn E14 1QE 020 71147000 GB 73160944
ÁNO ÁNO ÁNO ÁNO NIE 006 IBAN neobsahuje ilegálne znaky 001 IBAN Kontrolná číslica je správna 002 Kontrolné číslo účtu je správne 005 Štruktúra IBAN je správna 003 Dĺžka IBAN je správna 007 Krajina podporuje štandard IBAN

5. API V4 Stavové Kódy

Matematické kontrolné číslice a validácie formátovania sú vrátené v objekte "validácie"
Vo verzii API v4 sme oddelili každú validáciu na jej vlastný objekt, aby sme uľahčili prístup ku každému špecifickému overeniu v kóde.
To v podstate znamená, že namiesto toho, aby ste prechádzali cez objekt „validations“, môžete jednoducho odkazovať na konkrétny objekt validácie jeho menom, napríklad $validations->structure;

Stavový Kód Typ Popis
301 Chyba Účtu Kľúč API je neplatný
302 Chyba Účtu Platnosť odberu vypršala
303 Chyba Účtu Nie sú k dispozícii žiadne dotazy
304 Chyba Účtu K tomuto rozhraniu API nemáte prístup
305 Chyba Účtu Adresa IP nie je povolená
201 Validácia Zlyhala Kontrolné číslo účtu nie je správne
202 Validácia Zlyhala IBAN Kontrolné číslo nie je správne
203 Validácia Zlyhala Dĺžka IBAN nie je správna
205 Validácia Zlyhala Štruktúra IBAN nie je správna
206 Validácia Zlyhala IBAN obsahuje nepovolené znaky
207 Validácia Zlyhala Krajina nepodporuje štandard IBAN
001 Validácia bola úspešná IBAN Kontrolná číslica je správna
002 Validácia bola úspešná Kontrolné číslo účtu je správne
003 Validácia bola úspešná Dĺžka IBAN je správna
004 Validácia bola úspešná Kontrolná číslica účtu sa nevykonáva pre túto banku alebo pobočku
005 Validácia bola úspešná Štruktúra IBAN je správna
006 Validácia bola úspešná IBAN neobsahuje ilegálne znaky
007 Validácia bola úspešná Krajina podporuje štandard IBAN