승인내역

1. KB국민카드 기업카드 승인내역 조회 시작kb_biz_card.approvals.init

MCP 도구 이름 kb_biz_card__approvals__init

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

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

승인내역 조회 화면을 열어 부서 목록과 카드 목록, 기본 조회 조건을 받습니다.

KB국민카드 기업카드 세션 로그인을 먼저 호출해 세션을 등록한 뒤, 같은 account_link_id 로 호출합니다. [KB국민카드 기업카드 로그인]
sandbox 환경에서는 실제 KB국민카드에 접속하지 않습니다. result.data 에는 mock: true 와 보낸 params 를 그대로 담은 params_echo 가 오고, 업무 응답 필드는 오지 않습니다.

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

순번	변수명	타입	필수	설명
	date_from	string	N	조회시작일
	date_to	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-init-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "kb_biz_card",
  "action": "kb_biz_card.approvals.init",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {}
}'

Response

result.data 의 departments·cards 로 선택 가능한 부서·카드 목록을, default_search_params 로 승인내역 조회의 기본 조건을 확인합니다.

순번	변수명	설명
	success	요청 처리 성공 여부
	account_link_id	연동 ID
	default_search_params	승인내역 조회의 기본 조건 객체 - 선택한 부서 정보를 기관이 채워 줍니다
	departments	선택 가능한 부서 목록
	cards	선택 가능한 카드 목록(첫 부서 기준)
	form_context	화면 진입에 필요한 부가 정보 객체
	session_context	이 조회에 쓰인 세션 컨텍스트 객체(provider · account_link_id · env_scope)
	raw_field_map	기관 원본 필드명 대응 객체

json

{
    "job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
    "status": "QUEUED",
    "env_scope": "sandbox",
    "provider": "kb_biz_card",
    "action": "kb_biz_card.approvals.init",
    "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.approvals.page

MCP 도구 이름 kb_biz_card__approvals__page

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

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

앞서 정한 조회 조건을 그대로 두고 지정한 페이지의 승인 건만 받습니다.

KB국민카드 기업카드 세션 로그인을 먼저 호출해 세션을 등록한 뒤, 같은 account_link_id 로 호출합니다. kb_biz_card.approvals.search 또는 kb_biz_card.approvals.result 호출 응답의 search_context 를 그대로 넘겨야 합니다 - 직접 만들어 보내면 VALIDATION_INVALID_FIELD 로 거절됩니다. [KB국민카드 기업카드 로그인]
sandbox 환경에서는 실제 KB국민카드에 접속하지 않습니다. result.data 에는 mock: true 와 보낸 params 를 그대로 담은 params_echo 가 오고, 업무 응답 필드는 오지 않습니다.

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

순번	변수명	타입	필수	설명
	search_context	object	Y	-
	page	number	Y	-

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-page-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "kb_biz_card",
  "action": "kb_biz_card.approvals.page",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "search_context": "<필수: object>",
    "page": "<필수: number>"
  }
}'

Response

search 가 돌려준 search_context 조건 그대로, 지정한 페이지의 승인내역 건만 받습니다.

순번	변수명	설명
	success	요청 처리 성공 여부
	account_link_id	연동 ID
	search_context	이 조회 조건 객체 - .page 호출에 그대로 넘깁니다
	page	조회한 페이지 번호
	total_count	기관이 표시한 전체 건수(이 페이지에서 읽은 건수가 아닙니다 - 2026-09-15 2차 검증 정정: payments 만 len(rows), approvals·purchases 는 기관 원문의 총 건수입니다)
	pagination	페이지 정보 객체 - current_page · pages · total_pages · total_count · has_next
	rows	승인내역 목록(정리된 값)
	rows_raw	승인내역 목록(기관 원본 문자열 그대로)
	raw_field_map	기관 원본 필드명 대응 객체
	pages_fetched	실제로 조회를 호출한 페이지 번호 목록
	source_pages	페이지별 조회 건수 목록

json

{
    "job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
    "status": "QUEUED",
    "env_scope": "sandbox",
    "provider": "kb_biz_card",
    "action": "kb_biz_card.approvals.page",
    "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 로 표시되지만, 원인이 인증서 자체거나 값 자체가 잘못됐다면 재시도로 풀리지 않습니다 - 메시지를 먼저 확인합니다.

3. KB국민카드 기업카드 승인내역 전체 수집kb_biz_card.approvals.result

MCP 도구 이름 kb_biz_card__approvals__result

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

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

조건에 걸린 승인 건을 여러 페이지에 걸쳐 모두 모아 한 번에 받습니다.

KB국민카드 기업카드 세션 로그인을 먼저 호출해 세션을 등록한 뒤, 같은 account_link_id 로 호출합니다. [KB국민카드 기업카드 로그인]
sandbox 환경에서는 실제 KB국민카드에 접속하지 않습니다. result.data 에는 mock: true 와 보낸 params 를 그대로 담은 params_echo 가 오고, 업무 응답 필드는 오지 않습니다.

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

변수명	타입	필수	설명
date_from	string	Y	조회시작일
date_to	string	Y	조회종료일
department_sequence_no	string	N	부서번호 예시 : 00000
department_name	string	N	부서명
query_scope	string	N	조회구분 예시 : 2
query_scope_detail	string	N	조회구분1 예시 : 3
card_approval_type	string	N	카드승인종류구분
sales_type	string	N	매출구분
card_no_mode	string	N	-
card_no1	string	N	카드번호1
card_no2	string	N	카드번호2
card_no3	string	N	카드번호3
card_no4	string	N	카드번호4
max_pages	number	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-result-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "kb_biz_card",
  "action": "kb_biz_card.approvals.result",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "date_from": "<필수>",
    "date_to": "<필수>",
    "department_sequence_no": "00000",
    "query_scope": "2",
    "query_scope_detail": "3"
  }
}'

