개발자 문서
API 레퍼런스

인증 - KB국민은행 빠른조회

1. KB국민은행 빠른조회 계좌 연결 로그인kb_fast_account.session.login

MCP 도구 이름 kb_fast_account__session__login

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

현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.

등록한 계좌 자격으로 KB국민은행 조회용 연결을 열고 대상 계좌를 확인합니다.

  • 콘솔에서 등록한 KB국민은행 빠른조회 계좌 자격증명이 필요합니다.
  • 지정한 연동(account_link_id)을 쓸 수 없으면(없는 연동이거나, 이 계정 소유가 아니거나, 다른 서비스의 연동이거나, 비활성인 경우) 제출이 400 VALIDATION_INVALID_FIELD 로 거절되고 작업이 만들어지지 않습니다.
  • 이 액션은 파라미터가 없습니다. account_link_id 로 지정한 자격증명이 쓰입니다.

Request

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

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

[참고] 인증

X-Env-ScopeY호출 환경입니다.
  • real_test데모 — 현재 데모 한도 확인 필요
  • 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.session.login이 API 고정값 (기본값)

예시 : kb_fast_account.session.login

account_link_idstring36Y등록한 자격증명을 가리키는 아이디입니다. 이 기관은 자격증명을 자동으로 고르지 않으므로 생략할 수 없습니다. 생략하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다.

형식 : 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: real_test' \
  --header "Idempotency-Key: login-$(date +%s)-$RANDOM" \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "kb_fast_account",
  "action": "kb_fast_account.session.login",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {}
}'

Response

  • 아래 표의 칸은 작업이 SUCCEEDED 가 된 뒤 GET /v1/jobs/{job_id}/result 의 result.data 에 오고, 응답 예시는 작업을 제출했을 때(POST /v1/jobs)의 응답입니다.
  • result.data 의 authenticated 로 로그인 성공 여부를, 확인한 대상 계좌를 확인합니다.
순번변수명타입설명
authenticatedboolean인증 완료 여부
account_link_idstring연동 ID
session_statusstring세션 상태 문자열
masked_account_numberstring마스킹된 계좌번호 - 계좌 조회까지 됐을 때만 옵니다(조건부)
json
{
    "job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
    "status": "QUEUED",
    "env_scope": "real_test",
    "provider": "kb_fast_account",
    "action": "kb_fast_account.session.login",
    "submitted_at": "2026-05-27T12:34:56+09:00"
}
순번오류 코드발생 조건
PROVIDER_AUTH_FAILED인증 거부 — KB국민은행이 로그인 자체를 거부했습니다. error.provider_error_ref 는 kb_fast_account.auth_failed 입니다. retryable=false.
PROVIDER_AUTH_FAILED자격 정보 오류 — 콘솔에 등록된 계좌 자격증명을 쓸 수 없습니다. 등록돼 있지 않거나, 저장된 값을 읽지 못했거나, 형식에 맞지 않거나, 이 작업에 맞지 않는 경우입니다. retryable=false - error.message 가 안내하는 대로 콘솔에서 자격증명을 등록하거나 다시 등록합니다. error.message 가 서비스 제공 상태 문제라고 알리면 다시 등록해도 풀리지 않으니 서비스문의로 알려 주세요.
CREDENTIAL_OWNERSHIP_DENIED자격증명 접근 거부 — 로그인 작업이 돌 때 지정한 연동(account_link_id)을 쓸 수 없는 것으로 판정됐습니다. 없는 연동이거나, 이 계정 소유가 아니거나, 다른 서비스의 연동이거나, 비활성인 경우를 같은 문장으로 알립니다. retryable=false - error.message 가 안내하는 대로 콘솔의 연동 화면에서 계정 ID 와 연동 상태를 확인하고 바로잡은 뒤 다시 요청합니다. 제출할 때 이미 쓸 수 없는 연동이면 작업이 만들어지기 전에 제출이 거절됩니다.
PROVIDER_UPSTREAM_ERROR기관 응답 오류 — KB국민은행 응답을 해석하지 못했습니다. retryable=true.
PROVIDER_UPSTREAM_ERROR로그인 처리 오류 — KB국민은행의 응답 문제가 아니라 서버 쪽에서 로그인 처리를 마치지 못한 경우입니다(로그인 세션을 저장하지 못한 경우 등). error.message 는 일반 안내('서버 내부 오류로 작업을 마치지 못했습니다. 서비스문의로 알려 주세요.')이고 error.provider_error_ref 는 kb_fast_account.login_orchestrator_failed 이며 retryable=true 입니다. 「기관 응답 오류」 와 같은 코드라 error.code 로는 가르지 못하고 error.provider_error_ref 로 가릅니다(error.message 도 다릅니다). 잠시 후 다시 시도하고, 계속되면 서비스문의로 알려 주세요.
VALIDATION_INVALID_FIELD계좌 종류 미지원 — 등록된 계좌가 거래내역 조회를 지원하지 않는 종류입니다(KB_FAST_ACCOUNT_ACCOUNT_KIND_UNSUPPORTED). 로그인 시퀀스 안에서만 판정되며 transaction_history.search 에서는 나지 않습니다.
PROVIDER_UNAVAILABLE그 밖의 오류 — 그 밖의 KB국민은행 오류입니다. retryable=true.