개발자 문서
API 레퍼런스

인증 - KB국민카드 기업카드

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

MCP 도구 이름 kb_biz_card__session__login

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

현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.

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

  • 콘솔에서 발급한 API 키와 등록한 공동인증서가 필요합니다. 정식 환경은 라이트, 스탠다드, PRO 또는 멀티계정 요금제를 이용 중일 때만 호출할 수 있습니다.
  • auth_provider(기본값 npki_delfino, 그 외 값은 오류)·timeout(초 단위, 기본값 45)은 모두 선택입니다.

Request

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

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

[참고] 인증

X-Env-ScopeY호출 환경입니다.
  • real_test데모 — 현재 데모 한도 확인 필요
  • production정식 — 현재 공개 요금제 전용

[참고] 환경

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

[참고] 재시도

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

예시 : kb_biz_card

actionstring-Y호출할 작업입니다.
  • kb_biz_card.session.login이 API 고정값 (기본값)

예시 : kb_biz_card.session.login

account_link_idstring36조건부등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명이 하나뿐일 때만 그것이 자동으로 선택됩니다. 둘 이상이면 대표로 지정한 것이 있어도 고르지 않으므로 직접 지정해야 합니다. 대표는 묶음 상품이 기관마다 자격증명을 고를 때만 씁니다. 등록한 자격증명이 없거나 하나를 고르지 못하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다.

형식 : UUID v4

[참고] 자격증명 등록

paramsobject-N작업 파라미터입니다. 이 API 는 빈 객체로 호출할 수 있습니다.
encrypted_fieldsobject-N민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다.

[참고] 암호화

순번변수명타입필수설명
auth_providerstringN로그인에 쓸 인증 방식입니다. npki_delfino(공동인증서) 하나만 받으며 다른 값을 보내면 실패하고, 보내지 않으면 npki_delfino 입니다
timeoutstringN로그인 중 기관 사이트에 보내는 요청마다 기다리는 최대 시간(초)입니다. 숫자로 보내며 보내지 않으면 45 입니다
bash
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": "kb_biz_card",
  "action": "kb_biz_card.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_registered 로 로그인과 세션 등록 여부를, cookie_count 로 확보한 쿠키 수를 확인합니다.
순번변수명타입설명
successboolean요청 처리 성공 여부
account_link_idstring연동 ID
authenticatedboolean인증 완료 여부
session_registeredboolean세션 저장 완료 여부
cookie_countnumber저장된 쿠키 수
auth_providerstring인증 방식 - 등록한 공동인증서(npki_delfino)
generation_statusstring세션 생성 상태
json
{
    "job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
    "status": "QUEUED",
    "env_scope": "real_test",
    "provider": "kb_biz_card",
    "action": "kb_biz_card.session.login",
    "submitted_at": "2026-05-27T12:34:56+09:00"
}
순번오류 코드발생 조건
INTERNAL_ERROR서버 구성 문제 — 지금은 이 상품을 처리할 수 없습니다. 서버 구성 문제로 로그인 단계를 실행하지 못했습니다. 서비스문의로 알려 주세요. retryable=false - 재시도로 풀리지 않습니다.
PROVIDER_AUTH_FAILED인증서 인증 실패 — 등록된 공동인증서로 KB국민카드 인증에 실패했습니다(KB_BIZ_CARD_LOGIN_NOT_AUTHENTICATED). 등록한 공동인증서를 서명할 인증서 목록에서 고르지 못했을 때도 이 코드입니다(KB_BIZ_CARD_DELFINO_CERT_SELECTION_FAILED). error.message 는 「등록하신 공동인증서를 사용할 수 없습니다. 인증서가 유효한지 확인하시고, 콘솔에서 인증서를 다시 등록한 뒤 시도해 주세요.」 입니다. retryable=false - 재시도로 풀리지 않으므로 등록한 인증서와 계정 정보를 먼저 확인합니다.
PROVIDER_UNAVAILABLE세션 저장 실패 — 인증에는 성공했지만 세션을 저장하지 못했거나 저장한 세션을 다시 읽지 못했습니다. 재시도 가능으로 표시되니 error.message 안내대로 잠시 후 다시 호출합니다.
VALIDATION_INVALID_FIELD지원하지 않는 인증 방식 — auth_provider 는 npki_delfino 만 지원합니다(KB_BIZ_CARD_AUTH_PROVIDER_UNSUPPORTED). 값을 생략하거나 npki_delfino 로 보냅니다.