계좌
1. 우리은행 계좌 목록 조회woori_
MCP 도구 이름 woori_bank__accounts__list
POSThttps://api.xdata.kr/v1/jobsX-Env-Scope: sandbox
샌드박스입니다. 실제 기관을 호출하지 않는 모의 응답이며 일일 한도가 없습니다.
이 호출자가 우리은행 계좌로 등록한 연동과 그 아래 계좌를 나열합니다. 연동의 account_link_id 와 계좌의 bank_account_credential_id 를 함께 돌려주므로, 거래내역 조회를 부르기 전에 두 값을 얻는 데 씁니다. 기관에는 접속하지 않고 XBOSS 에 등록된 연동만 읽으며, 계좌번호는 가린 값으로 나옵니다.
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 | - | N | 작업 파라미터입니다. 이 API 는 빈 객체로 호출할 수 있습니다. | |
| encrypted_ | 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: sandbox' \
--header 'Idempotency-Key: demo-list-001' \
--header 'Content-Type: application/json' \
--data '{
"provider": "woori_bank",
"action": "woori_bank.accounts.list",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {}
}'Response
이 API 는 기관 응답 본문을 그대로 전달합니다. 고정 필드 목록이 없습니다.
json
{
"job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
"status": "QUEUED",
"env_scope": "sandbox",
"provider": "woori_bank",
"action": "woori_bank.accounts.list",
"submitted_at": "2026-05-27T12:34:56+09:00"
}2. 우리은행 빠른조회 거래내역 조회woori_
POSThttps://api.xdata.kr/v1/jobsX-Env-Scope: sandbox
샌드박스입니다. 실제 기관을 호출하지 않는 모의 응답이며 일일 한도가 없습니다.
기간을 지정해 우리은행 계좌의 입출금 내역과 잔액 요약을 함께 받습니다.
- 우리은행 빠른조회 세션 로그인을 먼저 호출해 세션을 등록한 뒤, 같은 account_link_id 로 호출합니다. [우리은행 빠른조회 로그인]
- sandbox 환경에서는 실제 우리은행에 접속하지 않습니다. 고정된 모의 값이 옵니다.
- sort_order(기본값 desc)는 선택입니다.
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 | - |
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": "woori_bank",
"action": "woori_bank.accounts.transaction_history.search",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {
"bank_account_credential_id": "<필수>",
"start_date": "<필수>",
"end_date": "<필수>",
"sort_order": "desc"
}
}'Response
- result.data 의 rows 로 입출금 내역을, 잔액 요약과 함께 확인합니다.
| 순번 | 변수명 | 설명 |
|---|---|---|
| success | 요청 처리 성공 여부 | |
| account_ | 연동 ID | |
| bank_ | 조회에 쓰인 계좌 자격증명 ID | |
| query | 이번 조회에 실제로 쓰인 조건 객체 | |
| account | 계좌 정보 객체 | |
| count | 조회된 건수 | |
| rows | 입출금 내역 목록 | |
| continuation | 이어받기 정보 객체 - requested_pages·has_more. 이 액션은 한 번에 최대 1페이지(50건)만 지원해 더 있으면 응답 대신 오류로 답합니다(위 오류표 참고) |
json
{
"job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
"status": "QUEUED",
"env_scope": "sandbox",
"provider": "woori_bank",
"action": "woori_bank.accounts.transaction_history.search",
"submitted_at": "2026-05-27T12:34:56+09:00"
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| INTERNAL_ | 상품 실행 잠금 — 현재 이 상품은 일시 중지 상태라 요청을 처리하지 못했습니다. 다시 시도해도 해결되지 않으니 서비스문의로 알려 주세요. retryable=false. | |
| VALIDATION_ | 파라미터 오류 — 필수값이 없거나 형식이 올바르지 않습니다(WOORI_BANK_INPUT_INVALID). retryable=false. | |
| AUTH_ | 세션 없음 — 우리은행 로그인 세션이 없습니다. session.login 을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다. retryable=false. | |
| PROVIDER_ | 세션 만료(주의: 2026-09-15 기준 도달 사례 없음) — 우리은행 세션이 흐름 중 만료되면 이 코드가 매핑되도록 설계돼 있지만, 실제로 이 신호를 던지는 코드 경로는 아직 없습니다(2026-09-15 확인). session.login 을 다시 호출합니다. retryable=false. | |
| PROVIDER_ | 자격 정보 오류(조회 중 재인증) — 이 조회는 호출마다 우리은행에 다시 인증합니다. 그 재인증에서 등록한 계좌 자격증명 형식 오류가 나면 이 코드로 옵니다. retryable=false. | |
| PROVIDER_ | 세션 갱신 실패 — 재인증에는 성공했지만 갱신된 세션을 저장하지 못했습니다(WOORI_BANK_SESSION_NOT_PERSISTED). retryable=false. | |
| INTERNAL_ | 주의: 잘못된 계좌 자격증명도 INTERNAL_ERROR — bank_account_credential_id 가 존재하지 않거나 비활성이어도 지금은 이 코드로 옵니다(수정 요청됨). 재시도보다 콘솔에서 자격증명 등록 상태를 먼저 확인합니다. | |
| PROVIDER_ | 조회 범위 초과(이어받기 미지원) — 이 조회는 한 번에 최대 50건(1페이지)만 지원합니다(v1). 기관이 더 있다고 응답하면 조용히 자르지 않고 오류로 답합니다(WOORI_BANK_RESPONSE_INVALID) - 기간을 좁혀 다시 시도합니다. | |
| PROVIDER_ | 연결 지연 — 우리은행 접속 자체가 시간 안에 되지 않았습니다. retryable 은 응답에 함께 옵니다. | |
| PROVIDER_ | 응답 지연 — 접속은 됐지만 응답이 시간 안에 오지 않았습니다. retryable 은 응답에 함께 옵니다. | |
| PROVIDER_ | 전체 시간 초과 — 접속·응답을 합친 전체 처리 시간이 한도를 넘었습니다. retryable 은 응답에 함께 옵니다. | |
| PROVIDER_ | 보안 위젯 오류 — 키보드 보안(transkey) 등 우리은행 보안 위젯을 실행하지 못했습니다. retryable 은 원인마다 다릅니다. | |
| PROVIDER_ | 그 밖의 오류 — 그 밖의 우리은행 오류입니다. retryable 은 원인마다 다릅니다. |