현금영수증

현금영수증을 발행하고 매출·매입 내역과 당일발행 건을 조회합니다.

1. 현금영수증 매출 내역 조회hometax.cash_receipt.sales.search_history

MCP 도구 이름 hometax__cash_receipt__sales__search_history

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

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

현금영수증 매출 내역 조회합니다.

홈택스 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [홈택스 로그인(세션 생성)]
조회 결과가 없으면 목록이 빈 배열로 돌아옵니다. 실패가 아닙니다.
sandbox 환경에서는 실제 홈택스에 접속하지 않습니다. result.data 에는 mock: true 와 보낸 params 를 그대로 담은 params_echo 가 오고, 업무 응답 필드는 오지 않습니다.

Request

변수명	필수	설명
Authorization	Y	API 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다. 형식 : Basic base64("{client_id}:{client_secret}") [참고] 인증
X-Env-Scope	Y	호출 환경입니다. `sandbox`샌드박스 — 모의 응답 `real_test`데모 — 하루 100 사용 토큰 `production`정식 — 유료 플랜 전용 [참고] 환경
Idempotency-Key	Y	재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다. [참고] 재시도
Content-Type	Y	요청 본문 형식입니다. `application/json`고정값 (기본값)
X-Trace-Id	N	추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.

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

변수명	타입	길이	필수	설명
from_date	string	-	Y	조회 시작일입니다. 별칭 inqr_dt_strt / trs_dt_rng_strt
to_date	string	-	Y	조회 종료일입니다. 별칭 inqr_dt_end / trs_dt_rng_end
fetch_all_pages	boolean	-	N	전체 페이지 자동 수집 여부
max_pages	number	-	N	전체 수집 최대 페이지 수 예시 : 100
page_num	number	-	N	페이지 번호 (기본: 1) 예시 : 1
page_size	number	-	N	페이지당 조회건수 (기본: 10) 예시 : 10
pbl_cl_cd	string	-	N	발행구분 (all=전체, 1=사업자, 2=국세청, 3=명세서, 기본: all) 예시 : all
trs_dt_rng_end	string	8	N	거래일자 범위 종료 ( 형식) 형식 : YYYYMMDD 예시 : 20251030
trs_dt_rng_strt	string	8	N	거래일자 범위 시작 ( 형식) 형식 : YYYYMMDD 예시 : 20251030

bash

curl --request POST \
  --url 'https://api.xdata.kr/v1/jobs' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: sandbox' \
  --header 'Idempotency-Key: demo-search_history-001' \
  --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_end": "20251030",
    "trs_dt_rng_strt": "20251030"
  }
}'

Response

result.data 에 담긴 홈택스 응답 본문을 확인합니다.
result.data 에는 홈택스가 내려준 응답 본문이 담깁니다. 화면마다 키 구성이 다르고, 기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다.

순번	변수명	설명
	totalCount	건수. 이 응답에 담긴 행 수보다 작지 않습니다(기관이 준 값이 행 수보다 작으면 행 수를 씁니다)
	pageInfoVO	페이지 정보 객체(pageNum · pageSize · totalCount). totalCount 는 위와 같은 규칙으로 정합니다. 기관 원본은 문자열이지만 이 값은 정수입니다
	collectionMeta	수집 결과 객체 - complete(이 응답이 전부인지, false 면 다음 페이지를 더 받아야 함) · pagesFetched(받은 페이지 수) · collectedCount(이 응답에 담긴 행 수) · totalCount(위 totalCount 와 같은 값)

json

// result.data — 나머지 키는 홈택스 응답 본문입니다
{
  "cshTrsBrkdInqrDVOList": [ { "...": "..." } ],
  "totalCount": 1,
  "pageInfoVO": { "pageNum": 1, "pageSize": 10, "totalCount": 1 },
  "collectionMeta": { "complete": true, "pagesFetched": 1, "collectedCount": 1, "totalCount": 1 }
}

순번	오류 코드	발생 조건
	AUTH_REQUIRED	세션 없음 — 홈택스 세션이 없습니다. 홈택스 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다.
	PROVIDER_BUSINESS_ERROR	업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다.
	PROVIDER_VALIDATION_ERROR	업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다.
	PROVIDER_UNAVAILABLE	업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다.
	PROVIDER_UPSTREAM_ERROR	업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다.

2. 현금영수증 매출내역누계hometax.cash_receipt.sales.search_summary

MCP 도구 이름 hometax__cash_receipt__sales__search_summary

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

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

