개발자 문서
서비스 소개키 관리자격증명 등록OpenAPI콘솔
API 레퍼런스

계좌

1. KB국민은행 빠른계좌조회 계좌 목록kb_fast_account.accounts.list

MCP 도구 이름 kb_fast_account__accounts__list

POSThttps://api.xdata.kr/v1/jobsX-Env-Scope: sandbox

샌드박스입니다. 실제 기관을 호출하지 않는 모의 응답이며 일일 한도가 없습니다.

이 호출자가 KB국민은행 계좌로 등록한 연동과 그 아래 계좌를 나열합니다. 연동의 account_link_id 와 계좌의 bank_account_credential_id 를 함께 돌려주므로, 거래내역 조회를 부르기 전에 두 값을 얻는 데 씁니다. 기관에는 접속하지 않고 XBOSS 에 등록된 연동만 읽으며, 계좌번호는 가린 값으로 나옵니다.

Request
순번변수명필수설명
AuthorizationYAPI 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다.

형식 : Basic base64("{client_id}:{client_secret}")

[참고] 인증

X-Env-ScopeY호출 환경입니다.
  • sandbox샌드박스 — 모의 응답
  • real_test데모 — 하루 100 사용 토큰
  • production정식 — 유료 플랜 전용

[참고] 환경

Idempotency-KeyY재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다.

[참고] 재시도

Content-TypeY요청 본문 형식입니다.
  • application/json고정값 (기본값)
X-Trace-IdN추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.
순번변수명타입길이필수설명
providerstring-Y호출할 기관입니다.
  • kb_fast_account이 API 고정값 (기본값)

예시 : kb_fast_account

actionstring-Y호출할 작업입니다.
  • kb_fast_account.accounts.list이 API 고정값 (기본값)

예시 : kb_fast_account.accounts.list

account_link_idstring36조건부등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명 중 대표로 지정한 것이 쓰입니다. 대표가 없으면 등록한 자격증명이 하나뿐일 때만 자동으로 선택되고, 둘 이상이면 직접 지정해야 합니다.

형식 : UUID v4

[참고] 자격증명 등록

paramsobject-N작업 파라미터입니다. 이 API 는 빈 객체로 호출할 수 있습니다.
encrypted_fieldsobject-N민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다.

[참고] 암호화

추가 파라미터가 없습니다. params 는 {} 로 보냅니다.

bash
curl --request POST \
  --url 'https://api.xdata.kr/v1/jobs' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: sandbox' \
  --header 'Idempotency-Key: demo-list-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "kb_fast_account",
  "action": "kb_fast_account.accounts.list",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {}
}'
Response

이 API 는 기관 응답 본문을 그대로 전달합니다. 고정 필드 목록이 없습니다.

json
{
    "job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
    "status": "QUEUED",
    "env_scope": "sandbox",
    "provider": "kb_fast_account",
    "action": "kb_fast_account.accounts.list",
    "submitted_at": "2026-05-27T12:34:56+09:00"
}

MCP 도구 이름 kb_fast_account__accounts__transaction_history__search

POSThttps://api.xdata.kr/v1/jobsX-Env-Scope: sandbox

샌드박스입니다. 실제 기관을 호출하지 않는 모의 응답이며 일일 한도가 없습니다.

기간과 입출금 구분을 지정해 KB 계좌의 거래내역을 거래 상대방까지 받습니다.

  • KB국민은행 빠른조회 세션 로그인을 먼저 호출해 세션을 등록한 뒤, 같은 account_link_id 로 호출합니다. [KB국민은행 빠른조회 로그인]
  • sandbox 환경에서는 실제 KB국민은행에 접속하지 않습니다. 고정된 모의 값이 옵니다.
  • transaction_type(기본값 all)·sort_order(기본값 desc)는 선택입니다.
Request
순번변수명필수설명
AuthorizationYAPI 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다.

형식 : Basic base64("{client_id}:{client_secret}")

[참고] 인증

