인증 - 하나은행 빠른조회

MCP 도구 이름 hana_fast_account__session__login

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

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

등록한 계좌 자격으로 하나은행 조회용 연결을 열고 연결 상태를 확인합니다.

콘솔에서 등록한 하나은행 계좌 자격증명(계좌번호, 계좌 비밀번호, 본인확인 번호)이 필요합니다. 정식 환경은 라이트, 스탠다드, PRO 또는 멀티계정 요금제를 이용 중일 때만 호출할 수 있습니다.
이 액션은 파라미터가 없습니다. account_link_id 로 지정한 자격증명이 쓰입니다.

Request

변수명	필수	설명
Authorization	Y	API 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다. 형식 : Basic base64("{client_id}:{client_secret}") [참고] 인증
X-Env-Scope	Y	호출 환경입니다. `real_test`데모 — 현재 데모 한도 확인 필요 `production`정식 — 현재 공개 요금제 전용 [참고] 환경
Idempotency-Key	Y	재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다. [참고] 재시도
Content-Type	Y	요청 본문 형식입니다. `application/json`고정값 (기본값)
X-Trace-Id	N	추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.

변수명	타입	길이	필수	설명
provider	string	-	Y	호출할 기관입니다. `hana_fast_account`이 API 고정값 (기본값) 예시 : hana_fast_account
action	string	-	Y	호출할 작업입니다. `hana_fast_account.session.login`이 API 고정값 (기본값) 예시 : hana_fast_account.session.login
account_link_id	string	36	Y	등록한 자격증명을 가리키는 아이디입니다. 이 기관은 자격증명을 자동으로 고르지 않으므로 생략할 수 없습니다. 생략하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다. 형식 : UUID v4 [참고] 자격증명 등록
params	object	-	N	작업 파라미터입니다. 이 API 는 빈 객체로 호출할 수 있습니다.
encrypted_fields	object	-	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: demo-login-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "hana_fast_account",
  "action": "hana_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 로 로그인 성공 여부를, session_status 로 세션 상태를 확인합니다.

변수명	타입	설명
authenticated	boolean	인증 완료 여부
account_link_id	string	연동 ID
session_status	string	세션 상태 문자열
masked_account_number	string	마스킹된 계좌번호 - 계좌 조회까지 됐을 때만 옵니다(조건부)

json

{
    "job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
    "status": "QUEUED",
    "env_scope": "real_test",
    "provider": "hana_fast_account",
    "action": "hana_fast_account.session.login",
    "submitted_at": "2026-05-27T12:34:56+09:00"
}

순번	오류 코드	발생 조건
	PROVIDER_AUTH_FAILED	자격 정보 오류 — 콘솔에 등록된 계좌 자격증명을 쓸 수 없습니다. 등록돼 있지 않거나, 저장된 값을 읽지 못했거나, 형식에 맞지 않거나, 이 작업에 맞지 않는 경우입니다. retryable=false - error.message 가 안내하는 대로 콘솔에서 자격증명을 등록하거나 다시 등록합니다. error.message 가 서비스 제공 상태 문제라고 알리면 다시 등록해도 풀리지 않으니 서비스문의로 알려 주세요.
	CREDENTIAL_OWNERSHIP_DENIED	자격증명 접근 거부 — 지정한 연동(account_link_id)을 쓸 수 없습니다. 없는 연동이거나 이 계정 소유가 아니거나 비활성인 경우를 같은 문장으로 알립니다. retryable=false.
	VALIDATION_INVALID_FIELD	계좌 종류 미지원 — 연동한 계좌가 거래내역 조회를 지원하지 않는 종류입니다(펀드 계좌와 대출 계좌는 조회되지 않고 입출금 계좌만 조회됩니다). error.message 는 '입출금 계좌만 조회할 수 있습니다. 연동한 계좌를 확인해 주세요.' 입니다. 로그인도 계좌를 한 번 조회해 확인하므로 로그인과 거래내역 조회 양쪽에서 납니다. retryable=false.
	PROVIDER_UPSTREAM_ERROR	기관 응답 오류 — 하나은행에서 받은 응답을 해석하지 못했거나 로그인 처리 중 오류가 있었습니다. 잠시 후 다시 시도하고, 계속되면 서비스문의로 알려 주세요. retryable=false.
	PROVIDER_UNAVAILABLE	기관 연결 실패 — 하나은행에 연결하지 못해 요청을 보내지 못했거나, 요청을 보냈지만 응답을 받지 못했습니다. error.message 가 둘 중 어느 쪽인지 알려 주고 잠시 후 다시 시도하라고 안내합니다. 연결 지연과 응답 지연을 가르는 별도 오류 코드는 없습니다. retryable 은 응답에 함께 옵니다.
	PROVIDER_UNAVAILABLE	세션 정보 오류 — 하나은행 응답에서 이어 쓸 세션 정보를 받지 못했거나, 받은 세션 정보를 저장하지 못했습니다. error.message 는 잠시 후 다시 시도하라고 안내하지만 retryable 은 false 입니다.
	INTERNAL_ERROR	서버 구성 문제 — 지금은 이 상품을 처리할 수 없습니다. 서버 구성 문제로 조회에 필요한 보안 처리를 실행하지 못했습니다. 서비스문의로 알려 주세요. retryable=false - 재시도로 풀리지 않습니다. 조회에 필요한 보안 처리의 규약이 어긋난 경우에는 error.message 가 '지금은 이 상품을 처리할 수 없습니다. 서비스문의로 알려 주세요.' 로 짧아지며 같은 코드와 같은 대처입니다.
	INTERNAL_ERROR	그 밖의 오류 — 위 어느 경우에도 해당하지 않는 실패입니다. error.message 는 일반 안내('서버 내부 오류로 작업을 마치지 못했습니다. 잠시 후 다시 시도해 주세요.')이고 retryable=false 입니다.

인증 - 하나은행 빠른조회

1. 하나은행 빠른조회 계좌 연결 로그인hana_fast_account.session.login

Request

Response