개발자 문서
서비스 소개키 관리자격증명 등록OpenAPI콘솔
API 레퍼런스

전자세금계산서

전자세금계산서를 발행·수정하고 목록·상세·합계·통계를 조회합니다.

1. 전자세금계산서 합계표 조회hometax.etax.invoice.search_summary

MCP 도구 이름 hometax__etax__invoice__search_summary

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

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

전자세금계산서 합계표 조회합니다.

  • 홈택스 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [홈택스 로그인(세션 생성)]
  • 조회 결과가 없으면 목록이 빈 배열로 돌아옵니다. 실패가 아닙니다.
  • sandbox 환경에서는 실제 홈택스에 접속하지 않습니다. result.data 에는 mock: true 와 보낸 params 를 그대로 담은 params_echo 가 오고, 업무 응답 필드는 오지 않습니다.
Request
순번변수명필수설명
AuthorizationYAPI 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다.

형식 : Basic base64("{client_id}:{client_secret}")

[참고] 인증

X-Env-ScopeY호출 환경입니다.
  • sandbox샌드박스 — 모의 응답
  • real_test데모 — 하루 100 사용 토큰
  • production정식 — 유료 플랜 전용

[참고] 환경

Idempotency-KeyY재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다.

[참고] 재시도

Content-TypeY요청 본문 형식입니다.
  • application/json고정값 (기본값)
X-Trace-IdN추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.
순번변수명타입길이필수설명
providerstring-Y호출할 기관입니다.
  • hometax이 API 고정값 (기본값)

예시 : hometax

actionstring-Y호출할 작업입니다.
  • hometax.etax.invoice.search_summary이 API 고정값 (기본값)

예시 : hometax.etax.invoice.search_summary

account_link_idstring36조건부등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명 중 대표로 지정한 것이 쓰입니다. 대표가 없으면 등록한 자격증명이 하나뿐일 때만 자동으로 선택되고, 둘 이상이면 직접 지정해야 합니다.

형식 : UUID v4

[참고] 자격증명 등록

paramsobject-Y작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다.
encrypted_fieldsobject-N민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다.

[참고] 암호화

순번변수명타입길이필수설명
date_typestring-N작성일자 구분 (01=일자별, 02=월별, 03=분기별)

예시 : 01

end_datestring8N종료일 () - 일자별 조회시 필수

형식 : YYYYMMDD

monthstring-N월 (MM) - 월별 조회시 필수
page_numnumber-N페이지 번호

예시 : 1

page_sizenumber-N페이지당 조회건수

예시 : 10

quarterstring-N분기 (1~6) - 분기별 조회시 필수
search_typestring-N조회 구분 (01=매출, 02=매입)

예시 : 01

start_datestring8N시작일 () - 일자별 조회시 필수

형식 : YYYYMMDD

yearstring4N연도 () - 월별/분기별 조회시 필수

형식 : 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_summary-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "hometax",
  "action": "hometax.etax.invoice.search_summary",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "date_type": "01",
    "page_num": 1,
    "page_size": 10,
    "search_type": "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업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다.

2. 전자세금계산서 목록 조회hometax.etax.invoice.search_list

MCP 도구 이름 hometax__etax__invoice__search_list

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

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

전자세금계산서 목록을 기간으로 조회합니다.

  • 홈택스 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [홈택스 로그인(세션 생성)]
  • 조회 결과가 없으면 목록이 빈 배열로 돌아옵니다. 실패가 아닙니다.
  • sandbox 환경에서는 실제 홈택스에 접속하지 않습니다. result.data 에는 mock: true 와 보낸 params 를 그대로 담은 params_echo 가 오고, 업무 응답 필드는 오지 않습니다.
Request
순번변수명필수설명
AuthorizationYAPI 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다.

형식 : Basic base64("{client_id}:{client_secret}")

[참고] 인증

X-Env-ScopeY호출 환경입니다.
  • sandbox샌드박스 — 모의 응답
  • real_test데모 — 하루 100 사용 토큰
  • production정식 — 유료 플랜 전용

