세무

사업자 상태, 신고 이력, 고지·체납·환급 등 세무 자료를 조회하고 원천징수를 신고합니다.

1. 개인사업자등록상태 조회hometax.tax.business_registration.search_status

MCP 도구 이름 hometax__tax__business_registration__search_status

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

순번	변수명	타입	필수	설명
	psb_search	string	N	조회가능여부 (기본: Y, 5초 이내 중복 조회 방지용) 예시 : Y
	txpr_dscm_no	string	Y	사업자등록번호 (필수, 10자리, 하이픈 제외)

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_status-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "hometax",
  "action": "hometax.tax.business_registration.search_status",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "psb_search": "Y",
    "txpr_dscm_no": "<필수>"
  }
}'

Response

result.data 의 success 값과 목록·페이지 필드를 확인합니다.

순번	변수명	설명
	result	홈택스 응답 본문 객체. 기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다
	trtCntn	처리내용
	trtEndCd	처리종료코드
	txprDscmNo	납세자식별번호
	success	요청 처리 성공 여부

json

// result.data
{
  "result": {},
  "trtCntn": "...",
  "trtEndCd": "...",
  "txprDscmNo": "...",
  "success": true
}

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

2. 나의세무대리인 수임동의hometax.tax.my_tax_agent.search

MCP 도구 이름 hometax__tax__my_tax_agent__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.tax.my_tax_agent.search`이 API 고정값 (기본값) 예시 : hometax.tax.my_tax_agent.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

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.tax.my_tax_agent.search",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "page_num": 1
  }
}'

Response

result.data 의 success 값과 목록·페이지 필드를 확인합니다.

순번	변수명	설명
	result	홈택스 응답 본문 객체. 기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다
	txaaInfrDVOList	세무대리인 목록 배열
	pageInfoVO	페이지 정보 객체
	totalCount	전체 건수
	pageNum	페이지 번호
	pageSize	페이지 크기
	success	요청 처리 성공 여부

json

// result.data
{
  "result": {},
  "txaaInfrDVOList": [],
  "pageInfoVO": {},
  "totalCount": "...",
  "pageNum": "...",
  "pageSize": "...",
  "success": true
}

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

3. 사업자 등록사항 및 담당자 안내hometax.tax.business_registration.search_info

MCP 도구 이름 hometax__tax__business_registration__search_info

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

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

사업자 등록사항 및 담당자 안내합니다.

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

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.tax.business_registration.search_info`이 API 고정값 (기본값) 예시 : hometax.tax.business_registration.search_info
account_link_id	string	36	조건부	등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명 중 대표로 지정한 것이 쓰입니다. 대표가 없으면 등록한 자격증명이 하나뿐일 때만 자동으로 선택되고, 둘 이상이면 직접 지정해야 합니다. 형식 : UUID v4 [참고] 자격증명 등록
params	object	-	N	작업 파라미터입니다. 이 API 는 빈 객체로 호출할 수 있습니다.
encrypted_fields	object	-	N	민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. [참고] 암호화

추가 파라미터가 없습니다. params 는 {} 로 보냅니다.

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_info-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "hometax",
  "action": "hometax.tax.business_registration.search_info",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {}
}'

Response

result.data 의 success 값과 목록·페이지 필드를 확인합니다.

순번	변수명	설명
	result	홈택스 응답 본문 객체. 기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다
	bmanBscInfrInqrDVOList	사업자등록사항 목록 배열
	totalCount	전체 건수
	success	요청 처리 성공 여부

json

// result.data
{
  "result": {},
  "bmanBscInfrInqrDVOList": [],
  "totalCount": 0,
  "success": true
}

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

4. 부가세 신고 이력 조회hometax.tax.return_history.search_vat