현금영수증 매출내역누계합니다.

홈택스 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [홈택스 로그인(세션 생성)]
조회 결과가 없으면 목록이 빈 배열로 돌아옵니다. 실패가 아닙니다.
sandbox 환경에서는 실제 홈택스에 접속하지 않습니다. result.data 에는 mock: true 와 보낸 params 를 그대로 담은 params_echo 가 오고, 업무 응답 필드는 오지 않습니다.

Request

변수명	필수	설명
Authorization	Y	API 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다. 형식 : Basic base64("{client_id}:{client_secret}") [참고] 인증
X-Env-Scope	Y	호출 환경입니다. `sandbox`샌드박스 — 모의 응답 `real_test`데모 — 하루 100 사용 토큰 `production`정식 — 유료 플랜 전용 [참고] 환경
Idempotency-Key	Y	재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다. [참고] 재시도
Content-Type	Y	요청 본문 형식입니다. `application/json`고정값 (기본값)
X-Trace-Id	N	추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.

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

순번	변수명	타입	길이	필수	설명
	cmtt_yr	string	4	Y	조회년도 ( 형식) 형식 : YYYY 예시 : 2025
	qrt	string	-	N	분기 (all=연도별 전체, 1=1분기, 2=2분기, 3=3분기, 4=4분기, 기본: all) 예시 : all

순번

변수명

타입

길이

필수

설명

cmtt_yr

string

조회년도 ( 형식)

형식 : YYYY

예시 : 2025

qrt

string

분기 (all=연도별 전체, 1=1분기, 2=2분기, 3=3분기, 4=4분기, 기본: all)

예시 : all

bash

curl --request POST \
  --url 'https://api.xdata.kr/v1/jobs' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: sandbox' \
  --header 'Idempotency-Key: demo-search_summary-001' \
  --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 는 기관 응답 본문을 그대로 전달합니다. 고정 필드 목록이 없습니다.

json

// result.data — 홈택스 응답 본문이 담깁니다. 화면마다 키 구성이 다르고, 기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다.
{}

순번	오류 코드	발생 조건
	AUTH_REQUIRED	세션 없음 — 홈택스 세션이 없습니다. 홈택스 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다.
	PROVIDER_BUSINESS_ERROR	업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다.
	PROVIDER_VALIDATION_ERROR	업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다.
	PROVIDER_UNAVAILABLE	업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다.
	PROVIDER_UPSTREAM_ERROR	업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다.

3. 현금영수증 매입 내역 조회hometax.cash_receipt.purchase.search_history

MCP 도구 이름 hometax__cash_receipt__purchase__search_history

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

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

현금영수증 매입 내역 조회합니다.

홈택스 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [홈택스 로그인(세션 생성)]
조회 결과가 없으면 목록이 빈 배열로 돌아옵니다. 실패가 아닙니다.
sandbox 환경에서는 실제 홈택스에 접속하지 않습니다. result.data 에는 mock: true 와 보낸 params 를 그대로 담은 params_echo 가 오고, 업무 응답 필드는 오지 않습니다.

Request

변수명	필수	설명
Authorization	Y	API 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다. 형식 : Basic base64("{client_id}:{client_secret}") [참고] 인증
X-Env-Scope	Y	호출 환경입니다. `sandbox`샌드박스 — 모의 응답 `real_test`데모 — 하루 100 사용 토큰 `production`정식 — 유료 플랜 전용 [참고] 환경
Idempotency-Key	Y	재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다. [참고] 재시도
Content-Type	Y	요청 본문 형식입니다. `application/json`고정값 (기본값)
X-Trace-Id	N	추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.

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

변수명	타입	길이	필수	설명
from_date	string	-	Y	조회 시작일입니다. 별칭 inqr_dt_strt / trs_dt_rng_strt
to_date	string	-	Y	조회 종료일입니다. 별칭 inqr_dt_end / trs_dt_rng_end
fetch_all_pages	boolean	-	N	전체 페이지 자동 수집 여부
max_pages	number	-	N	전체 수집 최대 페이지 수 예시 : 100
mrnt_txpr_dscm_no	string	-	N	가맹점 사업자번호 (하이픈 제거, 최대 10자리)
page_num	number	-	N	페이지 번호 (기본: 1) 예시 : 1
page_size	number	-	N	페이지당 조회건수 (기본: 10) 예시 : 10
pubc_user_no	string	-	N	부서 사용자 번호 (all=전체, 기본: all) 예시 : all
spjb_trs_yn	string	-	N	현금매출명세서 발행 여부 (all=전체, Y=현금매출명세서 발행만, 기본: all) 예시 : all
spst_cnfr_id	string	-	N	신분확인수단 ID (all=전체, 기본: all) 예시 : all
trs_dt_rng_end	string	8	N	거래일자 범위 종료 ( 형식) 형식 : YYYYMMDD 예시 : 20251030
trs_dt_rng_strt	string	8	N	거래일자 범위 시작 ( 형식) 형식 : YYYYMMDD 예시 : 20251030

