IBAN 계산 API 기록

해당 API는 IBAN 제품군 서비스의 일부입니다

API 통합 가이드

1. IBAN 계산 API란?

IBAN 계산(AKA IBAN 컨버전) 엔진은 고객이 국내 은행 코드와 계좌 번호 조합을 검증된 IBAN(국제 은행 계좌 번호)으로 변환할 수 있는 소프트웨어 시스템입니다.

이 시스템은 고객의 수동 인터페이스와 API를 통해 회사 내부 시스템에 통합할 수 있습니다.

해당 시스템은 또한 은행과 금융 기관을 식별하고 세부 정보를 고객에게 제공합니다.

2. 기능

IBAN 계산 엔진의 주요 기능은 아래에 나열된 다음과 같습니다:

지역 은행 코드/계좌 번호 체크섬을 확인합니다( *지원 국가 참조 )
지역 은행/지점을 기준으로 은행에 대한 정보를 검색합니다.
제공된 은행/지점 코드 및 계좌 번호에 유효한 IBAN 형식을 자동으로 생성합니다
시스템은 다중 응답 형식( JSON / XML )을 지원합니다

3. 지원 국가

IBAN Calculation API는 현재 IBAN을 계산하는 데 필요한 다음의 국가 및 필드를 지원합니다.

국가 코드	국가명	은행코드	지점	계좌	숫자 ** 를 확인하십시오
AT	오스트리아	네		네
BE	벨기에	네		네	네
CH	스위스	네		네
DE	도이칠란트	네		네
EE	에스토니아			네
ES	스페인	네	네	네	네
FI	핀란드			네	네
FR	프랑스	네	네	네	네
GB	영국	네		네	네
HU	헝가리			네	네
IE	아일랜드	네		네	네
IT	이탈리아	네	네	네	네
MC	모나코	네	네	네	네
MR	모리타니아	네	네	네
MT	몰타	네		네
NO	노르웨이			네	네
PT	포르투갈	네	네	네	네
SM	산마리노	네	네	네
CZ	체코 공화국	네		네	네
AL	알바니아	네		네
SK	슬로바키아	네		네	네
SI	슬로베니아 공화국	네		네	네
PL	폴란드	네		네	네
PK	파키스탄	네		네
SE	스웨덴	네		네	네
NL	네덜란드			네	네

체크 디지트(Check Digit) 열은 국가가 계좌 번호 및/또는 은행 코드 체크 디지트 유효성 검사를 지원하는지의 여부를 지정합니다.

체크 디지트 검증은 입력 오류에 대한 데이터 완전성 보호의 추가 레이어입니다.

4. API 입력

API는 입력 데이터에 관한 HTTP GET 및 POST 요청을 모두 수락합니다.
허용된 매개변수는 아래 표에 나열됩니다:

필드명	유형	설명
api_key	줄	개인 API 키입니다. 고객 영역에 확보됩니다.
포멧	줄	API 응답 형식 ( xml or json )
국가	줄	2자 국가 코드 ( UK/US/DE/FR )
은행코드	줄	고유의 은행 식별자. 나라마다 다릅니다. (선택 사항) 일부 국가에서는 계좌 번호만 요구합니다.
지점	줄	고유의 로컬 지점 식별자(선택 사항)
계좌	줄	개인 계좌 번호
cd	정수	일부 국가에서 사용되는 체크 디지트
접두사	정수	현재 체코에만 필요 ( 선택사항 )

첫 번째 인수는 API 키이며 이는 시스템이 귀하를 사용자로 식별하고 API에 접근할 수 있도록 지원하는 고유의 문자열입니다.

API는 보다 쉽게 통합할 수 있도록 여러 응답 형식을 지원합니다. 현재 XML과 JSON이 지원됩니다.

국가 인수는 영국의 경우 UK , 독일의 경우 DE, 프랑스의 경우 FR과 같은 2자의 ISO 국가 코드로 구성되어야 합니다 …
은행 코드는 국가마다 길이 및 구성이 다릅니다

지점 코드는 일부 국가에서만 필요한 선택적 인수입니다(예시 참조)
계좌 번호는 모든 국가에 필요하며, 경우에 따라 IBAN을 계산하는 데 사용되는 유일한 매개 변수입니다.

체크 디지트은 이러한 검증 알고리즘을 국내 은행 계좌 번호 구조에 통합한 특정 국가에만 필요합니다. ( 예시 참조 )

접두사는 선택적으로 체코 공화국 IBAN 계산에만 필요한 필드입니다.

5. API 예시

아래 표에는 각 국가의 API에 대한 GET 쿼리의 작동 예시가 나와 있습니다

