거래내역 - NH농협은행 빠른조회

1. NH농협은행 빠른조회 거래내역 조회nh_fast_account.transaction_history.search

MCP 도구 이름 nh_fast_account__transaction_history__search

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

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

기간과 입출금 구분을 지정해 NH농협은행 계좌의 거래내역을 건별로 받습니다.

NH농협은행 빠른조회 세션 로그인을 먼저 호출해 세션을 등록한 뒤, 같은 account_link_id 로 호출합니다. [NH농협은행 빠른조회 로그인]
start_date 와 end_date 는 선택이고 보내지 않으면 기관 기준일로 봅니다. transaction_type(기본값 all)과 sort_order(기본값 desc)도 선택입니다.

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.transaction_history.search`이 API 고정값 (기본값) 예시 : nh_fast_account.transaction_history.search
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 연동에 등록된 사용 중인 계좌여야 합니다
start_date	string	N	조회 시작일입니다. YYYY-MM-DD 나 YYYYMMDD 형식으로 보내며 보내지 않으면 기관 기준일로 봅니다. end_date 보다 늦을 수 없고, 형식이 맞지 않거나 순서가 거꾸로이면 거절합니다. 기간이 길면 서버가 기간을 나누어 조회해 한 번에 돌려줍니다
end_date	string	N	조회 종료일입니다. 형식은 start_date 와 같고 보내지 않으면 기관 기준일로 봅니다. start_date 보다 빠를 수 없고 기관 기준일보다 늦은 날짜는 거절합니다
transaction_type	string	N	조회할 거래 구분입니다. all 은 입금과 출금 전체, deposit 은 입금만, withdrawal 은 출금만이며 보내지 않으면 all 입니다
sort_order	string	N	거래 정렬 순서입니다. desc 는 최근 거래가 먼저, asc 는 오래된 거래가 먼저이며 보내지 않으면 desc 입니다
output_formats	array	N	이 결과를 엑셀(xlsx) 파일로도 받으려면 적습니다. 예: ["xlsx"]. 파일은 result.artifacts 에 함께 오고, 빼면 데이터만 옵니다

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

Response

result.data 의 rows 로 입출금 내역을, count 로 건수를 확인합니다.

변수명	타입	설명
account_link_id	string	조회에 쓴 연동의 ID 입니다. 요청에 보낸 값입니다.
bank_account_credential_id	string	조회에 쓴 계좌의 ID 입니다. 요청에 보낸 값입니다.
query	object	이번 조회에 실제로 쓴 조건입니다.
query.start_date	string	조회 시작일입니다. YYYY-MM-DD 모양의 문자열입니다. 요청에서 보내지 않으면 기관 기준일이 들어갑니다.
query.end_date	string	조회 종료일입니다. YYYY-MM-DD 모양의 문자열입니다. 요청에서 보내지 않으면 기관 기준일이 들어갑니다.
query.transaction_type	string	거래 구분 조건입니다. all, deposit, withdrawal 중 요청에서 쓴 값이고 보내지 않으면 all 입니다.
query.sort_order	string	정렬 방향입니다. desc 또는 asc 이고 보내지 않으면 desc 입니다.
account	object	조회한 계좌의 요약입니다.
account.masked_account_number	string	가려진 계좌번호입니다. 앞 자리는 별표로 가리고 끝 네 자리만 보여 주며 전체 번호는 돌려주지 않습니다.
count	number	rows 에 담긴 거래의 건수입니다.
rows	array	거래내역 목록입니다. 조건에 맞는 거래가 없으면 빈 배열입니다.
rows[].transaction_datetime	string	거래 일시입니다. 기관 화면의 글자를 그대로 옮긴 문자열이며 날짜와 시각을 공백으로 나눈 모양입니다. 시간대 표기는 없고 날짜와 시각의 표기는 기관 화면에 따라 다를 수 있습니다.
rows[].summary	string \| null	적요입니다. 기관 화면의 칸이 비어 있으면 null 입니다.
rows[].description	string \| null	거래 내용입니다. 기관 화면의 칸이 비어 있으면 null 입니다.
rows[].deposit_amount	number \| null	입금액입니다. 원 단위 정수이고, 입금 거래가 아니면 null 입니다. 한 거래는 입금액과 출금액 중 한쪽에만 값이 있습니다.
rows[].withdrawal_amount	number \| null	출금액입니다. 원 단위 정수이고, 출금 거래가 아니면 null 입니다. 한 거래는 입금액과 출금액 중 한쪽에만 값이 있습니다.
rows[].balance	number \| null	그 거래 건의 잔액입니다. 원 단위 정수이고, 기관 화면에 값이 없으면 null 입니다.
rows[].branch_or_channel	string \| null	거래점 또는 거래 채널입니다. 기관 화면의 칸이 비어 있으면 null 입니다.
continuation	object	이어받기 정보입니다. 기관의 이어받기는 서버가 끝까지 따라가 조회 기간의 거래를 한 번에 돌려주므로 성공 응답에서 이어받을 거래는 없습니다.
continuation.requested_pages	number	기관에 조회를 보낸 기간 구간의 수입니다. 조회 기간이 길면 서버가 기간을 나누어 구간마다 조회하며, 구간 안의 이어받기는 이 수에 더해지지 않습니다.
continuation.has_more	boolean	이어받을 거래가 더 남았는지를 나타냅니다. 서버가 끝까지 따라가므로 성공 응답에서는 항상 false 입니다.

json

// result.data
{
  "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": {
    "masked_account_number": "*********5678"
  },
  "count": 2,
  "rows": [
    {
      "transaction_datetime": "2026-01-20 10:15:30",
      "summary": "급여",
      "description": "1월 급여",
      "deposit_amount": 2500000,
      "withdrawal_amount": null,
      "balance": 2750000,
      "branch_or_channel": "인터넷뱅킹"
    },
    {
      "transaction_datetime": "2026-01-12 09:02:11",
      "summary": "카드대금",
      "description": null,
      "deposit_amount": null,
      "withdrawal_amount": 300000,
      "balance": 250000,
      "branch_or_channel": "자동이체"
    }
  ],
  "continuation": {
    "requested_pages": 1,
    "has_more": false
  }
}

순번	오류 코드	발생 조건
	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)이 없거나 비어 있거나, 날짜(start_date, end_date)가 YYYY-MM-DD 나 YYYYMMDD 형식이 아니거나, transaction_type 이나 sort_order 가 허용된 값이 아니거나, 조회 기간이 규칙에 맞지 않습니다(시작일이 종료일보다 늦음, 종료일이 기관 기준일보다 뒤). 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 입니다.