bash

curl --request POST \
  --url 'https://api.xdata.kr/v1/jobs' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: sandbox' \
  --header 'Idempotency-Key: demo-search_history-001' \
  --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_end": "20251030",
    "trs_dt_rng_strt": "20251030"
  }
}'

Response

result.data 에 담긴 홈택스 응답 본문을 확인합니다.
result.data 에는 홈택스가 내려준 응답 본문이 담깁니다. 화면마다 키 구성이 다르고, 기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다.

순번	변수명	설명
	totalCount	건수. 이 응답에 담긴 행 수보다 작지 않습니다(기관이 준 값이 행 수보다 작으면 행 수를 씁니다)
	pageInfoVO	페이지 정보 객체(pageNum · pageSize · totalCount). totalCount 는 위와 같은 규칙으로 정합니다. 기관 원본은 문자열이지만 이 값은 정수입니다
	collectionMeta	수집 결과 객체 - complete(이 응답이 전부인지, false 면 다음 페이지를 더 받아야 함) · pagesFetched(받은 페이지 수) · collectedCount(이 응답에 담긴 행 수) · totalCount(위 totalCount 와 같은 값)

json

// result.data — 나머지 키는 홈택스 응답 본문입니다
{
  "cshTrsBrkdInqrDVOList": [ { "...": "..." } ],
  "totalCount": 1,
  "pageInfoVO": { "pageNum": 1, "pageSize": 10, "totalCount": 1 },
  "collectionMeta": { "complete": true, "pagesFetched": 1, "collectedCount": 1, "totalCount": 1 }
}

순번	오류 코드	발생 조건
	AUTH_REQUIRED	세션 없음 — 홈택스 세션이 없습니다. 홈택스 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다.
	PROVIDER_BUSINESS_ERROR	업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다.
	PROVIDER_VALIDATION_ERROR	업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다.
	PROVIDER_UNAVAILABLE	업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다.
	PROVIDER_UPSTREAM_ERROR	업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다.

4. 현금영수증 발행hometax.cash_receipt.issue_individual

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

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

현금영수증을 개별 발행합니다.

홈택스 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [홈택스 로그인(세션 생성)]
sandbox 환경에서는 실제 홈택스에 접속하지 않습니다. result.data 에는 mock: true 와 보낸 params 를 그대로 담은 params_echo 가 오고, 업무 응답 필드는 오지 않습니다.

Request

변수명	필수	설명
Authorization	Y	API 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다. 형식 : Basic base64("{client_id}:{client_secret}") [참고] 인증
X-Env-Scope	Y	호출 환경입니다. `sandbox`샌드박스 — 모의 응답 `real_test`데모 — 하루 100 사용 토큰 `production`정식 — 유료 플랜 전용 [참고] 환경
Idempotency-Key	Y	재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다. [참고] 재시도
Content-Type	Y	요청 본문 형식입니다. `application/json`고정값 (기본값)
X-Trace-Id	N	추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.

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

변수명	타입	필수	설명
confirm	boolean	Y	실행 확인. 사용자에게 미리보기를 보여주고 동의를 받았을 때만 true 로 보낸다. 자동으로 채우지 않는다
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) 예시 : 0
totaTrsAmt	string	Y	총 거래금액 (최소 1원)

bash

curl --request POST \
  --url 'https://api.xdata.kr/v1/jobs' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: sandbox' \
  --header 'Idempotency-Key: demo-issue_individual-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "hometax",
  "action": "hometax.cash_receipt.issue_individual",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "confirm": "<필수: boolean>",
    "cshptTrsTypeCd": "<필수>",
    "cshptUsgClCd": "<필수>",
    "spstCnfrClCd": "<필수>",
    "spstCnfrNoEncCntn": "<필수>",
    "tip": "0",
    "totaTrsAmt": "<필수>"
  }
}'

Response

기관이 처리했음을 확인한 경우에만 성공합니다. result.data.outcome 은 CONFIRMED 이고, 나머지 키는 홈택스 응답 본문에서 옵니다(기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다).

