Documentazione API calcolo IBAN



Guida integrazione API


1. Cosa sono le API per il calcolo dell'IBAN?


Il motore di calcolo IBAN ( AKA Conversione IBAN ) è un sistema software che consente ai nostri clienti di convertire combinazioni di codice bancario ed il numero di conto domestico in numeri di conto bancario internazionale convalidati ( IBAN ).

Il sistema permette ai nostri clienti sia un'interfaccia manuale che delle API per premettere l'integrazione nei sistemi interni della propria azienda.

Il sistema identifica anche le banche e le istituzioni finanziarie e fornisce i dettagli ai nostri clienti.



2. Caratteristiche


Qui di seguito vi sono alcune delle caratteristiche principali del nostro motore di calcolo IBAN:




3. Paesi supportati


L'API per il calcolo IBAN al momento supporta i seguenti paesi e i campi richiesti dalla nostra API per calcolare l'IBAN.

Codice Paese Nome Paese CodiceBanca Filiale Conto Codice di Controllo
AT Austria SI   SI  
BE Belgio SI   SI SI
CH Svizzera SI   SI  
DE Germania SI   SI  
EE Estonia     SI  
ES Spagna SI SI SI SI
FI Finlandia     SI SI
FR Francia SI SI SI SI
GB Gran Bretagna SI   SI SI
HU Ungheria     SI SI
IE Irlanda SI   SI SI
IT Italia SI SI SI SI
MC Monaco SI SI SI SI
MR Mauritania SI SI SI  
MT Malta SI   SI  
NO Norvegia     SI SI
PT Portogallo SI SI SI SI
SE Svezia SI   SI  
SM San  Marino SI SI SI  
CZ Repubblica Ceca SI   SI SI
AL Albania SI   SI  
SK Slovacchia SI   SI SI
SI Slovenia SI   SI SI
PL Polonia SI   SI SI
SE Svezia SI   SI SI
NL Netherlandds SI SI
La colonna del Codice di Controllo specifica se il paese supporta un numero di conto e/o la convalida del codice di controllo della banca.

La convalida del codice di controllo è un ulteriore livello di protezione dell'integrità dei dati contro gli errori di battitura.



4. API Inputs


The API accepts both HTTP GET and POST request for input data.
The accepted parameters are listed in the table below:

L'API accetta sia richieste HTTP GET e POST per i dati in input.
I parametri accettati sono elencati nella seguente tabella:
Nome Campo Tipo Descrizione
api_key Stringa La tua Apy Key personale. Si ottiene nell'area clienti.
format String Formato risposta API ( xml or json )
country String Codice paese di 2 lettere ( UK/US/DE/FR )
bankcode String Un identificativo bancario unico. Diverso per ogni paese. ( opzionale ). Alcuni paesi richiedolo solamente un codice di conto.
branch String In identificativo di filiale unico ( opzionale )
account String Numero dell'account personale
cd Integer Codice di Controllo utilizzato in alcuni paesi. ( opzionale ).
prefix Integer Al momento richiesto solo in Replubblica Ceca ( opzionale )
Il primo argomento è la chiave API, si tratta di una stringa univoca che aiuta il nostro sistema di identificarti come utente e ti permette di accedere alle API.

L'API supporta diversi formati di risposta al fine di fornire una più facile integrazione. Attualmente sono supportati XML e JSON.

Gli argomenti Paese devono essere costituiti da un codice ISO di 2 lettere come UK per il Regno Unito, DE per la Germania, FR per la Francia...
Il Codice banca ha lunghezza e struttura diverse per ogni paese.

Il Codice filiale è un argomento opzionale richiesto solo in alcuni paesi (vedi esempi)

È richiesto il numero di conto per tutti i paesi e in alcuni casi è l'unico parametro utilizzato per calcolare un codice IBAN.

Il Codice di Controllo è richiesto solo in alcuni paesi che includono tali algoritmi di validazione nella loro struttura di numero di conto bancario domestico. (Vedi esempi)

Il Prefisso è un campo opzionale richiesto solo per il calcolo dell'IBAN in Repubblica Ceca.



5. Esempi API


Nella tabella qui sotto puoi trovare un esempio funzionante di query GET alla nostra API per ogni paese.

Paese Query di esempio (GET REQUEST)
AT ?country=AT&format=json&bankcode=12000&account=52700357958
BE ?country=BE&format=json&bankcode=250&account=0135106&cd=70
CH ?country=CH&format=json&bankcode=0240&account=240C08011570
DE ?country=DE&format=json&bankcode=BLZ37010050&account=399509
EE ?country=EE&format=json&account=55000005511439
ES ?country=ES&format=json&bankcode=0081&branch=1731&cd=91&account=0006040912
FI ?country=FI&format=json&account=52900261901092
FR ?country=FR&format=json&bankcode=30056&branch=00264&account=02640016443
GB ?country=GB&format=json&bankcode=090127&account=93496333
HU ?country=HU&format=json&account=107000240416330551100005
IE ?country=IE&format=json&bankcode=905838&account=71924374
IT ?country=IT&format=json&country=IT&bankcode=02008&branch=30545&account=000103685854
MC ?country=MC&format=json&country=MC&bankcode=30002&branch=03260&account=0000079112A
MR ?country=MR&format=json&bankcode=00012&branch=00001&account=00000078326
MT ?country=MT&format=json&bankcode=07113&account=199008240010
NO ?country=NO&format=json&account=96803502045
PT ?country=PT&format=json&bankcode=0038&branch=0000&cd=81&account=39551148771
SE ?country=SE&format=json&bankcode=9150&account=0092395696
SM ?country=SM&format=json&country=SM&bankcode=03034&branch=09800&account=000060164676
CZ ?country=CZ&format=json&prefix=51&account=1707230277&bankcode=0100
AL ?country=AL&format=json&bankcode=20511117&account=374362CLPRCFEURC
SK ?country=SK&format=json&prefix=&account=4110053902&bankcode=3100
SI ?country=SI&format=json&bankcode=33000&account=0000102423
PL ?country=PL&format=xml&bankcode=11402004&account=0000360275244226
SE ?country=SE&format=json&bankcode=9300&account=5913222524
NL ?country=NL&format=json&account=0006642318




