인증 - IBK기업은행 빠른조회
1. IBK기업은행 빠른조회 계좌 연결 로그인ibk_ fast_ account. session. login
MCP 도구 이름 ibk_
POSThttps:// api. xdata. kr/ v1/ jobsX-Env-Scope: real_test
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
IBK 계좌 자격으로 조회용 연결을 열고 일부가 가려진 계좌번호로 대상 계좌를 확인합니다.
- 콘솔에서 등록한 IBK기업은행 빠른조회 계좌 자격증명이 필요합니다.등록하는 값은 계좌번호, 계좌 비밀번호 4자리, 사업자등록번호 뒷자리 7자리 (개인은 생년월일 6자리) 입니다. 정식 환경은 라이트, 스탠다드, 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: login-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "ibk_fast_account",
"action": "ibk_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": "ibk_fast_account",
"action": "ibk_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 와 연동 상태를 확인하고 바로잡은 뒤 다시 요청합니다. 제출할 때 이미 쓸 수 없는 연동이면 작업이 만들어지기 전에 제출이 거절됩니다. | |
| PROVIDER_ | 기관 응답 오류 — IBK기업은행 응답을 해석하지 못했습니다. retryable=true. | |
| PROVIDER_ | 로그인 처리 오류 — IBK기업은행의 응답 문제가 아니라 서버 쪽에서 로그인 처리를 마치지 못한 경우입니다(로그인 세션을 저장하지 못한 경우 등). error.message 는 일반 안내('서버 내부 오류로 작업을 마치지 못했습니다. 서비스문의로 알려 주세요.')이고 error.provider_error_ref 는 ibk_fast_account.login_orchestrator_failed 이며 retryable=true 입니다. 「기관 응답 오류」 와 같은 코드라 error.code 로는 가르지 못하고 error.provider_error_ref 로 가릅니다(error.message 도 다릅니다). 잠시 후 다시 시도하고, 계속되면 서비스문의로 알려 주세요. | |
| PROVIDER_ | 그 밖의 오류 — 그 밖의 IBK기업은행 오류입니다. retryable=true. |