순번	변수명	설명
	outcome	기관 처리 판정. 성공 응답에서는 항상 CONFIRMED 입니다
	action	요청한 액션 이름. outcome · action 외의 키는 홈택스 응답 본문에서 옵니다(기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다)

json

// result.data — outcome · action 외의 키는 홈택스 응답 본문에서 옵니다(기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다).
{
  "outcome": "CONFIRMED",
  "action": "hometax.cash_receipt.issue_individual"
}

순번	오류 코드	발생 조건
	PROVIDER_OUTCOME_UNCONFIRMED	처리 확인 불가 — 요청은 홈택스로 전송됐지만 처리됐는지 확인하지 못했습니다. 이미 처리됐을 수 있으므로 다시 요청하지 않고, 오류 메시지가 안내하는 홈택스 화면에서 먼저 확인합니다.
	AUTH_REQUIRED	세션 없음 — 홈택스 세션이 없습니다. 홈택스 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다.
	PROVIDER_BUSINESS_ERROR	업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다.
	PROVIDER_VALIDATION_ERROR	업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다.
	PROVIDER_UNAVAILABLE	업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다.
	PROVIDER_UPSTREAM_ERROR	업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다.

5. 당일발행 조회hometax.cash_receipt.daily_issue.search

MCP 도구 이름 hometax__cash_receipt__daily_issue__search

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

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

당일발행 조회합니다.

홈택스 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [홈택스 로그인(세션 생성)]
조회 결과가 없으면 목록이 빈 배열로 돌아옵니다. 실패가 아닙니다.
sandbox 환경에서는 실제 홈택스에 접속하지 않습니다. result.data 에는 mock: true 와 보낸 params 를 그대로 담은 params_echo 가 오고, 업무 응답 필드는 오지 않습니다.

Request

변수명	필수	설명
Authorization	Y	API 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다. 형식 : Basic base64("{client_id}:{client_secret}") [참고] 인증
X-Env-Scope	Y	호출 환경입니다. `sandbox`샌드박스 — 모의 응답 `real_test`데모 — 하루 100 사용 토큰 `production`정식 — 유료 플랜 전용 [참고] 환경
Idempotency-Key	Y	재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다. [참고] 재시도
Content-Type	Y	요청 본문 형식입니다. `application/json`고정값 (기본값)
X-Trace-Id	N	추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.

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

변수명	타입	길이	필수	설명
page_num	number	-	N	페이지 번호 (기본: 1) 예시 : 1
page_size	number	-	N	페이지당 조회건수 (기본: 10) 예시 : 10
trs_dt	string	8	N	거래일자 ( 형식, 기본: 당일, 당일만 조회 가능) 형식 : YYYYMMDD

bash

curl --request POST \
  --url 'https://api.xdata.kr/v1/jobs' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: sandbox' \
  --header 'Idempotency-Key: demo-search-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "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	건수. 이 응답에 담긴 행 수보다 작지 않습니다(기관이 준 값이 행 수보다 작으면 행 수를 씁니다)
	pageInfoVO	페이지 정보 객체(pageNum · pageSize · totalCount). totalCount 는 위와 같은 규칙으로 정합니다. 기관 원본은 문자열이지만 이 값은 정수입니다
	collectionMeta	수집 결과 객체 - complete(이 응답이 전부인지, false 면 다음 페이지를 더 받아야 함) · pagesFetched(받은 페이지 수) · collectedCount(이 응답에 담긴 행 수) · totalCount(위 totalCount 와 같은 값)

json

// result.data — 나머지 키는 홈택스 응답 본문입니다
{
  "cshptIsfIsnPubcDVOList": [ { "...": "..." } ],
  "totalCount": 1,
  "pageInfoVO": { "pageNum": 1, "pageSize": 10, "totalCount": 1 },
  "collectionMeta": { "complete": true, "pagesFetched": 1, "collectedCount": 1, "totalCount": 1 }
}

순번	오류 코드	발생 조건
	AUTH_REQUIRED	세션 없음 — 홈택스 세션이 없습니다. 홈택스 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다.
	PROVIDER_BUSINESS_ERROR	업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다.
	PROVIDER_VALIDATION_ERROR	업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다.
	PROVIDER_UNAVAILABLE	업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다.
	PROVIDER_UPSTREAM_ERROR	업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다.

6. 당일발행 수정hometax.cash_receipt.daily_issue.modify

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

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

