Documentazione API V4 di ordinamento codice e bonifico bancario

Questa API fa parte del nostro servizio SortWare

1. Che cos'è l'API V4 SortWare?

L'API SortWare fornisce automazione per la convalida del codice di ordinamento del Regno Unito e dei numeri di conto.

L'API fornisce due funzioni principali 'cerca' e 'convalida'. La funzione 'convalida' esegue la validazione del modulo dato una combinazione di codice di ordinamento e numero di conto.
Nel caso in cui sia necessario cercare un codice di ordinamento nella directory banca, è possibile utilizzare la funzione 'cerca' e recuperare le informazioni bancarie e di filiale per quel determinato codice di ordinamento.

Changelog ( dalla v3 alla v4 ):


Nuova struttura di risposta
La nuova versione dell'API SortWare ora offre una struttura di risposta migliorata sia in formato XML che JSON.
Abbiamo suddiviso i risultati in cinque elementi (account_data, bank_data, payment_schemas, validations ed errors)
La struttura è molto simile alla nostra API di convalida IBAN che semplifica l'integrazione quando si utilizzano entrambe le nostre soluzioni. È possibile trovare una descrizione dettagliata della struttura di risposta di seguito (vedere la sezione 4. Struttura di risposta dell'API)

Codici di errore
I codici di errore sono stati implementati nella risposta di SortWare V4 per semplificare l'analisi dei risultati di convalida e delle risposte API.
Come con le altre API, i codici di errore restituiscono la formattazione leggibile dalla macchina per tutti gli errori che l'API V4 potrebbe incontrare.
Vedi la sezione 5. (Codici di errore) per la descrizione dettagliata dei codici di errore restituiti dal sistema.

Funzionalità di calcolo IBAN migliorata
Abbiamo introdotto un algoritmo nuovo e migliorato per il calcolo dell'IBAN da codice di ordinamento e dati del numero di conto per il Regno Unito e l'Irlanda.
La nuova funzionalità utilizza la nostra accurata directory del codice bancario per calcolare gli IBAN con maggiore precisione e ridotta possibilità di errori durante il calcolo.



2. Caratteristiche

L'API SortWare fornisce alcune delle seguenti funzionalità chiave:

  • Recupera le informazioni sulla banca e sul ramo in base al codice di ordinamento.
  • Genera automaticamente un IBAN valido per il codice di ordinamento e il numero di conto forniti
  • Identificare il supporto di pagamenti FPS / CHAPS e Addebito diretto per la banca e il ramo associati al codice di ordinamento fornito.
  • Restituisce risultati multipli visualizzati in una risposta strutturata XML e JSON adattabile al codice

3. Utilizzo API

Questa API consente di automatizzare la convalida del codice di ordinamento e del numero di conto tramite un'unica richiesta HTTP GET o POST.

I parametri accettati sono elencati nella tabella seguente:

Nome del campo Lunghezza Tipo Descrizione
format 4 Stringa Questo parametro può essere uno dei due formati supportati 'xml' o 'json'. Specifica il formato della risposta.
search 6 Stringa Questo parametro può essere utilizzato per cercare un codice di ordinamento nella nostra directory bancaria.
sortcode 6 Stringa Il codice di ordinamento fornito per la convalida in combinazione con il parametro 'account'.
account 8 Stringa Numero di conto bancario fornito per la convalida in combinazione con il parametro 'sortcode'.
api_key 128 Stringa La tua chiave API personale utilizzata per proteggere l'accesso al sistema.
All'interno dell'area clienti -> sezione Accesso API puoi trovare la tua chiave API, che viene utilizzata per identificare il tuo account durante le richieste API.

Abbiamo preparato esempi di invio di una richiesta basata su POST alla nostra API nella maggior parte dei linguaggi comuni:

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. Struttura di risposta dell'API

La risposta dell'API SortWare V4 contiene alcuni oggetti dati per aiutare a separare chiaramente le diverse caratteristiche dei dati restituiti.
Non esitate a fare riferimento allo schema XSD per la risposta in formato XML di seguito:

  
    
      
        
          
            
              
              
              
            
          
        
        
          
            
              
              
              
              
              
              
              
              
            
          
        
        
          
            
              
              
              
              
              
            
          
        
        
          
            
              
                
                  
                    
                    
                  
                
              
            
          
        
        
      
    
  

