인증

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

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

등록한 계좌 자격으로 우리은행 조회용 연결을 열고 연결 상태를 확인합니다.

콘솔에서 등록한 우리은행 계좌 자격증명(계좌번호·비밀번호)이 필요합니다. 이 상품의 실행 기능이 정책으로 켜져 있어야 합니다(WOORI_BANK_ENABLED). 정식 환경은 유료 플랜을 이용 중일 때만 호출할 수 있습니다.
sandbox 환경에서는 실제 우리은행에 접속하지 않습니다. 고정된 모의 값이 옵니다.
이 액션은 파라미터가 없습니다. account_link_id 로 지정한 자격증명이 쓰입니다.

Request

변수명	필수	설명
Authorization	Y	API 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다. 형식 : Basic base64("{client_id}:{client_secret}") [참고] 인증
X-Env-Scope	Y	호출 환경입니다. `sandbox`샌드박스 — 모의 응답 `real_test`데모 — 하루 100 사용 토큰 `production`정식 — 유료 플랜 전용 [참고] 환경
Idempotency-Key	Y	재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다. [참고] 재시도
Content-Type	Y	요청 본문 형식입니다. `application/json`고정값 (기본값)
X-Trace-Id	N	추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.

변수명	타입	길이	필수	설명
provider	string	-	Y	호출할 기관입니다. `woori_bank`이 API 고정값 (기본값) 예시 : woori_bank
action	string	-	Y	호출할 작업입니다. `woori_bank.session.login`이 API 고정값 (기본값) 예시 : woori_bank.session.login
account_link_id	string	36	조건부	등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명 중 대표로 지정한 것이 쓰입니다. 대표가 없으면 등록한 자격증명이 하나뿐일 때만 자동으로 선택되고, 둘 이상이면 직접 지정해야 합니다. 형식 : UUID v4 [참고] 자격증명 등록
params	object	-	N	작업 파라미터입니다. 이 API 는 빈 객체로 호출할 수 있습니다.
encrypted_fields	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-login-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "woori_bank",
  "action": "woori_bank.session.login",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {}
}'

Response

result.data 의 authenticated 로 로그인 성공 여부를, 연결 상태를 확인합니다.

순번	변수명	설명
	authenticated	인증 완료 여부
	account_link_id	연동 ID
	session_status	세션 상태 문자열(sandbox 호출이면 SANDBOX 등)
	masked_account_number	마스킹된 계좌번호 - 계좌 조회까지 됐을 때만 옵니다(조건부)

json

{
    "job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
    "status": "QUEUED",
    "env_scope": "sandbox",
    "provider": "woori_bank",
    "action": "woori_bank.session.login",
    "submitted_at": "2026-05-27T12:34:56+09:00"
}

순번	오류 코드	발생 조건
	INTERNAL_ERROR	상품 실행 잠금 — 현재 이 상품은 일시 중지 상태라 요청을 처리하지 못했습니다. 다시 시도해도 해결되지 않으니 서비스문의로 알려 주세요. retryable=false.
	PROVIDER_AUTH_FAILED	자격 정보 오류 — 등록한 계좌 자격증명으로 인증하지 못했습니다. retryable=false.
	CREDENTIAL_OWNERSHIP_DENIED	자격증명 접근 거부 — 지정한 자격증명이 이 계정 소유가 아닙니다. retryable=false.
	PROVIDER_AUTH_FAILED	로그인 거부(주의: 2026-09-15 기준 도달 사례 없음) — 우리은행이 로그인 자체를 거부하면 이 코드가 매핑되도록 설계돼 있지만, 실제로 이 경로로 던져지는 코드는 아직 없습니다(2026-09-15 확인). retryable=false.
	PROVIDER_TIMEOUT_CONNECT	연결 지연 — 우리은행 접속 자체가 시간 안에 되지 않았습니다. retryable 은 응답에 함께 옵니다.
	PROVIDER_TIMEOUT_READ	응답 지연 — 접속은 됐지만 응답이 시간 안에 오지 않았습니다. retryable 은 응답에 함께 옵니다.
	PROVIDER_TIMEOUT_OVERALL	전체 시간 초과 — 접속·응답을 합친 전체 처리 시간이 한도를 넘었습니다. retryable 은 응답에 함께 옵니다.
	PROVIDER_UPSTREAM_ERROR	기관 응답 오류 — 우리은행 응답을 해석하지 못했거나 로그인 처리 중 오류가 있었습니다. retryable=false.
	PROVIDER_UNAVAILABLE	보안 위젯 오류 — 키보드 보안(transkey) 등 우리은행 보안 위젯을 실행하지 못했습니다. retryable 은 원인마다 다릅니다.
	PROVIDER_UNAVAILABLE	그 밖의 오류 — 그 밖의 우리은행 오류입니다. retryable 은 원인마다 다릅니다.

인증

1. 우리은행 빠른조회 계좌 연결 로그인woori_bank.session.login

Request

Response