당일발행 수정합니다. 응답을 받지 못해 다시 보낼 때는 같은 Idempotency-Key를 씁니다.

홈택스 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [홈택스 로그인(세션 생성)]
sandbox 환경에서는 실제 홈택스에 접속하지 않습니다. result.data 에는 mock: true 와 보낸 params 를 그대로 담은 params_echo 가 오고, 업무 응답 필드는 오지 않습니다.

Request

변수명	필수	설명
Authorization	Y	API 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다. 형식 : Basic base64("{client_id}:{client_secret}") [참고] 인증
X-Env-Scope	Y	호출 환경입니다. `sandbox`샌드박스 — 모의 응답 `real_test`데모 — 하루 100 사용 토큰 `production`정식 — 유료 플랜 전용 [참고] 환경
Idempotency-Key	Y	재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다. [참고] 재시도
Content-Type	Y	요청 본문 형식입니다. `application/json`고정값 (기본값)
X-Trace-Id	N	추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.

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

변수명	타입	길이	필수	설명
aprv_no	string	-	Y	승인번호 (필수)
confirm	boolean	-	Y	실행 확인. 사용자에게 미리보기를 보여주고 동의를 받았을 때만 true 로 보낸다. 자동으로 채우지 않는다
cshpt_isn_mmo_cntn	string	-	N	현금영수증 발급 메모 (최대 300바이트)
cshpt_trs_type_cd	string	-	N	거래유형코드 (선택, 01=과세, 02=면세, 03=간이. 안 주면 원본에 부가세가 있을 때 과세로 본다. 원본으로 알 수 없으면 이 값을 요청한다)
cshpt_usg_cl_cd	string	-	N	용도구분코드 (선택, 0=소득공제용, 1=지출증빙용. 안 주면 오늘 발급 목록의 원본 값)
rcpr_tin	string	-	N	수취자 TIN (선택, 조회 결과에서 자동 설정)
spst_cnfr_cl_cd	string	-	N	발급수단구분코드 (선택, 01=주민등록번호, 02=사업자등록번호, 03=휴대전화번호, 04=카드번호. 안 주면 오늘 발급 목록의 원본 값)
spst_cnfr_no_enc_cntn	string	-	N	발급수단번호 (선택, 주민번호, 사업자번호, 휴대폰번호, 카드번호 등. 안 주면 오늘 발급 목록의 원본 값)
tip	string	-	N	봉사료 (기본: 0) 예시 : 0
tota_trs_amt	string	-	Y	총 거래금액 (필수, 최소 1원)
trs_dt	string	8	N	거래일자 ( 형식, 안 주면 원본의 거래일자. 오늘 발급분만 수정할 수 있다) 형식 : YYYYMMDD
trs_time	string	-	N	거래시간 (HHMMSS 형식, 안 주면 원본의 거래시각)

bash

curl --request POST \
  --url 'https://api.xdata.kr/v1/jobs' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: sandbox' \
  --header 'Idempotency-Key: demo-modify-001' \
  --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": "<필수>",
    "confirm": "<필수: boolean>",
    "tip": "0",
    "tota_trs_amt": "<필수>"
  }
}'

Response

기관이 처리했음을 확인한 경우에만 성공합니다. result.data.outcome 은 CONFIRMED 이고, 나머지 키는 홈택스 응답 본문에서 옵니다(기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다).

순번	변수명	설명
	outcome	기관 처리 판정. 성공 응답에서는 항상 CONFIRMED 입니다
	action	요청한 액션 이름. outcome · action 외의 키는 홈택스 응답 본문에서 옵니다(기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다)

json

// result.data — outcome · action 외의 키는 홈택스 응답 본문에서 옵니다(기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다).
{
  "outcome": "CONFIRMED",
  "action": "hometax.cash_receipt.daily_issue.modify"
}

순번	오류 코드	발생 조건
	PROVIDER_OUTCOME_UNCONFIRMED	처리 확인 불가 — 요청은 홈택스로 전송됐지만 처리됐는지 확인하지 못했습니다. 이미 처리됐을 수 있으므로 다시 요청하지 않고, 오류 메시지가 안내하는 홈택스 화면에서 먼저 확인합니다.
	AUTH_REQUIRED	세션 없음 — 홈택스 세션이 없습니다. 홈택스 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다.
	PROVIDER_BUSINESS_ERROR	업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다.
	PROVIDER_VALIDATION_ERROR	업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다.
	PROVIDER_UNAVAILABLE	업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다.
	PROVIDER_UPSTREAM_ERROR	업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다.

