BIC/SWIFT koda validācijas API

Kā integrēt BIC validācijas API jūsu programmatūrā

1. Kas ir BIC validācijas API?

Apstrādājot banku maksājumus un veicot ar IBAN saistītas transakcijas, veiksmīga maksājuma priekšnosacījums ir pareizi norādīts SWIFT/BIC kods.
Mūsu uzņēmums oficiālo BIC katalogu ir licencējis no "S.W.I.F.T SCRL", lai piedāvātu efektīvu un vienkāršu paņēmienu, kā veikt automātisku BIC validāciju. Šis pakalpojums meklēšanu BIC kodu katalogā ļauj integrēt jūsu programmatūrā iekšējo mērķu izpildes nolūkiem.

BIC validācijas API ietver "SWIFTRef" datus. BIC dati tiek izmantoti ar "S.W.I.F.T. SCRL" atļauju. Tiesības uz datubāzi rezervētas 2019

2. Raksturojums

BIC validācijas API galvenās iezīmes:

  • iegūstiet informāciju par banku, balstoties uz BIC;
  • veiciet meklējumus BIC katalogā pēc bankas nosaukuma daļas vai valsts;
  • veiciet vēsturisko ierakstu meklējumus BIC katalogā;
  • lai vienkāršotu integrāciju, izmantojiet gan visaptverošu, gan vienkāršotu API atbildi.


3. API izmantošana

BIC validācijas API pamatā ir REST tehnoloģija, un tā atbalsta vienkāršus HTTP GET un POST pieprasījumus.

Zemāk redzamajā tabulā doti pieejamie parametri:

Lauka nosaukums Garums Veids Apraksts
bic 11 Virkne Meklējamais BIC/SWIFT kods. Tas var saturēt 8 vai 11 rakstzīmes.
bank_name 256 Virkne Bankas nosaukuma daļa meklējuma veikšanai BIC katalogā.
country 2 Virkne Divu burtu valsts kods. Nepieciešams gadījumos, kad tiek veikta meklēšana pēc bankas nosaukuma.
api_key 128 Virkne Jūsu personīgā API atslēga.
format 4 Virkne Nepieciešams, lai norādītu atbildes datu formātu. Patlaban tiek atbalstītas šādas vērtības: json, xml
limit Vesels skaitlis Neobligāts: var lietot, lai, meklējot pēc bankas nosaukuma, ierobežotu rezultātu skaitu.
hist Vesels skaitlis Neobligāts: var lietot, lai rādītu vēsturiskos ierakstus no datubāzes gan banku, gan BIC meklēšanā.
Savā tiešsaistes portālā jūs atradīsiet savu API atslēgu un pieprasījuma galapunkta URL, ko lieto meklēšanas pieprasījumu veikšanai.


4. API XML atbildes struktūra

Jūs varat lejupielādēt API atbildes XSD shēmu.
Tabulā zemāk dots katra atbildes lauka detalizēts apraksts:

Lauka nosaukums Veids Garums Vienmēr klātesošs Apraksts
MODIFICATION FLAG Alfabētisks 1 Delta failos:
• A (pievienošana);
• M (pārveidošana);
• D (dzēšana);
• A (pievienošana).
CHANGED FIELD Ciparzīmju 186 Fiksē lauku (vai TAG), kas ir mainījies vai nu ieraksta pārveidošanas rezultātā, vai arī jauna notikuma (EVENT) rezultātā.
Viena vai vairākas slejas tiek parādītas kā ciparu virkne, kurā katrs cipars apzīmē izmainīto sleju salīdzinājumā ar iepriekšējo ierakstu vai iepriekšējo EVENT.
Piemērs: "6,7,8,9".
Tas nozīmē, ka ir mainījušies EVENT TYPE, EVENT DATE, BIC8 un
BRANCH BIC.
CHANGED FIELD netiek fiksēti šādi lauki:
• RECORD KEY
• CHANGED FIELD
• MODIFICATION FLAG
RECORD KEY Burtciparu 12 Unikālā atslēga ierakstam failā
Katrs ieraksts ir kāds notikums BIC dzīves ciklā.
Pēc piešķiršanas RECORD KEY nekad nemainās.
PREVIOUS RECORD KEY Burtciparu 12 RECORD KEY no iepriekšējā radniecīgā EVENT
Visi radniecīgie notikumi ir savstarpēji saistīti, un tos var atrast, izmantojot šo informāciju.
NEXT RECORD KEY Burtciparu 12 RECORD KEY no nākamā radniecīgā EVENT
Visi radniecīgie notikumi ir savstarpēji saistīti, un tos var atrast, izmantojot šo informāciju.
EVENT TYPE Alfabētisks 32 EVENT vai ar BIC saistītu izmaiņu, kas notikušas pagātnē vai gaidāmas nākotnē, apraksts.
Notikumu veidi:
• BIC ISSUED
• BIC EXPIRED
• BIC ACTIVATED ON FIN
• BIC ACTIVATED ON FA
• BIC ACTIVATED ON IA
• BIC DEACTIVATED ON FIN
• BIC DEACTIVATED ON FA
• BIC DEACTIVATED ON IA
• BIC DEACTIVATED
• BIC SUSPENDED
• BIC REACTIVATED
• BIC PUBLISHED
• BIC LEGAL NAME CHANGED
• BIC INSTITUTION NAME CHANGED
• BIC ADDRESS CHANGED
• FIN SERVICE CODE CHANGED
Pēdējās atjaunināšanas datums ir BIC sekvences pēdējā rinda (t.i., jaunākais ieraksts).
Pievienojot jaunu EVENT, tiks aktualizētas iepriekšējā
radniecīgā EVENT slejas MODIFICATION FLAG un CHANGED FIELD.
EVENT DATE Burtciparu 8 Notikuma (EVENT) datums
BIC8 Burtciparu 8 BIC (iestādes prefikss, valsts kods un darījuma partnera sufikss), kur:
• prefikss (4 rakstz.);
• valsts kods (2 rakstz.);
• sufikss (2 rakstz.).
BRANCH BIC Burtciparu 3 Ar astoņzīmju BIC saistītais BIC filiāles identifikators. Ja filiāles identifikators neeksistē, lieto XXX.
BIC Burtciparu 11 Pilnais BIC: 8 rakstzīmju BIC un filiāles identifikators
RECORD STATUS Alfabētisks 1 Norāda ieraksta statusu:
• [C] = pašreizējs, atspoguļojot pēdējo notikumu ķēdē līdz informācijas publicēšanas dienai, bet neskaitot nākotnes notikumus;
• [H] = vēsturiskie ieraksti notikumu ķēdē;
• [F] = nākotnes notikums, kas gaidāms pēc datu publicēšanas katalogā. [C] (pašreizējs) notikums ir spēkā līdz [F] (nākotnes) notikuma datumam.
Nākotnes notikuma gadījumā datums norāda uz brīdi, kad attiecīgās izmaiņas STĀSIES SPĒKĀ.
OPERATIONALLY ACTIVE RECORD Alfabētisks 1 Katram BIC ir vairāki ieraksti. Šis lauks norāda, kurš no šiem ierakstiem par vienu un to pašu BIC ir funkcionāli aktīvs BIC un tātad ir izmantojams.
• [Y] funkcionāli aktīvs
• [N] funkcionāli neaktīvs
Katram unikālam BIC ir tikai viens ieraksts ar AKTĪVU statusu (Y).
Ierakstiem ar statusu [H] (vēsturisks) vienmēr tiks parādīts [N].
Ierakstiem ar statusu [C] (pašreizējs) var tikt parādīts gan [Y], gan [N].
ierakstiem ar statusu [F] (nākotne) vienmēr tiks parādīts [N].
SUBTYPE INDICATOR Jebkāds 4 Organizācijas uzņēmējdarbības veids. "Subtype Indicator" (apakštipa indikators) ir pieejams tikai ierakstiem ar BIC.
SWIFT FIN Alfabētisks 1 Organizācijas statuss attiecībā uz saistību ar FIN:
• [Y] ir saistīta ar FIN;
• [N] nav saistīta ar FIN.
SWIFT FA Alfabētisks 1 Statuss attiecībā uz organizācijas sasniedzamību caur "FileAct":
• [Y] ir saistīta ar "FileAct";
• [N] nav saistīta ar "FileAct".
SWIFT IA Alfabētisks 1 Statuss attiecībā uz organizācijas sasniedzamību caur "InterAct":
• [Y] ir saistīta ar "InterAct";
• [N] nav saistīta ar "InterAct".
LEGAL NAME Jebkāds 105 Iestādes juridiskais nosaukums
INSTITUTION NAME Jebkāds 105 Iestādes tirdzniecības nosaukums (publicētais nosaukums)
INSTITUTION TYPE Alfabētisks 12 Organizācija, kas galvenokārt nodarbojas ar finanšu starpniecību un/vai finanšu palīgdarbībām
Iestādes veids (INSTITUTION TYPE):
• FINANCIAL
• NONFINANCIAL
ENTITY TYPE Alfabētisks 16 Identificē finanšu organizācijas tipu
• Legal Entity
• Branch
• Operational
RE STREET ADDRESS 1 Jebkāds 35 [Reģistrācija] Ielas nosaukums
RE STREET ADDRESS 2 Jebkāds 35 [Reģistrācija] Ēkas numurs
RE STREET ADDRESS 3 Jebkāds 35 [Reģistrācija] Ēka, ēkas nosaukums, stāvs
RE STREET ADDRESS 4 Jebkāds 35 [Reģistrācija] Rajons
RE CITY Jebkāds 35 [Reģistrācija] Iestādes/filiāles pilsētas nosaukums
RE CPS Jebkāds 90 [Reģistrācija] Īpašnieka iestādes/filiāles apgabals, province, štats vai cits administratīvais apgabals
RE ZIP CODE Jebkāds 15 [Reģistrācija] Iestādes/filiāles pasta indekss
RE POB NUMBER Jebkāds 35 Komatu saturošs lauks ar iestādes/filiāles pastkastītes numuru un atbilstošo pasta indeksu.
Piemērs
"POB 103352, 40024"
Ļauj klientiem izmantot pilnu pastkastītes adresi:
POB 103352
40024, DUESSELDORF (CITY)
OP STREET ADDRESS 1 Jebkāds 35 [Operatīvā darbība] Ielas nosaukums
OP STREET ADDRESS 2 Jebkāds 35 [Operatīvā darbība] Ēkas numurs
OP STREET ADDRESS 3 Jebkāds 35 [Operatīvā darbība] Ēka, ēkas nosaukums, stāvs
OP STREET ADDRESS 4 Jebkāds 35 [Operatīvā darbība] Rajons
OP CITY Jebkāds 35 [Operatīvā darbība] Iestādes/filiāles pilsētas nosaukums
OP CPS Jebkāds 90 [Operatīvā darbība] Īpašnieka iestādes/filiāles apgabals, province, štats vai cits administratīvais apgabals
OP ZIP CODE Jebkāds 15 [Operatīvā darbība] Iestādes/filiāles pasta indekss
OP POB NUMBER Jebkāds 35 Komatu saturošs lauks ar iestādes/filiāles pastkastītes numuru un atbilstošo pasta indeksu.
Piemērs
"POB 103352, 40024"
Ļauj klientiem izmantot pilnu pastkastītes adresi:
POB 103352
40024, DUESSELDORF (CITY)
BR STREET ADDRESS 1 Jebkāds 35 [Filiāle] Ielas nosaukums
BR STREET ADDRESS 2 Jebkāds 35 [Filiāle] Ēkas numurs
BR STREET ADDRESS 3 Jebkāds 35 [Filiāle] Ēka, ēkas nosaukums, stāvs
BR STREET ADDRESS 4 Jebkāds 35
[Filiāle] Rajons
BR CITY Jebkāds 35 [Filiāle] Iestādes/filiāles pilsētas nosaukums
BR CPS Jebkāds 90 [Filiāle] Īpašnieka iestādes/filiāles apgabals, province, štats vai cits administratīvais apgabals
BR ZIP CODE Jebkāds 15 [Filiāle] Iestādes/filiāles pasta indekss
BR POB NUMBER Jebkāds 35 Komatu saturošs lauks ar iestādes/filiāles pastkastītes numuru un atbilstošo pasta indeksu
Piemērs
"POB 103352, 40024"
Ļauj klientiem izmantot pilnu pastkastītes adresi:
POB 103352
40024, DUESSELDORF (CITY)
BRANCH INFORMATION Jebkāds 70 Informācija par filiāli
Filiāles apraksts brīvā formā, ko sniedz finanšu iestāde, kam pieder šī filiāle. Patlaban tas ir pieejams tikai ierakstiem ar BIC un tikai tad, ja attiecīgā finanšu iestāde vēlas sniegt šo papildu informāciju. Informācija tiek iegūta no BIC kataloga.
COUNTRY NAME Jebkāds 70 Iestādes/filiāles valsts nosaukums atbilstoši ISO 3166
ISO COUNTRY CODE Alfabētisks 2 Iestādes/filiāles valsts ISO 3166-1 alfa-2 kods
LOCATION CODE Jebkāds 1 Norāda atrašanās vietu (oficiāli pēc BIC:2009 standarta: 7. pozīcijā)
Piemēri:
• FR: BIC kodi Parīzē = P;
• BE: BIC kodi Briselē = B;
• US: BIC kodi austrumkrastā = 3.
FIN SERVICE CODES Jebkāds 60 FIN pakalpojumu kodi (saukti arī par pievienotās vērtības pakalpojumu kodiem). FIN SERVICE CODES ir pieejami tikai BIC saturošiem ierakstiem.
Lauks var saturēt līdz pat 20 trīszīmju kodiem alfabētiskā kārtībā.
RECORD KEY BDP Burtciparu 12 Failā esošā unikālā "Bank Directory Plus" ieraksta atslēga
FIELD A Jebkāds 1 Patlaban netiek izmantots
FIELD B Jebkāds 64 Patlaban netiek izmantots
FIELD C Jebkāds 128 Patlaban netiek izmantots
FIELD D Jebkāds 256 Patlaban netiek izmantots
FIELD E Jebkāds 11 Patlaban netiek izmantots
FIELD F Jebkāds 12 Patlaban netiek izmantots
API sistēmas atbildi ir iespējams saņemt XML formātā, kas ļauj to viegli analizēt dažādās programmēšanas valodās un platformās.

Zemāk dots piemērs XML atbildei no API, veicot BIC meklējumu:


<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. API kļūdas

Kļūdas gadījumā API sniedz XML atbildi ar šādu kļūdas paziņojumu:

XML tagi atgriezti bez citiem laukiem XML atbildē.

Zemāk aprakstīti visi iespējamie kļūdu paziņojumi:

Statusa kods Veids Apraksts
301 Account Error API atslēga nav derīga
302 Account Error Abonements beidzies
303 Account Error Nav pieejamu vaicājumu
304 Account Error Jums nav piekļuves šai API
401 Input Error Pieļaujamais SWIFT garums: 8 vai 11 rakstzīmes
402 Input Error Bankas nosaukums nav derīgs! Bankas meklējumam jāsatur ne mazāk kā 4 rakstzīmes.
Atļautās rakstzīmes: a-z, A-Z, 0-9, [atstarpe]!
403 Input Error Valsts kods nav pareizs! Valsts kods drīkst saturēt tikai divus burtus. Piemēri: LV, UK, DE