X-Env-ScopeY호출 환경입니다.
  • sandbox샌드박스 — 모의 응답
  • real_test데모 — 하루 100 사용 토큰
  • production정식 — 유료 플랜 전용

[참고] 환경

Idempotency-KeyY재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다.

[참고] 재시도

Content-TypeY요청 본문 형식입니다.
  • application/json고정값 (기본값)
X-Trace-IdN추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.
순번변수명타입길이필수설명
providerstring-Y호출할 기관입니다.
  • kb_fast_account이 API 고정값 (기본값)

예시 : kb_fast_account

actionstring-Y호출할 작업입니다.
  • kb_fast_account.accounts.transaction_history.search이 API 고정값 (기본값)

예시 : kb_fast_account.accounts.transaction_history.search

account_link_idstring36조건부등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명 중 대표로 지정한 것이 쓰입니다. 대표가 없으면 등록한 자격증명이 하나뿐일 때만 자동으로 선택되고, 둘 이상이면 직접 지정해야 합니다.

형식 : UUID v4

[참고] 자격증명 등록

paramsobject-Y작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다.
encrypted_fieldsobject-N민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다.

[참고] 암호화

순번변수명타입필수설명
bank_account_credential_idstringY-
start_datestringY-
end_datestringY-
transaction_typestringN-

예시 : all

sort_orderstringN-

예시 : desc

bash
curl --request POST \
  --url 'https://api.xdata.kr/v1/jobs' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: sandbox' \
  --header 'Idempotency-Key: demo-search-001' \
  --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": {
    "bank_account_credential_id": "<필수>",
    "start_date": "<필수>",
    "end_date": "<필수>",
    "transaction_type": "all",
    "sort_order": "desc"
  }
}'
Response
  • result.data 의 rows 로 거래내역을(거래 상대방 포함), 조회 조건에 맞는 건을 확인합니다.
순번변수명설명
success요청 처리 성공 여부
account_link_id연동 ID
bank_account_credential_id조회에 쓰인 계좌 자격증명 ID
query이번 조회에 실제로 쓰인 조건 객체
account계좌 정보 객체(계좌종류명 포함)
count조회된 건수
rows거래내역 목록
continuation이어받기 정보 객체 - requested_pages·has_more. 이 액션은 한 번에 최대 1페이지만 지원해 has_more 는 응답에 실리는 순간엔 이미 false 로 확정된 뒤입니다(더 있으면 오류로 답합니다 - 위 오류표 참고)
json
{
    "job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
    "status": "QUEUED",
    "env_scope": "sandbox",
    "provider": "kb_fast_account",
    "action": "kb_fast_account.accounts.transaction_history.search",
    "submitted_at": "2026-05-27T12:34:56+09:00"
}
순번오류 코드발생 조건
AUTH_REQUIRED세션 없음 — KB국민은행 로그인 세션이 없습니다. session.login 을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다. retryable=false.
INTERNAL_ERROR주의: 잘못된 계좌 자격증명도 INTERNAL_ERROR — bank_account_credential_id 가 존재하지 않거나 비활성이어도 지금은 이 코드로 옵니다(수정 요청됨). 재시도보다 콘솔에서 자격증명 등록 상태를 먼저 확인합니다.
VALIDATION_INVALID_FIELD파라미터 오류 — 필수값(bank_account_credential_id·start_date·end_date)이 없거나 형식이 올바르지 않습니다(KB_FAST_ACCOUNT_INPUT_INVALID).
PROVIDER_UPSTREAM_ERROR조회 범위 초과(이어받기 미지원) — 이 조회는 한 번에 1페이지만 지원합니다(v1). 기관이 더 있다고 응답하면 조용히 자르지 않고 오류로 답합니다 - 기간을 좁혀 다시 시도합니다.
PROVIDER_UNAVAILABLE그 밖의 오류 — 그 밖의 KB국민은행 오류입니다. retryable 은 원인마다 다릅니다.