Response

1페이지부터 조건에 걸린 승인내역을 화면이 알려준 페이지 링크만큼 모아(max_pages 로 상한 지정 가능 - 링크에 없는 페이지는 모으지 못합니다) rows 로 한 번에 받습니다.

순번	변수명	설명
	success	요청 처리 성공 여부
	account_link_id	연동 ID
	search_context	이 조회 조건 객체 - .page 호출에 그대로 넘깁니다
	page	조회한 페이지 번호
	total_count	기관이 표시한 전체 건수(이 페이지에서 읽은 건수가 아닙니다 - 2026-09-15 2차 검증 정정: payments 만 len(rows), approvals·purchases 는 기관 원문의 총 건수입니다)
	pagination	페이지 정보 객체 - current_page · pages · total_pages · total_count · has_next
	rows	승인내역 목록(정리된 값)
	rows_raw	승인내역 목록(기관 원본 문자열 그대로)
	raw_field_map	기관 원본 필드명 대응 객체
	pages_fetched	실제로 조회를 호출한 페이지 번호 목록
	source_pages	페이지별 조회 건수 목록

json

{
    "job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
    "status": "QUEUED",
    "env_scope": "sandbox",
    "provider": "kb_biz_card",
    "action": "kb_biz_card.approvals.result",
    "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 로 표시되지만, 원인이 인증서 자체거나 값 자체가 잘못됐다면 재시도로 풀리지 않습니다 - 메시지를 먼저 확인합니다.

4. KB국민카드 기업카드 승인내역 조건 조회kb_biz_card.approvals.search

MCP 도구 이름 kb_biz_card__approvals__search

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

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

기간과 부서, 카드 조건으로 승인내역 첫 페이지와 전체 건수를 조회합니다.

KB국민카드 기업카드 세션 로그인을 먼저 호출해 세션을 등록한 뒤, 같은 account_link_id 로 호출합니다. [KB국민카드 기업카드 로그인]
sandbox 환경에서는 실제 KB국민카드에 접속하지 않습니다. result.data 에는 mock: true 와 보낸 params 를 그대로 담은 params_echo 가 오고, 업무 응답 필드는 오지 않습니다.

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

변수명	타입	필수	설명
date_from	string	Y	조회시작일
date_to	string	Y	조회종료일
department_sequence_no	string	N	부서번호 예시 : 00000
department_name	string	N	부서명
query_scope	string	N	조회구분 예시 : 2
query_scope_detail	string	N	조회구분1 예시 : 3
card_approval_type	string	N	카드승인종류구분
sales_type	string	N	매출구분
card_no_mode	string	N	-
card_no1	string	N	카드번호1
card_no2	string	N	카드번호2
card_no3	string	N	카드번호3
card_no4	string	N	카드번호4
page	number	N	- 예시 : 1

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-search-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "kb_biz_card",
  "action": "kb_biz_card.approvals.search",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "date_from": "<필수>",
    "date_to": "<필수>",
    "department_sequence_no": "00000",
    "query_scope": "2",
    "query_scope_detail": "3",
    "page": 1
  }
}'

Response

result.data 의 rows 로 조회된 승인내역 건을, pagination 으로 페이지 정보를, search_context 로 다음 페이지 조회(.page)에 그대로 넘길 조건을 확인합니다.

순번	변수명	설명
	success	요청 처리 성공 여부
	account_link_id	연동 ID
	search_context	이 조회 조건 객체 - .page 호출에 그대로 넘깁니다
	page	조회한 페이지 번호
	total_count	기관이 표시한 전체 건수(이 페이지에서 읽은 건수가 아닙니다 - 2026-09-15 2차 검증 정정: payments 만 len(rows), approvals·purchases 는 기관 원문의 총 건수입니다)
	pagination	페이지 정보 객체 - current_page · pages · total_pages · total_count · has_next
	rows	승인내역 목록(정리된 값)
	rows_raw	승인내역 목록(기관 원본 문자열 그대로)
	raw_field_map	기관 원본 필드명 대응 객체
	pages_fetched	실제로 조회를 호출한 페이지 번호 목록
	source_pages	페이지별 조회 건수 목록

json

{
    "job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
    "status": "QUEUED",
    "env_scope": "sandbox",
    "provider": "kb_biz_card",
    "action": "kb_biz_card.approvals.search",
    "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 로 표시되지만, 원인이 인증서 자체거나 값 자체가 잘못됐다면 재시도로 풀리지 않습니다 - 메시지를 먼저 확인합니다.