7. 당일발행 취소hometax.cash_receipt.daily_issue.cancel

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

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

당일발행 취소합니다. 응답을 받지 못해 다시 보낼 때는 같은 Idempotency-Key를 씁니다.

홈택스 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [홈택스 로그인(세션 생성)]
sandbox 환경에서는 실제 홈택스에 접속하지 않습니다. result.data 에는 mock: true 와 보낸 params 를 그대로 담은 params_echo 가 오고, 업무 응답 필드는 오지 않습니다.

Request

변수명	필수	설명
Authorization	Y	API 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다. 형식 : Basic base64("{client_id}:{client_secret}") [참고] 인증
X-Env-Scope	Y	호출 환경입니다. `sandbox`샌드박스 — 모의 응답 `real_test`데모 — 하루 100 사용 토큰 `production`정식 — 유료 플랜 전용 [참고] 환경
Idempotency-Key	Y	재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다. [참고] 재시도
Content-Type	Y	요청 본문 형식입니다. `application/json`고정값 (기본값)
X-Trace-Id	N	추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.

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

변수명	타입	길이	필수	설명
aprv_no	string	-	Y	승인번호 (필수)
confirm	boolean	-	Y	실행 확인. 사용자에게 미리보기를 보여주고 동의를 받았을 때만 true 로 보낸다. 자동으로 채우지 않는다
cshpt_cncl_rsn_cd	string	-	Y	취소사유코드 (필수, 1=거래취소, 2=오류발급, 3=기타)
cshpt_trs_type_cd	string	-	N	거래유형코드 (선택, 조회 결과에서 가져옴, 01=과세, 02=면세, 03=간이)
cshpt_usg_cl_cd	string	-	N	용도구분코드 (선택, 조회 결과에서 가져옴)
rcpr_tin	string	-	N	수취자 TIN (선택, 조회 결과에서 가져옴)
spl_cft	string	-	N	공급가액 (선택, 조회 결과에서 가져옴)
spst_cnfr_cl_cd	string	-	N	발급수단구분코드 (선택, 조회 결과에서 가져옴)
spst_cnfr_no_enc_cntn	string	-	N	발급수단번호 (선택, 조회 결과에서 가져옴)
tip	string	-	N	봉사료 (선택, 조회 결과에서 가져옴)
tota_trs_amt	string	-	N	총 거래금액 (선택, 조회 결과에서 가져옴)
trs_dt	string	8	N	거래일자 ( 형식, 안 주면 원본의 거래일자. 오늘 발급분만 취소할 수 있다) 형식 : YYYYMMDD
trs_time	string	-	N	거래시간 (HHMMSS 형식, 조회 결과에서 가져옴)
va_txamt	string	-	N	부가세 (선택, 조회 결과에서 가져옴)

bash

curl --request POST \
  --url 'https://api.xdata.kr/v1/jobs' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: sandbox' \
  --header 'Idempotency-Key: demo-cancel-001' \
  --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": "<필수>",
    "confirm": "<필수: boolean>",
    "cshpt_cncl_rsn_cd": "<필수>"
  }
}'

Response

기관이 처리했음을 확인한 경우에만 성공합니다. result.data.outcome 은 CONFIRMED 이고, 나머지 키는 홈택스 응답 본문에서 옵니다(기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다).

순번	변수명	설명
	outcome	기관 처리 판정. 성공 응답에서는 항상 CONFIRMED 입니다
	action	요청한 액션 이름. outcome · action 외의 키는 홈택스 응답 본문에서 옵니다(기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다)

json

// result.data — outcome · action 외의 키는 홈택스 응답 본문에서 옵니다(기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다).
{
  "outcome": "CONFIRMED",
  "action": "hometax.cash_receipt.daily_issue.cancel"
}

순번	오류 코드	발생 조건
	PROVIDER_OUTCOME_UNCONFIRMED	처리 확인 불가 — 요청은 홈택스로 전송됐지만 처리됐는지 확인하지 못했습니다. 이미 처리됐을 수 있으므로 다시 요청하지 않고, 오류 메시지가 안내하는 홈택스 화면에서 먼저 확인합니다.
	AUTH_REQUIRED	세션 없음 — 홈택스 세션이 없습니다. 홈택스 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다.
	PROVIDER_BUSINESS_ERROR	업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다.
	PROVIDER_VALIDATION_ERROR	업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다.
	PROVIDER_UNAVAILABLE	업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다.
	PROVIDER_UPSTREAM_ERROR	업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다.