개발자 문서
API 레퍼런스

계좌 - 우리은행 빠른조회

1. 우리은행 계좌 목록 조회woori_bank.accounts.list

MCP 도구 이름 woori_bank__accounts__list

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

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

이 호출자가 우리은행 계좌로 등록한 연동과 그 아래 계좌를 나열합니다.

  • 이 API 는 기관 연동과 기관 로그인이 필요 없습니다. 기관 자격증명을 등록하지 않아도 호출할 수 있고, account_link_id 는 보내지 않습니다.

Request

순번변수명필수설명
AuthorizationYAPI 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다.

형식 : Basic base64("{client_id}:{client_secret}")

[참고] 인증

X-Env-ScopeY호출 환경입니다.
  • real_test데모 — 현재 데모 한도 확인 필요
  • production정식 — 현재 공개 요금제 전용

[참고] 환경

Idempotency-KeyY재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다.

[참고] 재시도

Content-TypeY요청 본문 형식입니다.
  • application/json고정값 (기본값)
X-Trace-IdN추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.
순번변수명타입필수설명
providerstringY호출할 기관입니다.
  • woori_bank이 API 고정값 (기본값)

예시 : woori_bank

actionstringY호출할 작업입니다.
  • woori_bank.accounts.list이 API 고정값 (기본값)

예시 : woori_bank.accounts.list

paramsobjectN작업 파라미터입니다. 이 API 는 빈 객체로 호출할 수 있습니다.
encrypted_fieldsobjectN민감한 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: real_test' \
  --header "Idempotency-Key: list-$(date +%s)-$RANDOM" \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "woori_bank",
  "action": "woori_bank.accounts.list",
  "params": {}
}'

Response

순번변수명타입설명
successboolean목록을 돌려줬다는 표지입니다. 항상 true 입니다.
providerstring연동을 가려낸 상품 구분 값입니다. 이 작업에서는 항상 woori_bank 입니다(호출한 작업 이름의 앞부분).
linksarray이 계정이 이 상품에 연결해 둔 연동 목록입니다. 사용 중인 연동만 담고 최근에 만든 연동이 앞에 옵니다. 연동이 없으면 빈 배열입니다.
links[].account_link_idstring연동 ID 입니다. 이 상품의 다른 작업을 부를 때 account_link_id 로 보냅니다.
links[].display_labelstring | null연동에 붙인 표시 이름입니다. 이름이 없으면 null 입니다.
links[].accountsarray이 연동에 등록된 계좌 목록입니다. 사용 중인 계좌만 담고 최근에 등록한 계좌가 앞에 옵니다.
links[].accounts[].bank_account_credential_idstring계좌 ID 입니다. 계좌를 고르는 작업을 부를 때 bank_account_credential_id 로 보냅니다.
links[].accounts[].masked_account_nostring가려진 계좌번호입니다. 전체 번호는 돌려주지 않습니다.
links[].accounts[].statusstring계좌의 상태입니다. 사용 중인 계좌만 담으므로 항상 ACTIVE 입니다.
link_countnumberlinks 에 담긴 연동의 수입니다.
account_countnumber모든 연동의 accounts 에 담긴 계좌의 총 수입니다.
truncatedboolean늘 false 입니다. 연동을 끝까지 모두 읽어 보내므로 빠지는 연동이 없고, 예전 응답과 맞추려고 남겨 둔 칸입니다.
json
// result.data - 값 자리에는 각 칸의 형식을 적었습니다 (실제 값이 아닙니다)
{
  "success": "<boolean>",
  "provider": "<string>",
  "links": [
    {
      "account_link_id": "<string>",
      "display_label": "<string | null>",
      "accounts": [
        {
          "bank_account_credential_id": "<string>",
          "masked_account_no": "<string>",
          "status": "<string>"
        }
      ]
    }
  ],
  "link_count": "<number>",
  "account_count": "<number>",
  "truncated": "<boolean>"
}

MCP 도구 이름 woori_bank__accounts__transaction_history__search

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

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

기간을 지정해 우리은행 계좌의 입출금 내역과 잔액 요약을 함께 받습니다.

  • 우리은행 빠른조회 세션 로그인을 먼저 호출해 세션을 등록한 뒤, 같은 account_link_id 로 호출합니다. [우리은행 빠른조회 로그인]
  • sort_order(기본값 desc)는 선택입니다.

Request

순번변수명필수설명
AuthorizationYAPI 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다.

형식 : Basic base64("{client_id}:{client_secret}")

[참고] 인증

X-Env-ScopeY호출 환경입니다.
  • real_test데모 — 현재 데모 한도 확인 필요
  • production정식 — 현재 공개 요금제 전용

[참고] 환경

Idempotency-KeyY재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다.

[참고] 재시도

Content-TypeY요청 본문 형식입니다.
  • application/json고정값 (기본값)
X-Trace-IdN추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.
순번변수명타입길이필수설명
providerstring-Y호출할 기관입니다.
  • woori_bank이 API 고정값 (기본값)

예시 : woori_bank

