인증 - 우리은행 빠른조회
1. 우리은행 빠른조회 계좌 연결 로그인woori_ bank. session. login
MCP 도구 이름 woori_
POSThttps:// api. xdata. kr/ v1/ jobsX-Env-Scope: real_test
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
등록한 계좌 자격으로 우리은행 조회용 연결을 열고 연결 상태를 확인합니다.
- 콘솔에서 등록한 우리은행 빠른조회 계좌 자격증명이 필요합니다.등록하는 값은 계좌번호, 계좌 비밀번호 4자리, 사업자등록번호 뒷자리 5자리 입니다. 정식 환경은 라이트, 스탠다드, 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": "woori_bank",
"action": "woori_bank.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 로 로그인 성공 여부를, 연결 상태를 확인합니다.
- 여러 JSON 타입이 함께 표시된 칸은 서버가 세부 타입을 고정하지 않는 기관 원문 또는 동적 값입니다.예시 값의 타입으로 단정하지 말고 실제 값의 타입을 확인해 주세요. null은 값이 비어 있다는 뜻이며, 필드 자체의 생략 여부는 필수 여부와 설명을 확인해 주세요.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| authenticated | boolean | 인증 완료 여부 | |
| account_ | string | number | boolean | object | array | null | 연동 ID | |
| session_ | string | 세션 상태 문자열 | |
| masked_ | string | number | boolean | object | array | null | 마스킹된 계좌번호 - 계좌 조회까지 됐을 때만 옵니다(조건부) |
{
"job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
"status": "QUEUED",
"env_scope": "real_test",
"provider": "woori_bank",
"action": "woori_bank.session.login",
"submitted_at": "2026-05-27T12:34:56+09:00"
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| POLICY_ | 상품 실행 잠금 — 현재 이 상품은 일시 중지 상태라 요청을 처리하지 못했습니다. 다시 시도해도 해결되지 않으니 서비스문의로 알려 주세요. retryable=false. | |
| PROVIDER_ | 자격 정보 오류 — 콘솔에 등록된 계좌 자격증명을 쓸 수 없습니다. 등록돼 있지 않거나, 저장된 값을 읽지 못했거나, 형식에 맞지 않거나, 이 작업에 맞지 않는 경우입니다. retryable=false - error.message 가 안내하는 대로 콘솔에서 자격증명을 등록하거나 다시 등록합니다. error.message 가 서비스 제공 상태 문제라고 알리면 다시 등록해도 풀리지 않으니 서비스문의로 알려 주세요. | |
| CREDENTIAL_ | 자격증명 접근 거부 — 로그인 작업이 돌 때 지정한 연동(account_link_id)을 쓸 수 없는 것으로 판정됐습니다. 없는 연동이거나, 이 계정 소유가 아니거나, 다른 서비스의 연동이거나, 비활성인 경우를 같은 문장으로 알립니다. retryable=false - error.message 가 안내하는 대로 콘솔의 연동 화면에서 계정 ID 와 연동 상태를 확인하고 바로잡은 뒤 다시 요청합니다. 제출할 때 이미 쓸 수 없는 연동이면 작업이 만들어지기 전에 제출이 거절됩니다. | |
| PROVIDER_ | 연결 지연 — 우리은행 접속 자체가 시간 안에 되지 않았습니다. retryable 은 응답에 함께 옵니다. | |
| PROVIDER_ | 응답 지연 — 접속은 됐지만 응답이 시간 안에 오지 않았습니다. retryable 은 응답에 함께 옵니다. | |
| PROVIDER_ | 전체 시간 초과 — 접속·응답을 합친 전체 처리 시간이 한도를 넘었습니다. retryable 은 응답에 함께 옵니다. | |
| PROVIDER_ | 기관 통신 오류 — 우리은행과 통신하지 못했거나(시간 초과가 아닌 연결 실패) 우리은행이 오류 상태로 응답했습니다. error.message 는 일반 안내('서버 내부 오류로 작업을 마치지 못했습니다. 서비스문의로 알려 주세요.')이고 error.provider_error_ref 는 woori_bank.http_failed 이며 retryable=true 입니다. 「기관 응답 오류」 와 같은 코드라 error.provider_error_ref 로 가릅니다. 잠시 후 다시 시도합니다. | |
| PROVIDER_ | 기관 응답 오류 — 우리은행 응답을 해석하지 못했습니다. retryable=true. | |
| PROVIDER_ | 로그인 처리 오류 — 우리은행의 응답 문제가 아니라 서버 쪽에서 로그인 처리를 마치지 못한 경우입니다(로그인 세션을 저장하지 못한 경우 등). error.message 는 일반 안내('서버 내부 오류로 작업을 마치지 못했습니다. 서비스문의로 알려 주세요.')이고 error.provider_error_ref 는 woori_bank.login_orchestrator_failed 이며 retryable=true 입니다. 「기관 응답 오류」 와 같은 코드라 error.code 로는 가르지 못하고 error.provider_error_ref 로 가릅니다(error.message 도 다릅니다). 잠시 후 다시 시도하고, 계속되면 서비스문의로 알려 주세요. | |
| PROVIDER_ | 보안 위젯 오류 — 키보드 보안(transkey) 등 우리은행 보안 위젯을 실행하지 못했습니다. retryable=true. | |
| PROVIDER_ | 그 밖의 오류 — 그 밖의 우리은행 오류입니다. retryable=true. |