MCP 도구 이름 hometax__tax__return_history__search_vat

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.tax.return_history.search_vat`이 API 고정값 (기본값) 예시 : hometax.tax.return_history.search_vat
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
rtn_dt_end	string	8	Y	신고일자 종료일 (, 필수) 형식 : YYYYMMDD 예시 : 20251106
rtn_dt_srt	string	8	Y	신고일자 시작일 (, 필수) 형식 : YYYYMMDD 예시 : 20241107

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_vat-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "hometax",
  "action": "hometax.tax.return_history.search_vat",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "page_num": 1,
    "page_size": 10,
    "rtn_dt_end": "20251106",
    "rtn_dt_srt": "20241107"
  }
}'

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	업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다.

5. 납부할세액 조회납부hometax.tax.payment_due.search_or_pay

MCP 도구 이름 hometax__tax__payment_due__search_or_pay

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

변수명	타입	필수	설명
inqr_cl_cd	string	N	조회구분코드 (선택, '01'=신고 납부기한이 지난 내역 보기)
page_num	number	N	페이지 번호 (기본: 1) 예시 : 1
page_size	number	N	페이지당 조회건수 (기본: 10) 예시 : 10

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_or_pay-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "hometax",
  "action": "hometax.tax.payment_due.search_or_pay",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "page_num": 1,
    "page_size": 10
  }
}'

Response

result.data 의 success 값과 목록·페이지 필드를 확인합니다.

순번	변수명	설명
	result	홈택스 응답 본문 객체. 기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다
	pubcRomCmnDVOList	납부할 세액 목록 배열
	amtSum	납부 세액 합계
	pageInfoVO	페이지 정보 객체
	totalCount	전체 건수
	pageNum	페이지 번호
	pageSize	페이지 크기
	success	요청 처리 성공 여부

json

// result.data
{
  "result": {},
  "pubcRomCmnDVOList": [],
  "amtSum": "...",
  "pageInfoVO": {},
  "totalCount": "...",
  "pageNum": "...",
  "pageSize": "...",
  "success": true
}

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

6. 전자고지 수신동의 상태 조회hometax.tax.electronic_notice.check_status

MCP 도구 이름 hometax__tax__electronic_notice__check_status

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

순번	변수명	타입	필수	설명
	user_srvc_cl_cd	string	N	사용자서비스구분코드 (기본: '03'=전자고지 사용자) 예시 : 03

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-check_status-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "hometax",
  "action": "hometax.tax.electronic_notice.check_status",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "user_srvc_cl_cd": "03"
  }
}'

Response

result.data 의 success 값과 목록·페이지 필드를 확인합니다.

순번	변수명	설명
	result	홈택스 응답 본문 객체. 기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다
	pubcUserInqrDVO	전자고지 조회 객체
	elctNtfYn	전자고지 여부
	userSrvcApplcStrtDtm	서비스 적용 시작일시
	userSrvcApplcEndDtm	서비스 적용 종료일시
	success	요청 처리 성공 여부

json

// result.data
{
  "result": {},
  "pubcUserInqrDVO": {},
  "elctNtfYn": "...",
  "userSrvcApplcStrtDtm": "...",
  "userSrvcApplcEndDtm": "...",
  "success": true
}

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

7. 환급세액 조회(정기신고)hometax.tax.refund.search_detail

MCP 도구 이름 hometax__tax__refund__search_detail

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

변수명	타입	길이	필수	설명
end_dt	string	8	Y	조회기간 종료일자 () 형식 : YYYYMMDD
inqr_cl_cd	string	-	N	조회구분코드 (선택, '00'=전체, '1'=지급완료, '2'=미수령, '3'=1년경과 미수령)
page_num	number	-	N	페이지 번호 (기본: 1) 예시 : 1
page_size	number	-	N	페이지당 조회건수 (기본: 10) 예시 : 10
strt_dt	string	8	Y	조회기간 시작일자 (, 조회일로부터 5년 이내만 조회 가능) 형식 : YYYYMMDD
txaa_id	string	-	N	세무대리인ID (세무대리인인 경우 필수)
txaa_yn	string	-	N	세무대리인 여부 (기본: N) 예시 : N
txpr_dscm_no	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-search_detail-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "hometax",
  "action": "hometax.tax.refund.search_detail",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "end_dt": "<필수>",
    "page_num": 1,
    "page_size": 10,
    "strt_dt": "<필수>",
    "txaa_yn": "N"
  }
}'

Response

result.data 의 success 값과 목록·페이지 필드를 확인합니다.

순번	변수명	설명
	result	홈택스 응답 본문 객체. 기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다
	unpdNtltxRfamtBrkdSVOList	환급 상세 목록 배열
	pageInfoVO	페이지 정보 객체
	totalCount	전체 건수
	pageNum	페이지 번호
	pageSize	페이지 크기
	success	요청 처리 성공 여부

json

// result.data
{
  "result": {},
  "unpdNtltxRfamtBrkdSVOList": [],
  "pageInfoVO": {},
  "totalCount": "...",
  "pageNum": "...",
  "pageSize": "...",
  "success": true
}

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

8. 미수령 환급금 조회hometax.tax.unclaimed_refund.search

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

변수명	타입	필수	설명
nnf_cl	string	N	내외국인구분 ('n'=내국인, '1'=외국인, 기본: 'n'=내국인) 예시 : n
txpr_dscm_no	string	Y	납세자식별번호 (주민등록번호 또는 사업자등록번호, 하이픈 없이 숫자만 입력)
txpr_nm	string	Y	납세자명 (성명 또는 상호, 상호는 일부 단어로 입력도 가능)

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.tax.unclaimed_refund.search",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "nnf_cl": "n",
    "txpr_dscm_no": "<필수>",
    "txpr_nm": "<필수>"
  }
}'

Response

result.data 의 success 값과 목록·페이지 필드를 확인합니다.

순번	변수명	설명
	result	홈택스 응답 본문 객체. 기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다
	unpdRfndScnt	미수령 환급 건수
	txprNm	납세자명
	chrgTelNo1	담당 전화번호1
	chrgTelNo2	담당 전화번호2
	exists	존재 여부
	message	결과 메시지
	success	요청 처리 성공 여부

json

// result.data
{
  "result": {},
  "unpdRfndScnt": 0,
  "txprNm": "...",
  "chrgTelNo1": "...",
  "chrgTelNo2": "...",
  "exists": true,
  "message": "...",
  "success": true
}

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

9. 세금 납부, 환급, 고지, 체납 내역hometax.tax.notice.search_history

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

변수명	타입	길이	필수	설명
end_dt	string	8	Y	발송종료일자 () 형식 : YYYYMMDD
ntpl_crp_cl_cd	string	-	N	개인법인구분코드 (기본: '01'=개인) 예시 : 01
page_num	number	-	N	페이지 번호 (기본: 1) 예시 : 1
page_size	number	-	N	페이지당 조회건수 (기본: 3) 예시 : 3
strt_dt	string	8	Y	발송시작일자 (, 최근 10년전부터 입력 가능) 형식 : YYYYMMDD
surv_ttl	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-search_history-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "hometax",
  "action": "hometax.tax.notice.search_history",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "end_dt": "<필수>",
    "ntpl_crp_cl_cd": "01",
    "page_num": 1,
    "page_size": 3,
    "strt_dt": "<필수>"
  }
}'

Response

result.data 의 success 값과 목록·페이지 필드를 확인합니다.

순번	변수명	설명
	result	홈택스 응답 본문 객체. 기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다
	ntfBrkdDVOList	고지 내역 목록 배열
	pageInfoVO	페이지 정보 객체
	totalCount	전체 건수
	pageNum	페이지 번호
	pageSize	페이지 크기
	success	요청 처리 성공 여부

json

// result.data
{
  "result": {},
  "ntfBrkdDVOList": [],
  "pageInfoVO": {},
  "totalCount": "...",
  "pageNum": "...",
  "pageSize": "...",
  "success": true
}

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

10. 체납(연체) 내역 조회hometax.tax.overdue.search_history

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

변수명	타입	길이	필수	설명
end_dt	string	8	N	발송종료일자 (, 선택) 형식 : YYYYMMDD
ntpl_crp_cl_cd	string	-	N	개인법인구분코드 (기본: '01'=개인) 예시 : 01
page_num	number	-	N	페이지 번호 (기본: 1) 예시 : 1
page_size	number	-	N	페이지당 조회건수 (기본: 3) 예시 : 3
strt_dt	string	8	N	발송시작일자 (, 선택) 형식 : YYYYMMDD
surv_ttl	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-search_history-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "hometax",
  "action": "hometax.tax.overdue.search_history",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "ntpl_crp_cl_cd": "01",
    "page_num": 1,
    "page_size": 3
  }
}'

Response

result.data 의 success 값과 목록·페이지 필드를 확인합니다.

순번	변수명	설명
	result	홈택스 응답 본문 객체. 기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다
	aftBrkdDVOList	체납 내역 목록 배열
	pageInfoVO	페이지 정보 객체
	totalCount	전체 건수
	pageNum	페이지 번호
	pageSize	페이지 크기
	success	요청 처리 성공 여부

json

// result.data
{
  "result": {},
  "aftBrkdDVOList": [],
  "pageInfoVO": {},
  "totalCount": "...",
  "pageNum": "...",
  "pageSize": "...",
  "success": true
}

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

11. 지급명세서 조회hometax.tax.payment_statement.search

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

변수명	타입	길이	필수	설명
attr_yr	string	4	N	귀속년도 (, 지정 시 txtn_ym_strt/end를 자동으로 YYYY01/YYYY12로 설정) 형식 : YYYY
bman_bsno	string	-	N	사업자등록번호 (10자리, 하이픈 제외)
infp_yn	string	-	N	정보공개여부 (Y/N, 기본: Y) 예시 : Y
mate_knd_cd	string	-	Y	자료종류코드 (A0051=근로소득, A0053=퇴직소득, A0086=사업소득 등)
page_num	number	-	N	페이지 번호 (기본: 1) 예시 : 1
page_size	number	-	N	페이지당 조회건수 (기본: 10) 예시 : 10
rcat_no	string	-	N	접수번호
sbms_ym_end	string	6	Y	제출년월 종료 ( 형식) 형식 : YYYYMM 예시 : 202510
sbms_ym_strt	string	6	Y	제출년월 시작 ( 형식) 형식 : YYYYMM 예시 : 202509
txtn_ym_end	string	6	N	과세년월 종료 ( 형식, 선택) 형식 : YYYYMM
txtn_ym_strt	string	6	N	과세년월 시작 ( 형식, 선택) 형식 : YYYYMM

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.tax.payment_statement.search",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "infp_yn": "Y",
    "mate_knd_cd": "<필수>",
    "page_num": 1,
    "page_size": 10,
    "sbms_ym_end": "202510",
    "sbms_ym_strt": "202509"
  }
}'

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	업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다.

12. 지급명세서 등 제출내역hometax.tax.payment_statement.search_submit_history

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

변수명	타입	길이	필수	설명
mate_knd_cd	string	-	N	자료종류코드 (A0161=일용근로소득 간이지급명세서, A0162=연말정산 간이지급명세서, F0025=사업장 제공자 등의 과세자료 제출명세서 등)
page_num	number	-	N	페이지 번호 (기본: 1) 예시 : 1
page_size	number	-	N	페이지당 조회건수 (기본: 10) 예시 : 10
sbms_ym_end	string	6	Y	제출년월 종료 ( 형식) 형식 : YYYYMM 예시 : 202510
sbms_ym_strt	string	6	Y	제출년월 시작 ( 형식) 형식 : YYYYMM 예시 : 202510
txpr_dscm_no	string	-	N	납세자번호/사업자번호 (세무대리인 조회시, 하이픈 포함/미포함 모두 가능)
txtn_ym_end	string	6	N	지급(귀속)연월 종료 ( 형식, 선택) 형식 : YYYYMM
txtn_ym_strt	string	6	N	지급(귀속)연월 시작 ( 형식, 선택) 형식 : YYYYMM

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_submit_history-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "hometax",
  "action": "hometax.tax.payment_statement.search_submit_history",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "page_num": 1,
    "page_size": 10,
    "sbms_ym_end": "202510",
    "sbms_ym_strt": "202510"
  }
}'

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	업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다.

13. 전자세금계산서 거래처 관리hometax.tax.trade_partner.search_list

MCP 도구 이름 hometax__tax__trade_partner__search_list

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.tax.trade_partner.search_list`이 API 고정값 (기본값) 예시 : hometax.tax.trade_partner.search_list
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
rprs_fnm	string	N	대표자명
srt_cl_cd	string	N	정렬 기준 (1=거래처명, 2=거래처등록번호, 3=대표자명, 4=등록일자, 기본: 1) 예시 : 1
srt_opt	string	N	정렬 방식 (01=오름차순, 02=내림차순, 기본: 01) 예시 : 01
txpr_dscm_no	string	N	거래처 등록번호 (하이픈 포함/미포함 모두 가능, 10자리=사업자, 13자리=주민)
txpr_nm	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-search_list-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "hometax",
  "action": "hometax.tax.trade_partner.search_list",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "page_num": 1,
    "page_size": 10,
    "srt_cl_cd": "1",
    "srt_opt": "01"
  }
}'

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	업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다.

14. 신용카드 매출자료 조회hometax.tax.credit_card.search_sales_data

MCP 도구 이름 hometax__tax__credit_card__search_sales_data

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

변수명	타입	길이	필수	설명
bsno	string	-	Y	사업자등록번호 (10자리, 하이픈 제외)
page_num	number	-	N	페이지 번호 예시 : 1
page_size	number	-	N	페이지당 조회건수 예시 : 50
qrt_from	string	-	Y	분기 시작 (1~4)
qrt_to	string	-	Y	분기 종료 (1~4)
stl_yr	string	4	Y	결제년도 () 형식 : YYYY

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_sales_data-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "hometax",
  "action": "hometax.tax.credit_card.search_sales_data",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "bsno": "<필수>",
    "page_num": 1,
    "page_size": 50,
    "qrt_from": "<필수>",
    "qrt_to": "<필수>",
    "stl_yr": "<필수>"
  }
}'

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	업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다.