개발자 문서
API 레퍼런스

승인내역 - KB국민카드 기업카드

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

MCP 도구 이름 kb_biz_card__approvals__init

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

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

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

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.approvals.init이 API 고정값 (기본값)

예시 : kb_biz_card.approvals.init

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

형식 : UUID v4

[참고] 자격증명 등록

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

[참고] 암호화

순번변수명타입필수설명
date_fromstringN결과의 default_search_params 에 그대로 돌려줄 조회 시작일입니다. 이 값으로 조회하지는 않으며 보내지 않으면 null 입니다
date_tostringN결과의 default_search_params 에 그대로 돌려줄 조회 종료일입니다. 이 값으로 조회하지는 않으며 보내지 않으면 null 입니다
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: init-$(date +%s)-$RANDOM" \
  --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

  • 아래 표의 칸은 작업이 SUCCEEDED 가 된 뒤 GET /v1/jobs/{job_id}/result 의 result.data 에 오고, 응답 예시는 작업을 제출했을 때(POST /v1/jobs)의 응답입니다.
  • result.data 의 departments·cards 로 선택 가능한 부서·카드 목록을, default_search_params 로 승인내역 조회의 기본 조건을 확인합니다.
  • 여러 JSON 타입이 함께 표시된 칸은 서버가 세부 타입을 고정하지 않는 기관 원문 또는 동적 값입니다.