actionstring-Y호출할 작업입니다.
  • woori_bank.accounts.transaction_history.search이 API 고정값 (기본값)

예시 : woori_bank.accounts.transaction_history.search

account_link_idstring36Y등록한 자격증명을 가리키는 아이디입니다. 이 기관은 자격증명을 자동으로 고르지 않으므로 생략할 수 없습니다. 생략하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다.

형식 : UUID v4

[참고] 자격증명 등록

paramsobject-Y작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다.
encrypted_fieldsobject-N민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다.

[참고] 암호화

순번변수명타입필수설명
bank_account_credential_idstringY조회할 계좌의 ID 입니다. woori_bank.accounts.list 결과의 links[].accounts[].bank_account_credential_id 값을 그대로 보내며, 요청의 account_link_id 연동에 등록된 사용 중인 계좌여야 합니다
start_datestringY조회 시작일입니다. YYYY-MM-DD 나 YYYYMMDD 형식으로 보내며 end_date 보다 늦을 수 없고, 형식이 맞지 않거나 순서가 거꾸로이면 거절합니다. 조회 기간의 거래가 50건 이상이면 한 번에 다 받았는지 확인할 수 없어 결과를 돌려주지 않고 실패하므로 기간을 나누어 보냅니다
end_datestringY조회 종료일입니다. 형식은 start_date 와 같고 start_date 보다 빠를 수 없습니다
sort_orderstringN거래 정렬 순서입니다. desc 는 최근 거래가 먼저, asc 는 오래된 거래가 먼저이며 보내지 않으면 desc 입니다

예시 : desc

