인증

MCP 도구 이름 kb_biz_card__session__login

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

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

법인 공동인증서로 KB국민카드 기업카드 사이트에 로그인해 조회용 세션을 등록합니다.

콘솔에서 발급한 API 키와 등록한 공동인증서가 필요합니다. 정식 환경은 유료 플랜을 이용 중일 때만 호출할 수 있습니다.
sandbox 환경에서는 실제 KB국민카드에 접속하지 않습니다. result.data 에는 mock: true 와 보낸 params 를 그대로 담은 params_echo 가 오고, 업무 응답 필드는 오지 않습니다.
auth_provider(기본값 npki_delfino, 그 외 값은 오류)·timeout(초 단위, 기본값 45)은 모두 선택입니다.

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	호출할 기관입니다. `kb_biz_card`이 API 고정값 (기본값) 예시 : kb_biz_card
action	string	-	Y	호출할 작업입니다. `kb_biz_card.session.login`이 API 고정값 (기본값) 예시 : kb_biz_card.session.login
account_link_id	string	36	조건부	등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명 중 대표로 지정한 것이 쓰입니다. 대표가 없으면 등록한 자격증명이 하나뿐일 때만 자동으로 선택되고, 둘 이상이면 직접 지정해야 합니다. 형식 : UUID v4 [참고] 자격증명 등록
params	object	-	Y	작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다.
encrypted_fields	object	-	N	민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. [참고] 암호화

순번	변수명	타입	필수	설명
	auth_provider	string	N	-
	timeout	string	N	-

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": "kb_biz_card",
  "action": "kb_biz_card.session.login",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {}
}'

Response

result.data 의 authenticated·session_registered 로 로그인과 세션 등록 여부를, cookie_count 로 확보한 쿠키 수를 확인합니다.

순번	변수명	설명
	success	요청 처리 성공 여부
	account_link_id	연동 ID
	authenticated	인증 완료 여부
	session_registered	세션 저장 완료 여부
	cookie_count	저장된 쿠키 수
	auth_provider	인증 방식 - 등록한 공동인증서(npki_delfino)
	generation_status	세션 생성 상태
	login_probe	로그인 확인 요청 결과

json

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

순번	오류 코드	발생 조건
	INTERNAL_ERROR	서버 구성 결함(운영 미해결) — 지금은 이 상품을 처리할 수 없습니다. 서버 구성 문제로 로그인 단계를 실행하지 못했습니다. 서비스문의로 알려 주세요. retryable=false - 재시도로 풀리지 않습니다(2026-09-26 기준 CLAUDE.md §5 정정 - 운영 VM 에는 Node.js 가 설치돼 있습니다. 이 오류가 지금도 로그인마다 나는지는 운영 로그로 아직 확정되지 않았고, 남은 조건으로 의심되는 것은 브라우저 신원 환경변수 하나뿐입니다).
	PROVIDER_AUTH_FAILED	인증서 인증 실패 — 등록된 공동인증서로 KB국민카드 인증에 실패했습니다(KB_BIZ_CARD_LOGIN_NOT_AUTHENTICATED). retryable=false - 재시도로 풀리지 않으므로 등록한 인증서와 계정 정보를 먼저 확인합니다.
	PROVIDER_AUTH_FAILED	세션 저장 실패 — 인증에는 성공했지만 세션을 저장하지 못했거나 저장한 세션을 다시 읽지 못했습니다(KB_BIZ_CARD_SESSION_NOT_PERSISTED). retryable=false 로 응답합니다 - 같은 원인이면 다시 호출해도 풀리지 않을 수 있습니다.
	VALIDATION_INVALID_FIELD	지원하지 않는 인증 방식 — auth_provider 는 npki_delfino 만 지원합니다(KB_BIZ_CARD_AUTH_PROVIDER_UNSUPPORTED). 값을 생략하거나 npki_delfino 로 보냅니다.

인증

1. KB국민카드 기업카드 공동인증서 로그인kb_biz_card.session.login

Request

Response