Validazione API BIC / SWIFT Code

Come integrare l'API di convalida BIC nel tuo software

1. Cos'è l'API di convalida BIC?

Quando si elaborano i bonifici bancari e si fa riferimento alle transazioni relative all'IBAN, fornire il codice SWIFT / BIC corretto è vitale per effettuare pagamenti corretti.
La nostra azienda ha in licenza la directory BIC ufficiale concessa da SWIFT SCRL per fornire un modo semplice e potente per convalidare automaticamente i BIC. Questo servizio consente di integrare la ricerca della directory del codice BIC nel software per scopi interni

L'API di convalida BIC ha SWIFTRef Data Inside. I dati BIC sono usati con il permesso di S.W.I.F.T. SCRL. Database rights reserved 2018

2. Caratteristiche

Funzioni chiave dell'API di convalida BIC:

  • Recupera le informazioni sulla banca in base al BIC.
  • Cerca nella directory BIC una parte del nome della banca e del Paese.
  • Cerca nella directory BIC per i record storici.
  • Utilizza la risposta API completa e semplificata per un'integrazione più semplice.


3. Utilizzo API

L'API di convalida BIC è basata su REST e supporta semplici richieste HTTP GET o POST.

I parametri accettati sono elencati nella tabella seguente:

Nome del campo Lunghezza Tipo Descrizione
bic 11 Stringa Codice BIC / SWIFT per la ricerca. Può contenere 8 o 11 caratteri
bank_name 256 Stringa Parte di un nome di banca per eseguire la ricerca nella directory BIC.
country 2 Stringa Codice paese di due lettere. Richiesto durante la ricerca per nome della banca.
api_key 128 Stringa La tua chiave API personale.
format 4 Stringa Necessario per specificare il formato dei dati restituiti. Valori attualmente supportati: json, xml
limit Numero intero Facoltativo: può essere utilizzato per limitare il numero di risultati durante la ricerca per nome della banca.
hist Numero intero Facoltativo: può essere utilizzato per visualizzare record storici dal database sia per la ricerca bancaria che per quella BIC.
All'interno del tuo portale online puoi trovare la tua chiave API e l'URL dell'endpoint di richiesta, che viene utilizzato per proteggere le richieste di ricerca.


4. Struttura di risposta XML dell'API

È possibile scaricare uno schema XSD della risposta dell'API.
Una descrizione dettagliata dei campi restituiti può essere vista nella tabella seguente:

Nome del campo Tipo Lunghezza Sempre presente Descrizione
MODIFICATION FLAG Alfabetico 1 Si Nei file delta:
• A (aggiunta)
• M (modifica)
• D (eliminazione) in file completi In file completi:
• A (aggiunta)
CHANGED FIELD Numerico 186 No Registra il campo (o TAG) che è stato modificato a seguito di una modifica a un record o come risultato di un nuovo evento.
Una o più colonne sono indicate come una sequenza di numeri con ciascun numero che rappresenta la colonna modificata rispetto all'istanza del record precedente o EVENTO precedente.
Esempio "6,7,8,9"
Ciò significa che TIPO EVENTO, DATA EVENTO, BIC8 e FILIALE BIC sono
cambiati.
I seguenti campi sono esclusi dalla registrazione in CAMPO CAMBIATO:
• TASTO DI REGISTRAZIONE
• CAMPO CAMBIATO
• BANDIERA DI MODIFICA
RECORD KEY Alfanumerico 12 Si La chiave univoca del record nel file
Ogni record rappresenta un evento nel ciclo di vita del BIC.
Una volta assegnato, il tasto RECORD KEY non cambia mai.
PREVIOUS RECORD KEY Alfanumerico 12 No La chiave RECORD dell'evento EVENT collegato in precedenza
Tutti gli eventi correlati sono collegati e possono essere individuati utilizzando queste informazioni.
NEXT RECORD KEY Alfanumerico 12 No La chiave RECORD del successivo evento collegato correlato
Tutti gli eventi correlati sono collegati e possono essere individuati utilizzando queste informazioni
EVENT TYPE Alfabetico 32 Si L'EVENTO o modifica descrizione relativa al BIC che si è verificato nel passato, nel presente o che si verificherà in futuro.
Tipi di eventi:
• BIC PROBLEMA
• BIC SCADUTO
• BIC ATTIVATO SULLA FIN
• BIC ATTIVATO SU FA
• BIC ATTIVATO SU IA
• BIC DISATTIVATO SULLA FIN
• BIC DISATTIVATO SU FA
• BIC DISATTIVATO SU IA
• BIC DISATTIVATO
• BIC SOSPESO
• BIC REATTIVATO
• BIC PUBBLICATO
• IL NOME GIURIDICO BIC È STATO CAMBIATO
• IL NOME DELL'ISTITUZIONE BIC È STATO CAMBIATO
• L'INDIRIZZO BIC È CAMBIATO
• MODIFICA DEL CODICE SERVIZIO FIN
L'ultima data di aggiornamento è l'ultima riga della sequenza BIC (ovvero la voce più recente).
Quando viene aggiunto un nuovo EVENTO, il MODIFICA BANDIERA e MODIFICATO
La colonna CAMPO verrà aggiornata nell'EVENTO correlato immediatamente precedente.
EVENT DATE Alfanumerico 8 Si La data dell'evento
BIC8 Alfanumerico 8 Si BIC (prefisso ente, paese e gruppo) dove:
• Prefisso gruppo (4 caratteri)
• Codice paese (2 caratteri)
• Prefisso gruppo (2 caratteri)
BRANCH BIC Alfanumerico 3 Si L'identificativo di ramo BIC associato al BIC di 8 caratteri. Se non esiste alcun identificatore di ramo, viene utilizzato XXX.
BIC Alfanumerico 11 Si Il BIC completo: BIC a 8 caratteri e identificativo di ramo
RECORD STATUS Alfabetico 1 Si Indica lo stato del record:
• [C] = Corrente che rappresenta l'ultimo evento della catena fino alla data di pubblicazione, esclusi gli [F] eventi reali
• [H] = record storici nella catena di eventi
• [F] = evento futuro che si verificherà dopo la data di pubblicazione della directory. L'evento [C]currente precedentemente indicato sarà valido fino alla data specificata nell'evento [F] uturo.
Per gli eventi FUTURO, la data indica quando il cambiamento sarà VALIDO DA.
OPERATIONALLY ACTIVE RECORD Alfa 1 Si Esistono più record per lo stesso BIC. Questo campo indica quale dei record per lo stesso BIC è il BIC operativamente attivo e deve essere utilizzato.
• [Y] Operativamente attivo
• [N] Operativamente inattivo
Per ogni BIC univoco, c'è una singola voce del record che indica uno stato ACTIVE (Y).
Record con stato storico [H] indicheranno sempre [N].
Record con [C] urrent possono indicare [Y] o [N].
I record con [F] indicano sempre [N].
SUBTYPE INDICATOR Qualsiasi tipo 4 Si Il tipo di attività dell'entità. Indicatore di sottotipo viene fornito solo per i record con un BIC.
SWIFT FIN Alfabetico 1 Si Stato della connessione di un'entità a FIN:
• [Y] collegato a FIN
• [N] non connesso a FIN
SWIFT FA Alfabetico 1 Si Stato della raggiungibilità di un'entità tramite FileAct:
• [Y] connesso a FileAct
• [N] non connesso a FileAct
SWIFT IA Alfa 1 Si Stato della raggiungibilità di un entità attraverso InterAct:
• [Y] collegato a InterAct
• [N] non connesso a InterAct
LEGAL NAME Qualunque 105 No Nome legale dell'istituzione
INSTITUTION NAME Qualunque 105 Si Nome commerciale dell'istituzione (nome pubblicato)
INSTITUTION TYPE Alfabetico 12 Si Organizzazione che si occupa principalmente dell'intermediazione finanziaria e / o di attività finanziarie ausiliarie
Tipo di istituzione:
• FINANZIARIO
• NON FINANZIARIO
ENTITY TYPE Alfabetico 16 Si Identifica il tipo di entità finanziaria:
• Entità Legale
Filiale
• Operativo
RE STREET ADDRESS 1 Qualunque 35 No [Registrazione] Nome della via
RE STREET ADDRESS 2 Qualunque 35 No [Registrazione] Numero civico
RE STREET ADDRESS 3 Qualunque 35 No [Registrazione] Edificio, nome dell'edificio, piano
RE STREET ADDRESS 4 Qualunque 35 No [Registrazione] Area
RE CITY Qualunque 35 No [Registrazione] Nome città dell'istituzione/filiale
RE CPS Qualunque 90 No [Registrazione] Regione, provincia, stato o altra regione amministrativa dell'istituzione/filiale proprietario
RE ZIP CODE Qualunque 15 No [Registrazione] Codice postale dell'istituzione/filiale
RE POB NUMBER Qualunque 35 No Campo separato da virgola con il numero POB dell'istituzione/filiale e il relativo codice di avviamento postale.
Esempio
"POB 103352, 40024"
Ciò consente ai clienti di utilizzare l'indirizzo POB completo:
POB 103352
40024, DUESSELDORF (CITTÀ)
OP STREET ADDRESS 1 Qualunque 35 No [Operational] Nome della strada
OP STREET ADDRESS 2 Qualunque 35 No [Operativo] Numero civico
OP STREET ADDRESS 3 Qualunque 35 No [Operativo] Edificio, nome dell'edificio, piano
OP STREET ADDRESS 4 Qualunque 35 No [Operational] Area
OP CITY Qualunque 35 No [Operational] Nome della città dell'istituzione/filiale
OP CPS Qualunque 90 No [Operativo] Contea, provincia, stato o altra regione amministrativa dell'istituzione/filiale proprietario
OP ZIP CODE Qualunque 15 No [Operational] Codice postale dell'istituzione/filiale
OP POB NUMBER Qualunque 35 No Campo separato da virgola con il numero POB dell'istituzione/filiale e il relativo codice di avviamento postale.
Esempio
"POB 103352, 40024"
Ciò consente ai clienti di utilizzare l'indirizzo POB completo:
POB 103352
40024, DUESSELDORF (CITTÀ)
BR STREET ADDRESS 1 Qualunque 35 No [Filiale] Nome della via
BR STREET ADDRESS 2 Qualunque 35 No [Filiale] Numero civico
BR STREET ADDRESS 3 Qualunque 35 No [Filiale] Edificio, nome dell'edificio, piano
BR STREET ADDRESS 4 Qualunque 35 No [Filiale] Area
BR CITY Qualunque 35 No [Filiale] Nome della città dell'istituzione/filiale
BR CPS Qualunque 90 No [Filiale] Regione, provincia, stato o altra regione amministrativa dell'istituzione/filiale proprietario
BR ZIP CODE Qualunque 15 No [Filiale] Codice postale dell'istituzione/filiale
BR POB NUMBER Qualunque 35 No Campo separato da virgola con il numero POB dell'istituzione/filiale e il relativo codice di avviamento postale.
Esempio
"POB 103352, 40024"
Ciò consente ai clienti di utilizzare l'indirizzo POB completo:
POB 103352
40024, DUESSELDORF (CITTÀ)
BRANCH INFORMATION Qualunque 70 No Informazioni sulla filiale
Questa è una descrizione a testo libero del ramo fornita dall'istituto finanziario a cui appartiene. Per il momento questo sarà fornito solo per le voci con un BIC e solo quando l'istituto finanziario interessato vuole fornire queste informazioni extra. Le informazioni provengono dalla directory BIC.
COUNTRY NAME Qualunque 70 Si Il nome del paese dell'istituzione/filiale come indicato nella ISO 3166
ISO COUNTRY CODE Alfabetico 2 Si Il codice ISO 3166-1 alfa-2 del paese dell'istituzione/filiale
LOCATION CODE Qualsiasi tipo 1 Si Contiene la posizione (formalmente nella posizione 7 dello standard BIC: 2009)
Esempi:
• In FR, BIC a Parigi = P
• In BE, BIC a Bruxelles = B
• Negli Stati Uniti, BIC in East Cost = 3
FIN SERVICE CODES Qualsiasi tipo 60 No Codici di servizio FIN (detti anche codici di servizio a valore aggiunto). I codici di servizio sono forniti solo per i record contenenti un BIC.
Il campo può contenere fino a 20 codici a tre caratteri in ordine alfabetico.
RECORD KEY BDP Alfanumerico 12 No La chiave univoca del record di Bank Directory Plus nel file.
FIELD A Qualunque 1 No Riservato per uso futuro
FIELD B Qualunque 64 No Riservato per uso futuro
FIELD C Qualunque 128 No Riservato per uso futuro
FIELD D Qualunque 256 No Riservato per uso futuro
FIELD E Qualunque 11 No Riservato per uso futuro
FIELD F Qualunque 12 No Riservato per uso futuro
Il sistema API restituisce risultati in formato XML, che è facile da analizzare in una varietà di linguaggi e piattaforme di programmazione.

