잔액 - NH농협은행 빠른조회

1. NH농협은행 빠른조회 잔액 조회nh_fast_account.balance.query

MCP 도구 이름 nh_fast_account__balance__query

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

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

등록한 NH농협은행 계좌 하나의 현재 잔액과 출금 가능 금액을 받습니다.

NH농협은행 빠른조회 세션 로그인을 먼저 호출해 세션을 등록한 뒤, 같은 account_link_id 로 호출합니다. [NH농협은행 빠른조회 로그인]
bank_account_credential_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	호출할 기관입니다. `nh_fast_account`이 API 고정값 (기본값) 예시 : nh_fast_account
action	string	-	Y	호출할 작업입니다. `nh_fast_account.balance.query`이 API 고정값 (기본값) 예시 : nh_fast_account.balance.query
account_link_id	string	36	Y	등록한 자격증명을 가리키는 아이디입니다. 이 기관은 자격증명을 자동으로 고르지 않으므로 생략할 수 없습니다. 생략하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다. 형식 : UUID v4 [참고] 자격증명 등록
params	object	-	Y	작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다.
encrypted_fields	object	-	N	민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. [참고] 암호화

순번	변수명	타입	필수	설명
	bank_account_credential_id	string	Y	조회할 계좌의 ID 입니다. nh_fast_account.accounts.list 결과의 links[].accounts[].bank_account_credential_id 값을 그대로 보내며, 요청의 account_link_id 연동에 등록된 사용 중인 계좌여야 합니다

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-query-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "nh_fast_account",
  "action": "nh_fast_account.balance.query",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "bank_account_credential_id": "<필수>"
  }
}'

Response

result.data 의 balance 로 잔액을, withdrawable_amount 로 출금 가능 금액을 확인합니다.

변수명	타입	설명
account_link_id	string	조회에 쓴 연동의 ID 입니다. 요청에 보낸 값입니다.
bank_account_credential_id	string	조회에 쓴 계좌의 ID 입니다. 요청에 보낸 값입니다.
account	object	조회한 계좌의 요약입니다.
account.masked_account_number	string	가려진 계좌번호입니다. 앞 자리는 별표로 가리고 끝 네 자리만 보여 주며 전체 번호는 돌려주지 않습니다.
balance	number	계좌 잔액입니다. 원 단위 정수입니다.
withdrawable_amount	number \| null	출금 가능 금액입니다. 원 단위 정수입니다.

json

// result.data
{
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "bank_account_credential_id": "5d1e7a90-0000-4000-8000-000000000000",
  "account": {
    "masked_account_number": "*********5678"
  },
  "balance": 2750000,
  "withdrawable_amount": 2750000
}

