부서·카드 선택

1. KB국민카드 기업카드 카드 목록 조회kb_biz_card.common.cards.select

MCP 도구 이름 kb_biz_card__common__cards__select

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

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

회사에 발급된 기업카드를 부서별로 조회해 조회 조건에 쓸 카드를 고릅니다.

KB국민카드 기업카드 세션 로그인을 먼저 호출해 세션을 등록한 뒤, 같은 account_link_id 로 호출합니다. [KB국민카드 기업카드 로그인]
sandbox 환경에서는 실제 KB국민카드에 접속하지 않습니다. result.data 에는 mock: true 와 보낸 params 를 그대로 담은 params_echo 가 오고, 업무 응답 필드는 오지 않습니다.
department_sequence_no·department_name(부서 필터)은 모두 선택입니다. 생략하면 전체 부서의 카드를 돌려줍니다 - departments.select 를 먼저 부를 필요는 없습니다.

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

순번	변수명	타입	필수	설명
	department_sequence_no	string	N	부서번호
	department_name	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-select-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "kb_biz_card",
  "action": "kb_biz_card.common.cards.select",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {}
}'

Response

result.data 의 cards 로 발급된 기업카드 목록(마스킹된 카드번호 포함)을, count 로 총 건수를 확인합니다.

순번	변수명	설명
	success	요청 처리 성공 여부
	account_link_id	연동 ID
	count	조회된 카드 총 건수(주의: 이 셀렉터는 1페이지만 조회해 count 가 실제 카드 수보다 클 수 있습니다 - 미실측)
	cards	카드 목록 - department_sequence_no · department_name · masked_card_no(마스킹된 카드번호) · card_owner_name · status · encrypted_card_ref 를 담습니다
	raw_field_map	기관 원본 필드명 대응 객체

json

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

순번	오류 코드	발생 조건
	AUTH_REQUIRED	세션 없음 — KB국민카드 기업카드 세션이 없거나(로그인 전) 저장된 세션에 필요한 정보가 깨져 있습니다. 공동인증서 로그인을 다시 호출한 뒤 같은 account_link_id 로 다시 요청합니다. retryable=false - 재로그인 없이는 재시도해도 풀리지 않습니다.
	VALIDATION_INVALID_FIELD	파라미터 오류 — 필수값이 없거나 형식이 올바르지 않습니다(예: page<1, search_context 가 객체가 아님, 날짜 형식 오류, 소유하지 않은 account_link_id). retryable=false - page·search_context 는 반드시 같은 카테고리의 .search 또는 .result 응답을 그대로 다시 보냅니다.
	PROVIDER_TIMEOUT_CONNECT	연결 지연 — KB국민카드 포털 접속 자체가 시간 안에 되지 않았습니다. retryable 은 응답에 함께 옵니다.
	PROVIDER_TIMEOUT_READ	응답 지연 — 접속은 됐지만 응답이 시간 안에 오지 않았습니다. retryable 은 응답에 함께 옵니다.
	INTERNAL_ERROR	포털 응답 오류 — KB국민카드 포털이 오류 상태(4xx/5xx)로 응답했습니다. retryable=false - 위 '그 밖의 오류'(PROVIDER_UNAVAILABLE)와 코드가 다르니 재시도 가능 여부를 이 행 기준으로 판단합니다.
	PROVIDER_UNAVAILABLE	그 밖의 오류 — 인증서 인증 실패·세션 저장 실패 등 도메인 예외(KbBizCardLoginError/KbBizCardBusinessError)로 던져진 그 밖의 오류가 이 코드 하나로 옵니다(원인 문구는 매번 다릅니다). retryable=true 로 표시되지만, 원인이 인증서 자체거나 값 자체가 잘못됐다면 재시도로 풀리지 않습니다 - 메시지를 먼저 확인합니다.

2. KB국민카드 기업카드 부서 목록 조회kb_biz_card.common.departments.select

MCP 도구 이름 kb_biz_card__common__departments__select