Documentazione dell'API di calcolo IBAN

Questa API fa parte del nostro servizio IBAN Suite

Guida all'integrazione dell'API

1. Cos'è l'API di calcolo IBAN?

Il motore IBAN Calculation (AKA IBAN Conversion) è un sistema software che consente ai nostri clienti di convertire le combinazioni di codice bancario nazionale e numero di conto in IBAN (International Bank Account Numbers) convalidati.

Il sistema consente l'interfaccia manuale dei nostri clienti e un'API per consentire l'integrazione nei sistemi interni della loro azienda.

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

2. Caratteristiche

Di seguito sono elencate alcune delle funzionalità chiave del nostro motore di calcolo IBAN:

  • Convalida il codice bancario locale / il numero di conto bancario (* vedi Paesi supportati)
  • Recupera le informazioni sulla banca in base al codice banca/filiale locale.
  • Genera automaticamente un formato IBAN valido per il codice banca/filiale e il numero di conto forniti
  • Il sistema supporta la formattazione a risposta multipla (JSON / XML)


3. Paesi supportati

L'API di calcolo IBAN attualmente supporta i seguenti paesi e i campi richiesti dalla nostra API per calcolare un IBAN.

Prefisso internazionale Nome del paese Codice bancario Filiale Account Verifica Cifra **
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
SM San Marino Si Si Si  
CZ Repubblica Ceca Si   Si Si
AL Albania Si   Si  
SK Repubblica Slovacca Si   Si Si
SI Slovenia Si   Si Si
PL Polonia Si   Si Si
PK Pakistan Si   Si  
SE Svezia Si   Si Si
NL Olanda Si Si
La colonna Verifica Cifra specifica se il paese supporta la convalida delle cifre del numero di conto e / o del codice bancario.

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

4. Input API

L'API accetta sia la richiesta HTTP GET che POST per i dati di input.
I parametri accettati sono elencati nella tabella seguente:

Nome del campo Tipo Descrizione
api_key Stringa La tua chiave API personale. Ottenuto nell'area cliente.
format Stringa Formato di risposta API (xml o json)
country Stringa Codice paese di 2 lettere (UK / US / DE / FR)
bankcode Stringa Un identificatore di banca univoco. Diverso per ogni paese (facoltativo). Alcuni paesi richiedono solo il numero di conto.
branch Stringa Un identificativo di filiale locale univoco (facoltativo)
account Stringa Numero di conto personale
cd Numero intero Controllare le cifre utilizzate in alcuni paesi.
prefix Numero intero Attualmente richiesto solo per la Repubblica Ceca (facoltativo)
Il primo argomento è la chiave API, questa è una stringa univoca che aiuta il nostro sistema a identificarti come utente e ti consente di accedere all'API.

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

Le argomentazioni del Paese devono essere composte da un codice paese ISO di 2 lettere, quale il UK per il Regno Unito, il DE per la Germania, il FR per la Francia ...
Il codice bancario ha una lunghezza e una struttura diversa per ogni paese.

Branch Code è un argomento facoltativo richiesto solo per alcuni paesi (fare riferimento agli esempi)
Il numero di conto è richiesto per tutti i paesi e in alcuni casi è l'unico parametro utilizzato per calcolare un IBAN.

Check Digits è richiesto solo per alcuni paesi che hanno incorporato tali algoritmi di convalida nella loro struttura numerica del conto bancario nazionale. (fare riferimento agli esempi)

Il prefisso è un campo facoltativo richiesto solo per il calcolo IBAN Repubblica ceca.

5. Esempi di API

Nella tabella seguente puoi trovare l'esempio di query GET di lavoro alla nostra API per ogni paese.

Nazione Query 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
PK ?country=PK&format=json&bankcode=HABBPKKA&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. Struttura di risposta XML dell'API

Una tabella dettagliata dei possibili campi restituiti può essere vista nella tabella seguente:

Nome del campo Tipo Descrizione
address Stringa Indirizzo della filiale bancaria o della sede centrale
bank Stringa Nome della banca o istituto finanziario
bic Stringa BIC (Bank Identifier Code) della banca
branch Stringa Nome della filiale identificata dal codice bancario
city Stringa Il nome della città in cui si trova il ramo.
country Stringa Abbreviazione di due lettere del codice del paese, ad esempio Stati Uniti, Regno Unito, Regno Unito, Francia, ecc.
email Stringa Indirizzo email di contatto nominato per la banca o la filiale
fax Stringa Numero di fax della banca/filiale
phone Stringa Numero di telefono di contatto della banca/filiale
state Stringa Stato dell'indirizzo banca/filiale
website Stringa Indirizzo del sito web della banca/filiale
zip Stringa CAP o codice postale dell'indirizzo della filiale bancaria
Il sistema API restituisce risultati in formato XML o JSON, che è facile da analizzare in una varietà di linguaggi e piattaforme di programmazione.

Una risposta XML di esempio dall'API per un codice SORT del Regno Unito e la ricerca del numero di conto potrebbe essere:

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, l'API di calcolo IBAN restituisce una risposta XML o JSON contenente il messaggio di errore.
I tag XML <error></error> vengono restituiti senza altri campi nella risposta XML.
Di seguito è possibile trovare una descrizione di tutti i possibili messaggi di errore che potrebbero essere restituiti:

<error>Il checksum del numero di conto non è valido.</error>
<error>Numero account (checksum) non è corretto.</error>
<error> Il numero di conto deve essere lungo 11 caratteri</error>
<error> Il numero di conto deve essere lungo 14 caratteri</error>
<error> Il numero dell'account deve essere lungo 24 caratteri</error>
<error>Numero account non è valido</error>
<error>Numero account del codice di ordinamento non è valido</error>
<error>Prefisso del numero di conto troppo lungo.</error>
<error>Numero account troppo lungo.</error>
<error>Bank / Branch Code / KIB (checksum) non è corretto.</error>
<error>Codice banca / Codice filiale / Numero account troppo lungo.</error>
<error>Codice bancario / Codice filiale (checksum) non corretto.</error>
<error>Codice banca non valido</error>
<error>Codice banca troppo lungo.</error>
<error>Banca non trovata</​​error>
<error>Banca non riconosciuta</​​error>
<error>BBAN / NIB (checksum) non è corretto.</error>
<error>BLZ / codice banca non valido</error>
<error>Filiale / Agenzia non trovato</error>
<error>Codice filiale troppo lungo.</error>
<error>Filiale non trovata</​​error>
<error>Verifica cifra troppo lunga.</error>
<error> Clearingnummer / Account Number non è valido. Verifica cifra errata.</error>
<error>Clearingnummer / BankCode non può essere identificato. L'IBAN non può essere calcolato.</error>
<error>Clearingnummer o Numero account troppo lungo.</error>
<error>Codice ABI della Banca / Codice banca non valido</error>
<error>Codice CAB della Filiale / Codice filiale non valido</error>
<error>Il codice paese non è valido</error>
<error>Paese o banca non supportati</error>
<error>IBAN non è valido</error>
<error> Kontonummer / Account Number non è valido</error>
<error>Campi mancanti</error>
<error>IBAN non FR</error>
<error>Paese IBAN non FR</error>
<error>Il campo obbligatorio è mancante. Inserisci il codice banca e il numero di conto</error>
<error>Campi obbligatori non inviati.</error>
<error>RIB non è valido</error>
<error>SortCode / BankCode non può essere identificato. L'IBAN non può essere calcolato.</error>
<error>Impossibile trovare il codice di ordinamento</error>