# 은행코드 조회 계좌 관련 API에 쓰는 은행 코드와 은행명 목록을 조회합니다. 인증: Authorization: Bearer $APICK_API_KEY 본문 있는 REST 요청: multipart/form-data. GET 본문 및 MCP JSON-RPC 규격은 해당 명세를 따릅니다. 인증키는 서버에 보관하세요. 모든 예제는 정적 자료입니다. ## POST /rest/bank_code 응답 필드 - `data` (object): 요청 처리 결과 묶음입니다. 조회한 값·작업 상태·오류 설명이 이 안에 들어 있으며, 실제 하위 필드 구성은 서비스마다 다릅니다. 값이 없으면 null·빈 배열·필드 생략 중 해당 서비스의 규칙을 따릅니다. - `data.result` (array): 조회 결과 본문입니다. 서비스가 찾은 실제 데이터가 들어 있으며, 자료가 없거나 조회에 실패하면 null이거나 필드가 생략됩니다. - `data.result[].code` (string): 표준 은행 코드입니다. 숫자 3자리 문자열로 오며 예: 004(국민), 088(신한), 020(우리). 요청의 bank_code와 같은 체계이므로 응답 코드를 저장해 두면 다음 조회에 그대로 재사용할 수 있습니다. - `data.result[].name` (string): 은행명입니다. 계좌 API의 bank_name에 넣을 때는 이 값을 그대로 씁니다. 예: 국민, 카카오뱅크 - `data.success` (integer): 업무 처리 결과 코드입니다. 1은 정상 결과, 0은 실패 또는 무료 응답입니다. 서비스에 따라 2·3처럼 추가 코드를 쓰므로 같은 응답의 status·msg·error 필드도 함께 확인하세요. - `data.error` (string): 오류 원인을 설명하는 문구입니다. 성공 응답에는 없거나 빈 문자열입니다. - `api` (object): API 호출 메타데이터입니다. 이번 요청의 서버 처리 성공 여부(api.success), 실제 차감 포인트(api.cost), 결제 기록 ID(api.pl_id)를 담습니다. 처리 시간(api.ms)은 응답에 포함된 경우에만 제공됩니다. 업무 결과는 data에서 확인합니다. - `api.success` (boolean): API 서버가 이번 요청을 정상 처리했는지 여부입니다. true여도 업무 결과가 실패일 수 있으므로 data.success·data.status와 함께 판단합니다. 인증 실패·잘못된 입력·서버 오류 응답에서는 false입니다. - `api.cost` (integer): 이번 호출에서 실제로 차감된 포인트입니다. 유료 성공 응답에서만 단가만큼 차감되며, 실패·무료 조회·같은 요청의 멱등 재전송은 0입니다. 화면의 표시 단가와 실제 차감액이 다를 수 있으므로 정산은 이 값을 기준으로 합니다. - `api.ms` (integer): 서버가 요청을 받아 응답 본문을 만들기까지 걸린 처리 시간(밀리초)입니다. 네트워크 왕복 시간과 클라이언트 대기 시간은 포함되지 않습니다. - `api.pl_id` (integer): 포인트 차감 기록 ID입니다. 차감이 발생한 호출에만 값이 있으며, 과금 내역을 문의할 때 이 번호를 사용합니다. 무과금 응답은 -1·null이거나 필드가 생략됩니다. ## API 요청: POST /rest/bank_code ### 입력 ### 응답 명세 ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "은행 코드 3자리입니다. 앞자리 0까지 문자열 그대로 쓰세요. 예: 004(국민), 088(신한), 050(저축은행)" }, "name": { "type": "string", "description": "은행명입니다. 계좌 API의 bank_name에 넣을 때는 이 값을 그대로 씁니다. 예: 국민, 카카오뱅크" } } }, "description": "은행 코드 목록입니다. 항목마다 코드(code)와 은행명(name)이 한 쌍으로 들어 있습니다." }, "success": { "type": "integer", "description": "처리 상태입니다. 1이면 정상 응답, 0이면 실패 응답입니다." }, "error": { "type": "string", "description": "실패 사유 문구입니다. 정상 응답에는 없습니다. \"알 수 없는 이유로 금융정보를 불러오지 못했습니다.\"가 오면(HTTP 424) 잠시 후 다시 요청하세요." } }, "description": "은행 코드 목록 묶음입니다. 실패하면 result 대신 error 문구가 들어 있습니다." }, "api": { "type": "object", "properties": { "success": { "type": "boolean", "description": "요청을 정상적으로 받아 처리했는지 여부입니다. 목록을 받았는지는 data.result로 확인하세요." }, "cost": { "type": "integer", "description": "이번 호출에서 차감된 포인트입니다. 실패 응답은 0입니다." }, "ms": { "type": "integer", "description": "요청을 받아 응답을 만들기까지 걸린 시간(밀리초)입니다. 네트워크 왕복 시간은 포함되지 않습니다." }, "pl_id": { "type": "integer", "description": "포인트 차감 기록 번호입니다. 차감이 없으면 -1이거나 필드가 없습니다." } }, "description": "호출 공통 정보입니다. 처리 여부·차감 포인트·처리 시간·차감 기록 번호가 들어 있습니다." } } } ``` ### 정적 응답 예시 ```json { "data": { "result": [ { "code": "088", "name": "신한" }, { "code": "035", "name": "제주" }, { "code": "004", "name": "국민" }, { "code": "003", "name": "기업" }, { "code": "011", "name": "농협" }, { "code": "002", "name": "산업" }, { "code": "007", "name": "수협" }, { "code": "048", "name": "신협" }, { "code": "020", "name": "우리" }, { "code": "081", "name": "하나" }, { "code": "027", "name": "한국씨티" }, { "code": "090", "name": "카카오뱅크" }, { "code": "089", "name": "케이뱅크" }, { "code": "092", "name": "토스뱅크" }, { "code": "039", "name": "경남" }, { "code": "034", "name": "광주" }, { "code": "031", "name": "아이엠뱅크(대구)" }, { "code": "032", "name": "부산" }, { "code": "037", "name": "전북" }, { "code": "030", "name": "회원수협" }, { "code": "045", "name": "새마을" }, { "code": "071", "name": "우체국" }, { "code": "050", "name": "저축은행" }, { "code": "012", "name": "지역농.축협" }, { "code": "055", "name": "도이치" }, { "code": "063", "name": "중국" }, { "code": "067", "name": "중국건설" }, { "code": "062", "name": "중국공상" }, { "code": "061", "name": "BNP파리바" }, { "code": "060", "name": "BOA" }, { "code": "054", "name": "HSBC" }, { "code": "057", "name": "JP모간" }, { "code": "023", "name": "SC" }, { "code": "064", "name": "산림조합" }, { "code": "278", "name": "신한투자증권" }, { "code": "261", "name": "교보증권" }, { "code": "227", "name": "다올투자증권" }, { "code": "267", "name": "대신증권" }, { "code": "287", "name": "메리츠증권" }, { "code": "238", "name": "미래에셋증권" }, { "code": "290", "name": "부국증권" }, { "code": "240", "name": "삼성증권" }, { "code": "221", "name": "상상인증권" }, { "code": "291", "name": "신영증권" }, { "code": "266", "name": "에스케이증권" }, { "code": "209", "name": "유안타증권" }, { "code": "280", "name": "유진투자증권" }, { "code": "265", "name": "LS증권" }, { "code": "288", "name": "카카오페이증권" }, { "code": "292", "name": "케이프투자증권" }, { "code": "264", "name": "키움증권" }, { "code": "271", "name": "토스증권" }, { "code": "294", "name": "우리투자증권" }, { "code": "270", "name": "하나증권" }, { "code": "262", "name": "아이엠증권" }, { "code": "243", "name": "한국투자증권" }, { "code": "269", "name": "한화투자증권" }, { "code": "263", "name": "현대차증권" }, { "code": "224", "name": "BNK투자증권" }, { "code": "279", "name": "DB증권" }, { "code": "225", "name": "IBK투자증권" }, { "code": "218", "name": "KB증권" }, { "code": "247", "name": "NH투자증권" } ], "success": 1 }, "api": { "success": true, "cost": 0, "ms": 431, "pl_id": -1 } } ``` ### curl ```curl printf '%s\r\n' '--apick-empty--' | curl --fail-with-body --request POST 'https://apick.app/rest/bank_code' \ --header "Authorization: Bearer $APICK_API_KEY" \ --header 'Content-Type: multipart/form-data; boundary=apick-empty' \ --data-binary @- ``` ### Node.js (서버 ESM) ```javascript const form = new FormData(); const response = await fetch("https://apick.app/rest/bank_code", { method: "POST", headers: { Authorization: "Bearer " + process.env.APICK_API_KEY }, body: form, signal: AbortSignal.timeout(120_000), }); if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`); const result = await response.json(); console.log(result); ``` ### python ```python import os import requests response = requests.request("POST", "https://apick.app/rest/bank_code", headers={"Authorization": "Bearer " + os.environ["APICK_API_KEY"], "Content-Type": "multipart/form-data; boundary=apick-empty"}, data=b"--apick-empty--\r\n", timeout=(10, 120)) response.raise_for_status() result = response.json() print(result) ``` ### php ```php 'POST', CURLOPT_HTTPHEADER => $headers, CURLOPT_POSTFIELDS => $form, CURLOPT_RETURNTRANSFER => true, CURLOPT_CONNECTTIMEOUT => 10, CURLOPT_TIMEOUT => 120, ]); $body = curl_exec($curl); if ($body === false) { throw new RuntimeException(curl_error($curl)); } $status = curl_getinfo($curl, CURLINFO_HTTP_CODE); curl_close($curl); if ($status >= 400) { throw new RuntimeException($body); } $result = json_decode($body, true, 512, JSON_THROW_ON_ERROR); print_r($result); ``` ## 사용 예시 1. 은행 선택 목록 만들기 계좌 입력 화면의 은행 선택 목록을 만들 때 호출합니다. 요청 파라미터는 없습니다. ```bash printf '%s\r\n' '--apick-empty--' | curl --fail-with-body --request POST 'https://apick.app/rest/bank_code' \ --header "Authorization: Bearer $APICK_API_KEY" \ --header 'Content-Type: multipart/form-data; boundary=apick-empty' \ --data-binary @- ``` - `data.result[]`의 `code`를 값으로, `name`을 화면 표시 이름으로 씁니다. - 저축은행 계좌는 모두 `code` 050으로 조회합니다. - 계좌 API에 bank_name으로 보낼 때는 `name` 표기를 그대로 씁니다. 국민은행처럼 다르게 쓰면 "잘못된 은행명 또는 은행코드를 입력했습니다."가 됩니다. ## 코드·오류 ### 업무 실패 응답 입력 오류·대상 없음·일시 실패는 data.error(사유)와 data.success=0으로 오며 api.cost는 0(과금 없음)입니다. HTTP 상태는 400·404·408·424 중 하나입니다. 입력 오류는 값을 고쳐 다시 요청하고, 408·424는 잠시 후 한 번 다시 시도하세요. ```json { "data": { "error": "입력값을 확인해 주세요.", "success": 0 }, "api": { "success": true, "cost": 0, "ms": 5 } } ``` ## 상세 기능·요금 제공 정보 계좌 관련 API에 넣을 은행 코드(code)와 은행명(name) 전체 목록을 돌려줍니다. 은행·증권사·상호금융·저축은행이 모두 들어 있습니다. 계좌 예금주 조회(/rest/account_realname)의 bank_code 값을 고를 때 사용합니다. 목록은 자주 바뀌지 않으므로 하루 한 번 정도 받아 두고 은행 선택 화면에 쓰면 됩니다. 계좌 API에 bank_name으로 보낼 때는 이 목록의 name과 글자까지 똑같아야 합니다(예: 국민, 지역농.축협). 다르게 쓰면 은행을 찾지 못합니다. Method URL POST https://apick.app/rest/bank_code 저축은행(050) 포함 기관 저축은행 계좌는 기관별 코드가 따로 나뉘지 않고 050 하나로 조회됩니다. 아래 79개 저축은행이 모두 050에 포함되며, bank_code=050으로 조회할 수 있습니다. 권역 포함 저축은행 서울 (23개) DB, JT친애, KB, NH, OK, OSB, SBI, 대신, 더케이, 민국, HB, 스카이, 바로, 신한, 애큐온, 예가람, 웰컴, 유안타, 다올, 조은, 키움예스, 푸른, 하나 인천/경기 (19개) JT, 금화, 남양, 모아, 부림, 삼정, 상상인, 세람, 안국, 안양, 영진, 융창, 인성, 인천, 키움, 페퍼, 평택, 한국투자, 한화 부산/경남 (12개) BNK, DH, IBK, 고려, 국제, 동원제일, 솔브레인, 에스앤티, 우리, 조흥, 진주, 흥국 대구/경북/강원 (11개) CK, 대백, 대아, 대원, 드림, 라온, 머스트삼일, 엠에스, 오성, 유니온, 참 광주/전남/전북/제주 (7개) 대한, 라인, 동양, 삼호, 센트럴, 스마트, 스타 대전/충남/충북 (7개) 대명, 상상인플러스, 아산, 우리금융, 오투, 청주, 한성 ## 상세 요청 Header 이름 필수 설명 Authorization 필수 Bearer 인증키. 예: Authorization: Bearer 발급받은_API_키 요청 파라미터가 없습니다. 인증 헤더만 넣어 POST로 호출합니다. ## 상세 응답 Body 필드 타입 설명 data Object 은행 코드 목록 묶음입니다. 실패하면 result 대신 error 문구가 들어 있습니다. result Array 은행 코드 목록입니다. 항목마다 코드(code)와 은행명(name)이 한 쌍으로 들어 있습니다. code String 은행 코드 3자리입니다. 앞자리 0까지 문자열 그대로 쓰세요. 예: 004(국민), 088(신한), 050(저축은행) name String 은행명입니다. 계좌 API의 bank_name에 넣을 때는 이 값을 그대로 씁니다. 예: 국민, 카카오뱅크 error String 실패 사유 문구입니다. 정상 응답에는 없습니다. "알 수 없는 이유로 금융정보를 불러오지 못했습니다."가 오면(HTTP 424) 잠시 후 다시 요청하세요. success Integer 처리 상태입니다. 1이면 정상 응답, 0이면 실패 응답입니다. api Object 호출 공통 정보입니다. 처리 여부·차감 포인트·처리 시간·차감 기록 번호가 들어 있습니다. success Boolean 요청을 정상적으로 받아 처리했는지 여부입니다. 목록을 받았는지는 data.result로 확인하세요. cost Integer 이번 호출에서 차감된 포인트입니다. 실패 응답은 0입니다. ms Integer 요청을 받아 응답을 만들기까지 걸린 시간(밀리초)입니다. 네트워크 왕복 시간은 포함되지 않습니다. pl_id Integer 포인트 차감 기록 번호입니다. 차감이 없으면 -1이거나 필드가 없습니다. ## 상세 예제 요청 예시 form-data 전체 예제 보기 응답 예시 { "data": { "result": [ { "code": "088", "name": "신한" }, { "code": "035", "name": "제주" }, { "code": "004", "name": "국민" }, { "code": "003", "name": "기업" }, { "code": "011", "name": "농협" }, { "code": "002", "name": "산업" }, { "code": "007", "name": "수협" }, { "code": "048", "name": "신협" }, { "code": "020", "name": "우리" }, { "code": "081", "name": "하나" }, { "code": "027", "name": "한국씨티" }, { "code": "090", "name": "카카오뱅크" }, { "code": "089", "name": "케이뱅크" }, { "code": "092", "name": "토스뱅크" }, { "code": "039", "name": "경남" }, { "code": "034", "name": "광주" }, { "code": "031", "name": "아이엠뱅크(대구)" }, { "code": "032", "name": "부산" }, { "code": "037", "name": "전북" }, { "code": "030", "name": "회원수협" }, { "code": "045", "name": "새마을" }, { "code": "071", "name": "우체국" }, { "code": "050", "name": "저축은행" }, { "code": "012", "name": "지역농.축협" }, { "code": "055", "name": "도이치" }, { "code": "063", "name": "중국" }, { "code": "067", "name": "중국건설" }, { "code": "062", "name": "중국공상" }, { "code": "061", "name": "BNP파리바" }, { "code": "060", "name": "BOA" }, { "code": "054", "name": "HSBC" }, { "code": "057", "name": "JP모간" }, { "code": "023", "name": "SC" }, { "code": "064", "name": "산림조합" }, { "code": "278", "name": "신한투자증권" }, { "code": "261", "name": "교보증권" }, { "code": "227", "name": "다올투자증권" }, { "code": "267", "name": "대신증권" }, { "code": "287", "name": "메리츠증권" }, { "code": "238", "name": "미래에셋증권" }, { "code": "290", "name": "부국증권" }, { "code": "240", "name": "삼성증권" }, { "code": "221", "name": "상상인증권" }, { "code": "291", "name": "신영증권" }, { "code": "266", "name": "에스케이증권" }, { "code": "209", "name": "유안타증권" }, { "code": "280", "name": "유진투자증권" }, { "code": "265", "name": "LS증권" }, { "code": "288", "name": "카카오페이증권" }, { "code": "292", "name": "케이프투자증권" }, { "code": "264", "name": "키움증권" }, { "code": "271", "name": "토스증권" }, { "code": "294", "name": "우리투자증권" }, { "code": "270", "name": "하나증권" }, { "code": "262", "name": "아이엠증권" }, { "code": "243", "name": "한국투자증권" }, { "code": "269", "name": "한화투자증권" }, { "code": "263", "name": "현대차증권" }, { "code": "224", "name": "BNK투자증권" }, { "code": "279", "name": "DB증권" }, { "code": "225", "name": "IBK투자증권" }, { "code": "218", "name": "KB증권" }, { "code": "247", "name": "NH투자증권" } ], "success": 1 }, "api": { "success": true, "cost": 0, "ms": 431, "pl_id": -1 } } 호출 예시 입력값 없이 인증 헤더만으로 호출합니다. 응답의 code 값을 다른 API의 bank_code 입력에 그대로 사용하세요. JavaScript 예시 form-data 전체 예제 보기 Python 예시 form-data 전체 예제 보기