개발자 문서
API 레퍼런스

매입내역 - KB국민카드 기업카드

1. KB국민카드 기업카드 매입내역 조회 시작kb_biz_card.purchases.init

MCP 도구 이름 kb_biz_card__purchases__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.purchases.init이 API 고정값 (기본값)

예시 : kb_biz_card.purchases.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.purchases.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 로 선택 가능한 부서 목록을, 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.purchases.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.purchases.page

MCP 도구 이름 kb_biz_card__purchases__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.purchases.page이 API 고정값 (기본값)

예시 : kb_biz_card.purchases.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.purchases.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.purchases.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.purchases.result

MCP 도구 이름 kb_biz_card__purchases__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.purchases.result이 API 고정값 (기본값)

예시 : kb_biz_card.purchases.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 로 보내며 하이픈과 점은 떼고 기관에 보냅니다
date_tostringY조회 종료일입니다. 시작일과 같은 형식으로 보냅니다
department_sequence_nostringN조회할 부서의 번호입니다. 부서 목록 조회(common.departments.select) 결과의 department_sequence_no 를 넣으며 보내지 않거나 비우면 00000 을 보냅니다. 모든 부서를 한꺼번에 조회하는 값은 확인하지 않았으니 부서마다 번호를 넣어 조회하세요

예시 : 00000

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

예시 : 1

sales_slip_type_namestringN기관 조회 화면의 매출전표종류구분명 칸에 실어 보내는 값입니다. 값은 검사하지 않고 그대로 보내며 보내지 않으면 빈 값입니다. 기본값 밖의 값은 확인하지 않았으니 비워 두기를 권합니다
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.purchases.result",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "date_from": "<필수>",
    "date_to": "<필수>",
    "department_sequence_no": "00000",
    "query_scope": "1"
  }
}'

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[].purchase_datestring | null매입일
rows[].approval_datestring | 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.purchases.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그 밖의 오류 — 인증서 인증 실패·세션 저장 실패처럼 위에서 나눈 경우 밖의 KB국민카드 연동 오류가 이 코드 하나로 옵니다(원인 문구는 매번 다릅니다). retryable=true 로 표시되지만, 원인이 인증서 자체거나 값 자체가 잘못됐다면 재시도로 풀리지 않습니다 - 메시지를 먼저 확인합니다.

MCP 도구 이름 kb_biz_card__purchases__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.purchases.search이 API 고정값 (기본값)

예시 : kb_biz_card.purchases.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 로 보내며 하이픈과 점은 떼고 기관에 보냅니다
date_tostringY조회 종료일입니다. 시작일과 같은 형식으로 보냅니다
department_sequence_nostringN조회할 부서의 번호입니다. 부서 목록 조회(common.departments.select) 결과의 department_sequence_no 를 넣으며 보내지 않거나 비우면 00000 을 보냅니다. 모든 부서를 한꺼번에 조회하는 값은 확인하지 않았으니 부서마다 번호를 넣어 조회하세요

예시 : 00000

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

예시 : 1

sales_slip_type_namestringN기관 조회 화면의 매출전표종류구분명 칸에 실어 보내는 값입니다. 값은 검사하지 않고 그대로 보내며 보내지 않으면 빈 값입니다. 기본값 밖의 값은 확인하지 않았으니 비워 두기를 권합니다
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.purchases.search",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "date_from": "<필수>",
    "date_to": "<필수>",
    "department_sequence_no": "00000",
    "query_scope": "1",
    "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.purchases.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그 밖의 오류 — 인증서 인증 실패·세션 저장 실패처럼 위에서 나눈 경우 밖의 KB국민카드 연동 오류가 이 코드 하나로 옵니다(원인 문구는 매번 다릅니다). retryable=true 로 표시되지만, 원인이 인증서 자체거나 값 자체가 잘못됐다면 재시도로 풀리지 않습니다 - 메시지를 먼저 확인합니다.