Una risposta XML di esempio dall'API per una ricerca BIC sarebbe:


<result>
<bicdata>
<row>
<modification_flag>A</modification_flag>
<changed_field>34</changed_field>
<record_key>BP0000004OQQ</record_key>
<previous_record_key>BP00000030XZ</previous_record_key>
<next_record_key/>
<event_type>BIC ADDRESS CHANGED</event_type>
<event_date>20150606</event_date>
<bic8>BARCGB22</bic8>
<branch_bic>XXX</branch_bic>
<bic>BARCGB22XXX</bic>
<record_status>C</record_status>
<operationally_active_record>Y</operationally_active_record>
<subtype_indicator>SUPE</subtype_indicator>
<swift_fin>Y</swift_fin>
<swift_fa>N</swift_fa>
<swift_ia>N</swift_ia>
<legal_name>BARCLAYS BANK PLC</legal_name>
<institution_name>BARCLAYS BANK PLC</institution_name>
<institution_type>FINANCIAL</institution_type>
<entity_type>Legal Entity</entity_type>
<re_street_address_1>1, CHURCHILL PLACE</re_street_address_1>
<re_street_address_2/>
<re_street_address_3/>
<re_street_address_4/>
<re_city>LONDON</re_city>
<re_cps/>
<re_zip_code>E14 5HP</re_zip_code>
<re_pob_number/>
<op_street_address_1>1 CHURCHILL PLACE</op_street_address_1>
<op_street_address_2/>
<op_street_address_3/>
<op_street_address_4/>
<op_city>LONDON</op_city>
<op_cps>LONDON E14 5HP</op_cps>
<op_zip_code/>
<op_pob_number/>
<br_street_address_1/>
<br_street_address_2/>
<br_street_address_3/>
<br_street_address_4/>
<br_city/>
<br_cps/>
<br_zip_code/>
<br_pob_number/>
<branch_information>(ALL U.K. OFFICES)</branch_information>
<country_name>UNITED KINGDOM</country_name>
<iso_country_code>GB</iso_country_code>
<location_code>2</location_code>
<fin_service_codes>EBAERPFINSCOSTGTGT</fin_service_codes>
<record_key_bdp>BD00000006FO</record_key_bdp>
<field_a/>
<field_b/>
<field_c/>
<field_d/>
<field_e/>
<field_f></field_f>
</row>
</bicdata>
<errors/>
</result>




5. Errori API

In caso di errore, l'API restituisce una risposta XML contenente il messaggio di errore.

Il I tag XML 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:

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
401 Errore di input Lunghezza SWIFT accettata 8 o 11 caratteri
402 Errore di input Nome banca non valido! La ricerca bancaria deve avere un minimo di 4 caratteri.
Caratteri consentiti az, AZ, 0-9, [spazio]!
403 Errore di input Codice Paese errato! Consentito è un codice paese di 2 lettere. Esempio: UK, DE, FR