국가	쿼리 예시 (GET 요청)
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. API XML 응답 구조

반환될 수 있는 필드에 관한 자세한 설명은 아래 표를 참조하십시오:

필드명	유형	설명
주소	문자열	은행 지점 또는 본사 주소
은행	문자열	은행 또는 금융 기관의 이름
bic	문자열	은행의 BIC ( 은행 식별자 코드 )
지점	문자열	은행 코드로 식별된 지점 이름
도시	문자열	지점이 위치한 도시의 이름
국가	문자열	국가 코드 2글자의 약어 (예시: US, UK, AU, FR 등...)
이메일	문자열	은행 또는 지점에 대해 예약된 연락처 이메일 주소
팩스	문자열	은행/지점의 팩스 번호
전화	문자열	은행 / 지점의 전화번호
상태	문자열	은행/지점 주소의 상태
웹 사이트	문자열	은행/지점의 웹 사이트 주소
우편번호	문자열	은행 지점 주소의 우편 번호

API 시스템은 결과를 XML 또는 JSON 형식으로 반환하기 때문에 다양한 프로그래밍 언어 및 플랫폼에서 쉽게 분석할 수 있습니다.

영국 SORT 코드 및 계정 번호 검색을 위한 API의 샘플 XML 회신은 다음과 같습니다:

쿼리 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>

사용자가 JSON 형식을 지정한 경우 동일한 쿼리에 대한 응답은 다음과 같습니다:

"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. API 오류

오류가 발생한 경우, IBAN Calculation API는 오류 메시지가 포함된 XML 또는 JSON 응답을 반환합니다.
<error></error> XML 태그는 XML 응답에 다른 필드 없이 반환됩니다
아래에는 반환될 수 있는 모든 오류 메시지에 대한 설명을 찾을 수 있습니다:

<error>계좌 번호 체크섬이 올바르지 않습니다.</error>
<error>계좌 번호 (체크섬)가 올바르지 않습니다.</error>
<error>계좌 번호는 11자이어야 합니다</error>
<error>계좌 번호는 14자여야 합니다</error>
<error>계좌 번호는 24자여야 합니다</error>
<error>계좌 번호가 올바르지 않습니다;/error>
<error>계좌 번호 은행 식별 코드가 잘못되었습니다</error>
<error>계좌 번호 접두사가 너무 깁니다.</error>
<error>계좌 번호가 너무 깁니다.</error>
<error>은행/지점 코드 / KIB (체크섬) 가 올바르지 않습니다.</error>
<error>은행 코드/지점 코드/계좌 번호가 너무 깁니다.</error>
<error>은행 코드/지점 코드(체크섬)가 올바르지 않습니다.</error>
<error>은행 코드가 유효하지 않습니다</error>
<error>은행 코드가 너무 깁니다.</error>
<error>은행을 찾을 수 없습니다</error>
<error>은행이 인식되지 않습니다</error>
<error>BBAN / NIB (체크섬) 올바르지 않습니다.</error>
<error>BLZ/은행 코드가 올바르지 않습니다</error>
<error>지점/Agencia 를 찾을 수 없습니다</error>
<error>지점 코드가 너무 깁니다.</error>
<error>지점을 찾을 수 없습니다</error>
<error>체크 디지트가 너무 깁니다.</error>
<error>Clearingnummer/계좌 번호가 유효하지 않습니다. 체크 디지트가 올바르지 않습니다.</error>
<error>Clearingnummer / 은행코드 확인할 수 없습니다. IBAN을 계산할 수 없습니다.</error>
<error>Clearingnummer 또는 계좌 번호가 너무 깁니다.</error>
<error>Codice ABI della Banca/은행코드가 유효하지 않습니다</error>
<error>Codice CAB della Filiale/지점코드가 유효하지 않습니다</error>
<error>국가 코드가 유효하지 않습니다</error>
<error>국가 또는 은행이 지원되지 않습니다</error>
<error>IBAN 유효하지 않습니다</error>
<error>Kontonummer/계좌 번호가 유효하지 않습니다</error>
<error>누락된 필드</error>
<error>비 FR IBAN</error>
<error>비 FR IBAN 국가</error>
<error>필수 코드가 누락되었습니다. 은행 코드와 계좌 번호를 입력해주십시오</error>
<error>필수 필드가 제출되지 않음</error>
<error>RIB가 유효하지 않음</error>
<error>SortCode / BankCode를 식별할 수 없습니다. IBAN 은 계산할 수 없습니다</error>
<error>Sort 코드를 찾을 수 없음</error>