[참고] 환경

Idempotency-KeyY재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다.

[참고] 재시도

Content-TypeY요청 본문 형식입니다.
  • application/json고정값 (기본값)
X-Trace-IdN추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.
순번변수명타입길이필수설명
providerstring-Y호출할 기관입니다.
  • hometax이 API 고정값 (기본값)

예시 : hometax

actionstring-Y호출할 작업입니다.
  • hometax.etax.invoice.search_list이 API 고정값 (기본값)

예시 : hometax.etax.invoice.search_list

account_link_idstring36조건부등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명 중 대표로 지정한 것이 쓰입니다. 대표가 없으면 등록한 자격증명이 하나뿐일 때만 자동으로 선택되고, 둘 이상이면 직접 지정해야 합니다.

형식 : UUID v4

[참고] 자격증명 등록

paramsobject-Y작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다.
encrypted_fieldsobject-N민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다.

[참고] 암호화

순번변수명타입길이필수설명
from_datestring-Y조회 시작일입니다. 별칭 inqr_dt_strt / trs_dt_rng_strt
to_datestring-Y조회 종료일입니다. 별칭 inqr_dt_end / trs_dt_rng_end
bman_cdstring-N공급받는자 등록번호 구분 (00=전체, 01=사업자, 02=주민, 03=외국인)

예시 : 00

dmnr_mpb_nostring-N공급받는자 종사업장번호
dmnr_txpr_dscm_nostring-N공급받는자 등록번호 (매출 조회시, 하이픈 포함/미포함 모두 가능)
dt_clstring-N조회기간 구분 (01=작성일자, 02=발급일자, 03=전송일자)

예시 : 01

etxiv_cl_cdstring-N전자세금계산서 분류 (01=건별, 02=위수탁)

예시 : 01

etxiv_knd_cdstring-N전자세금계산서 종류 (all=전체, 01=일반, 02=영세율, 03=위수탁, 04=수입, 05=위수탁영세율, 06=수입납부유예)
inqr_dt_endstring8N조회 종료일 ( 형식)

형식 : YYYYMMDD

예시 : 20251031

inqr_dt_strtstring8N조회 시작일 ( 형식)

형식 : YYYYMMDD

예시 : 20251001

isn_type_cdstring-N발급유형 (all=전체, 10=인터넷발급, 20=ARS발급, 30=VAN발급, 41=ASP발급, 42=자체발급, 50=겸용서식발급, 70=모바일발급, 90=대리발급)
page_numnumber-N페이지 번호 (기본: 1)

예시 : 1

page_sizenumber-N페이지당 조회건수 (기본: 10)

예시 : 10

prh_sls_cl_cdstring-N매출/매입 구분 (01=매출, 02=매입)

예시 : 01

resno_sec_ynstring-N주민번호 마스킹 여부 (Y/N)

예시 : Y

splr_mpb_nostring-N공급자 종사업장번호
splr_txpr_dscm_nostring-N공급자 등록번호 (매입 조회시, 하이픈 포함/미포함 모두 가능)
srt_cl_cdstring-N정렬 기준 (1=작성일자, 2=승인번호, 3=발급일자, 4=전송일자, 5=사업자등록번호, 6=상호, 7=대표자명, 8=합계금액, 9=공급가액, 10=세액)

예시 : 1

srt_optstring-N정렬 방식 (01=내림차순, 02=오름차순)

예시 : 01

tnm_nmstring-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.etax.invoice.search_list",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "from_date": "<필수>",
    "to_date": "<필수>",
    "bman_cd": "00",
    "dt_cl": "01",
    "etxiv_cl_cd": "01",
    "inqr_dt_end": "20251031",
    "inqr_dt_strt": "20251001",
    "page_num": 1,
    "page_size": 10,
    "prh_sls_cl_cd": "01",
    "resno_sec_yn": "Y",
    "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업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다.