Di seguito, puoi trovare descrizioni dettagliate dei tipi di elementi di dati restituiti in ogni singolo oggetto di dati:

Descrizione dell'oggetto 'account_data'
Nome del campo Lunghezza Tipo Descrizione
SORTCODE 6 Numero intero Restituisce l'ordinamento codificato che il client ha inviato per riferimento a posteriori.
ACCOUNT 8 Numero intero Contiene il numero di conto inviato dal cliente.
IBAN 125 Stringa Contiene il numero di conto bancario internazionale (IBAN) calcolato dal codice di ordinamento e dal numero di conto validi


Descrizione dell'oggetto "bank_data" contenente informazioni sulla banca emittente e sul ramo del codice di ordinamento inviato
Nome del campo Lunghezza Tipo Descrizione
BIC 8 o 11 Stringa Il codice BIC della banca e del ramo corrispondenti.
BANK 256 Stringa Il nome della banca che detiene il codice di ordinamento inviato.
BRANCH 256 Stringa Nome dello specifico ramo bancario a cui è assegnato il codice di ordinamento.
ADDRESS 256 Stringa Indirizzo del ramo bancario corrispondente a cui appartiene il codice di ordinamento.
CITY 11 Stringa Nome della città in cui si trova la rispettiva filiale.
ZIP 11 Stringa La parte del codice postale dell'indirizzo del ramo bancario.
PHONE 20 Stringa Numero di telefono di contatto per la rispettiva banca e filiale.
COUNTRY 2 Stringa Il codice ISO a due lettere del paese in cui si trovano la banca e la filiale.


Descrizione dell'oggetto 'payment_schemes' che fornisce informazioni sugli schemi di pagamento supportati
Nome del campo Lunghezza Tipo Descrizione
DD 3 Stringa Indicatore per il supporto di addebito diretto della rispettiva filiale. I valori possono essere 'SI' o 'NO'
FPS_PAYMENTS 3 Stringa Indicatore per il supporto Faster Payments Service (FPS) della rispettiva filiale. I valori possono essere 'SI' o 'NO'
CHAPS 3 Stringa Indicatore per supporto pagamenti CHAPS della rispettiva filiale. I valori possono essere 'SI' o 'NO'
BACS 3 Stringa Indicatore per il supporto pagamento BACS della rispettiva filiale. I valori possono essere 'SI' o 'NO'
CCC_PAYMENTS 3 Stringa Indicatore per il supporto dei pagamenti di Check and Credit Clearing Company (C & CCC) della rispettiva filiale. I valori possono essere 'SI' o 'NO'


Descrizione dell'oggetto 'validations'
Nome del campo Lunghezza Tipo Descrizione
CODE 3 Numero intero Restituisce il codice di stato della convalida del modulo eseguita sulla combinazione del codice di banca e del numero di conto. vedere la sezione 5 (Codici di stato) per la descrizione dei valori.
MESSAGE 256 Stringa Contiene la descrizione testuale dei risultati della convalida. Vedere la sezione 5 (codici di stato) per tutti i possibili risultati.


Descrizione dell'oggetto 'errors'
Nome del campo Lunghezza Tipo Descrizione
CODE 3 Numero intero Restituisce il codice di stato dell'errore se tale errore si è verificato. vedere la sezione 5 (Codici di stato) per la descrizione dei valori.
MESSAGE 256 Stringa Contiene una descrizione testuale dell'errore corrente se si è verificato. Vedere la sezione 5 (codici di stato) per tutti i possibili risultati.


5. Codici di stato V4 API SortWare

Esistono due tipi di codici di stato restituiti dall'API.
Il successo o il fallimento della convalida vengono restituiti nell'oggetto dati 'validations'.
Gli errori dell'account vengono restituiti nell'oggetto "errors".

Codice di stato Tipo Descrizione
301 Errore Account La chiave API non è valida
302 Errore Account Abbonamento scaduto
303 Errore Account Nessuna query disponibile
304 Errore Account Non hai accesso a questa API
201 Validazione Fallita La cifra di controllo del numero di conto non è corretta
202 Validazione Fallita Ordina codice non trovato nella directory bancaria
001 Validazione eseguita con successo La cifra di controllo del numero di conto è valida