output_formatsarrayN이 결과를 엑셀(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: search-$(date +%s)-$RANDOM" \
  --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 로 입출금 내역을, 잔액 요약과 함께 확인합니다.
순번변수명타입설명
successboolean조회를 마쳤다는 표지입니다. 성공 응답에서는 항상 true 입니다.
account_link_idstring조회에 쓴 연동의 ID 입니다. 요청에 보낸 값입니다.
bank_account_credential_idstring조회에 쓴 계좌의 ID 입니다. 요청에 보낸 값입니다.
queryobject이번 조회에 실제로 쓴 조건입니다.
query.start_datestring조회 시작일입니다. 요청에 보낸 값을 YYYY-MM-DD 모양으로 맞춘 문자열입니다.
query.end_datestring조회 종료일입니다. 요청에 보낸 값을 YYYY-MM-DD 모양으로 맞춘 문자열입니다.
query.sort_orderstring정렬 방향입니다. 요청에서 쓴 값(desc 또는 asc)입니다.
query.page_sizenumber한 번에 가져오는 거래 건수의 상한입니다. 이 작업에서는 항상 50 입니다.
accountobject조회한 계좌의 요약입니다.
account.account_no_displaystring가려진 계좌번호입니다. 전체 번호는 돌려주지 않습니다.
account.balancenumber | null계좌 잔액입니다. 원 단위 정수이고, 기관이 값을 주지 않으면 null 입니다.
account.withdrawable_amountnumber | null출금 가능 금액입니다. 원 단위 정수이고, 기관이 값을 주지 않으면 null 입니다.
countnumberrows 에 담긴 거래의 건수입니다.
rowsarray거래내역 목록입니다. 조건에 맞는 거래가 없으면 빈 배열입니다.
rows[].transaction_datetimestring거래 일시입니다. 기관 화면의 시각을 YYYY-MM-DDTHH:MM:SS 모양으로 옮긴 문자열이며 시간대 표기는 없습니다.
rows[].summarystring | null적요입니다. 기관 화면의 칸이 비어 있으면 null 입니다.
rows[].descriptionstring | null거래 내용입니다. 기관 화면의 칸이 비어 있으면 null 입니다.
rows[].withdrawal_amountnumber | null출금액입니다. 원 단위 정수이고, 기관 화면의 칸이 비어 있으면 null 입니다.
rows[].deposit_amountnumber | null입금액입니다. 원 단위 정수이고, 기관 화면의 칸이 비어 있으면 null 입니다.
rows[].balancenumber | null그 거래 건의 잔액입니다. 원 단위 정수이고, 기관 화면의 칸이 비어 있으면 null 입니다.
rows[].branch_or_channelstring | null거래점 또는 거래 채널입니다. 기관 화면의 칸이 비어 있으면 null 입니다.
rows[].transaction_nostring | null기관이 거래에 붙인 번호입니다. 기관 화면의 칸이 비어 있으면 null 입니다.
rows[].securities_amountnumber | null유가증권 금액입니다. 원 단위 정수이고, 기관 화면의 칸이 비어 있으면 null 입니다.
continuationobject이어받기 정보입니다. 이 작업은 한 번에 1쪽만 가져옵니다. 기관에 더 있으면 응답 대신 오류로 끝나므로(오류표 참고) 성공 응답에서 이어받을 거래는 없습니다.
continuation.requested_pagesnumber가져온 쪽 수입니다. 이 작업에서는 항상 1 입니다.
continuation.has_moreboolean이어받을 거래가 더 남았는지를 나타냅니다. 더 있으면 응답 대신 오류로 끝나므로 성공 응답에서는 항상 false 입니다.
json
// result.data
{
  "success": true,
  "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",
    "sort_order": "desc",
    "page_size": 50
  },
  "account": {
    "account_no_display": "123-******-789",
    "balance": 2750000,
    "withdrawable_amount": 2750000
  },
  "count": 2,
  "rows": [
    {
      "transaction_datetime": "2026-01-20T10:15:30",
      "summary": "급여",
      "description": "1월 급여",
      "withdrawal_amount": null,
      "deposit_amount": 2500000,
      "balance": 2750000,
      "branch_or_channel": "인터넷뱅킹",
      "transaction_no": "000102",
      "securities_amount": null
    },
    {
      "transaction_datetime": "2026-01-12T09:02:11",
      "summary": "카드대금",
      "description": null,
      "withdrawal_amount": 300000,
      "deposit_amount": null,
      "balance": 250000,
      "branch_or_channel": "자동이체",
      "transaction_no": "000101",
      "securities_amount": null
    }
  ],
  "continuation": {
    "requested_pages": 1,
    "has_more": false
  }
}
순번오류 코드발생 조건
POLICY_FEATURE_DISABLED상품 실행 잠금 — 현재 이 상품은 일시 중지 상태라 요청을 처리하지 못했습니다. 다시 시도해도 해결되지 않으니 서비스문의로 알려 주세요. retryable=false.
VALIDATION_INVALID_FIELD파라미터 오류 — 필수값이 없거나 형식이 올바르지 않습니다(WOORI_BANK_INPUT_INVALID). retryable=false.
AUTH_REQUIRED세션 없음 — 우리은행 로그인 세션이 없습니다. session.login 을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다. retryable=false.
PROVIDER_AUTH_FAILED자격 정보 오류 — 이 조회는 호출마다 콘솔에 등록된 계좌 자격증명의 저장값을 읽습니다. 저장된 값이 형식에 맞지 않아 읽지 못하면 이 코드로 옵니다. retryable=false - error.message 가 안내하는 대로 콘솔에서 자격증명을 다시 등록합니다.
PROVIDER_UPSTREAM_ERROR세션 갱신 실패 — 재인증에는 성공했지만 갱신된 세션을 저장하지 못했습니다(WOORI_BANK_SESSION_NOT_PERSISTED). retryable=true.
VALIDATION_INVALID_FIELD계좌 자격증명 오류 — 조회에 쓸 계좌를 찾지 못했습니다. bank_account_credential_id 가 없는 계좌이거나, 이미 해제됐거나, 요청한 연동(account_link_id)의 계좌가 아닌 경우이고, 연동한 계정을 찾지 못한 경우도 같은 코드입니다. error.provider_error_ref 는 woori_bank.bank_account_credential 입니다. retryable=false - error.message 가 안내하는 대로 계좌 목록에서 계좌를 다시 선택하거나 계정을 먼저 연동한 뒤 다시 요청합니다.
VALIDATION_INVALID_FIELD조회 범위 초과(이어받기 미지원) — 이 조회는 한 번에 한 쪽(최대 50건)만 가져옵니다(v1). 기관이 다음 쪽이 있다고 답하거나 거래가 50건에 닿으면 끝까지 받았는지 확인할 수 없어 조용히 자르지 않고 오류로 답합니다. error.provider_error_ref 는 woori_bank.transaction_continuation_limit 입니다. retryable=false - 기간을 나누어 다시 요청합니다.
PROVIDER_TIMEOUT_CONNECT연결 지연 — 우리은행 접속 자체가 시간 안에 되지 않았습니다. retryable 은 응답에 함께 옵니다.
PROVIDER_TIMEOUT_READ응답 지연 — 접속은 됐지만 응답이 시간 안에 오지 않았습니다. retryable 은 응답에 함께 옵니다.
PROVIDER_TIMEOUT_OVERALL전체 시간 초과 — 접속·응답을 합친 전체 처리 시간이 한도를 넘었습니다. retryable 은 응답에 함께 옵니다.
PROVIDER_UPSTREAM_ERROR기관 통신 오류 — 우리은행과 통신하지 못했거나(시간 초과가 아닌 연결 실패) 우리은행이 오류 상태로 응답했습니다. error.message 는 일반 안내('서버 내부 오류로 작업을 마치지 못했습니다. 서비스문의로 알려 주세요.')이고 error.provider_error_ref 는 woori_bank.http_failed 이며 retryable=true 입니다. 「기관 응답 오류」 와 같은 코드라 error.provider_error_ref 로 가릅니다. 잠시 후 다시 시도합니다.
PROVIDER_UNAVAILABLE보안 위젯 오류 — 키보드 보안(transkey) 등 우리은행 보안 위젯을 실행하지 못했습니다. retryable=true.
PROVIDER_UNAVAILABLE그 밖의 오류 — 그 밖의 우리은행 오류입니다. retryable=true.