3. 전자세금계산서 통계 조회hometax.etax.invoice.search_statistics

MCP 도구 이름 hometax__etax__invoice__search_statistics

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

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

전자세금계산서 통계 조회합니다.

  • 홈택스 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [홈택스 로그인(세션 생성)]
  • 조회 결과가 없으면 목록이 빈 배열로 돌아옵니다. 실패가 아닙니다.
  • sandbox 환경에서는 실제 홈택스에 접속하지 않습니다. result.data 에는 mock: true 와 보낸 params 를 그대로 담은 params_echo 가 오고, 업무 응답 필드는 오지 않습니다.
Request
순번변수명필수설명
AuthorizationYAPI 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다.

형식 : Basic base64("{client_id}:{client_secret}")

[참고] 인증

X-Env-ScopeY호출 환경입니다.
  • sandbox샌드박스 — 모의 응답
  • real_test데모 — 하루 100 사용 토큰
  • production정식 — 유료 플랜 전용

[참고] 환경

Idempotency-KeyY재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다.

[참고] 재시도

Content-TypeY요청 본문 형식입니다.
  • application/json고정값 (기본값)
X-Trace-IdN추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.
순번변수명타입길이필수설명
providerstring-Y호출할 기관입니다.
  • hometax이 API 고정값 (기본값)

예시 : hometax

actionstring-Y호출할 작업입니다.
  • hometax.etax.invoice.search_statistics이 API 고정값 (기본값)

예시 : hometax.etax.invoice.search_statistics

account_link_idstring36조건부등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명 중 대표로 지정한 것이 쓰입니다. 대표가 없으면 등록한 자격증명이 하나뿐일 때만 자동으로 선택되고, 둘 이상이면 직접 지정해야 합니다.

형식 : UUID v4

[참고] 자격증명 등록

paramsobject-Y작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다.
encrypted_fieldsobject-N민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다.

[참고] 암호화

순번변수명타입길이필수설명
dt_clstring-N조회기간 구분 (01=월별, 02=분기별, 03=년도별, 기본: 01)

예시 : 01

etxiv_clsf_cdstring-N전자세금계산서 분류 (01=전자세금계산서, 03=전자계산서, 기본: 01)

예시 : 01

ht_rtn_cd_endstring-N분기 종료 코드 (분기별 조회시만 사용 = 2025년 2기 확정)

예시 : 20254

ht_rtn_cd_strtstring-N분기 시작 코드 (분기별 조회시만 사용 = 2025년 1기 예정)

예시 : 20251

page_numnumber-N페이지 번호 (기본: 1)

예시 : 1

page_sizenumber-N페이지당 조회건수 (기본: 10)

예시 : 10

wrt_ym_endstring6Y작성년월 종료 (월별:, 분기별: YYYY+분기코드, 년도별: YYYY)

형식 : YYYYMM

예시 : 202510

wrt_ym_strtstring6Y작성년월 시작 (월별:, 분기별: YYYY+분기코드, 년도별: YYYY)

형식 : YYYYMM

예시 : 202509

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_statistics-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "hometax",
  "action": "hometax.etax.invoice.search_statistics",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "dt_cl": "01",
    "etxiv_clsf_cd": "01",
    "ht_rtn_cd_end": "20254",
    "ht_rtn_cd_strt": "20251",
    "page_num": 1,
    "page_size": 10,
    "wrt_ym_end": "202510",
    "wrt_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업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다.

4. 전자세금계산서 상세 조회hometax.etax.invoice.search_detail

MCP 도구 이름 hometax__etax__invoice__search_detail

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

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

전자세금계산서 상세 조회합니다.

  • 홈택스 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [홈택스 로그인(세션 생성)]
  • 조회 결과가 없으면 목록이 빈 배열로 돌아옵니다. 실패가 아닙니다.
  • sandbox 환경에서는 실제 홈택스에 접속하지 않습니다. result.data 에는 mock: true 와 보낸 params 를 그대로 담은 params_echo 가 오고, 업무 응답 필드는 오지 않습니다.
