계좌
1. 신한은행 간편조회 계좌 목록 조회shinhan_
MCP 도구 이름 shinhan_easy__accounts__list
POSThttps://api.xdata.kr/v1/jobsX-Env-Scope: sandbox
샌드박스입니다. 실제 기관을 호출하지 않는 모의 응답이며 일일 한도가 없습니다.
연결된 신한 계좌를 계좌번호와 별칭, 계좌 과목까지 한 번에 나열합니다.
- 신한은행 간편조회 세션 로그인을 먼저 호출해 세션을 등록한 뒤, 같은 account_link_id 로 호출합니다. [신한은행 간편조회 로그인]
- sandbox 환경에서는 실제 신한은행에 접속하지 않습니다. result.data 에는 mock: true 와 보낸 params 를 그대로 담은 params_echo 가 오고, 업무 응답 필드는 오지 않습니다.
- include_raw(기관 원본 값 포함 여부)는 선택입니다.
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 | 조건부 | 등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명 중 대표로 지정한 것이 쓰입니다. 대표가 없으면 등록한 자격증명이 하나뿐일 때만 자동으로 선택되고, 둘 이상이면 직접 지정해야 합니다. | |
| params | object | - | Y | 작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다. | |
| encrypted_ | object | - | N | 민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| include_ | boolean | N | - |
bash
curl --request POST \
--url 'https://api.xdata.kr/v1/jobs' \
--header 'Authorization: Basic {base64(client_id:client_secret)}' \
--header 'X-Env-Scope: sandbox' \
--header 'Idempotency-Key: demo-list-001' \
--header 'Content-Type: application/json' \
--data '{
"provider": "shinhan_easy",
"action": "shinhan_easy.accounts.list",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {}
}'Response
- result.data 의 accounts 로 연결된 계좌 목록을(계좌번호·별칭·계좌 과목) 확인합니다.
| 순번 | 변수명 | 설명 |
|---|---|---|
| success | 요청 처리 성공 여부 | |
| account_ | 연동 ID | |
| count | 조회된 계좌 수(1건 이상 - 0건이면 성공이 아니라 오류로 옵니다) | |
| accounts | 계좌 목록 - 계좌번호·별칭·계좌 과목을 담습니다 | |
| raw | 기관 원본 응답 보존 객체 - include_raw:true 일 때만 옵니다(기본값 true) |
json
{
"job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
"status": "QUEUED",
"env_scope": "sandbox",
"provider": "shinhan_easy",
"action": "shinhan_easy.accounts.list",
"submitted_at": "2026-05-27T12:34:56+09:00"
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| INTERNAL_ | 상품 실행 잠금 — 현재 이 상품은 일시 중지 상태라 요청을 처리하지 못했습니다. 다시 시도해도 해결되지 않으니 서비스문의로 알려 주세요. retryable=false. | |
| AUTH_ | 세션 없음 — 신한은행 간편조회 세션이 없습니다. auth.id_password_session.login 을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다. retryable=false. | |
| VALIDATION_ | 입력값 오류·연결된 계좌 없음 — 보낸 값이 이 액션의 요청 형식과 맞지 않거나(필수 필드 누락·타입 불일치), 이 로그인에 연결된 계좌가 없습니다(SHINHAN_ACCOUNT_LIST_EMPTY). | |
| PROVIDER_ | 그 밖의 오류 — 그 밖의 신한은행 오류입니다. retryable=true 로 표시되지만 원인이 값 자체라면 재시도로 풀리지 않습니다 - 메시지를 먼저 확인합니다. |
2. 신한은행 간편조회 거래내역 조회shinhan_
MCP 도구 이름 shinhan_easy__accounts__transaction_history__search
POSThttps://api.xdata.kr/v1/jobsX-Env-Scope: sandbox
샌드박스입니다. 실제 기관을 호출하지 않는 모의 응답이며 일일 한도가 없습니다.
기간을 지정해 신한 계좌의 입출금 내역을 계좌 요약과 함께 건별로 받습니다.
- 신한은행 간편조회 세션 로그인을 먼저 호출해 세션을 등록한 뒤, 같은 account_link_id 로 호출합니다. [신한은행 간편조회 로그인]
- sandbox 환경에서는 실제 신한은행에 접속하지 않습니다. result.data 에는 mock: true 와 보낸 params 를 그대로 담은 params_echo 가 오고, 업무 응답 필드는 오지 않습니다.
- sort_order(기본값 desc)·business_type·employee_yn·max_pages(기본값 20)·include_raw 는 모두 선택입니다.
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 | 조건부 | 등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명 중 대표로 지정한 것이 쓰입니다. 대표가 없으면 등록한 자격증명이 하나뿐일 때만 자동으로 선택되고, 둘 이상이면 직접 지정해야 합니다. | |
| params | object | - | Y | 작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다. | |
| encrypted_ | object | - | N | 민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| bank_ | string | Y | - | |
| start_ | string | Y | - | |
| end_ | string | Y | - | |
| sort_ | string | N | - | |
| business_ | string | N | - | |
| employee_ | string | N | - | |
| max_ | number | N | - | |
| include_ | boolean | N | - |
bash
curl --request POST \
--url 'https://api.xdata.kr/v1/jobs' \
--header 'Authorization: Basic {base64(client_id:client_secret)}' \
--header 'X-Env-Scope: sandbox' \
--header 'Idempotency-Key: demo-search-001' \
--header 'Content-Type: application/json' \
--data '{
"provider": "shinhan_easy",
"action": "shinhan_easy.accounts.transaction_history.search",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {
"bank_account_credential_id": "<필수>",
"start_date": "<필수>",
"end_date": "<필수>",
"sort_order": "desc",
"business_type": "2",
"employee_yn": "2",
"max_pages": 20
}
}'Response
- result.data 의 rows 로 입출금 내역을, 계좌 요약과 함께 건별로 확인합니다.
| 순번 | 변수명 | 설명 |
|---|---|---|
| success | 요청 처리 성공 여부 | |
| account_ | 연동 ID | |
| query | 이번 조회에 실제로 쓰인 조건 객체 | |
| account | 계좌 요약 정보 객체 | |
| count | 조회된 건수 | |
| rows | 입출금 내역 목록(정리된 값) | |
| rows_ | 입출금 내역 목록(기관 원본 값) | |
| continuation | 이어받기 정보 객체 - requested_pages·has_more·next_transaction_no·next_sub_transaction_no. max_pages 안에서 자동으로 이어받은 결과입니다 - has_more 가 true 로 남으면 max_pages 를 늘려 다시 조회합니다(그 전에 한도를 넘기면 오류로 답합니다 - 위 오류표 참고) | |
| raw_ | 기관 원본 필드명 대응 객체 | |
| raw | 기관 원본 응답 보존 객체 - include_raw:true 일 때만 옵니다 |
json
{
"job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
"status": "QUEUED",
"env_scope": "sandbox",
"provider": "shinhan_easy",
"action": "shinhan_easy.accounts.transaction_history.search",
"submitted_at": "2026-05-27T12:34:56+09:00"
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| INTERNAL_ | 상품 실행 잠금 — 현재 이 상품은 일시 중지 상태라 요청을 처리하지 못했습니다. 다시 시도해도 해결되지 않으니 서비스문의로 알려 주세요. retryable=false. | |
| AUTH_ | 세션 없음 — 신한은행 간편조회 세션이 없습니다. auth.id_password_session.login 을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다. retryable=false. | |
| VALIDATION_ | 계좌 자격증명 오류 — bank_account_credential_id 가 존재하지 않거나 비활성입니다. 이 provider 는 이 오류를 정확히 구분해 안내합니다(다른 은행 3종은 INTERNAL_ERROR 로 옵니다 - 위 provider 공통 설명 참고). | |
| VALIDATION_ | 입력값 오류·연결된 계좌 없음 — 보낸 값이 이 액션의 요청 형식과 맞지 않거나(필수 필드 누락·타입 불일치), 이 로그인에 연결된 계좌가 없습니다(SHINHAN_ACCOUNT_LIST_EMPTY). | |
| PROVIDER_ | 조회 범위 초과 — max_pages 안에서 이어받았는데도 기관이 여전히 다음 페이지가 있다고 응답합니다(SHINHAN_TRANSACTION_CONTINUATION_LIMIT_EXCEEDED). 조용히 자르지 않고 오류로 답합니다 - max_pages 를 늘리거나 기간을 좁혀 다시 시도합니다. | |
| PROVIDER_ | 그 밖의 오류 — 그 밖의 신한은행 오류입니다. retryable=true 로 표시되지만 원인이 값 자체라면 재시도로 풀리지 않습니다 - 메시지를 먼저 확인합니다. |