결제내역 - KB국민카드 기업카드
1. KB국민카드 기업카드 결제내역 조회 시작kb_ biz_ card. payments. init
MCP 도구 이름 kb_
POSThttps:// api. xdata. kr/ v1/ jobsX-Env-Scope: real_test
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
결제내역 조회 화면을 열어 부서 목록과 기본 조회 조건을 받습니다.
- KB국민카드 기업카드 세션 로그인을 먼저 호출해 세션을 등록한 뒤, 같은 account_link_id 로 호출합니다. [KB국민카드 기업카드 로그인]
Request
| 순번 | 변수명 | 필수 | 설명 |
|---|---|---|---|
| Authorization | Y | API 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다. | |
| X- | Y | 호출 환경입니다.
| |
| Idempotency- | Y | 재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다. | |
| Content- | Y | 요청 본문 형식입니다.
| |
| X- | N | 추적 아이디입니다. 지정하지 않으면 서버가 발급합니다. |
| 순번 | 변수명 | 타입 | 길이 | 필수 | 설명 |
|---|---|---|---|---|---|
| provider | string | - | Y | 호출할 기관입니다.
| |
| action | string | - | Y | 호출할 작업입니다.
| |
| account_ | string | 36 | 조건부 | 등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명이 하나뿐일 때만 그것이 자동으로 선택됩니다. 둘 이상이면 대표로 지정한 것이 있어도 고르지 않으므로 직접 지정해야 합니다. 대표는 묶음 상품이 기관마다 자격증명을 고를 때만 씁니다. 등록한 자격증명이 없거나 하나를 고르지 못하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다. | |
| params | object | - | N | 작업 파라미터입니다. 이 API 는 빈 객체로 호출할 수 있습니다. | |
| encrypted_ | object | - | N | 민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| date_ | string | N | 결과의 default_search_params 에 그대로 돌려줄 조회 시작일입니다. 이 값으로 조회하지는 않으며 보내지 않으면 null 입니다 | |
| date_ | string | N | 결과의 default_search_params 에 그대로 돌려줄 조회 종료일입니다. 이 값으로 조회하지는 않으며 보내지 않으면 null 입니다 |
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.payments.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 타입이 함께 표시된 칸은 서버가 세부 타입을 고정하지 않는 기관 원문 또는 동적 값입니다.예시 값의 타입으로 단정하지 말고 실제 값의 타입을 확인해 주세요. null은 값이 비어 있다는 뜻이며, 필드 자체의 생략 여부는 필수 여부와 설명을 확인해 주세요.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| success | boolean | 요청 처리 성공 여부 | |
| account_ | string | 연동 ID | |
| default_ | object | 결제내역 조회의 기본 조건 객체 - 선택한 부서 정보를 기관이 채워 줍니다 | |
| departments | string | number | boolean | object | array | null | 선택 가능한 부서 목록 | |
| cards | array | 이 카테고리는 카드 선택이 없어 항상 빈 배열입니다 | |
| form_ | object | 화면 진입에 필요한 부가 정보 객체 | |
| session_ | object | 이 조회에 쓰인 세션 컨텍스트 객체(provider · account_link_id · env_scope) | |
| raw_ | object | 기관 원본 필드명 대응 객체 |
{
"job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
"status": "QUEUED",
"env_scope": "real_test",
"provider": "kb_biz_card",
"action": "kb_biz_card.payments.init",
"submitted_at": "2026-05-27T12:34:56+09:00"
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| AUTH_ | 세션 없음 — KB국민카드 기업카드 세션이 없거나(로그인 전) 저장된 세션에 필요한 정보가 깨져 있습니다. 공동인증서 로그인을 다시 호출한 뒤 같은 account_link_id 로 다시 요청합니다. retryable=false - 재로그인 없이는 재시도해도 풀리지 않습니다. | |
| VALIDATION_ | 파라미터 오류 — 필수값이 없거나 형식이 올바르지 않습니다(예: page<1, search_context 가 객체가 아님, 날짜 형식 오류, 소유하지 않은 account_link_id). retryable=false - page·search_context 는 반드시 같은 카테고리의 .search 또는 .result 응답을 그대로 다시 보냅니다. | |
| PROVIDER_ | 연결 지연 — KB국민카드 포털 접속 자체가 시간 안에 되지 않았습니다. retryable 은 응답에 함께 옵니다. | |
| PROVIDER_ | 응답 지연 — 접속은 됐지만 응답이 시간 안에 오지 않았습니다. retryable 은 응답에 함께 옵니다. | |
| INTERNAL_ | 포털 응답 오류 — KB국민카드 포털이 오류 상태(4xx/5xx)로 응답했습니다. retryable=false - 위 '그 밖의 오류' 행과 코드가 다르니 재시도 가능 여부를 이 행 기준으로 판단합니다. | |
| PROVIDER_ | 그 밖의 오류 — 인증서 인증 실패·세션 저장 실패처럼 위에서 나눈 경우 밖의 KB국민카드 연동 오류가 이 코드 하나로 옵니다(원인 문구는 매번 다릅니다). retryable=true 로 표시되지만, 원인이 인증서 자체거나 값 자체가 잘못됐다면 재시도로 풀리지 않습니다 - 메시지를 먼저 확인합니다. |
2. KB국민카드 기업카드 결제내역 페이지 조회kb_ biz_ card. payments. page
MCP 도구 이름 kb_
POSThttps:// api. xdata. kr/ v1/ jobsX-Env-Scope: real_test
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
앞서 정한 결제 조회 조건을 유지한 채 지정한 페이지만 받습니다.
- KB국민카드 기업카드 세션 로그인을 먼저 호출해 세션을 등록한 뒤, 같은 account_link_id 로 호출합니다. [KB국민카드 기업카드 로그인]kb_biz_card.payments.search 또는 kb_biz_card.payments.result 호출 응답의 search_context 를 그대로 넘겨야 합니다 - 직접 만들어 보내면 VALIDATION_INVALID_FIELD 로 거절됩니다.
Request
| 순번 | 변수명 | 필수 | 설명 |
|---|---|---|---|
| Authorization | Y | API 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다. | |
| X- | Y | 호출 환경입니다.
| |
| Idempotency- | Y | 재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다. | |
| Content- | Y | 요청 본문 형식입니다.
| |
| X- | N | 추적 아이디입니다. 지정하지 않으면 서버가 발급합니다. |
| 순번 | 변수명 | 타입 | 길이 | 필수 | 설명 |
|---|---|---|---|---|---|
| provider | string | - | Y | 호출할 기관입니다.
| |
| action | string | - | Y | 호출할 작업입니다.
| |
| account_ | string | 36 | 조건부 | 등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명이 하나뿐일 때만 그것이 자동으로 선택됩니다. 둘 이상이면 대표로 지정한 것이 있어도 고르지 않으므로 직접 지정해야 합니다. 대표는 묶음 상품이 기관마다 자격증명을 고를 때만 씁니다. 등록한 자격증명이 없거나 하나를 고르지 못하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다. | |
| params | object | - | Y | 작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다. | |
| encrypted_ | object | - | N | 민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| search_ | object | Y | 앞서 같은 종류의 조회(search)가 돌려준 결과의 search_context 객체를 그대로 보냅니다. 그 안에 조회 조건이 들어 있어 조건을 다시 적지 않고 다른 쪽을 받습니다 | |
| page | number | Y | 받을 쪽 번호입니다. 1 이상의 정수이고 search_context 와 함께 보냅니다 |
- 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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.payments.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 조건 그대로, 지정한 페이지의 결제내역 건만 받습니다.
- 여러 JSON 타입이 함께 표시된 칸은 서버가 세부 타입을 고정하지 않는 기관 원문 또는 동적 값입니다.예시 값의 타입으로 단정하지 말고 실제 값의 타입을 확인해 주세요. null은 값이 비어 있다는 뜻이며, 필드 자체의 생략 여부는 필수 여부와 설명을 확인해 주세요.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| success | boolean | 요청 처리 성공 여부 | |
| account_ | string | 연동 ID | |
| search_ | object | 이 조회 조건 객체 - .page 호출에 그대로 넘깁니다 | |
| page | number | 조회한 페이지 번호 | |
| total_ | number | 이 페이지에서 읽은 건수 | |
| pagination | object | 페이지 정보 객체 - current_page · pages · total_pages · total_count · has_next | |
| rows | array | 결제내역 목록(정리된 값) | |
| rows_ | array | 결제내역 목록(기관 원본 문자열 그대로) | |
| raw_ | object | 기관 원본 필드명 대응 객체 | |
| pages_ | array | 실제로 조회를 호출한 페이지 번호 목록 | |
| source_ | array | 페이지별 조회 건수 목록 | |
| company | string | number | boolean | object | array | null | 조회 대상 회사(부서)명 | |
| period | object | 조회 기간 객체 - date_from · date_to · query_text(기관이 보여준 조회기간 문구) | |
| summary | object | 합계 객체 - billing_total(청구) · payment_total(결제) · refund_total(환급) |
{
"job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
"status": "QUEUED",
"env_scope": "real_test",
"provider": "kb_biz_card",
"action": "kb_biz_card.payments.page",
"submitted_at": "2026-05-27T12:34:56+09:00"
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| AUTH_ | 세션 없음 — KB국민카드 기업카드 세션이 없거나(로그인 전) 저장된 세션에 필요한 정보가 깨져 있습니다. 공동인증서 로그인을 다시 호출한 뒤 같은 account_link_id 로 다시 요청합니다. retryable=false - 재로그인 없이는 재시도해도 풀리지 않습니다. | |
| VALIDATION_ | 파라미터 오류 — 필수값이 없거나 형식이 올바르지 않습니다(예: page<1, search_context 가 객체가 아님, 날짜 형식 오류, 소유하지 않은 account_link_id). retryable=false - page·search_context 는 반드시 같은 카테고리의 .search 또는 .result 응답을 그대로 다시 보냅니다. | |
| PROVIDER_ | 연결 지연 — KB국민카드 포털 접속 자체가 시간 안에 되지 않았습니다. retryable 은 응답에 함께 옵니다. | |
| PROVIDER_ | 응답 지연 — 접속은 됐지만 응답이 시간 안에 오지 않았습니다. retryable 은 응답에 함께 옵니다. | |
| INTERNAL_ | 포털 응답 오류 — KB국민카드 포털이 오류 상태(4xx/5xx)로 응답했습니다. retryable=false - 위 '그 밖의 오류' 행과 코드가 다르니 재시도 가능 여부를 이 행 기준으로 판단합니다. | |
| PROVIDER_ | 그 밖의 오류 — 인증서 인증 실패·세션 저장 실패처럼 위에서 나눈 경우 밖의 KB국민카드 연동 오류가 이 코드 하나로 옵니다(원인 문구는 매번 다릅니다). retryable=true 로 표시되지만, 원인이 인증서 자체거나 값 자체가 잘못됐다면 재시도로 풀리지 않습니다 - 메시지를 먼저 확인합니다. |
3. KB국민카드 기업카드 결제내역 전체 수집kb_ biz_ card. payments. result
MCP 도구 이름 kb_
POSThttps:// api. xdata. kr/ v1/ jobsX-Env-Scope: real_test
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
조건에 걸린 결제내역을 한 번에 모아 합계와 수집 범위까지 받습니다.
- KB국민카드 기업카드 세션 로그인을 먼저 호출해 세션을 등록한 뒤, 같은 account_link_id 로 호출합니다. [KB국민카드 기업카드 로그인]
Request
| 순번 | 변수명 | 필수 | 설명 |
|---|---|---|---|
| Authorization | Y | API 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다. | |
| X- | Y | 호출 환경입니다.
| |
| Idempotency- | Y | 재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다. | |
| Content- | Y | 요청 본문 형식입니다.
| |
| X- | N | 추적 아이디입니다. 지정하지 않으면 서버가 발급합니다. |
| 순번 | 변수명 | 타입 | 길이 | 필수 | 설명 |
|---|---|---|---|---|---|
| provider | string | - | Y | 호출할 기관입니다.
| |
| action | string | - | Y | 호출할 작업입니다.
| |
| account_ | string | 36 | 조건부 | 등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명이 하나뿐일 때만 그것이 자동으로 선택됩니다. 둘 이상이면 대표로 지정한 것이 있어도 고르지 않으므로 직접 지정해야 합니다. 대표는 묶음 상품이 기관마다 자격증명을 고를 때만 씁니다. 등록한 자격증명이 없거나 하나를 고르지 못하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다. | |
| params | object | - | Y | 작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다. | |
| encrypted_ | object | - | N | 민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| date_ | string | Y | 조회 시작일입니다. YYYYMMDD 나 YYYY-MM-DD 로 보내며 하이픈과 점은 떼고 기관에 보냅니다 | |
| date_ | string | Y | 조회 종료일입니다. 시작일과 같은 형식으로 보냅니다 | |
| department_ | string | N | 조회할 부서의 번호입니다. 부서 목록 조회(common.departments.select) 결과의 department_sequence_no 를 넣으며 보내지 않거나 비우면 00000 을 보냅니다. 모든 부서를 한꺼번에 조회하는 값은 확인하지 않았으니 부서마다 번호를 넣어 조회하세요 | |
| department_ | string | N | 기관 조회 화면의 부서명 칸에 실어 보내는 부서 이름입니다. 보내지 않으면 빈 값입니다 | |
| query_ | string | N | 기관 조회 화면의 조회구분 칸에 실어 보내는 값입니다. 값은 검사하지 않고 그대로 보내며 보내지 않거나 비우면 2 입니다. 기본값 밖의 값은 확인하지 않았으니 비워 두기를 권합니다 | |
| search_ | string | N | 결제내역의 조회 구분을 정하는 기관 조회 화면의 값입니다. 값은 검사하지 않고 그대로 보내며 보내지 않으면 1 입니다 | |
| max_ | number | N | 한꺼번에 모을 최대 쪽 수입니다. 1 이상의 정수이고 보내지 않으면 조회된 모든 쪽을 모읍니다 | |
| output_ | array | N | 이 결과를 엑셀(xlsx) 파일로도 받으려면 적습니다. 예: ["xlsx"]. 파일은 result.artifacts 에 함께 오고, 빼면 데이터만 옵니다 |
- 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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.payments.result",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {
"date_from": "<필수>",
"date_to": "<필수>",
"department_sequence_no": "00000",
"query_scope": "2",
"search_type": "1"
}
}'Response
- 아래 표의 칸은 작업이 SUCCEEDED 가 된 뒤 GET /v1/jobs/{job_id}/result 의 result.data 에 오고, 응답 예시는 작업을 제출했을 때(POST /v1/jobs)의 응답입니다.
- 1페이지부터 조건에 걸린 결제내역을 화면이 알려준 페이지 링크만큼 모아(max_pages 로 상한 지정 가능 - 링크에 없는 페이지는 모으지 못합니다) rows 로 한 번에 받습니다.
- 아래 표의 rows[] 줄은 엑셀 파일(params 의 output_formats 에 ["xlsx"])의 열로 내보내는 칸이고, 열 이름은 엑셀 파일 맨 윗줄의 머리글입니다.
- 아래 표의 줄은 엑셀로 내보내는 열이라 응답 행의 칸 전부가 아닐 수 있습니다.
- 여러 JSON 타입이 함께 표시된 칸은 서버가 세부 타입을 고정하지 않는 기관 원문 또는 동적 값입니다.예시 값의 타입으로 단정하지 말고 실제 값의 타입을 확인해 주세요. null은 값이 비어 있다는 뜻이며, 필드 자체의 생략 여부는 필수 여부와 설명을 확인해 주세요.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| success | boolean | 요청 처리 성공 여부 | |
| account_ | string | 연동 ID | |
| search_ | object | 이 조회 조건 객체 - .page 호출에 그대로 넘깁니다 | |
| page | number | 조회한 페이지 번호 | |
| total_ | number | 이 페이지에서 읽은 건수 | |
| pagination | object | 페이지 정보 객체 - current_page · pages · total_pages · total_count · has_next | |
| rows | array | 결제내역 목록(정리된 값) | |
| rows[]. | string | null | 결제일 | |
| rows[]. | string | null | 부서번호 | |
| rows[]. | string | null | 부서명 | |
| rows[]. | string | null | 결제구분 | |
| rows[]. | string | null | 구분 | |
| rows[]. | string | null | 원금 | |
| rows[]. | string | null | 수수료 | |
| rows[]. | string | null | 연체료 | |
| rows[]. | string | null | 기타대금 | |
| rows[]. | string | null | 합계 | |
| rows_ | array | 결제내역 목록(기관 원본 문자열 그대로) | |
| raw_ | object | 기관 원본 필드명 대응 객체 | |
| pages_ | array | 실제로 조회를 호출한 페이지 번호 목록 | |
| source_ | array | 페이지별 조회 건수 목록 | |
| company | string | number | boolean | object | array | null | 조회 대상 회사(부서)명 | |
| period | object | 조회 기간 객체 - date_from · date_to · query_text(기관이 보여준 조회기간 문구) | |
| summary | object | 합계 객체 - billing_total(청구) · payment_total(결제) · refund_total(환급) |
{
"job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
"status": "QUEUED",
"env_scope": "real_test",
"provider": "kb_biz_card",
"action": "kb_biz_card.payments.result",
"submitted_at": "2026-05-27T12:34:56+09:00"
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| AUTH_ | 세션 없음 — KB국민카드 기업카드 세션이 없거나(로그인 전) 저장된 세션에 필요한 정보가 깨져 있습니다. 공동인증서 로그인을 다시 호출한 뒤 같은 account_link_id 로 다시 요청합니다. retryable=false - 재로그인 없이는 재시도해도 풀리지 않습니다. | |
| VALIDATION_ | 파라미터 오류 — 필수값이 없거나 형식이 올바르지 않습니다(예: page<1, search_context 가 객체가 아님, 날짜 형식 오류, 소유하지 않은 account_link_id). retryable=false - page·search_context 는 반드시 같은 카테고리의 .search 또는 .result 응답을 그대로 다시 보냅니다. | |
| PROVIDER_ | 연결 지연 — KB국민카드 포털 접속 자체가 시간 안에 되지 않았습니다. retryable 은 응답에 함께 옵니다. | |
| PROVIDER_ | 응답 지연 — 접속은 됐지만 응답이 시간 안에 오지 않았습니다. retryable 은 응답에 함께 옵니다. | |
| INTERNAL_ | 포털 응답 오류 — KB국민카드 포털이 오류 상태(4xx/5xx)로 응답했습니다. retryable=false - 위 '그 밖의 오류' 행과 코드가 다르니 재시도 가능 여부를 이 행 기준으로 판단합니다. | |
| PROVIDER_ | 그 밖의 오류 — 인증서 인증 실패·세션 저장 실패처럼 위에서 나눈 경우 밖의 KB국민카드 연동 오류가 이 코드 하나로 옵니다(원인 문구는 매번 다릅니다). retryable=true 로 표시되지만, 원인이 인증서 자체거나 값 자체가 잘못됐다면 재시도로 풀리지 않습니다 - 메시지를 먼저 확인합니다. |
4. KB국민카드 기업카드 결제내역 조건 조회kb_ biz_ card. payments. search
MCP 도구 이름 kb_
POSThttps:// api. xdata. kr/ v1/ jobsX-Env-Scope: real_test
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
기간을 지정해 청구와 결제, 환급 내역을 한 페이지씩 결제일별로 조회합니다.
- KB국민카드 기업카드 세션 로그인을 먼저 호출해 세션을 등록한 뒤, 같은 account_link_id 로 호출합니다. [KB국민카드 기업카드 로그인]
Request
| 순번 | 변수명 | 필수 | 설명 |
|---|---|---|---|
| Authorization | Y | API 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다. | |
| X- | Y | 호출 환경입니다.
| |
| Idempotency- | Y | 재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다. | |
| Content- | Y | 요청 본문 형식입니다.
| |
| X- | N | 추적 아이디입니다. 지정하지 않으면 서버가 발급합니다. |
| 순번 | 변수명 | 타입 | 길이 | 필수 | 설명 |
|---|---|---|---|---|---|
| provider | string | - | Y | 호출할 기관입니다.
| |
| action | string | - | Y | 호출할 작업입니다.
| |
| account_ | string | 36 | 조건부 | 등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명이 하나뿐일 때만 그것이 자동으로 선택됩니다. 둘 이상이면 대표로 지정한 것이 있어도 고르지 않으므로 직접 지정해야 합니다. 대표는 묶음 상품이 기관마다 자격증명을 고를 때만 씁니다. 등록한 자격증명이 없거나 하나를 고르지 못하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다. | |
| params | object | - | Y | 작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다. | |
| encrypted_ | object | - | N | 민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| date_ | string | Y | 조회 시작일입니다. YYYYMMDD 나 YYYY-MM-DD 로 보내며 하이픈과 점은 떼고 기관에 보냅니다 | |
| date_ | string | Y | 조회 종료일입니다. 시작일과 같은 형식으로 보냅니다 | |
| department_ | string | N | 조회할 부서의 번호입니다. 부서 목록 조회(common.departments.select) 결과의 department_sequence_no 를 넣으며 보내지 않거나 비우면 00000 을 보냅니다. 모든 부서를 한꺼번에 조회하는 값은 확인하지 않았으니 부서마다 번호를 넣어 조회하세요 | |
| department_ | string | N | 기관 조회 화면의 부서명 칸에 실어 보내는 부서 이름입니다. 보내지 않으면 빈 값입니다 | |
| query_ | string | N | 기관 조회 화면의 조회구분 칸에 실어 보내는 값입니다. 값은 검사하지 않고 그대로 보내며 보내지 않거나 비우면 2 입니다. 기본값 밖의 값은 확인하지 않았으니 비워 두기를 권합니다 | |
| search_ | string | N | 결제내역의 조회 구분을 정하는 기관 조회 화면의 값입니다. 값은 검사하지 않고 그대로 보내며 보내지 않으면 1 입니다 | |
| page | number | N | 받을 쪽 번호입니다. 1부터 세는 정수이고 보내지 않으면 1 입니다 |
- 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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.payments.search",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {
"date_from": "<필수>",
"date_to": "<필수>",
"department_sequence_no": "00000",
"query_scope": "2",
"search_type": "1",
"page": 1
}
}'Response
- 아래 표의 칸은 작업이 SUCCEEDED 가 된 뒤 GET /v1/jobs/{job_id}/result 의 result.data 에 오고, 응답 예시는 작업을 제출했을 때(POST /v1/jobs)의 응답입니다.
- result.data 의 rows 로 조회된 결제내역 건을, pagination 으로 페이지 정보를, search_context 로 다음 페이지 조회(.page)에 그대로 넘길 조건을 확인합니다.
- 여러 JSON 타입이 함께 표시된 칸은 서버가 세부 타입을 고정하지 않는 기관 원문 또는 동적 값입니다.예시 값의 타입으로 단정하지 말고 실제 값의 타입을 확인해 주세요. null은 값이 비어 있다는 뜻이며, 필드 자체의 생략 여부는 필수 여부와 설명을 확인해 주세요.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| success | boolean | 요청 처리 성공 여부 | |
| account_ | string | 연동 ID | |
| search_ | object | 이 조회 조건 객체 - .page 호출에 그대로 넘깁니다 | |
| page | number | 조회한 페이지 번호 | |
| total_ | number | 이 페이지에서 읽은 건수 | |
| pagination | object | 페이지 정보 객체 - current_page · pages · total_pages · total_count · has_next | |
| rows | array | 결제내역 목록(정리된 값) | |
| rows_ | array | 결제내역 목록(기관 원본 문자열 그대로) | |
| raw_ | object | 기관 원본 필드명 대응 객체 | |
| pages_ | array | 실제로 조회를 호출한 페이지 번호 목록 | |
| source_ | array | 페이지별 조회 건수 목록 | |
| company | string | number | boolean | object | array | null | 조회 대상 회사(부서)명 | |
| period | object | 조회 기간 객체 - date_from · date_to · query_text(기관이 보여준 조회기간 문구) | |
| summary | object | 합계 객체 - billing_total(청구) · payment_total(결제) · refund_total(환급) |
{
"job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
"status": "QUEUED",
"env_scope": "real_test",
"provider": "kb_biz_card",
"action": "kb_biz_card.payments.search",
"submitted_at": "2026-05-27T12:34:56+09:00"
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| AUTH_ | 세션 없음 — KB국민카드 기업카드 세션이 없거나(로그인 전) 저장된 세션에 필요한 정보가 깨져 있습니다. 공동인증서 로그인을 다시 호출한 뒤 같은 account_link_id 로 다시 요청합니다. retryable=false - 재로그인 없이는 재시도해도 풀리지 않습니다. | |
| VALIDATION_ | 파라미터 오류 — 필수값이 없거나 형식이 올바르지 않습니다(예: page<1, search_context 가 객체가 아님, 날짜 형식 오류, 소유하지 않은 account_link_id). retryable=false - page·search_context 는 반드시 같은 카테고리의 .search 또는 .result 응답을 그대로 다시 보냅니다. | |
| PROVIDER_ | 연결 지연 — KB국민카드 포털 접속 자체가 시간 안에 되지 않았습니다. retryable 은 응답에 함께 옵니다. | |
| PROVIDER_ | 응답 지연 — 접속은 됐지만 응답이 시간 안에 오지 않았습니다. retryable 은 응답에 함께 옵니다. | |
| INTERNAL_ | 포털 응답 오류 — KB국민카드 포털이 오류 상태(4xx/5xx)로 응답했습니다. retryable=false - 위 '그 밖의 오류' 행과 코드가 다르니 재시도 가능 여부를 이 행 기준으로 판단합니다. | |
| PROVIDER_ | 그 밖의 오류 — 인증서 인증 실패·세션 저장 실패처럼 위에서 나눈 경우 밖의 KB국민카드 연동 오류가 이 코드 하나로 옵니다(원인 문구는 매번 다릅니다). retryable=true 로 표시되지만, 원인이 인증서 자체거나 값 자체가 잘못됐다면 재시도로 풀리지 않습니다 - 메시지를 먼저 확인합니다. |