Request
순번변수명필수설명
AuthorizationYAPI 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다.

형식 : Basic base64("{client_id}:{client_secret}")

[참고] 인증

X-Env-ScopeY호출 환경입니다.
  • sandbox샌드박스 — 모의 응답
  • real_test데모 — 하루 100 사용 토큰
  • production정식 — 유료 플랜 전용

[참고] 환경

Idempotency-KeyY재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다.

[참고] 재시도

Content-TypeY요청 본문 형식입니다.
  • application/json고정값 (기본값)
X-Trace-IdN추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.
순번변수명타입길이필수설명
providerstring-Y호출할 기관입니다.
  • hometax이 API 고정값 (기본값)

예시 : hometax

actionstring-Y호출할 작업입니다.
  • hometax.etax.invoice.search_detail이 API 고정값 (기본값)

예시 : hometax.etax.invoice.search_detail

account_link_idstring36조건부등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명 중 대표로 지정한 것이 쓰입니다. 대표가 없으면 등록한 자격증명이 하나뿐일 때만 자동으로 선택되고, 둘 이상이면 직접 지정해야 합니다.

형식 : UUID v4

[참고] 자격증명 등록

paramsobject-Y작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다.
encrypted_fieldsobject-N민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다.

[참고] 암호화

순번변수명타입필수설명
etanstringY승인번호 (24자리 영숫자, 하이픈 포함/미포함 모두 가능)

예시 : 202510291025102920450277

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.etax.invoice.search_detail",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "etan": "202510291025102920450277"
  }
}'
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.etax.invoice.issue

MCP 도구 이름 hometax__etax__invoice__issue

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

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

전자세금계산서 발행합니다. 응답을 받지 못해 다시 보낼 때는 같은 Idempotency-Key를 씁니다.

  • 홈택스 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [홈택스 로그인(세션 생성)]
  • sandbox 환경에서는 실제 홈택스에 접속하지 않습니다. result.data 에는 mock: true 와 보낸 params 를 그대로 담은 params_echo 가 오고, 업무 응답 필드는 오지 않습니다.
Request
순번변수명필수설명
AuthorizationYAPI 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다.

형식 : Basic base64("{client_id}:{client_secret}")

[참고] 인증

X-Env-ScopeY호출 환경입니다.
  • sandbox샌드박스 — 모의 응답
  • real_test데모 — 하루 100 사용 토큰
  • production정식 — 유료 플랜 전용

[참고] 환경

Idempotency-KeyY재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다.

[참고] 재시도

Content-TypeY요청 본문 형식입니다.
  • application/json고정값 (기본값)
X-Trace-IdN추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.
순번변수명타입길이필수설명
providerstring-Y호출할 기관입니다.
  • hometax이 API 고정값 (기본값)

예시 : hometax

actionstring-Y호출할 작업입니다.
  • hometax.etax.invoice.issue이 API 고정값 (기본값)

예시 : hometax.etax.invoice.issue

account_link_idstring36조건부등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명 중 대표로 지정한 것이 쓰입니다. 대표가 없으면 등록한 자격증명이 하나뿐일 때만 자동으로 선택되고, 둘 이상이면 직접 지정해야 합니다.

형식 : UUID v4

[참고] 자격증명 등록

paramsobject-Y작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다.
encrypted_fieldsobject-N민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다.

[참고] 암호화

순번변수명타입길이필수설명
bill_methodstring-Y청구방법 (01: 영수, 02: 청구)
confirmboolean-Y발행 확인. 사용자에게 발행 내용을 보여주고 동의를 받았을 때만 true 로 보낸다. 자동으로 채우지 않는다
dmnr_bsnostring-Y공급받는자 사업자번호
etxiv_clsf_cdstring-N전자세금계산서 구분 코드

예시 : 01

etxiv_dmnr_clsf_cdstring-N전자세금계산서 공급받는자 구분 코드

