개발자 문서
서비스 소개키 관리자격증명 등록OpenAPI콘솔
API 레퍼런스

계좌

1. IBK 빠른계좌조회 계좌 목록ibk_fast_account.accounts.list

MCP 도구 이름 ibk_fast_account__accounts__list

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

샌드박스입니다. 실제 기관을 호출하지 않는 모의 응답이며 일일 한도가 없습니다.

이 호출자가 IBK 계좌로 등록한 연동과 그 아래 계좌를 나열합니다. 연동의 account_link_id 와 계좌의 bank_account_credential_id 를 함께 돌려주므로, 잔액 요약 조회를 부르기 전에 두 값을 얻는 데 씁니다. 기관에는 접속하지 않고 XBOSS 에 등록된 연동만 읽으며, 계좌번호는 가린 값으로 나옵니다.

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

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

[참고] 인증

X-Env-ScopeY호출 환경입니다.
  • sandbox샌드박스 — 모의 응답
  • real_test데모 — 하루 100 사용 토큰
  • production정식 — 유료 플랜 전용

[참고] 환경

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

[참고] 재시도

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

예시 : ibk_fast_account

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

예시 : ibk_fast_account.accounts.list

account_link_idstring36조건부등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명 중 대표로 지정한 것이 쓰입니다. 대표가 없으면 등록한 자격증명이 하나뿐일 때만 자동으로 선택되고, 둘 이상이면 직접 지정해야 합니다.

형식 : UUID v4

[참고] 자격증명 등록

paramsobject-N작업 파라미터입니다. 이 API 는 빈 객체로 호출할 수 있습니다.
encrypted_fieldsobject-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": "ibk_fast_account",
  "action": "ibk_fast_account.accounts.list",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {}
}'
Response

이 API 는 기관 응답 본문을 그대로 전달합니다. 고정 필드 목록이 없습니다.

json
{
    "job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
    "status": "QUEUED",
    "env_scope": "sandbox",
    "provider": "ibk_fast_account",
    "action": "ibk_fast_account.accounts.list",
    "submitted_at": "2026-05-27T12:34:56+09:00"
}

2. IBK기업은행 빠른조회 계좌 잔액 요약 조회ibk_fast_account.accounts.quick_summary.get

MCP 도구 이름 ibk_fast_account__accounts__quick_summary__get

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

샌드박스입니다. 실제 기관을 호출하지 않는 모의 응답이며 일일 한도가 없습니다.

IBK 계좌의 예금주와 원장잔액, 최근 일자별 입출금 요약을 한 번에 받습니다.

  • IBK기업은행 빠른조회 세션 로그인을 먼저 호출해 세션을 등록한 뒤, 같은 account_link_id 로 호출합니다. [IBK기업은행 빠른조회 로그인]
  • sandbox 환경에서는 실제 IBK기업은행에 접속하지 않습니다. result.data 에 마스킹된 계좌번호·예금주명('샌드박스 예금주')·원장잔액 0·빈 일자별 요약 등 고정된 모의 값이 옵니다.
Request
순번변수명필수설명
AuthorizationYAPI 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다.

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

[참고] 인증

X-Env-ScopeY호출 환경입니다.
  • sandbox샌드박스 — 모의 응답
  • real_test데모 — 하루 100 사용 토큰
  • production정식 — 유료 플랜 전용

[참고] 환경

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

[참고] 재시도

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

예시 : ibk_fast_account

actionstring-Y호출할 작업입니다.
  • ibk_fast_account.accounts.quick_summary.get이 API 고정값 (기본값)

예시 : ibk_fast_account.accounts.quick_summary.get

account_link_idstring36조건부등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명 중 대표로 지정한 것이 쓰입니다. 대표가 없으면 등록한 자격증명이 하나뿐일 때만 자동으로 선택되고, 둘 이상이면 직접 지정해야 합니다.

형식 : UUID v4

[참고] 자격증명 등록

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

[참고] 암호화

순번변수명타입필수설명
bank_account_credential_idstringN-
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-get-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "ibk_fast_account",
  "action": "ibk_fast_account.accounts.quick_summary.get",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {}
}'
Response
  • result.data 의 account 객체(마스킹된 계좌번호·예금주명·원장잔액)와 daily_summaries(최근 일자별 입출금 요약)로 확인합니다. 호출마다 IBK기업은행에 다시 인증해 그 시점 값을 가져옵니다(세션을 그냥 재사용하지 않습니다).
순번변수명설명
provider호출한 기관 - 고정값 ibk_fast_account
action이번에 처리한 액션 이름
account계좌 정보 객체 - masked_account_no(마스킹된 계좌번호) · account_holder_name(예금주명) · ledger_balance(원장잔액) · currency 를 담습니다
summary_window요약 조회 범위 객체 - day_count · from_date · to_date
daily_summaries최근 일자별 입출금 요약 목록
account_link_id연동 ID
bank_account_credential_id조회에 쓰인 계좌 자격증명 ID
json
{
    "job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
    "status": "QUEUED",
    "env_scope": "sandbox",
    "provider": "ibk_fast_account",
    "action": "ibk_fast_account.accounts.quick_summary.get",
    "submitted_at": "2026-05-27T12:34:56+09:00"
}
순번오류 코드발생 조건
AUTH_REQUIRED세션 없음 — IBK기업은행 로그인 세션이 없습니다. session.login 을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다. retryable=false.
INTERNAL_ERROR주의: 잘못된 계좌 자격증명도 INTERNAL_ERROR — bank_account_credential_id 가 존재하지 않거나 비활성이어도 지금은 이 코드로 옵니다(수정 요청됨 - 다른 provider 처럼 VALIDATION 으로 고쳐질 예정). 재시도보다 콘솔에서 자격증명 등록 상태를 먼저 확인합니다.
VALIDATION_INVALID_FIELD파라미터 오류 — bank_account_credential_id 외의 키가 섞여 있습니다(이 액션은 bank_account_credential_id 하나만 받습니다).
PROVIDER_UNAVAILABLE필수 파라미터 없음(주의: VALIDATION 이 아님) — bank_account_credential_id 자체를 생략하면(BANK_ACCOUNT_CREDENTIAL_REQUIRED) 위 파라미터 오류와 같은 VALIDATION 계열이 아니라 이 코드로 옵니다(2026-09-15 2차 검증 확인 - 매퍼의 검증 코드 목록에 없어 그렇게 됩니다). retryable=true 로 표시되지만 값을 채우지 않으면 재시도해도 똑같습니다.
PROVIDER_UNAVAILABLE세션 갱신 실패 — 다시 인증은 됐지만 갱신된 세션을 저장하지 못했습니다(IBK_FAST_ACCOUNT_SESSION_NOT_PERSISTED). retryable=false.
PROVIDER_UNAVAILABLE그 밖의 오류 — 그 밖의 IBK기업은행 오류입니다. retryable 은 원인마다 다릅니다(응답에 함께 옵니다).