인증 - NH농협은행 빠른조회
1. NH농협은행 빠른조회 계좌 연결 로그인nh_
MCP 도구 이름 nh_
POSThttps://
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
등록한 계좌 자격으로 NH농협은행 조회용 연결을 열고 연결 상태를 확인합니다.
- 콘솔에서 등록한 NH농협은행 계좌 자격증명(계좌번호, 계좌 비밀번호 4자리, 사업자등록번호 10자리)이 필요합니다.정식 환경은 라이트, 스탠다드, PRO 또는 멀티계정 요금제를 이용 중일 때만 호출할 수 있습니다.
- 지정한 연동(account_link_id)을 쓸 수 없으면(없는 연동이거나, 이 계정 소유가 아니거나, 다른 서비스의 연동이거나, 비활성인 경우) 제출이 400 VALIDATION_INVALID_FIELD 로 거절되고 작업이 만들어지지 않습니다.error.message 가 안내하는 대로 콘솔의 연동 화면에서 계정 ID 와 연동 상태를 확인하고 바로잡은 뒤 다시 제출합니다.
- 이 액션은 파라미터가 없습니다. account_link_id 로 지정한 자격증명이 쓰입니다.
Request
| 순번 | 변수명 | 필수 | 설명 |
|---|---|---|---|
| Authorization | Y | API 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다. | |
| X- | Y | 호출 환경입니다.
| |
| Idempotency- | Y | 재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다. | |
| Content- | Y | 요청 본문 형식입니다.
| |
| X- | N | 추적 아이디입니다. 지정하지 않으면 서버가 발급합니다. |
| 순번 | 변수명 | 타입 | 길이 | 필수 | 설명 |
|---|---|---|---|---|---|
| provider | string | - | Y | 호출할 기관입니다.
| |
| action | string | - | Y | 호출할 작업입니다.
| |
| account_ | string | 36 | Y | 등록한 자격증명을 가리키는 아이디입니다. 이 기관은 자격증명을 자동으로 고르지 않으므로 생략할 수 없습니다. 생략하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다. | |
| params | object | - | N | 작업 파라미터입니다. 이 API 는 빈 객체로 호출할 수 있습니다. | |
| encrypted_ | object | - | N | 민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. |
추가 파라미터가 없습니다. params 는 {} 로 보냅니다.
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": "nh_fast_account",
"action": "nh_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 로 세션 상태를 확인합니다.로그인은 등록한 계좌로 빠른조회를 한 번 실행해 확인하며, 성공하면 masked_account_number(마스킹된 계좌번호)도 옵니다.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| authenticated | boolean | 인증 완료 여부 | |
| account_ | string | 연동 ID | |
| session_ | string | 세션 상태 문자열 | |
| masked_ | string | 마스킹된 계좌번호 - 계좌 조회까지 됐을 때만 옵니다(조건부) |
{
"job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
"status": "QUEUED",
"env_scope": "real_test",
"provider": "nh_fast_account",
"action": "nh_fast_account.session.login",
"submitted_at": "2026-05-27T12:34:56+09:00"
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| PROVIDER_ | 자격 정보 오류 — 콘솔에 등록된 계좌 자격증명을 쓸 수 없습니다. 등록돼 있지 않거나, 저장된 값을 읽지 못했거나, 형식에 맞지 않거나, 이 작업에 맞지 않는 경우입니다. retryable=false - error.message 가 안내하는 대로 콘솔에서 자격증명을 등록하거나 다시 등록합니다. error.message 가 서비스 제공 상태 문제라고 알리면 다시 등록해도 풀리지 않으니 서비스문의로 알려 주세요. | |
| CREDENTIAL_ | 자격증명 접근 거부 — 로그인 작업이 돌 때 지정한 연동(account_link_id)을 쓸 수 없는 것으로 판정됐습니다. 없는 연동이거나, 이 계정 소유가 아니거나, 다른 서비스의 연동이거나, 비활성인 경우를 같은 문장으로 알립니다. retryable=false - error.message 가 안내하는 대로 콘솔의 연동 화면에서 계정 ID 와 연동 상태를 확인하고 바로잡은 뒤 다시 요청합니다. 제출할 때 이미 쓸 수 없는 연동이면 작업이 만들어지기 전에 제출이 거절됩니다. | |
| VALIDATION_ | 파라미터 오류 — 이 액션에 조회 조건 같은 파라미터를 함께 보냈습니다. error.message 는 '계좌 연동 정보와 조회 조건을 확인해 주세요.' 이고 error.provider_error_ref 는 nh_fast_account.NH_FAST_ACCOUNT_INPUT_INVALID 입니다. retryable=false - 파라미터 없이 다시 요청합니다. | |
| VALIDATION_ | 계좌 종류 미지원 — 연동한 계좌가 빠른조회 대상이 아닌 유형입니다(유형은 계좌번호의 과목 코드로 정해지고, 외화예금은 일부 과목만 대상입니다). 기관에는 요청을 보내지 않고 거절합니다. error.message 는 '계좌 연동 정보와 조회 조건을 확인해 주세요.' 로 「파라미터 오류」 와 같아 error.message 로는 가르지 못하고 error.provider_error_ref 로 가릅니다(error.provider_error_ref 는 nh_fast_account.NH_FAST_ACCOUNT_UNSUPPORTED_ACCOUNT 입니다). retryable=false - 다른 계좌로 다시 요청합니다. | |
| PROVIDER_ | 기관 응답 오류 — NH농협은행에서 받은 응답을 성공 결과로 해석하지 못했습니다. 응답에 오류, 보안, 로그인 관련 내용이 담겨 성공 결과로 읽을 수 없는 경우, 응답의 계좌번호나 형식이 요청과 맞지 않는 경우, 기관이 조회 요청이나 보안 키패드 입력을 받아 주지 않은 경우, 보안 키패드 설정을 확인하지 못한 경우가 여기에 옵니다. retryable=true - 잠시 후 다시 시도하고, 계속되면 서비스문의로 알려 주세요. | |
| PROVIDER_ | 세션 저장 실패 — 로그인 확인은 끝났지만 로그인 세션을 저장하지 못했거나, 저장한 세션을 다시 읽지 못했습니다. 「기관 응답 오류」 와 같은 코드라 error.code 로는 가르지 못하고 error.provider_error_ref 로 가릅니다(error.provider_error_ref 는 nh_fast_account.NH_FAST_ACCOUNT_SESSION_NOT_PERSISTED 입니다). retryable=true - 잠시 후 다시 시도하고, 계속되면 서비스문의로 알려 주세요. | |
| PROVIDER_ | 로그인 처리 오류 — NH농협은행의 응답 문제가 아니라 서버 쪽에서 로그인 처리를 마치지 못한 경우입니다(로그인 세션을 저장하지 못한 경우 등). error.message 는 일반 안내('서버 내부 오류로 작업을 마치지 못했습니다. 잠시 후 다시 시도해 주세요.')이고 error.provider_error_ref 는 nh_fast_account.login_orchestrator_failed 이며 retryable=true 입니다. 「기관 응답 오류」 와 같은 코드라 error.code 로는 가르지 못하고 error.provider_error_ref 로 가릅니다(error.message 도 다릅니다). 잠시 후 다시 시도하고, 계속되면 서비스문의로 알려 주세요. | |
| PROVIDER_ | 기관 연결 실패 — NH농협은행에 연결하지 못해 요청을 보내지 못했습니다(연결이 거절되거나 끊긴 경우). retryable=true. | |
| PROVIDER_ | 연결 지연 — NH농협은행 접속 자체가 시간 안에 되지 않았습니다. retryable=true. | |
| PROVIDER_ | 응답 지연 — 접속은 됐지만 NH농협은행의 응답이 시간 안에 오지 않았습니다. retryable=true. | |
| PROVIDER_ | 기관 일시 오류 — NH농협은행이 서버 오류(500 번대) 상태로 답했습니다. 「기관 응답 오류」 와 같은 코드라 error.provider_error_ref 로 가릅니다(기관이 502 로 답하면 error.provider_error_ref 는 nh_fast_account.upstream_http_502 이고, 끝의 숫자가 기관의 HTTP 상태 코드입니다). error.message 는 '일시적인 오류로 요청을 마치지 못했습니다. 잠시 후 다시 시도해 주세요.' 입니다. retryable=true. | |
| PROVIDER_ | 기관 요청 거절 — NH농협은행이 요청을 거절하는 400 번대 오류 상태로 답했습니다(401 은 「그 밖의 오류」, 403 과 429 는 「접근 제한」 행입니다). error.message 는 '요청을 처리할 수 없습니다. 입력한 값을 다시 확인해 주세요.' 입니다. retryable=false - 입력한 값을 확인한 뒤에도 계속되면 서비스문의로 알려 주세요. | |
| PROVIDER_ | 접근 제한 — NH농협은행이 접근을 제한했습니다(403 또는 429 상태). 429 이면 error.message 가 '요청이 잠시 제한되었습니다. 잠시 후 다시 시도해 주세요.' 이고, 403 이면 '요청하신 자료를 조회할 권한이 없습니다. 연동한 계정에 그 권한이 있는지 확인해 주세요.' 입니다. retryable=true. | |
| INTERNAL_ | 그 밖의 오류 — 위 어느 경우에도 해당하지 않는 실패입니다. NH농협은행이 401 상태로 답한 경우도 여기에 옵니다. error.message 는 일반 안내('서버 내부 오류로 작업을 마치지 못했습니다. 잠시 후 다시 시도해 주세요.')이고 retryable=false 입니다. |