예시 : 01

etxiv_knd_cdstring-N전자세금계산서 종류 코드

예시 : 01

item_namestring-Y품명
item_quantitynumber-Y수량
item_unit_pricenumber-Y단가
splr_mpb_nostring-N공급자 종사업장번호(주사업장은 0)
splr_tinstring-N공급자 세무서 번호
supply_datestring8Y공급일자 ()

형식 : 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-issue-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "hometax",
  "action": "hometax.etax.invoice.issue",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "bill_method": "<필수>",
    "confirm": "<필수: boolean>",
    "dmnr_bsno": "<필수>",
    "etxiv_clsf_cd": "01",
    "etxiv_dmnr_clsf_cd": "01",
    "etxiv_knd_cd": "01",
    "item_name": "<필수>",
    "item_quantity": "<필수: number>",
    "item_unit_price": "<필수: number>",
    "supply_date": "<필수>"
  }
}'
Response
  • 기관이 발행을 확인한 경우에만 성공합니다. result.data.outcome 은 CONFIRMED 이고, approval_number 에 국세청 승인번호가 담깁니다.
순번변수명설명
success발행 확인 여부. 성공 응답에서는 항상 true 입니다
outcome기관 처리 판정. 성공 응답에서는 항상 CONFIRMED 입니다
etan전자세금계산서 승인번호
message처리 결과 안내 문구
approval_number국세청이 발번한 승인번호(apprvNo). etan 과 같은 값입니다
issue_datetime발행 일시. 기관 응답에 없으면 빈 문자열입니다
result_code기관 판정 코드(resultMsg.result). 성공 응답에서는 S 입니다
issue_data기관의 최종 발행 응답 본문. 기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다
json
// result.data
{
  "success": true,
  "outcome": "CONFIRMED",
  "etan": "...",
  "message": "...",
  "approval_number": "...",
  "issue_datetime": "...",
  "result_code": "S",
  "issue_data": {}
}
순번오류 코드발생 조건
PROVIDER_OUTCOME_UNCONFIRMED처리 확인 불가 — 요청은 홈택스로 전송됐지만 처리됐는지 확인하지 못했습니다. 이미 처리됐을 수 있으므로 다시 요청하지 않고, 오류 메시지가 안내하는 홈택스 화면에서 먼저 확인합니다.
AUTH_REQUIRED세션 없음 — 홈택스 세션이 없습니다. 홈택스 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다.
PROVIDER_BUSINESS_ERROR업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다.
PROVIDER_VALIDATION_ERROR업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다.
PROVIDER_UNAVAILABLE업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다.
PROVIDER_UPSTREAM_ERROR업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다.

6. 전자세금계산서 수정·취소hometax.etax.invoice.modify

MCP 도구 이름 hometax__etax__invoice__modify

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

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

전자세금계산서 수정·취소합니다. 응답을 받지 못해 다시 보낼 때는 같은 Idempotency-Key를 씁니다.

  • 홈택스 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [홈택스 로그인(세션 생성)]
  • sandbox 환경에서는 실제 홈택스에 접속하지 않습니다. result.data 에는 mock: true 와 보낸 params 를 그대로 담은 params_echo 가 오고, 업무 응답 필드는 오지 않습니다.
Request
순번변수명필수설명
AuthorizationYAPI 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다.

형식 : Basic base64("{client_id}:{client_secret}")

[참고] 인증

X-Env-ScopeY호출 환경입니다.
  • sandbox샌드박스 — 모의 응답
  • real_test데모 — 하루 100 사용 토큰
  • production정식 — 유료 플랜 전용

[참고] 환경

Idempotency-KeyY재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다.

[참고] 재시도

Content-TypeY요청 본문 형식입니다.
  • application/json고정값 (기본값)
X-Trace-IdN추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.
순번변수명타입길이필수설명
providerstring-Y호출할 기관입니다.
  • hometax이 API 고정값 (기본값)

예시 : hometax