6. API XML Response Structure


A detailed description of the possible fields returned can be seen in the table below:

Nome Campo Tipo Descrizione
address String Indirizzo della filiale della banca o della sede
bank String Nome della banca o dell'istituto finanziario
bic String BIC (Bank Identifier Code) della banca
branch String Nome della filiale identificata dal codice bancario
city String Il nome della città in cui si trova la filiale.
country String Abbreviazione del codice del paese di due lettere, per esempio US, UK, AU, FR … etc.
email String Indirizzo e-mail di contatto per la banca o per la filiale
fax String Numero di fax della banca / filiale
phone String Numero di telefono della banca / filiale
state String Nazione della banca/filiale
website String Indirizzo Web della banca / filiale
zip String ZIP o CAP dell'indirizzo della banca / filiale
Il sistema API restituisce i risultati in formato XML o JSON, che è facile da analizzare da una varietà di linguaggi di programmazione e piattaforme.

Una risposta XML di esempio dall'API per una ricerca di codice SORT e numero di conto del Regno Unito sarebbe:

Query URL:

?api_key=9834hAHx78ba4g8habsdk&country=GB&format=json&bankcode=110377&account=10218962

<result>
<iban>GB20ULSB98006054100029</iban>
<account>54100029</account>
<sort_code>980060</sort_code>
<bank>ULSTER BANK LTD</bank>
<branch>BELFAST CITY OFFICE 1</branch>
<bic>ULSBGB2BXXX</bic>
<address>PO BOX 232 11-16 DONEGALL SQUARE EAST </address>
<city>BT1 5UB</city>
<country>GB<country/>
<phone>028 90244112</phone>
</result>

La risposta per la stessa query se l'utente ha specificato una formattazione JSON sarà:

"iban":"GB20ULSB98006054100029","account":"54100029","sort_code":"980060","bank":"ULSTER BANK LTD","branch":"BELFAST CITY OFFICE 1","bic":"ULSBGB2BXXX","address":"PO BOX 232 11-16 DONEGALL SQUARE EAST ","city":"BT1 5UB","country":"GB","phone":"028 90244112"



7. Errori API


In caso di errore di calcolo del codice IBAN l'API restituisce una risposta XML o JSON contenente il messaggio di errore.
Gli <error></error> vengono restituiti senza alcun altro campo nella risposta XML.
Qui sotto puoi trovare una descrizione di tutti i possibili messaggi di errore che possono essere restituiti:

<error>Account Number checksum is invalid.</error>
<error>Account Number (checksum) is not correct.</error>
<error>Account Number has to be 11 characters long</error>
<error>Account Number has to be 14 characters long</error>
<error>Account Number has to be 24 characters long</error>
<error>Account Number is not valid</error>
<error>Account Number of Sort Code is not valid</error>
<error>Account Number prefix too long.</error>
<error>Account Number too long.</error>
<error>Bank/Branch Code / KIB (checksum) is not correct.</error>
<error>Bank Code/ Branch Code/ Account Number too long.</error>
<error>Bank Code/ Branch Code (checksum) is not correct.</error>
<error>Bank Code not valid</error>
<error>Bank Code too long.</error>
<error>Bank Not Found</error>
<error>Bank Not Recognized</error>
<error>BBAN / NIB (checksum) is not correct.</error>
<error>BLZ/Bank Code not valid</error>
<error>Branch/Agencia not found</error>
<error>Branch Code too long.</error>
<error>Branch not found</error>
<error>Check Digit too long.</error>
<error>Clearingnummer/Account Number is not valid. Check digit incorrect.</error>
<error>Clearingnummer / BankCode can not be identified. IBAN can not be calculated.</error>
<error>Clearingnummer or Account Number too long.</error>
<error>Codice ABI della Banca/Bank Code not valid</error>
<error>Codice CAB della Filiale/Branch Code not valid</error>
<error>Country code is not valid</error>
<error>Country or Bank not supported</error>
<error>IBAN is not valid</error>
<error>Kontonummer/Account Number is not valid</error>
<error>Missing fields</error>
<error>Non FR IBAN</error>
<error>Non FR IBAN country</error>
<error>Required field is missing. Please enter Bank Code and Account Number</error>
<error>Required fields not submitted.</error>
<error>RIB is not valid</error>
<error>SortCode / BankCode can not be identified. IBAN can not be calculated.</error>
<error>Sort code cannot be found</error>