순번	오류 코드	발생 조건
	AUTH_REQUIRED	세션 없음 — NH농협은행 빠른조회 세션이 없거나, 저장된 로그인 확인 정보를 읽지 못했습니다. session.login 을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다. retryable=false.
	PROVIDER_AUTH_FAILED	자격 정보 오류 — 이 조회는 호출마다 콘솔에 등록된 계좌 자격증명의 저장값을 읽습니다. 저장된 값이 형식에 맞지 않아 읽지 못하면 이 코드로 옵니다. retryable=false - error.message 가 안내하는 대로 콘솔에서 자격증명을 다시 등록합니다.
	VALIDATION_INVALID_FIELD	계좌 자격증명 오류 — 조회에 쓸 계좌를 찾지 못했습니다. bank_account_credential_id 가 없는 계좌이거나, 이미 해제됐거나, 요청한 연동(account_link_id)의 계좌가 아닌 경우이고, 연동한 계정을 찾지 못한 경우도 같은 코드입니다. error.provider_error_ref 는 nh_fast_account.bank_account_credential 입니다. retryable=false - error.message 가 안내하는 대로 계좌 목록에서 계좌를 다시 선택하거나 계정을 먼저 연동한 뒤 다시 요청합니다.
	VALIDATION_INVALID_FIELD	파라미터 오류 — 필수값(bank_account_credential_id)이 없거나 비어 있거나, 정해진 파라미터 밖의 값을 보냈습니다. error.message 는 '계좌 연동 정보와 조회 조건을 확인해 주세요.' 이고 error.provider_error_ref 는 nh_fast_account.NH_FAST_ACCOUNT_INPUT_INVALID 입니다. retryable=false.
	VALIDATION_INVALID_FIELD	계좌 종류 미지원 — 연동한 계좌가 빠른조회 대상이 아닌 유형입니다(유형은 계좌번호의 과목 코드로 정해지고, 외화예금은 일부 과목만 대상입니다). 기관에는 요청을 보내지 않고 거절합니다. error.message 는 '계좌 연동 정보와 조회 조건을 확인해 주세요.' 로 「파라미터 오류」 와 같아 error.message 로는 가르지 못하고 error.provider_error_ref 로 가릅니다(error.provider_error_ref 는 nh_fast_account.NH_FAST_ACCOUNT_UNSUPPORTED_ACCOUNT 입니다). retryable=false - 다른 계좌로 다시 요청합니다.
	PROVIDER_UPSTREAM_ERROR	기관 응답 오류 — NH농협은행에서 받은 응답을 성공 결과로 해석하지 못했습니다. 응답에 오류, 보안, 로그인 관련 내용이 담겨 성공 결과로 읽을 수 없는 경우, 응답의 계좌번호나 형식이 요청과 맞지 않는 경우, 기관이 조회 요청이나 보안 키패드 입력을 받아 주지 않은 경우, 보안 키패드 설정을 확인하지 못한 경우가 여기에 옵니다. retryable=true - 잠시 후 다시 시도하고, 계속되면 서비스문의로 알려 주세요.
	PROVIDER_UPSTREAM_ERROR	세션 저장 실패 — 조회는 끝났지만 갱신된 로그인 세션을 서버가 저장하지 못해 결과를 돌려주지 못했습니다. 「기관 응답 오류」 와 같은 코드라 error.code 로는 가르지 못하고 error.provider_error_ref 로 가릅니다(error.provider_error_ref 는 nh_fast_account.NH_FAST_ACCOUNT_SESSION_NOT_PERSISTED 입니다). retryable=true - 잠시 후 다시 시도하고, 계속되면 서비스문의로 알려 주세요.
	PROVIDER_UNAVAILABLE	기관 연결 실패 — NH농협은행에 연결하지 못해 요청을 보내지 못했습니다(연결이 거절되거나 끊긴 경우). retryable=true.
	PROVIDER_TIMEOUT_CONNECT	연결 지연 — NH농협은행 접속 자체가 시간 안에 되지 않았습니다. retryable=true.
	PROVIDER_TIMEOUT_READ	응답 지연 — 접속은 됐지만 NH농협은행의 응답이 시간 안에 오지 않았습니다. retryable=true.
	PROVIDER_UPSTREAM_ERROR	기관 일시 오류 — NH농협은행이 서버 오류(500 번대) 상태로 답했습니다. 「기관 응답 오류」 와 같은 코드라 error.provider_error_ref 로 가릅니다(기관이 502 로 답하면 error.provider_error_ref 는 nh_fast_account.upstream_http_502 이고, 끝의 숫자가 기관의 HTTP 상태 코드입니다). error.message 는 '일시적인 오류로 요청을 마치지 못했습니다. 잠시 후 다시 시도해 주세요.' 입니다. retryable=true.
	PROVIDER_VALIDATION_ERROR	기관 요청 거절 — NH농협은행이 요청을 거절하는 400 번대 오류 상태로 답했습니다(401 은 「그 밖의 오류」, 403 과 429 는 「접근 제한」 행입니다). error.message 는 '요청을 처리할 수 없습니다. 입력한 값을 다시 확인해 주세요.' 입니다. retryable=false - 입력한 값을 확인한 뒤에도 계속되면 서비스문의로 알려 주세요.
	PROVIDER_IP_REJECTED	접근 제한 — NH농협은행이 접근을 제한했습니다(403 또는 429 상태). 429 이면 error.message 가 '요청이 잠시 제한되었습니다. 잠시 후 다시 시도해 주세요.' 이고, 403 이면 '요청하신 자료를 조회할 권한이 없습니다. 연동한 계정에 그 권한이 있는지 확인해 주세요.' 입니다. retryable=true.
	INTERNAL_ERROR	그 밖의 오류 — 위 어느 경우에도 해당하지 않는 실패입니다. NH농협은행이 401 상태로 답한 경우도 여기에 옵니다. error.message 는 일반 안내('서버 내부 오류로 작업을 마치지 못했습니다. 잠시 후 다시 시도해 주세요.')이고 retryable=false 입니다.