계좌 - KB국민은행 빠른조회
1. KB국민은행 빠른계좌조회 계좌 목록kb_ fast_ account. accounts. list
MCP 도구 이름 kb_
POSThttps:// api. xdata. kr/ v1/ jobsX-Env-Scope: real_test
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
이 호출자가 KB국민은행 계좌로 등록한 연동과 그 아래 계좌를 나열합니다.연동의 account_link_id 와 계좌의 bank_account_credential_id 를 함께 돌려주므로, 거래내역 조회를 부르기 전에 두 값을 얻는 데 씁니다.기관에는 접속하지 않고 XBOSS 에 등록된 연동만 읽으며, 계좌번호는 가린 값으로 나옵니다.
- 이 API 는 기관 연동과 기관 로그인이 필요 없습니다. 기관 자격증명을 등록하지 않아도 호출할 수 있고, account_link_id 는 보내지 않습니다.
Request
| 순번 | 변수명 | 필수 | 설명 |
|---|---|---|---|
| Authorization | Y | API 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다. | |
| X- | Y | 호출 환경입니다.
| |
| Idempotency- | Y | 재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다. | |
| Content- | Y | 요청 본문 형식입니다.
| |
| X- | N | 추적 아이디입니다. 지정하지 않으면 서버가 발급합니다. |
| 순번 | 변수명 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| provider | string | Y | 호출할 기관입니다.
| |
| action | string | Y | 호출할 작업입니다.
| |
| params | object | N | 작업 파라미터입니다. 이 API 는 빈 객체로 호출할 수 있습니다. | |
| encrypted_ | object | N | 민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. |
추가 파라미터가 없습니다. params 는 {} 로 보냅니다.
curl --request POST \
--url 'https://api.xdata.kr/v1/jobs' \
--header 'Authorization: Basic {base64(client_id:client_secret)}' \
--header 'X-Env-Scope: real_test' \
--header "Idempotency-Key: list-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "kb_fast_account",
"action": "kb_fast_account.accounts.list",
"params": {}
}'Response
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| success | boolean | 목록을 돌려줬다는 표지입니다. 항상 true 입니다. | |
| provider | string | 연동을 가려낸 상품 구분 값입니다. 이 작업에서는 항상 kb_fast_account 입니다(호출한 작업 이름의 앞부분). | |
| links | array | 이 계정이 이 상품에 연결해 둔 연동 목록입니다. 사용 중인 연동만 담고 최근에 만든 연동이 앞에 옵니다. 연동이 없으면 빈 배열입니다. | |
| links[]. | string | 연동 ID 입니다. 이 상품의 다른 작업을 부를 때 account_link_id 로 보냅니다. | |
| links[]. | string | null | 연동에 붙인 표시 이름입니다. 이름이 없으면 null 입니다. | |
| links[]. | array | 이 연동에 등록된 계좌 목록입니다. 사용 중인 계좌만 담고 최근에 등록한 계좌가 앞에 옵니다. | |
| links[]. | string | 계좌 ID 입니다. 계좌를 고르는 작업을 부를 때 bank_account_credential_id 로 보냅니다. | |
| links[]. | string | 가려진 계좌번호입니다. 전체 번호는 돌려주지 않습니다. | |
| links[]. | string | 계좌의 상태입니다. 사용 중인 계좌만 담으므로 항상 ACTIVE 입니다. | |
| link_ | number | links 에 담긴 연동의 수입니다. | |
| account_ | number | 모든 연동의 accounts 에 담긴 계좌의 총 수입니다. | |
| truncated | boolean | 늘 false 입니다. 연동을 끝까지 모두 읽어 보내므로 빠지는 연동이 없고, 예전 응답과 맞추려고 남겨 둔 칸입니다. |
// result.data - 값 자리에는 각 칸의 형식을 적었습니다 (실제 값이 아닙니다)
{
"success": "<boolean>",
"provider": "<string>",
"links": [
{
"account_link_id": "<string>",
"display_label": "<string | null>",
"accounts": [
{
"bank_account_credential_id": "<string>",
"masked_account_no": "<string>",
"status": "<string>"
}
]
}
],
"link_count": "<number>",
"account_count": "<number>",
"truncated": "<boolean>"
}2. KB국민은행 빠른조회 거래내역 조회kb_ fast_ account. accounts. transaction_ history. search
MCP 도구 이름 kb_
POSThttps:// api. xdata. kr/ v1/ jobsX-Env-Scope: real_test
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
기간과 입출금 구분을 지정해 KB 계좌의 거래내역을 거래 상대방까지 받습니다.
- KB국민은행 빠른조회 세션 로그인을 먼저 호출해 세션을 등록한 뒤, 같은 account_link_id 로 호출합니다. [KB국민은행 빠른조회 로그인]
- transaction_type(기본값 all)·sort_order(기본값 desc)는 선택입니다.
Request
| 순번 | 변수명 | 필수 | 설명 |
|---|---|---|---|
| Authorization | Y | API 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다. | |
| X- | Y | 호출 환경입니다.
| |
| Idempotency- | Y | 재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다. | |
| Content- | Y | 요청 본문 형식입니다.
| |
| X- | N | 추적 아이디입니다. 지정하지 않으면 서버가 발급합니다. |
| 순번 | 변수명 | 타입 | 길이 | 필수 | 설명 |
|---|---|---|---|---|---|
| provider | string | - | Y | 호출할 기관입니다.
| |
| action | string | - | Y | 호출할 작업입니다.
| |
| account_ | string | 36 | Y | 등록한 자격증명을 가리키는 아이디입니다. 이 기관은 자격증명을 자동으로 고르지 않으므로 생략할 수 없습니다. 생략하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다. | |
| params | object | - | Y | 작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다. | |
| encrypted_ | object | - | N | 민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| bank_ | string | N | 조회할 계좌의 ID 입니다. kb_fast_account.accounts.list 결과의 links[].accounts[].bank_account_credential_id 값을 그대로 보내며, 요청의 account_link_id 연동에 등록된 사용 중인 계좌여야 합니다. 보내지 않으면 연동한 계좌가 하나일 때 서버가 그 계좌를 고르고, 여럿이면 고르지 않고 RESOURCE_CONFLICT 로 실패하며 오류의 next 가 고를 계좌 목록(choices)을 줍니다. 정식(production) 환경에서는 세션 로그인에 쓴 계좌(연동할 때 입력한 계좌)만 조회할 수 있고 같은 연동의 다른 계좌를 입력하면 입력 오류로 거절합니다. 데모(real_test) 환경에서는 다른 계좌도 그 계좌로 한 번 더 로그인해 조회합니다 | |
| start_ | string | Y | 조회 시작일입니다. YYYY-MM-DD 나 YYYYMMDD 형식으로 보내며 end_date 보다 늦을 수 없고, 형식이 맞지 않거나 순서가 거꾸로이면 거절합니다. 서버가 다음 쪽을 따라가 최대 20쪽까지 이어 받아 한 결과로 돌려주고, 그 안에 마지막 쪽을 확인하지 못하면 결과를 돌려주지 않고 실패합니다. 그때는 기간을 나누어 보냅니다 | |
| end_ | string | Y | 조회 종료일입니다. 형식은 start_date 와 같고 start_date 보다 빠를 수 없습니다 | |
| transaction_ | string | N | 조회할 거래 구분입니다. all 은 입금과 출금 전체, deposit 은 입금만, withdrawal 은 출금만이며 보내지 않으면 all 입니다 | |
| sort_ | string | N | 거래 정렬 순서입니다. desc 는 최근 거래가 먼저, asc 는 오래된 거래가 먼저이며 보내지 않으면 desc 입니다 | |
| output_ | array | N | 이 결과를 엑셀(xlsx) 파일로도 받으려면 적습니다. 예: ["xlsx"]. 파일은 result.artifacts 에 함께 오고, 빼면 데이터만 옵니다 |
- 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
curl --request POST \
--url 'https://api.xdata.kr/v1/jobs' \
--header 'Authorization: Basic {base64(client_id:client_secret)}' \
--header 'X-Env-Scope: real_test' \
--header "Idempotency-Key: search-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "kb_fast_account",
"action": "kb_fast_account.accounts.transaction_history.search",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {
"start_date": "<필수>",
"end_date": "<필수>",
"transaction_type": "all",
"sort_order": "desc"
}
}'Response
- result.data 의 rows 로 거래내역을(거래 상대방 포함), 조회 조건에 맞는 건을 확인합니다.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| success | boolean | 조회를 마쳤다는 표지입니다. 성공 응답에서는 항상 true 입니다. | |
| account_ | string | 조회에 쓴 연동의 ID 입니다. 요청에 보낸 값입니다. | |
| bank_ | string | 조회에 쓴 계좌의 ID 입니다. 요청에 보냈으면 그 값이고, 보내지 않아 서버가 계좌를 고른 경우에는 고른 계좌의 ID 입니다. | |
| query | object | 이번 조회에 실제로 쓴 조건입니다. | |
| query. | string | 조회 시작일입니다. 요청에 보낸 값을 YYYY-MM-DD 모양으로 맞춘 문자열입니다. | |
| query. | string | 조회 종료일입니다. 요청에 보낸 값을 YYYY-MM-DD 모양으로 맞춘 문자열입니다. | |
| query. | string | 거래 구분 조건입니다. 요청에서 쓴 값입니다. | |
| query. | string | 정렬 방향입니다. 요청에서 쓴 값(desc 또는 asc)입니다. | |
| account | object | 조회한 계좌의 요약입니다. | |
| account. | string | 가려진 계좌번호입니다. 전체 번호는 돌려주지 않습니다. | |
| account. | string | 계좌 종류의 이름입니다. 로그인 때 확인한 값입니다. | |
| account. | string | 통화 코드입니다. 항상 KRW 입니다. | |
| account. | number | null | 계좌 잔액입니다. 원 단위 정수이고, 기관이 값을 주지 않으면 null 입니다. | |
| account. | number | null | 출금 가능 금액입니다. 원 단위 정수이고, 기관이 값을 주지 않으면 null 입니다. | |
| count | number | rows 에 담긴 거래의 건수입니다. | |
| rows | array | 거래내역 목록입니다. 조건에 맞는 거래가 없으면 빈 배열입니다. | |
| rows[]. | string | 거래 일시입니다. 기관 화면의 시각을 YYYY-MM-DDTHH:MM:SS 모양으로 옮긴 문자열이며 시간대 표기는 없습니다. | |
| rows[]. | string | null | 적요입니다. 기관 화면의 칸이 비어 있으면 null 입니다. | |
| rows[]. | string | null | 거래 내용입니다. 기관 화면의 칸이 비어 있으면 null 입니다. | |
| rows[]. | number | null | 출금액입니다. 원 단위 정수이고, 기관 화면의 칸이 비어 있으면 null 입니다. | |
| rows[]. | number | null | 입금액입니다. 원 단위 정수이고, 기관 화면의 칸이 비어 있으면 null 입니다. | |
| rows[]. | number | null | 그 거래 건의 잔액입니다. 원 단위 정수이고, 기관 화면의 칸이 비어 있으면 null 입니다. | |
| rows[]. | string | null | 거래점 또는 거래 채널입니다. 기관 화면의 칸이 비어 있으면 null 입니다. | |
| rows[]. | string | null | 거래 구분입니다. 기관 화면의 칸이 비어 있으면 null 입니다. | |
| rows[]. | string | null | 거래 상대방입니다. 기관 화면의 칸이 비어 있으면 null 입니다. | |
| continuation | object | 이어받기 정보입니다. 기관 화면이 거래를 여러 쪽으로 나눠 보여 주면 서버가 마지막 쪽까지 이어 가져와 rows 에 합칠 수 있습니다. 끝까지 가져오지 못하면 응답 대신 오류로 끝나므로(오류표 참고) 성공 응답에서 이어받을 거래는 없습니다. | |
| continuation. | number | 기관에서 가져온 쪽 수입니다. 1 이상의 정수입니다. | |
| continuation. | boolean | 이어받을 거래가 더 남았는지를 나타냅니다. 더 있으면 응답 대신 오류로 끝나므로 성공 응답에서는 항상 false 입니다. |
// result.data
{
"success": true,
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"bank_account_credential_id": "5d1e7a90-0000-4000-8000-000000000000",
"query": {
"start_date": "2026-01-01",
"end_date": "2026-01-31",
"transaction_type": "all",
"sort_order": "desc"
},
"account": {
"account_no_display": "123-******-789",
"account_type_name": "보통예금",
"currency": "KRW",
"balance": 2750000,
"withdrawable_amount": 2750000
},
"count": 2,
"rows": [
{
"transaction_datetime": "2026-01-20T10:15:30",
"summary": "급여",
"description": "1월 급여",
"withdrawal_amount": null,
"deposit_amount": 2500000,
"balance": 2750000,
"branch_or_channel": "인터넷뱅킹",
"transaction_kind": "입금",
"counterparty": "주식회사 예시상사"
},
{
"transaction_datetime": "2026-01-12T09:02:11",
"summary": "카드대금",
"description": null,
"withdrawal_amount": 300000,
"deposit_amount": null,
"balance": 250000,
"branch_or_channel": "자동이체",
"transaction_kind": "출금",
"counterparty": "예시카드"
}
],
"continuation": {
"requested_pages": 1,
"has_more": false
}
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| AUTH_ | 세션 없음 — KB국민은행 로그인 세션이 없습니다. session.login 을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다. retryable=false. | |
| VALIDATION_ | 계좌 자격증명 오류 — 조회에 쓸 계좌를 찾지 못했습니다. bank_account_credential_id 가 없는 계좌이거나, 이미 해제됐거나, 요청한 연동(account_link_id)의 계좌가 아닌 경우이고, 연동한 계정을 찾지 못한 경우도 같은 코드입니다. error.provider_error_ref 는 kb_fast_account.bank_account_credential 입니다. retryable=false - error.message 가 안내하는 대로 계좌 목록에서 계좌를 다시 선택하거나 계정을 먼저 연동한 뒤 다시 요청합니다. | |
| RESOURCE_ | 계좌 선택 필요 — bank_account_credential_id 를 보내지 않았는데 연동한 계좌가 여러 개라 서버가 고르지 않습니다. error.provider_error_ref 는 kb_fast_account.bank_account_selection_required 입니다. retryable=false - 오류의 next 가 stage=choose_bank_account 로 고를 수 있는 계좌 목록(choices: bank_account_credential_id, 가린 계좌번호, 기본 계좌 여부)을 싣습니다. 그중 하나의 bank_account_credential_id 를 넣어 같은 요청을 다시 보냅니다(kb_fast_account.accounts.list 에서 골라도 됩니다). | |
| VALIDATION_ | 로그인한 계좌가 아님 — 정식(production) 환경에서 bank_account_credential_id 가 세션 로그인에 쓴 계좌(연동할 때 입력한 계좌)가 아닙니다(KB_FAST_ACCOUNT_INPUT_INVALID). 정식 환경에서는 같은 연동의 다른 계좌를 조회하지 않습니다(데모(real_test) 환경은 그 계좌로 한 번 더 로그인해 조회합니다). retryable=false - 로그인에 쓴 계좌의 bank_account_credential_id 를 입력해 다시 요청합니다. | |
| VALIDATION_ | 파라미터 오류 — 필수값(start_date, end_date)이 없거나 형식이 올바르지 않습니다(KB_FAST_ACCOUNT_INPUT_INVALID). | |
| VALIDATION_ | 조회 범위 초과 — 이 조회는 서버가 다음 쪽(한 쪽 최대 100건)을 따라가 최대 20쪽까지 이어 받습니다. 그 안에 마지막 쪽을 확인하지 못하면 끝까지 받았는지 확인할 수 없어 조용히 자르지 않고 오류로 답합니다. error.provider_error_ref 는 kb_fast_account.transaction_continuation_limit 입니다. retryable=false - 기간을 나누어 다시 요청합니다. | |
| PROVIDER_ | 그 밖의 오류 — 그 밖의 KB국민은행 오류입니다. retryable=true. |