actionstring-Y호출할 작업입니다.
  • hometax.etax.invoice.modify이 API 고정값 (기본값)

예시 : hometax.etax.invoice.modify

account_link_idstring36조건부등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명 중 대표로 지정한 것이 쓰입니다. 대표가 없으면 등록한 자격증명이 하나뿐일 때만 자동으로 선택되고, 둘 이상이면 직접 지정해야 합니다.

형식 : UUID v4

[참고] 자격증명 등록

paramsobject-Y작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다.
encrypted_fieldsobject-N민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다.

[참고] 암호화

순번변수명타입길이필수설명
confirmboolean-Y수정발급 확인. 사용자에게 수정 내용을 보여주고 동의를 받았을 때만 true 로 보낸다. 자동으로 채우지 않는다
etxiv_dmnr_clsf_cdstring-N공급받는자 구분 코드 (01: 사업자)

예시 : 01

etxiv_knd_cdstring-N전자세금계산서 종류 코드 (01: 세금계산서)

예시 : 01

etxiv_mdf_rsn_cdstring-N수정사유코드. 04 계약의 해제(당초분 전액 음수 1장(계약 해제일)) - 계약 전부가 해제됐을 때만 씁니다(일부 해지는 공급가액 변동). 계약 해제일이 속한 달의 다음 달 10일까지 발급해야 하며, 넘기면 지연발급 가산세 대상입니다. / 06 착오에 의한 이중발급(당초분 전액 음수 1장(당초 작성일))
old_aprv_nostring-Y원본 세금계산서 승인번호 (24자리, 하이픈 포함 가능)
prepare_onlyboolean-N서명 방식. 비워 두거나 false 면 서버 서명으로 수정발행합니다. true(고객 PC 인증서 서명 준비)는 API Job · MCP 에서 받지 않습니다 - 준비 응답에 홈택스 세션 정보가 실립니다
supply_datestring8Y공급일자 ( 형식)

형식 : 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-modify-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "hometax",
  "action": "hometax.etax.invoice.modify",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "confirm": "<필수: boolean>",
    "etxiv_dmnr_clsf_cd": "01",
    "etxiv_knd_cd": "01",
    "old_aprv_no": "<필수>",
    "supply_date": "<필수>"
  }
}'
Response
  • 기관이 발행을 확인한 경우에만 성공합니다. result.data.outcome 은 CONFIRMED 이고, approval_number 에 국세청 승인번호가 담깁니다.
순번변수명설명
success발행 확인 여부. 성공 응답에서는 항상 true 입니다
outcome기관 처리 판정. 성공 응답에서는 항상 CONFIRMED 입니다
etan전자세금계산서 승인번호
message처리 결과 안내 문구
approval_number국세청이 발번한 승인번호(apprvNo). etan 과 같은 값입니다
issue_datetime발행 일시. 기관 응답에 없으면 빈 문자열입니다
result_code기관 판정 코드(resultMsg.result). 성공 응답에서는 S 입니다
issue_data기관의 최종 발행 응답 본문. 기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다
json
// result.data
{
  "success": true,
  "outcome": "CONFIRMED",
  "etan": "...",
  "message": "...",
  "approval_number": "...",
  "issue_datetime": "...",
  "result_code": "S",
  "issue_data": {}
}
순번오류 코드발생 조건
PROVIDER_OUTCOME_UNCONFIRMED처리 확인 불가 — 요청은 홈택스로 전송됐지만 처리됐는지 확인하지 못했습니다. 이미 처리됐을 수 있으므로 다시 요청하지 않고, 오류 메시지가 안내하는 홈택스 화면에서 먼저 확인합니다.
AUTH_REQUIRED세션 없음 — 홈택스 세션이 없습니다. 홈택스 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다.
PROVIDER_BUSINESS_ERROR업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다.
PROVIDER_VALIDATION_ERROR업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다.
PROVIDER_UNAVAILABLE업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다.
PROVIDER_UPSTREAM_ERROR업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다.