현금영수증 - 홈택스
현금영수증을 발행하고 당일 발행 건을 수정하거나 취소합니다. 매출·매입 내역도 조회합니다.
이 쪽의 모든 작업에 해당
- 홈택스 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [홈택스 로그인(세션 생성)]
1. 현금영수증 매출 내역 조회hometax. cash_ receipt. sales. search_ history
MCP 도구 이름 hometax__
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
현금영수증 매출 내역을 조회합니다.
- 조회 결과가 없으면 목록이 빈 배열로 돌아옵니다. 실패가 아닙니다.
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 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 길이 | 필수 | 설명 |
|---|---|---|---|---|---|
| from_ | string | 8-10 | Y | 조회 시작일입니다. 별칭 inqr_dt_strt / trs_dt_rng_strt | |
| to_ | string | 8-10 | Y | 조회 종료일입니다. 별칭 inqr_dt_end / trs_dt_rng_end | |
| fetch_ | boolean | - | N | true 면 한 쪽이 아니라 모든 쪽을 모읍니다(기본 false). 쪽마다 기관 요청이 따로 나가 더 느립니다 | |
| max_ | number | - | N | fetch_all_pages 가 true 일 때만 씁니다. 전체 수집에서 읽을 최대 쪽 수입니다(기본 100). 이 쪽 수를 다 읽고도 남은 행이 있으면 부분 결과 없이 입력 오류(VALIDATION_INVALID_FIELD)로 끝나니 조회 기간을 나누거나 값을 올려 다시 요청하세요 | |
| page_ | number | - | N | 페이지 번호 (기본: 1) | |
| page_ | number | - | N | 페이지당 조회건수 (기본: 10) | |
| pbl_ | string | - | N | 발행구분 (all=전체, 1=사업자, 2=국세청, 3=명세서, 기본: all) | |
| trs_ | string | 8 | N | 거래일자 범위 시작 | |
| trs_ | string | 8 | N | 거래일자 범위 종료 |
- 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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_history-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "hometax",
"action": "hometax.cash_receipt.sales.search_history",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {
"from_date": "<필수>",
"to_date": "<필수>",
"max_pages": 100,
"page_num": 1,
"page_size": 10,
"pbl_cl_cd": "all",
"trs_dt_rng_strt": "20251030",
"trs_dt_rng_end": "20251030"
}
}'Response
- result.data 에 담긴 홈택스 응답 본문을 확인합니다.
- result.data 에는 홈택스가 내려준 응답 본문이 담깁니다. 화면마다 키 구성이 다르고, 기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| totalCount | number | 건수. 이 응답에 담긴 행 수보다 작지 않습니다(기관이 준 값이 행 수보다 작으면 행 수를 씁니다) | |
| pageInfoVO | object | 페이지 정보 객체(pageNum · pageSize · totalCount). totalCount 는 위와 같은 규칙으로 정합니다. 기관 원본은 문자열이지만 이 값은 정수입니다 | |
| collectionMeta | object | 수집 결과 객체 - complete(이 응답이 전부인지, false 면 다음 페이지를 더 받아야 함) · pagesFetched(받은 페이지 수) · collectedCount(이 응답에 담긴 행 수) · totalCount(위 totalCount 와 같은 값) |
// result.data — 나머지 키는 홈택스 응답 본문입니다
{
"cshTrsBrkdInqrDVOList": [ { "...": "..." } ],
"totalCount": 1,
"pageInfoVO": { "pageNum": 1, "pageSize": 10, "totalCount": 1 },
"collectionMeta": { "complete": true, "pagesFetched": 1, "collectedCount": 1, "totalCount": 1 }
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| VALIDATION_ | 요청 값 오류 — 필수 값이 빠지면 홈택스에 요청하지 않고 이 코드로 끝나며, 자동 재시도 대상이 아닙니다. error.message 가 빠진 값의 이름을 알려 주니 그 값을 넣어 다시 요청합니다. | |
| VALIDATION_ | 쪽 수 상한 — fetch_all_pages 를 true 로 보내 모든 쪽을 모을 때 max_pages 만큼 쪽을 읽고도 남은 행이 있으면 부분 결과 없이 이 코드로 끝나며, 자동 재시도 대상이 아닙니다. 조회 기간을 나누거나 max_pages 를 늘려 다시 요청합니다. | |
| VALIDATION_ | 숫자 값 오류 — page_num, page_size, max_pages 에 1 이상의 정수가 아닌 값(0, 음수, 소수부가 있는 수, 숫자가 아닌 글자)을 보내면 홈택스에 요청하지 않고 이 코드로 끝나며, 자동 재시도 대상이 아닙니다. error.message 가 확인할 값의 이름을 알려 주니 그 값을 고쳐 다시 요청합니다. 숫자로 된 문자열도 받고, null 로 보내면 보내지 않은 것으로 보아 기본값을 씁니다. | |
| AUTH_ | 세션 없음 — 홈택스 세션이 없습니다. 홈택스 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다. | |
| PROVIDER_ | 업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다. | |
| PROVIDER_ | 업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다. | |
| PROVIDER_ | 업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다. | |
| PROVIDER_ | 업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다. | |
| PROVIDER_ | 세션 만료 — 조회하는 도중 홈택스 로그인 세션이 끝난 것을 알게 되면 이 코드로 끝나며, error.message 안내대로 로그인 액션을 다시 실행해 세션을 연 뒤 같은 요청을 다시 보냅니다. |
2. 현금영수증 매출내역누계hometax. cash_ receipt. sales. search_ summary
MCP 도구 이름 hometax__
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
현금영수증 매출내역누계를 조회합니다.
- 조회 결과가 없으면 목록이 빈 배열로 돌아옵니다. 실패가 아닙니다.
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 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 길이 | 필수 | 설명 |
|---|---|---|---|---|---|
| cmtt_ | string | 4 | Y | 조회년도 | |
| qrt | string | - | N | 분기 (all=연도별 전체, 1=1분기, 2=2분기, 3=3분기, 4=4분기, 기본: all) |
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_summary-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "hometax",
"action": "hometax.cash_receipt.sales.search_summary",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {
"cmtt_yr": "2025",
"qrt": "all"
}
}'Response
- result.data 에 담긴 홈택스 응답 본문을 확인합니다.
- result.data 에는 홈택스가 내려준 응답 본문이 담깁니다. 화면마다 키 구성이 다르고, 기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다.
이 API 는 기관 응답 본문을 그대로 전달합니다. 고정 필드 목록이 없습니다.
// result.data — 홈택스 응답 본문이 담깁니다. 화면마다 키 구성이 다르고, 기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다.
{}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| VALIDATION_ | 요청 값 오류 — 필수 값이 빠지면 홈택스에 요청하지 않고 이 코드로 끝나며, 자동 재시도 대상이 아닙니다. error.message 가 빠진 값의 이름을 알려 주니 그 값을 넣어 다시 요청합니다. | |
| AUTH_ | 세션 없음 — 홈택스 세션이 없습니다. 홈택스 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다. | |
| PROVIDER_ | 업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다. | |
| PROVIDER_ | 업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다. | |
| PROVIDER_ | 업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다. | |
| PROVIDER_ | 업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다. | |
| PROVIDER_ | 세션 만료 — 조회하는 도중 홈택스 로그인 세션이 끝난 것을 알게 되면 이 코드로 끝나며, error.message 안내대로 로그인 액션을 다시 실행해 세션을 연 뒤 같은 요청을 다시 보냅니다. |
3. 현금영수증 매입 내역 조회hometax. cash_ receipt. purchase. search_ history
MCP 도구 이름 hometax__
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
현금영수증 매입 내역을 조회합니다.
- 조회 결과가 없으면 목록이 빈 배열로 돌아옵니다. 실패가 아닙니다.
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 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 길이 | 필수 | 설명 |
|---|---|---|---|---|---|
| from_ | string | 8-10 | Y | 조회 시작일입니다. 별칭 inqr_dt_strt / trs_dt_rng_strt | |
| to_ | string | 8-10 | Y | 조회 종료일입니다. 별칭 inqr_dt_end / trs_dt_rng_end | |
| fetch_ | boolean | - | N | true 면 한 쪽이 아니라 모든 쪽을 모읍니다(기본 false). 쪽마다 기관 요청이 따로 나가 더 느립니다 | |
| max_ | number | - | N | fetch_all_pages 가 true 일 때만 씁니다. 전체 수집에서 읽을 최대 쪽 수입니다(기본 100). 이 쪽 수를 다 읽고도 남은 행이 있으면 부분 결과 없이 입력 오류(VALIDATION_INVALID_FIELD)로 끝나니 조회 기간을 나누거나 값을 올려 다시 요청하세요 | |
| mrnt_ | string | - | N | 가맹점 사업자번호 (하이픈 제거, 최대 10자리) | |
| page_ | number | - | N | 페이지 번호 (기본: 1) | |
| page_ | number | - | N | 페이지당 조회건수 (기본: 10) | |
| pubc_ | string | - | N | 부서 사용자 번호 (all=전체, 기본: all) | |
| spjb_ | string | - | N | 현금매출명세서 발행 여부 (all=전체, Y=현금매출명세서 발행만, 기본: all) | |
| spst_ | string | - | N | 신분확인수단 ID (all=전체, 기본: all) | |
| trs_ | string | 8 | N | 거래일자 범위 시작 | |
| trs_ | string | 8 | N | 거래일자 범위 종료 | |
| 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: search_history-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "hometax",
"action": "hometax.cash_receipt.purchase.search_history",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {
"from_date": "<필수>",
"to_date": "<필수>",
"max_pages": 100,
"page_num": 1,
"page_size": 10,
"pubc_user_no": "all",
"spjb_trs_yn": "all",
"spst_cnfr_id": "all",
"trs_dt_rng_strt": "20251030",
"trs_dt_rng_end": "20251030"
}
}'Response
- result.data 에 담긴 홈택스 응답 본문을 확인합니다.
- result.data 에는 홈택스가 내려준 응답 본문이 담깁니다. 화면마다 키 구성이 다르고, 기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다.
- 아래 표의 cshTrsBrkdInqrDVOList[] 줄은 엑셀 파일(params 의 output_formats 에 ["xlsx"])의 열로 내보내는 칸이고, 열 이름은 홈택스 화면의 표 머리글입니다.
- 기관이 내려주는 행에는 아래 표에 없는 칸도 더 있습니다.
- 여러 JSON 타입이 함께 표시된 칸은 서버가 세부 타입을 고정하지 않는 기관 원문 또는 동적 값입니다.예시 값의 타입으로 단정하지 말고 실제 값의 타입을 확인해 주세요. null은 값이 비어 있다는 뜻이며, 필드 자체의 생략 여부는 필수 여부와 설명을 확인해 주세요.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| totalCount | number | 건수. 이 응답에 담긴 행 수보다 작지 않습니다(기관이 준 값이 행 수보다 작으면 행 수를 씁니다) | |
| pageInfoVO | object | 페이지 정보 객체(pageNum · pageSize · totalCount). totalCount 는 위와 같은 규칙으로 정합니다. 기관 원본은 문자열이지만 이 값은 정수입니다 | |
| collectionMeta | object | 수집 결과 객체 - complete(이 응답이 전부인지, false 면 다음 페이지를 더 받아야 함) · pagesFetched(받은 페이지 수) · collectedCount(이 응답에 담긴 행 수) · totalCount(위 totalCount 와 같은 값) | |
| cshTrsBrkdInqrDVOList | string | number | boolean | object | array | null | 조회한 행의 목록 배열입니다. 아래 줄이 그 행의 칸입니다 | |
| cshTrsBrkdInqrDVOList[]. | string | number | boolean | object | array | null | 매입일시 기관 원문입니다. 칸 존재와 값의 꼴을 확인한 뒤 읽어 주세요. | |
| cshTrsBrkdInqrDVOList[]. | string | number | boolean | object | array | null | 사용자명 기관 원문입니다. 칸 존재와 값의 꼴을 확인한 뒤 읽어 주세요. | |
| cshTrsBrkdInqrDVOList[]. | string | number | boolean | object | array | null | 가맹점명 기관 원문입니다. 칸 존재와 값의 꼴을 확인한 뒤 읽어 주세요. | |
| cshTrsBrkdInqrDVOList[]. | string | number | boolean | object | array | null | 공급가액 기관 원문입니다. 칸 존재와 값의 꼴을 확인한 뒤 읽어 주세요. | |
| cshTrsBrkdInqrDVOList[]. | string | number | boolean | object | array | null | 부가세 기관 원문입니다. 칸 존재와 값의 꼴을 확인한 뒤 읽어 주세요. | |
| cshTrsBrkdInqrDVOList[]. | string | number | boolean | object | array | null | 봉사료 기관 원문입니다. 칸 존재와 값의 꼴을 확인한 뒤 읽어 주세요. | |
| cshTrsBrkdInqrDVOList[]. | string | number | boolean | object | array | null | 매입금액 기관 원문입니다. 칸 존재와 값의 꼴을 확인한 뒤 읽어 주세요. | |
| cshTrsBrkdInqrDVOList[]. | string | number | boolean | object | array | null | 거래구분 기관 원문입니다. 칸 존재와 값의 꼴을 확인한 뒤 읽어 주세요. | |
| cshTrsBrkdInqrDVOList[]. | string | number | boolean | object | array | null | 공제여부 기관 원문입니다. 칸 존재와 값의 꼴을 확인한 뒤 읽어 주세요. |
// result.data — 나머지 키는 홈택스 응답 본문입니다
{
"cshTrsBrkdInqrDVOList": [
{
"trsDtTime": "...",
"cardOwnrNm": "...",
"mrntTxprNm": "...",
"splCft": "...",
"vaTxamt": "...",
"tip": "...",
"totaTrsAmt": "...",
"trsClNm": "...",
"prhTxamtDdcClNm": "..."
}
],
"totalCount": 1,
"pageInfoVO": {
"pageNum": 1,
"pageSize": 10,
"totalCount": 1
},
"collectionMeta": {
"complete": true,
"pagesFetched": 1,
"collectedCount": 1,
"totalCount": 1
}
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| VALIDATION_ | 요청 값 오류 — 필수 값이 빠지면 홈택스에 요청하지 않고 이 코드로 끝나며, 자동 재시도 대상이 아닙니다. error.message 가 빠진 값의 이름을 알려 주니 그 값을 넣어 다시 요청합니다. | |
| VALIDATION_ | 쪽 수 상한 — fetch_all_pages 를 true 로 보내 모든 쪽을 모을 때 max_pages 만큼 쪽을 읽고도 남은 행이 있으면 부분 결과 없이 이 코드로 끝나며, 자동 재시도 대상이 아닙니다. 조회 기간을 나누거나 max_pages 를 늘려 다시 요청합니다. | |
| VALIDATION_ | 숫자 값 오류 — page_num, page_size, max_pages 에 1 이상의 정수가 아닌 값(0, 음수, 소수부가 있는 수, 숫자가 아닌 글자)을 보내면 홈택스에 요청하지 않고 이 코드로 끝나며, 자동 재시도 대상이 아닙니다. error.message 가 확인할 값의 이름을 알려 주니 그 값을 고쳐 다시 요청합니다. 숫자로 된 문자열도 받고, null 로 보내면 보내지 않은 것으로 보아 기본값을 씁니다. | |
| AUTH_ | 세션 없음 — 홈택스 세션이 없습니다. 홈택스 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다. | |
| PROVIDER_ | 업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다. | |
| PROVIDER_ | 업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다. | |
| PROVIDER_ | 업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다. | |
| PROVIDER_ | 업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다. | |
| PROVIDER_ | 세션 만료 — 조회하는 도중 홈택스 로그인 세션이 끝난 것을 알게 되면 이 코드로 끝나며, error.message 안내대로 로그인 액션을 다시 실행해 세션을 연 뒤 같은 요청을 다시 보냅니다. |
4. 현금영수증 발행hometax. cash_ receipt. issue_ individual
MCP 도구 이름 hometax__
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
현금영수증을 개별 발행합니다.
- 요청 거절(HTTP 400, 작업은 만들어지지 않음).error.code=WRITE_CONFIRMATION_REQUIRED — confirmation_token 없이 부르면 홈택스에 아무것도 보내지 않고 이 오류로 끝납니다.error.message 에 확인할 내용이, error.confirmation_token 에 1회용 토큰이, error.preview 에 실행할 내용(what_will_happen_ko), 보낸 값(items), 보내지 않은 칸에 쓰일 값(defaults_ko), 되돌릴 수 없다는 안내(irreversible_ko)가 함께 옵니다.안내를 사용자에게 보여 주고 동의를 받은 뒤 같은 요청의 params.confirmation_token 에 그 토큰을 넣어 다시 보냅니다. 토큰은 10분 안에 한 번만 쓸 수 있고 처음 요청과 같은 본문에만 맞습니다.confirm 칸은 확인으로 쓰이지 않으며, 다시 보낼 때 더하면 본문이 달라져 확인 토큰 불일치로 끝납니다.표의 필수 값이 하나라도 빠졌으면 토큰을 내주지 않고 같은 HTTP 400 의 error.code=VALIDATION_INVALID_FIELD 로 거절하며(자동 재시도 대상이 아닙니다) error.message 가 빠진 값을 말합니다.
- 요청 거절(HTTP 409, 작업은 만들어지지 않음).error.code=WRITE_CONFIRMATION_INVALID — 토큰이 만료됐거나, 이미 썼거나, 다른 호출자나 다른 환경에서 받은 것이거나, 확인한 요청 본문과 달라졌으면 홈택스에 아무것도 보내지 않고 이 오류로 끝나며 어느 쪽인지는 알려 주지 않습니다.error.message 는 「확인이 만료됐거나 확인한 내용과 달라졌습니다. 다시 확인해 주세요.」 입니다. confirmation_token 없이 같은 요청을 다시 보내 새 토큰과 안내를 받은 뒤 사용자에게 다시 확인을 받습니다.
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 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| cshptIsnMmoCntn | string | N | 현금영수증 발급 메모 (최대 300바이트) | |
| cshptTrsTypeCd | string | Y | 거래유형코드 (01=과세, 02=면세, 03=간이) | |
| cshptUsgClCd | string | Y | 용도구분코드 (0=소득공제용, 1=지출증빙용) | |
| spstCnfrClCd | string | Y | 발급수단구분코드 (01=주민등록번호, 02=사업자등록번호, 03=휴대전화번호, 04=카드번호) | |
| spstCnfrNoEncCntn | string | Y | 발급수단번호 (주민번호, 사업자번호, 휴대폰번호, 카드번호 등) | |
| tip | string | N | 봉사료 (기본: 0) | |
| totaTrsAmt | string | Y | 총 거래금액 (최소 1원) | |
| confirmation_ | string | N | 1회용 확인 토큰입니다. 처음에는 보내지 않습니다. 토큰 없이 부르면 기관에 아무것도 보내지 않고 작업도 만들지 않은 채 확인이 필요하다는 오류(WRITE_CONFIRMATION_REQUIRED)로 끝나고, 응답의 error.confirmation_token 에 토큰이 옵니다. error.message 의 안내를 사용자에게 보여 주고 동의를 받은 뒤 같은 요청에 이 토큰을 넣어 다시 부릅니다. 토큰은 10분 안에 한 번만 쓸 수 있고 처음 요청과 같은 본문, 같은 호출자, 같은 환경에서만 맞으며, 아니면 확인이 만료됐거나 내용이 달라졌다는 오류로 거절합니다 |
- 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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: issue_individual-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "hometax",
"action": "hometax.cash_receipt.issue_individual",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {
"cshptTrsTypeCd": "<필수>",
"cshptUsgClCd": "<필수>",
"spstCnfrClCd": "<필수>",
"spstCnfrNoEncCntn": "<필수>",
"tip": "0",
"totaTrsAmt": "<필수>"
}
}'Response
- 기관이 처리했음을 확인한 경우에만 성공합니다.result.data.outcome 은 confirmed 이고, 나머지 키는 홈택스 응답 본문에서 옵니다(기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다).
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| outcome | string | 기관 처리 판정. 성공 응답에서는 항상 confirmed 입니다 | |
| action | string | 요청한 액션 이름. outcome · action 외의 키는 홈택스 응답 본문에서 옵니다(기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다) |
// result.data — outcome · action 외의 키는 홈택스 응답 본문에서 옵니다(기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다).
{
"outcome": "confirmed",
"action": "hometax.cash_receipt.issue_individual"
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| PROVIDER_ | 처리 확인 불가 — 요청은 홈택스로 전송됐지만 처리됐는지 확인하지 못했습니다. 이미 처리됐을 수 있으므로 다시 요청하지 않고, 오류 메시지가 안내하는 홈택스 화면에서 먼저 확인합니다. | |
| AUTH_ | 세션 없음 — 홈택스 세션이 없습니다. 홈택스 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다. | |
| PROVIDER_ | 업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다. | |
| PROVIDER_ | 홈택스 통신 오류 — 홈택스가 오류로 답하거나 연결이 끊겨 요청이 처리됐는지 알 수 없을 수 있으니, 다시 요청하기 전에 홈택스 화면에서 먼저 확인합니다. 홈택스가 오류 응답을 보내거나 연결이 끊긴 경우 error.message 는 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')입니다. | |
| PROVIDER_ | 홈택스 통신 오류 — 홈택스가 오류로 답하거나 연결이 끊겨 요청이 처리됐는지 알 수 없을 수 있으니, 다시 요청하기 전에 홈택스 화면에서 먼저 확인합니다. 홈택스가 오류 응답을 보내거나 연결이 끊긴 경우 error.message 는 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')입니다. | |
| PROVIDER_ | 홈택스 통신 오류 — 홈택스가 오류로 답하거나 연결이 끊겨 요청이 처리됐는지 알 수 없을 수 있으니, 다시 요청하기 전에 홈택스 화면에서 먼저 확인합니다. 홈택스가 오류 응답을 보내거나 연결이 끊긴 경우 error.message 는 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')입니다. |
5. 당일발행 조회hometax. cash_ receipt. daily_ issue. search
MCP 도구 이름 hometax__
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
당일발행을 조회합니다.
- 조회 결과가 없으면 목록이 빈 배열로 돌아옵니다. 실패가 아닙니다.
- params 는 빈 객체로 보내도 호출됩니다. 사용할 인증서는 account_link_id 로 지정합니다.
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 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 길이 | 필수 | 설명 |
|---|---|---|---|---|---|
| page_ | number | - | N | 페이지 번호 (기본: 1) | |
| page_ | number | - | N | 페이지당 조회건수 (기본: 10) | |
| trs_ | string | 8 | N | 거래일자 (기본: 당일, 당일만 조회 가능) |
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": "hometax",
"action": "hometax.cash_receipt.daily_issue.search",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {
"page_num": 1,
"page_size": 10
}
}'Response
- result.data 에 담긴 홈택스 응답 본문을 확인합니다.
- result.data 에는 홈택스가 내려준 응답 본문이 담깁니다. 화면마다 키 구성이 다르고, 기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| totalCount | number | 건수. 이 응답에 담긴 행 수보다 작지 않습니다(기관이 준 값이 행 수보다 작으면 행 수를 씁니다) | |
| pageInfoVO | object | 페이지 정보 객체(pageNum · pageSize · totalCount). totalCount 는 위와 같은 규칙으로 정합니다. 기관 원본은 문자열이지만 이 값은 정수입니다 | |
| collectionMeta | object | 수집 결과 객체 - complete(이 응답이 전부인지, false 면 다음 페이지를 더 받아야 함) · pagesFetched(받은 페이지 수) · collectedCount(이 응답에 담긴 행 수) · totalCount(위 totalCount 와 같은 값) |
// result.data — 나머지 키는 홈택스 응답 본문입니다
{
"cshptIsfIsnPubcDVOList": [ { "...": "..." } ],
"totalCount": 1,
"pageInfoVO": { "pageNum": 1, "pageSize": 10, "totalCount": 1 },
"collectionMeta": { "complete": true, "pagesFetched": 1, "collectedCount": 1, "totalCount": 1 }
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| VALIDATION_ | 숫자 값 오류 — page_num, page_size 에 1 이상의 정수가 아닌 값(0, 음수, 소수부가 있는 수, 숫자가 아닌 글자)을 보내면 홈택스에 요청하지 않고 이 코드로 끝나며, 자동 재시도 대상이 아닙니다. error.message 가 확인할 값의 이름을 알려 주니 그 값을 고쳐 다시 요청합니다. 숫자로 된 문자열도 받고, null 로 보내면 보내지 않은 것으로 보아 기본값을 씁니다. | |
| AUTH_ | 세션 없음 — 홈택스 세션이 없습니다. 홈택스 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다. | |
| PROVIDER_ | 업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다. | |
| PROVIDER_ | 업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다. | |
| PROVIDER_ | 업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다. | |
| PROVIDER_ | 업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다. | |
| PROVIDER_ | 세션 만료 — 조회하는 도중 홈택스 로그인 세션이 끝난 것을 알게 되면 이 코드로 끝나며, error.message 안내대로 로그인 액션을 다시 실행해 세션을 연 뒤 같은 요청을 다시 보냅니다. |
6. 당일발행 수정hometax. cash_ receipt. daily_ issue. modify
MCP 도구 이름 hometax__
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
당일발행 수정합니다. 응답을 받지 못해 다시 보낼 때는 같은 Idempotency-Key를 씁니다.
- 요청 거절(HTTP 400, 작업은 만들어지지 않음).error.code=WRITE_CONFIRMATION_REQUIRED — confirmation_token 없이 부르면 홈택스에 아무것도 보내지 않고 이 오류로 끝납니다.error.message 에 확인할 내용이, error.confirmation_token 에 1회용 토큰이, error.preview 에 실행할 내용(what_will_happen_ko), 보낸 값(items), 보내지 않은 칸에 쓰일 값(defaults_ko), 되돌릴 수 없다는 안내(irreversible_ko)가 함께 옵니다.안내를 사용자에게 보여 주고 동의를 받은 뒤 같은 요청의 params.confirmation_token 에 그 토큰을 넣어 다시 보냅니다. 토큰은 10분 안에 한 번만 쓸 수 있고 처음 요청과 같은 본문에만 맞습니다.confirm 칸은 확인으로 쓰이지 않으며, 다시 보낼 때 더하면 본문이 달라져 확인 토큰 불일치로 끝납니다.표의 필수 값이 하나라도 빠졌으면 토큰을 내주지 않고 같은 HTTP 400 의 error.code=VALIDATION_INVALID_FIELD 로 거절하며(자동 재시도 대상이 아닙니다) error.message 가 빠진 값을 말합니다.
- 요청 거절(HTTP 409, 작업은 만들어지지 않음).error.code=WRITE_CONFIRMATION_INVALID — 토큰이 만료됐거나, 이미 썼거나, 다른 호출자나 다른 환경에서 받은 것이거나, 확인한 요청 본문과 달라졌으면 홈택스에 아무것도 보내지 않고 이 오류로 끝나며 어느 쪽인지는 알려 주지 않습니다.error.message 는 「확인이 만료됐거나 확인한 내용과 달라졌습니다. 다시 확인해 주세요.」 입니다. confirmation_token 없이 같은 요청을 다시 보내 새 토큰과 안내를 받은 뒤 사용자에게 다시 확인을 받습니다.
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 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 길이 | 필수 | 설명 |
|---|---|---|---|---|---|
| aprv_ | string | - | Y | 승인번호 (필수) | |
| cshpt_ | string | - | N | 현금영수증 발급 메모 (선택, 최대 300바이트. 입력하지 않으면 오늘 발급 목록의 원본 메모를 유지합니다) | |
| cshpt_ | string | - | N | 거래유형코드 (선택, 01=과세, 02=면세, 03=간이. 안 주면 원본에 부가세가 있을 때 과세로 본다. 원본으로 알 수 없으면 이 값을 요청한다) | |
| cshpt_ | string | - | N | 용도구분코드 (선택, 0=소득공제용, 1=지출증빙용. 안 주면 오늘 발급 목록의 원본 값) | |
| rcpr_ | string | - | N | 수취자 TIN (선택, 조회 결과에서 자동 설정) | |
| spst_ | string | - | N | 발급수단구분코드 (선택, 01=주민등록번호, 02=사업자등록번호, 03=휴대전화번호, 04=카드번호. 안 주면 오늘 발급 목록의 원본 값) | |
| spst_ | string | - | N | 발급수단번호 (선택, 주민번호, 사업자번호, 휴대폰번호, 카드번호 등. 안 주면 오늘 발급 목록의 원본 값) | |
| tip | string | - | N | 봉사료 (선택. 입력하지 않으면 오늘 발급 목록의 원본 값을 유지합니다. 봉사료를 없애려면 0 을 입력합니다) | |
| tota_ | string | - | Y | 총 거래금액 (필수, 최소 1원) | |
| trs_ | string | 8 | N | 거래일자 (안 주면 원본의 거래일자. 오늘 발급분만 수정할 수 있다) | |
| trs_ | string | - | N | 거래시간 (HHMMSS 형식, 안 주면 원본의 거래시각) | |
| confirmation_ | string | - | N | 1회용 확인 토큰입니다. 처음에는 보내지 않습니다. 토큰 없이 부르면 기관에 아무것도 보내지 않고 작업도 만들지 않은 채 확인이 필요하다는 오류(WRITE_CONFIRMATION_REQUIRED)로 끝나고, 응답의 error.confirmation_token 에 토큰이 옵니다. error.message 의 안내를 사용자에게 보여 주고 동의를 받은 뒤 같은 요청에 이 토큰을 넣어 다시 부릅니다. 토큰은 10분 안에 한 번만 쓸 수 있고 처음 요청과 같은 본문, 같은 호출자, 같은 환경에서만 맞으며, 아니면 확인이 만료됐거나 내용이 달라졌다는 오류로 거절합니다 |
- 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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: modify-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "hometax",
"action": "hometax.cash_receipt.daily_issue.modify",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {
"aprv_no": "<필수>",
"tota_trs_amt": "<필수>"
}
}'Response
- 기관이 처리했음을 확인한 경우에만 성공합니다.result.data.outcome 은 confirmed 이고, 나머지 키는 홈택스 응답 본문에서 옵니다(기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다).
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| outcome | string | 기관 처리 판정. 성공 응답에서는 항상 confirmed 입니다 | |
| action | string | 요청한 액션 이름. outcome · action 외의 키는 홈택스 응답 본문에서 옵니다(기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다) |
// result.data — outcome · action 외의 키는 홈택스 응답 본문에서 옵니다(기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다).
{
"outcome": "confirmed",
"action": "hometax.cash_receipt.daily_issue.modify"
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| PROVIDER_ | 처리 확인 불가 — 요청은 홈택스로 전송됐지만 처리됐는지 확인하지 못했습니다. 이미 처리됐을 수 있으므로 다시 요청하지 않고, 오류 메시지가 안내하는 홈택스 화면에서 먼저 확인합니다. | |
| AUTH_ | 세션 없음 — 홈택스 세션이 없습니다. 홈택스 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다. | |
| PROVIDER_ | 업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다. | |
| PROVIDER_ | 홈택스 통신 오류 — 홈택스가 오류로 답하거나 연결이 끊겨 요청이 처리됐는지 알 수 없을 수 있으니, 다시 요청하기 전에 홈택스 화면에서 먼저 확인합니다. 홈택스가 오류 응답을 보내거나 연결이 끊긴 경우 error.message 는 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')입니다. | |
| PROVIDER_ | 홈택스 통신 오류 — 홈택스가 오류로 답하거나 연결이 끊겨 요청이 처리됐는지 알 수 없을 수 있으니, 다시 요청하기 전에 홈택스 화면에서 먼저 확인합니다. 홈택스가 오류 응답을 보내거나 연결이 끊긴 경우 error.message 는 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')입니다. | |
| PROVIDER_ | 홈택스 통신 오류 — 홈택스가 오류로 답하거나 연결이 끊겨 요청이 처리됐는지 알 수 없을 수 있으니, 다시 요청하기 전에 홈택스 화면에서 먼저 확인합니다. 홈택스가 오류 응답을 보내거나 연결이 끊긴 경우 error.message 는 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')입니다. |
7. 당일발행 취소hometax. cash_ receipt. daily_ issue. cancel
MCP 도구 이름 hometax__
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
당일발행 취소합니다. 응답을 받지 못해 다시 보낼 때는 같은 Idempotency-Key를 씁니다.
- 요청 거절(HTTP 400, 작업은 만들어지지 않음).error.code=WRITE_CONFIRMATION_REQUIRED — confirmation_token 없이 부르면 홈택스에 아무것도 보내지 않고 이 오류로 끝납니다.error.message 에 확인할 내용이, error.confirmation_token 에 1회용 토큰이, error.preview 에 실행할 내용(what_will_happen_ko), 보낸 값(items), 보내지 않은 칸에 쓰일 값(defaults_ko), 되돌릴 수 없다는 안내(irreversible_ko)가 함께 옵니다.안내를 사용자에게 보여 주고 동의를 받은 뒤 같은 요청의 params.confirmation_token 에 그 토큰을 넣어 다시 보냅니다. 토큰은 10분 안에 한 번만 쓸 수 있고 처음 요청과 같은 본문에만 맞습니다.confirm 칸은 확인으로 쓰이지 않으며, 다시 보낼 때 더하면 본문이 달라져 확인 토큰 불일치로 끝납니다.표의 필수 값이 하나라도 빠졌으면 토큰을 내주지 않고 같은 HTTP 400 의 error.code=VALIDATION_INVALID_FIELD 로 거절하며(자동 재시도 대상이 아닙니다) error.message 가 빠진 값을 말합니다.
- 요청 거절(HTTP 409, 작업은 만들어지지 않음).error.code=WRITE_CONFIRMATION_INVALID — 토큰이 만료됐거나, 이미 썼거나, 다른 호출자나 다른 환경에서 받은 것이거나, 확인한 요청 본문과 달라졌으면 홈택스에 아무것도 보내지 않고 이 오류로 끝나며 어느 쪽인지는 알려 주지 않습니다.error.message 는 「확인이 만료됐거나 확인한 내용과 달라졌습니다. 다시 확인해 주세요.」 입니다. confirmation_token 없이 같은 요청을 다시 보내 새 토큰과 안내를 받은 뒤 사용자에게 다시 확인을 받습니다.
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 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 길이 | 필수 | 설명 |
|---|---|---|---|---|---|
| aprv_ | string | - | Y | 승인번호 (필수) | |
| cshpt_ | string | - | Y | 취소사유코드 (필수, 1=거래취소, 2=오류발급, 3=기타) | |
| cshpt_ | string | - | N | 거래유형코드 (선택, 조회 결과에서 가져옴, 01=과세, 02=면세, 03=간이) | |
| cshpt_ | string | - | N | 용도구분코드 (선택, 조회 결과에서 가져옴) | |
| rcpr_ | string | - | N | 수취자 TIN (선택, 조회 결과에서 가져옴) | |
| spl_ | string | - | N | 공급가액 (선택, 조회 결과에서 가져옴) | |
| spst_ | string | - | N | 발급수단구분코드 (선택, 조회 결과에서 가져옴) | |
| spst_ | string | - | N | 발급수단번호 (선택, 조회 결과에서 가져옴) | |
| tip | string | - | N | 봉사료 (선택, 조회 결과에서 가져옴) | |
| tota_ | string | - | N | 총 거래금액 (선택, 조회 결과에서 가져옴) | |
| trs_ | string | 8 | N | 거래일자 (안 주면 원본의 거래일자. 오늘 발급분만 취소할 수 있다) | |
| trs_ | string | - | N | 거래시간 (HHMMSS 형식, 조회 결과에서 가져옴) | |
| va_ | string | - | N | 부가세 (선택, 조회 결과에서 가져옴) | |
| confirmation_ | string | - | N | 1회용 확인 토큰입니다. 처음에는 보내지 않습니다. 토큰 없이 부르면 기관에 아무것도 보내지 않고 작업도 만들지 않은 채 확인이 필요하다는 오류(WRITE_CONFIRMATION_REQUIRED)로 끝나고, 응답의 error.confirmation_token 에 토큰이 옵니다. error.message 의 안내를 사용자에게 보여 주고 동의를 받은 뒤 같은 요청에 이 토큰을 넣어 다시 부릅니다. 토큰은 10분 안에 한 번만 쓸 수 있고 처음 요청과 같은 본문, 같은 호출자, 같은 환경에서만 맞으며, 아니면 확인이 만료됐거나 내용이 달라졌다는 오류로 거절합니다 |
- 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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: cancel-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "hometax",
"action": "hometax.cash_receipt.daily_issue.cancel",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {
"aprv_no": "<필수>",
"cshpt_cncl_rsn_cd": "<필수>"
}
}'Response
- 기관이 처리했음을 확인한 경우에만 성공합니다.result.data.outcome 은 confirmed 이고, 나머지 키는 홈택스 응답 본문에서 옵니다(기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다).
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| outcome | string | 기관 처리 판정. 성공 응답에서는 항상 confirmed 입니다 | |
| action | string | 요청한 액션 이름. outcome · action 외의 키는 홈택스 응답 본문에서 옵니다(기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다) |
// result.data — outcome · action 외의 키는 홈택스 응답 본문에서 옵니다(기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다).
{
"outcome": "confirmed",
"action": "hometax.cash_receipt.daily_issue.cancel"
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| PROVIDER_ | 처리 확인 불가 — 요청은 홈택스로 전송됐지만 처리됐는지 확인하지 못했습니다. 이미 처리됐을 수 있으므로 다시 요청하지 않고, 오류 메시지가 안내하는 홈택스 화면에서 먼저 확인합니다. | |
| AUTH_ | 세션 없음 — 홈택스 세션이 없습니다. 홈택스 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다. | |
| PROVIDER_ | 업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다. | |
| PROVIDER_ | 홈택스 통신 오류 — 홈택스가 오류로 답하거나 연결이 끊겨 요청이 처리됐는지 알 수 없을 수 있으니, 다시 요청하기 전에 홈택스 화면에서 먼저 확인합니다. 홈택스가 오류 응답을 보내거나 연결이 끊긴 경우 error.message 는 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')입니다. | |
| PROVIDER_ | 홈택스 통신 오류 — 홈택스가 오류로 답하거나 연결이 끊겨 요청이 처리됐는지 알 수 없을 수 있으니, 다시 요청하기 전에 홈택스 화면에서 먼저 확인합니다. 홈택스가 오류 응답을 보내거나 연결이 끊긴 경우 error.message 는 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')입니다. | |
| PROVIDER_ | 홈택스 통신 오류 — 홈택스가 오류로 답하거나 연결이 끊겨 요청이 처리됐는지 알 수 없을 수 있으니, 다시 요청하기 전에 홈택스 화면에서 먼저 확인합니다. 홈택스가 오류 응답을 보내거나 연결이 끊긴 경우 error.message 는 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')입니다. |