순번변수명타입설명
successboolean요청 처리 성공 여부
account_link_idstring연동 ID
default_search_paramsobject승인내역 조회의 기본 조건 객체 - 선택한 부서 정보를 기관이 채워 줍니다
departmentsstring | number | boolean | object | array | null선택 가능한 부서 목록
cardsarray선택 가능한 카드 목록(첫 부서 기준)
form_contextobject화면 진입에 필요한 부가 정보 객체
session_contextobject이 조회에 쓰인 세션 컨텍스트 객체(provider · account_link_id · env_scope)
raw_field_mapobject기관 원본 필드명 대응 객체
json
{
    "job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
    "status": "QUEUED",
    "env_scope": "real_test",
    "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그 밖의 오류 — 인증서 인증 실패·세션 저장 실패처럼 위에서 나눈 경우 밖의 KB국민카드 연동 오류가 이 코드 하나로 옵니다(원인 문구는 매번 다릅니다). retryable=true 로 표시되지만, 원인이 인증서 자체거나 값 자체가 잘못됐다면 재시도로 풀리지 않습니다 - 메시지를 먼저 확인합니다.

2. KB국민카드 기업카드 승인내역 페이지 조회kb_biz_card.approvals.page

MCP 도구 이름 kb_biz_card__approvals__page

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

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

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

  • KB국민카드 기업카드 세션 로그인을 먼저 호출해 세션을 등록한 뒤, 같은 account_link_id 로 호출합니다. [KB국민카드 기업카드 로그인]
  • page 가 2 이상이고 첫 쪽이 알린 마지막 쪽(pagination.total_pages)보다 큰데 기관 화면이 표를 그리지 않으면(마지막 쪽을 넘긴 요청입니다) 오류가 아니라 정상 응답으로 끝 데이터를 알립니다.

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.approvals.page이 API 고정값 (기본값)

예시 : kb_biz_card.approvals.page

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

형식 : UUID v4

[참고] 자격증명 등록

paramsobject-Y작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다.
encrypted_fieldsobject-N민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다.

[참고] 암호화

순번변수명타입필수설명
search_contextobjectY앞서 같은 종류의 조회(search)가 돌려준 결과의 search_context 객체를 그대로 보냅니다. 그 안에 조회 조건이 들어 있어 조건을 다시 적지 않고 다른 쪽을 받습니다
pagenumberY받을 쪽 번호입니다. 1 이상의 정수이고 search_context 와 함께 보냅니다
  • 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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: page-$(date +%s)-$RANDOM" \
  --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

  • 아래 표의 칸은 작업이 SUCCEEDED 가 된 뒤 GET /v1/jobs/{job_id}/result 의 result.data 에 오고, 응답 예시는 작업을 제출했을 때(POST /v1/jobs)의 응답입니다.
  • search 가 돌려준 search_context 조건 그대로, 지정한 페이지의 승인내역 건만 받습니다.
순번변수명타입설명
successboolean요청 처리 성공 여부
account_link_idstring연동 ID
search_contextobject이 조회 조건 객체 - .page 호출에 그대로 넘깁니다
pagenumber조회한 페이지 번호
total_countnumber기관이 표시한 전체 건수(이 페이지에서 읽은 건수가 아닙니다)
paginationobject페이지 정보 객체 - current_page · pages · total_pages · total_count · has_next
rowsarray승인내역 목록(정리된 값)
rows_rawarray승인내역 목록(기관 원본 문자열 그대로)
raw_field_mapobject기관 원본 필드명 대응 객체
pages_fetchedarray실제로 조회를 호출한 페이지 번호 목록
source_pagesarray페이지별 조회 건수 목록
json
{
    "job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
    "status": "QUEUED",
    "env_scope": "real_test",
    "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그 밖의 오류 — 인증서 인증 실패·세션 저장 실패처럼 위에서 나눈 경우 밖의 KB국민카드 연동 오류가 이 코드 하나로 옵니다(원인 문구는 매번 다릅니다). retryable=true 로 표시되지만, 원인이 인증서 자체거나 값 자체가 잘못됐다면 재시도로 풀리지 않습니다 - 메시지를 먼저 확인합니다.

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

MCP 도구 이름 kb_biz_card__approvals__result

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

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

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

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.approvals.result이 API 고정값 (기본값)

예시 : kb_biz_card.approvals.result

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

형식 : UUID v4

[참고] 자격증명 등록

paramsobject-Y작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다.
encrypted_fieldsobject-N민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다.

[참고] 암호화

순번변수명타입필수설명
date_fromstringY조회 시작일입니다. YYYYMMDD 나 YYYY-MM-DD 로 보내며 하이픈과 점은 떼고 기관에 보냅니다. 오늘(한국 시각)로부터 1년 전 같은 날보다 앞선 날짜는 기관이 승인내역을 주지 않아 실패합니다
date_tostringY조회 종료일입니다. 시작일과 같은 형식으로 보냅니다
department_sequence_nostringN조회할 부서의 번호입니다. 부서 목록 조회(common.departments.select) 결과의 department_sequence_no 를 넣으며 보내지 않거나 비우면 00000 을 보냅니다. 모든 부서를 한꺼번에 조회하는 값은 확인하지 않았으니 부서마다 번호를 넣어 조회하세요

예시 : 00000

department_namestringN부서 이름입니다. 이 조회는 이 값을 기관에 보내지 않으며 부서는 department_sequence_no 로 고릅니다
query_scopestringN기관 조회 화면의 조회구분 칸에 실어 보내는 값입니다. 값은 검사하지 않고 그대로 보내며 보내지 않거나 비우면 2 입니다. 기본값 밖의 값은 확인하지 않았으니 비워 두기를 권합니다

예시 : 2

query_scope_detailstringN기관 조회 화면의 조회구분1 칸에 실어 보내는 값입니다. 값은 검사하지 않고 그대로 보내며 보내지 않거나 비우면 3 입니다. 기본값 밖의 값은 확인하지 않았으니 비워 두기를 권합니다

예시 : 3

card_approval_typestringN기관 조회 화면의 카드승인종류구분 칸에 실어 보내는 값입니다. 값은 검사하지 않고 그대로 보내며 보내지 않으면 빈 값입니다. 기본값 밖의 값은 확인하지 않았으니 비워 두기를 권합니다
sales_typestringN기관 조회 화면의 매출구분 칸에 실어 보내는 값입니다. 값은 검사하지 않고 그대로 보내며 보내지 않으면 빈 값입니다. 기본값 밖의 값은 확인하지 않았으니 비워 두기를 권합니다
card_no_modestringN카드번호 칸(card_no1 에서 card_no4)을 어떻게 입력하는지 정하는 기관 조회 화면의 값입니다. 값은 검사하지 않고 그대로 보내며 보내지 않으면 빈 값입니다
card_no1stringN기관 조회 화면의 카드번호 칸 넷 가운데 첫째 칸에 실어 보내는 값입니다. 값은 검사하지 않고 그대로 보내며 보내지 않으면 빈 값입니다
card_no2stringN기관 조회 화면의 카드번호 칸 넷 가운데 둘째 칸에 실어 보내는 값입니다. 값은 검사하지 않고 그대로 보내며 보내지 않으면 빈 값입니다
card_no3stringN기관 조회 화면의 카드번호 칸 넷 가운데 셋째 칸에 실어 보내는 값입니다. 값은 검사하지 않고 그대로 보내며 보내지 않으면 빈 값입니다
card_no4stringN기관 조회 화면의 카드번호 칸 넷 가운데 넷째 칸에 실어 보내는 값입니다. 값은 검사하지 않고 그대로 보내며 보내지 않으면 빈 값입니다
max_pagesnumberN한꺼번에 모을 최대 쪽 수입니다. 1 이상의 정수이고 보내지 않으면 조회된 모든 쪽을 모읍니다
output_formatsarrayN이 결과를 엑셀(xlsx) 파일로도 받으려면 적습니다. 예: ["xlsx"]. 파일은 result.artifacts 에 함께 오고, 빼면 데이터만 옵니다
  • 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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: result-$(date +%s)-$RANDOM" \
  --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

  • 아래 표의 칸은 작업이 SUCCEEDED 가 된 뒤 GET /v1/jobs/{job_id}/result 의 result.data 에 오고, 응답 예시는 작업을 제출했을 때(POST /v1/jobs)의 응답입니다.
  • 1페이지부터 조건에 걸린 승인내역을 화면이 알려준 페이지 링크만큼 모아(max_pages 로 상한 지정 가능 - 링크에 없는 페이지는 모으지 못합니다) rows 로 한 번에 받습니다.
  • 아래 표의 rows[] 줄은 엑셀 파일(params 의 output_formats 에 ["xlsx"])의 열로 내보내는 칸이고, 열 이름은 엑셀 파일 맨 윗줄의 머리글입니다.
  • 아래 표의 줄은 엑셀로 내보내는 열이라 응답 행의 칸 전부가 아닐 수 있습니다.
순번변수명타입설명
successboolean요청 처리 성공 여부
account_link_idstring연동 ID
search_contextobject이 조회 조건 객체 - .page 호출에 그대로 넘깁니다
pagenumber조회한 페이지 번호
total_countnumber기관이 표시한 전체 건수(이 페이지에서 읽은 건수가 아닙니다)
paginationobject페이지 정보 객체 - current_page · pages · total_pages · total_count · has_next
rowsarray승인내역 목록(정리된 값)
rows[].approval_datetimestring | null승인일
rows[].department_sequence_nostring | null부서번호
rows[].department_namestring | null부서명
rows[].masked_card_nostring | null카드번호
rows[].user_namestring | null이용자명
rows[].merchant_namestring | null가맹점명
rows[].business_typestring | null업종(업종코드)
rows[].payment_methodstring | null결제방법
rows[].installment_monthsstring | null할부개월
rows[].approval_amount_displaystring | null승인금액
rows[].vat_amount_displaystring | null부가세
rows[].approval_categorystring | null승인구분
rows[].approval_methodstring | null승인방식
rows[].approval_nostring | null승인번호
rows[].statusstring | null상태
rows[].tax_typestring | null과세유형
rows[].merchant_statusstring | null가맹점상태
rows[].merchant_nostring | null가맹점번호
rows[].merchant_business_nostring | null가맹점사업자번호
rows[].merchant_owner_namestring | null대표자성명
rows[].merchant_phone_nostring | null가맹점전화번호
rows[].merchant_addressstring | null가맹점주소
rows_rawarray승인내역 목록(기관 원본 문자열 그대로)
raw_field_mapobject기관 원본 필드명 대응 객체
pages_fetchedarray실제로 조회를 호출한 페이지 번호 목록
source_pagesarray페이지별 조회 건수 목록
json
{
    "job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
    "status": "QUEUED",
    "env_scope": "real_test",
    "provider": "kb_biz_card",
    "action": "kb_biz_card.approvals.result",
    "submitted_at": "2026-05-27T12:34:56+09:00"
}
순번오류 코드발생 조건
VALIDATION_INVALID_FIELD시작일 범위 초과 — 시작일(date_from)이 오늘로부터 1년 전 같은 날짜보다 이릅니다. error.message 는 '승인내역은 오늘로부터 1년 전 같은 날짜까지만 조회할 수 있습니다. 시작일을 그 날짜 또는 그 뒤로 넣어 다시 조회해 주세요.' 이고 error.provider_error_ref 는 kb_biz_card.invalid_params.KB_BIZ_CARD_APPROVAL_DATE_TOO_OLD 입니다. retryable=false.
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그 밖의 오류 — 인증서 인증 실패·세션 저장 실패처럼 위에서 나눈 경우 밖의 KB국민카드 연동 오류가 이 코드 하나로 옵니다(원인 문구는 매번 다릅니다). retryable=true 로 표시되지만, 원인이 인증서 자체거나 값 자체가 잘못됐다면 재시도로 풀리지 않습니다 - 메시지를 먼저 확인합니다.

MCP 도구 이름 kb_biz_card__approvals__search

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

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

기간을 정해 승인내역을 한 페이지(최대 열 건)씩 조회하고 전체 페이지 수를 함께 받습니다.

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.approvals.search이 API 고정값 (기본값)

예시 : kb_biz_card.approvals.search

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

형식 : UUID v4

[참고] 자격증명 등록

paramsobject-Y작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다.
encrypted_fieldsobject-N민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다.

[참고] 암호화

순번변수명타입필수설명
date_fromstringY조회 시작일입니다. YYYYMMDD 나 YYYY-MM-DD 로 보내며 하이픈과 점은 떼고 기관에 보냅니다. 오늘(한국 시각)로부터 1년 전 같은 날보다 앞선 날짜는 기관이 승인내역을 주지 않아 실패합니다
date_tostringY조회 종료일입니다. 시작일과 같은 형식으로 보냅니다
department_sequence_nostringN조회할 부서의 번호입니다. 부서 목록 조회(common.departments.select) 결과의 department_sequence_no 를 넣으며 보내지 않거나 비우면 00000 을 보냅니다. 모든 부서를 한꺼번에 조회하는 값은 확인하지 않았으니 부서마다 번호를 넣어 조회하세요

예시 : 00000

department_namestringN부서 이름입니다. 이 조회는 이 값을 기관에 보내지 않으며 부서는 department_sequence_no 로 고릅니다
query_scopestringN기관 조회 화면의 조회구분 칸에 실어 보내는 값입니다. 값은 검사하지 않고 그대로 보내며 보내지 않거나 비우면 2 입니다. 기본값 밖의 값은 확인하지 않았으니 비워 두기를 권합니다

예시 : 2

query_scope_detailstringN기관 조회 화면의 조회구분1 칸에 실어 보내는 값입니다. 값은 검사하지 않고 그대로 보내며 보내지 않거나 비우면 3 입니다. 기본값 밖의 값은 확인하지 않았으니 비워 두기를 권합니다

예시 : 3

card_approval_typestringN기관 조회 화면의 카드승인종류구분 칸에 실어 보내는 값입니다. 값은 검사하지 않고 그대로 보내며 보내지 않으면 빈 값입니다. 기본값 밖의 값은 확인하지 않았으니 비워 두기를 권합니다
sales_typestringN기관 조회 화면의 매출구분 칸에 실어 보내는 값입니다. 값은 검사하지 않고 그대로 보내며 보내지 않으면 빈 값입니다. 기본값 밖의 값은 확인하지 않았으니 비워 두기를 권합니다
card_no_modestringN카드번호 칸(card_no1 에서 card_no4)을 어떻게 입력하는지 정하는 기관 조회 화면의 값입니다. 값은 검사하지 않고 그대로 보내며 보내지 않으면 빈 값입니다
card_no1stringN기관 조회 화면의 카드번호 칸 넷 가운데 첫째 칸에 실어 보내는 값입니다. 값은 검사하지 않고 그대로 보내며 보내지 않으면 빈 값입니다
card_no2stringN기관 조회 화면의 카드번호 칸 넷 가운데 둘째 칸에 실어 보내는 값입니다. 값은 검사하지 않고 그대로 보내며 보내지 않으면 빈 값입니다
card_no3stringN기관 조회 화면의 카드번호 칸 넷 가운데 셋째 칸에 실어 보내는 값입니다. 값은 검사하지 않고 그대로 보내며 보내지 않으면 빈 값입니다
card_no4stringN기관 조회 화면의 카드번호 칸 넷 가운데 넷째 칸에 실어 보내는 값입니다. 값은 검사하지 않고 그대로 보내며 보내지 않으면 빈 값입니다
pagenumberN받을 쪽 번호입니다. 1부터 세는 정수이고 보내지 않으면 1 입니다

예시 : 1

  • 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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: search-$(date +%s)-$RANDOM" \
  --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

  • 아래 표의 칸은 작업이 SUCCEEDED 가 된 뒤 GET /v1/jobs/{job_id}/result 의 result.data 에 오고, 응답 예시는 작업을 제출했을 때(POST /v1/jobs)의 응답입니다.
  • result.data 의 rows 로 조회된 승인내역 건을, pagination 으로 페이지 정보를, search_context 로 다음 페이지 조회(.page)에 그대로 넘길 조건을 확인합니다.
순번변수명타입설명
successboolean요청 처리 성공 여부
account_link_idstring연동 ID
search_contextobject이 조회 조건 객체 - .page 호출에 그대로 넘깁니다
pagenumber조회한 페이지 번호
total_countnumber기관이 표시한 전체 건수(이 페이지에서 읽은 건수가 아닙니다)
paginationobject페이지 정보 객체 - current_page · pages · total_pages · total_count · has_next
rowsarray승인내역 목록(정리된 값)
rows_rawarray승인내역 목록(기관 원본 문자열 그대로)
raw_field_mapobject기관 원본 필드명 대응 객체
pages_fetchedarray실제로 조회를 호출한 페이지 번호 목록
source_pagesarray페이지별 조회 건수 목록
json
{
    "job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
    "status": "QUEUED",
    "env_scope": "real_test",
    "provider": "kb_biz_card",
    "action": "kb_biz_card.approvals.search",
    "submitted_at": "2026-05-27T12:34:56+09:00"
}
순번오류 코드발생 조건
VALIDATION_INVALID_FIELD시작일 범위 초과 — 시작일(date_from)이 오늘로부터 1년 전 같은 날짜보다 이릅니다. error.message 는 '승인내역은 오늘로부터 1년 전 같은 날짜까지만 조회할 수 있습니다. 시작일을 그 날짜 또는 그 뒤로 넣어 다시 조회해 주세요.' 이고 error.provider_error_ref 는 kb_biz_card.invalid_params.KB_BIZ_CARD_APPROVAL_DATE_TOO_OLD 입니다. retryable=false.
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그 밖의 오류 — 인증서 인증 실패·세션 저장 실패처럼 위에서 나눈 경우 밖의 KB국민카드 연동 오류가 이 코드 하나로 옵니다(원인 문구는 매번 다릅니다). retryable=true 로 표시되지만, 원인이 인증서 자체거나 값 자체가 잘못됐다면 재시도로 풀리지 않습니다 - 메시지를 먼저 확인합니다.