개발자 문서
API 레퍼런스

전자세금계산서 - 홈택스

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

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

MCP 도구 이름 hometax__etax__invoice__search_summary

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

현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.

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

  • 홈택스 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [홈택스 로그인(세션 생성)]
  • 조회 결과가 없으면 목록이 빈 배열로 돌아옵니다. 실패가 아닙니다.
  • params 는 빈 객체로 보내도 호출됩니다. 사용할 인증서는 account_link_id 로 지정합니다.

Request

순번변수명필수설명
AuthorizationYAPI 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다.

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

[참고] 인증

X-Env-ScopeY호출 환경입니다.
  • real_test데모 — 현재 데모 한도 확인 필요
  • 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조건부등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명이 하나뿐일 때만 그것이 자동으로 선택됩니다. 둘 이상이면 대표로 지정한 것이 있어도 고르지 않으므로 직접 지정해야 합니다. 대표는 묶음 상품이 기관마다 자격증명을 고를 때만 씁니다. 등록한 자격증명이 없거나 하나를 고르지 못하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다.

형식 : UUID v4

[참고] 자격증명 등록

paramsobject-N작업 파라미터입니다. 이 API 는 빈 객체로 호출할 수 있습니다.
encrypted_fieldsobject-N민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다.

[참고] 암호화

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

예시 : 01

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

형식 : YYYYMMDD

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

형식 : YYYYMMDD

monthstring-N월 (MM) - 월별 조회시 필수
page_sizenumber-N페이지당 조회건수

예시 : 10

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

예시 : 01

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: real_test' \
  --header "Idempotency-Key: search_summary-$(date +%s)-$RANDOM" \
  --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_size": 10,
    "search_type": "01"
  }
}'

Response

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

이 API 는 기관 응답 본문을 그대로 전달합니다. 고정 필드 목록이 없습니다.

json
// result.data — 홈택스 응답 본문이 담깁니다. 화면마다 키 구성이 다르고, 기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다.
{}
순번오류 코드발생 조건
VALIDATION_INVALID_FIELD요청 값 오류 — date_type 이 고른 날짜 방식에 필요한 칸(start_date, end_date, year, month, quarter 가운데 그 방식의 칸)이 비면 홈택스에 요청하지 않고 이 코드로 끝나며, 자동 재시도 대상이 아닙니다. error.message 가 빠진 값의 이름을 알려 주니 그 값을 넣어 다시 요청합니다.
VALIDATION_INVALID_FIELD숫자 값 오류 — page_size 에 1 이상의 정수가 아닌 값(0, 음수, 소수부가 있는 수, 숫자가 아닌 글자)을 보내면 홈택스에 요청하지 않고 이 코드로 끝나며, 자동 재시도 대상이 아닙니다. error.message 가 확인할 값의 이름을 알려 주니 그 값을 고쳐 다시 요청합니다. 숫자로 된 문자열도 받고, null 로 보내면 보내지 않은 것으로 보아 기본값을 씁니다.
AUTH_REQUIRED세션 없음 — 홈택스 세션이 없습니다. 홈택스 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다.
PROVIDER_BUSINESS_ERROR업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다.
PROVIDER_VALIDATION_ERROR업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다.
PROVIDER_UNAVAILABLE업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다.
PROVIDER_UPSTREAM_ERROR업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다.
PROVIDER_SESSION_EXPIRED세션 만료 — 조회하는 도중 홈택스 로그인 세션이 끝난 것을 알게 되면 이 코드로 끝나며, error.message 안내대로 로그인 액션을 다시 실행해 세션을 연 뒤 같은 요청을 다시 보냅니다.

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

MCP 도구 이름 hometax__etax__invoice__search_list

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

현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.

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

  • 홈택스 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [홈택스 로그인(세션 생성)]
  • 조회 결과가 없으면 목록이 빈 배열로 돌아옵니다. 실패가 아닙니다.

Request

순번변수명필수설명
AuthorizationYAPI 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다.

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

[참고] 인증

X-Env-ScopeY호출 환경입니다.
  • real_test데모 — 현재 데모 한도 확인 필요
  • 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조건부등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명이 하나뿐일 때만 그것이 자동으로 선택됩니다. 둘 이상이면 대표로 지정한 것이 있어도 고르지 않으므로 직접 지정해야 합니다. 대표는 묶음 상품이 기관마다 자격증명을 고를 때만 씁니다. 등록한 자격증명이 없거나 하나를 고르지 못하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다.

형식 : UUID v4

[참고] 자격증명 등록

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

[참고] 암호화

순번변수명타입길이필수설명
from_datestring8-10Y조회 시작일입니다. 별칭 inqr_dt_strt / trs_dt_rng_strt

형식 : YYYY-MM-DD 또는 YYYYMMDD

to_datestring8-10Y조회 종료일입니다. 홈택스가 6개월 이상의 기간은 조회하지 않으므로 더 긴 기간은 6개월보다 짧게 나눠 여러 번 부릅니다. 별칭 inqr_dt_end / trs_dt_rng_end

형식 : YYYY-MM-DD 또는 YYYYMMDD

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_strtstring8N조회 시작일

형식 : YYYYMMDD

예시 : 20251001

inqr_dt_endstring8N조회 종료일

형식 : YYYYMMDD

예시 : 20251031

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: real_test' \
  --header "Idempotency-Key: search_list-$(date +%s)-$RANDOM" \
  --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_strt": "20251001",
    "inqr_dt_end": "20251031",
    "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 은 빼고 전달합니다.
{}
순번오류 코드발생 조건
VALIDATION_INVALID_FIELD요청 값 오류 — 필수 값이 빠지면 홈택스에 요청하지 않고 이 코드로 끝나며, 자동 재시도 대상이 아닙니다. error.message 가 빠진 값의 이름을 알려 주니 그 값을 넣어 다시 요청합니다.
VALIDATION_INVALID_FIELD숫자 값 오류 — page_num, page_size 에 1 이상의 정수가 아닌 값(0, 음수, 소수부가 있는 수, 숫자가 아닌 글자)을 보내면 홈택스에 요청하지 않고 이 코드로 끝나며, 자동 재시도 대상이 아닙니다. error.message 가 확인할 값의 이름을 알려 주니 그 값을 고쳐 다시 요청합니다. 숫자로 된 문자열도 받고, null 로 보내면 보내지 않은 것으로 보아 기본값을 씁니다.
AUTH_REQUIRED세션 없음 — 홈택스 세션이 없습니다. 홈택스 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다.
PROVIDER_BUSINESS_ERROR업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다.
PROVIDER_VALIDATION_ERROR업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다.
PROVIDER_UNAVAILABLE업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다.
PROVIDER_UPSTREAM_ERROR업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다.
PROVIDER_SESSION_EXPIRED세션 만료 — 조회하는 도중 홈택스 로그인 세션이 끝난 것을 알게 되면 이 코드로 끝나며, error.message 안내대로 로그인 액션을 다시 실행해 세션을 연 뒤 같은 요청을 다시 보냅니다.

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

MCP 도구 이름 hometax__etax__invoice__search_statistics

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

현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.

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

  • 홈택스 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [홈택스 로그인(세션 생성)]
  • 조회 결과가 없으면 목록이 빈 배열로 돌아옵니다. 실패가 아닙니다.

Request

순번변수명필수설명
AuthorizationYAPI 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다.

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

[참고] 인증

X-Env-ScopeY호출 환경입니다.
  • real_test데모 — 현재 데모 한도 확인 필요
  • 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조건부등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명이 하나뿐일 때만 그것이 자동으로 선택됩니다. 둘 이상이면 대표로 지정한 것이 있어도 고르지 않으므로 직접 지정해야 합니다. 대표는 묶음 상품이 기관마다 자격증명을 고를 때만 씁니다. 등록한 자격증명이 없거나 하나를 고르지 못하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다.

형식 : UUID v4

[참고] 자격증명 등록

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

[참고] 암호화

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

예시 : 01

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

예시 : 01

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

예시 : 20251

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

예시 : 20254

page_numnumberN페이지 번호 (기본: 1)

예시 : 1

page_sizenumberN페이지당 조회건수 (기본: 10)

예시 : 10

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

예시 : 202509

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

예시 : 202510

bash
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_statistics-$(date +%s)-$RANDOM" \
  --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_strt": "20251",
    "ht_rtn_cd_end": "20254",
    "page_num": 1,
    "page_size": 10,
    "wrt_ym_strt": "202509",
    "wrt_ym_end": "202510"
  }
}'

Response

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

이 API 는 기관 응답 본문을 그대로 전달합니다. 고정 필드 목록이 없습니다.

json
// result.data — 홈택스 응답 본문이 담깁니다. 화면마다 키 구성이 다르고, 기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다.
{}
순번오류 코드발생 조건
VALIDATION_INVALID_FIELD요청 값 오류 — 필수 값이 빠지면 홈택스에 요청하지 않고 이 코드로 끝나며, 자동 재시도 대상이 아닙니다. error.message 가 빠진 값의 이름을 알려 주니 그 값을 넣어 다시 요청합니다.
VALIDATION_INVALID_FIELD숫자 값 오류 — page_num, page_size 에 1 이상의 정수가 아닌 값(0, 음수, 소수부가 있는 수, 숫자가 아닌 글자)을 보내면 홈택스에 요청하지 않고 이 코드로 끝나며, 자동 재시도 대상이 아닙니다. error.message 가 확인할 값의 이름을 알려 주니 그 값을 고쳐 다시 요청합니다. 숫자로 된 문자열도 받고, null 로 보내면 보내지 않은 것으로 보아 기본값을 씁니다.
AUTH_REQUIRED세션 없음 — 홈택스 세션이 없습니다. 홈택스 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다.
PROVIDER_BUSINESS_ERROR업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다.
PROVIDER_VALIDATION_ERROR업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다.
PROVIDER_UNAVAILABLE업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다.
PROVIDER_UPSTREAM_ERROR업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다.
PROVIDER_SESSION_EXPIRED세션 만료 — 조회하는 도중 홈택스 로그인 세션이 끝난 것을 알게 되면 이 코드로 끝나며, error.message 안내대로 로그인 액션을 다시 실행해 세션을 연 뒤 같은 요청을 다시 보냅니다.

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

MCP 도구 이름 hometax__etax__invoice__search_detail

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

현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.

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

  • 홈택스 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [홈택스 로그인(세션 생성)]
  • 조회 결과가 없으면 목록이 빈 배열로 돌아옵니다. 실패가 아닙니다.

Request

순번변수명필수설명
AuthorizationYAPI 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다.

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

[참고] 인증

X-Env-ScopeY호출 환경입니다.
  • real_test데모 — 현재 데모 한도 확인 필요
  • 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조건부등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명이 하나뿐일 때만 그것이 자동으로 선택됩니다. 둘 이상이면 대표로 지정한 것이 있어도 고르지 않으므로 직접 지정해야 합니다. 대표는 묶음 상품이 기관마다 자격증명을 고를 때만 씁니다. 등록한 자격증명이 없거나 하나를 고르지 못하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다.

형식 : UUID v4

[참고] 자격증명 등록

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

[참고] 암호화

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

예시 : 123456789012345678901234

bash
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_detail-$(date +%s)-$RANDOM" \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "hometax",
  "action": "hometax.etax.invoice.search_detail",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "etan": "123456789012345678901234"
  }
}'

Response

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

이 API 는 기관 응답 본문을 그대로 전달합니다. 고정 필드 목록이 없습니다.

json
// result.data — 홈택스 응답 본문이 담깁니다. 화면마다 키 구성이 다르고, 기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다.
{}
순번오류 코드발생 조건
VALIDATION_INVALID_FIELD요청 값 오류 — 필수 값이 빠지면 홈택스에 요청하지 않고 이 코드로 끝나며, 자동 재시도 대상이 아닙니다. error.message 가 빠진 값의 이름을 알려 주니 그 값을 넣어 다시 요청합니다.
AUTH_REQUIRED세션 없음 — 홈택스 세션이 없습니다. 홈택스 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다.
PROVIDER_BUSINESS_ERROR업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다.
PROVIDER_VALIDATION_ERROR업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다.
PROVIDER_UNAVAILABLE업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다.
PROVIDER_UPSTREAM_ERROR업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다.
PROVIDER_SESSION_EXPIRED세션 만료 — 조회하는 도중 홈택스 로그인 세션이 끝난 것을 알게 되면 이 코드로 끝나며, error.message 안내대로 로그인 액션을 다시 실행해 세션을 연 뒤 같은 요청을 다시 보냅니다.

5. 전자세금계산서 발행hometax.etax.invoice.issue

MCP 도구 이름 hometax__etax__invoice__issue

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

현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.

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

  • 홈택스 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [홈택스 로그인(세션 생성)]
  • 요청 거절(HTTP 400, 작업은 만들어지지 않음).
  • 요청 거절(HTTP 409, 작업은 만들어지지 않음).

Request

순번변수명필수설명
AuthorizationYAPI 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다.

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

[참고] 인증

X-Env-ScopeY호출 환경입니다.
  • real_test데모 — 현재 데모 한도 확인 필요
  • 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조건부등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명이 하나뿐일 때만 그것이 자동으로 선택됩니다. 둘 이상이면 대표로 지정한 것이 있어도 고르지 않으므로 직접 지정해야 합니다. 대표는 묶음 상품이 기관마다 자격증명을 고를 때만 씁니다. 등록한 자격증명이 없거나 하나를 고르지 못하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다.

형식 : UUID v4

[참고] 자격증명 등록

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

[참고] 암호화

순번변수명타입길이필수설명
bill_methodstring-Y청구방법 (01: 영수, 02: 청구)
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수량. 1 이상의 정수
item_unit_pricenumber-Y단가. 1 이상의 정수
splr_mpb_nostring-N공급자 종사업장번호(주사업장은 0)
splr_tinstring-N공급자 식별값(tin). 보통 입력하지 않습니다. 서버가 기관 응답과 로그인 세션에서 공급자 값을 채우고, 거기서 얻지 못할 때만 이 값을 씁니다
supply_datestring8Y공급일자

형식 : YYYYMMDD

confirmation_tokenstring-N1회용 확인 토큰입니다. 처음에는 보내지 않습니다. 토큰 없이 부르면 기관에 아무것도 보내지 않고 작업도 만들지 않은 채 확인이 필요하다는 오류(WRITE_CONFIRMATION_REQUIRED)로 끝나고, 응답의 error.confirmation_token 에 토큰이 옵니다. error.message 의 안내를 사용자에게 보여 주고 동의를 받은 뒤 같은 요청에 이 토큰을 넣어 다시 부릅니다. 토큰은 10분 안에 한 번만 쓸 수 있고 처음 요청과 같은 본문, 같은 호출자, 같은 환경에서만 맞으며, 아니면 확인이 만료됐거나 내용이 달라졌다는 오류로 거절합니다
  • 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
bash
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-$(date +%s)-$RANDOM" \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "hometax",
  "action": "hometax.etax.invoice.issue",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "bill_method": "<필수>",
    "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 에 국세청 승인번호가 담깁니다.
  • 여러 JSON 타입이 함께 표시된 칸은 서버가 세부 타입을 고정하지 않는 기관 원문 또는 동적 값입니다.
순번변수명타입설명
successboolean발행 확인 여부. 성공 응답에서는 항상 true 입니다
outcomestring기관 처리 판정. 성공 응답에서는 항상 confirmed 입니다
etanstring | number | boolean | object | array | null전자세금계산서 승인번호
messagestring처리 결과 안내 문구
approval_numberstring국세청이 발번한 승인번호(apprvNo). etan 과 같은 값입니다
issue_datetimestring발행 일시. 기관 응답에 없으면 빈 문자열입니다
result_codestring기관 판정 코드(resultMsg.result). 성공 응답에서는 S 입니다
issue_datastring | number | boolean | object | array | null기관의 최종 발행 응답 본문. 기관 세션 정보 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홈택스 통신 오류 — 홈택스가 오류로 답하거나 연결이 끊겨 요청이 처리됐는지 알 수 없을 수 있으니, 다시 요청하기 전에 홈택스 화면에서 먼저 확인합니다. 홈택스가 오류 응답을 보내거나 연결이 끊긴 경우 error.message 는 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')입니다.
PROVIDER_UPSTREAM_ERROR홈택스 통신 오류 — 홈택스가 오류로 답하거나 연결이 끊겨 요청이 처리됐는지 알 수 없을 수 있으니, 다시 요청하기 전에 홈택스 화면에서 먼저 확인합니다. 홈택스가 오류 응답을 보내거나 연결이 끊긴 경우 error.message 는 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')입니다.
PROVIDER_UNAVAILABLE홈택스 통신 오류 — 홈택스가 오류로 답하거나 연결이 끊겨 요청이 처리됐는지 알 수 없을 수 있으니, 다시 요청하기 전에 홈택스 화면에서 먼저 확인합니다. 홈택스가 오류 응답을 보내거나 연결이 끊긴 경우 error.message 는 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')입니다.

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

MCP 도구 이름 hometax__etax__invoice__modify

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

현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.

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

  • 홈택스 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [홈택스 로그인(세션 생성)]
  • 요청 거절(HTTP 400, 작업은 만들어지지 않음).
  • 요청 거절(HTTP 409, 작업은 만들어지지 않음).

Request

순번변수명필수설명
AuthorizationYAPI 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다.

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

[참고] 인증

X-Env-ScopeY호출 환경입니다.
  • real_test데모 — 현재 데모 한도 확인 필요
  • 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조건부등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명이 하나뿐일 때만 그것이 자동으로 선택됩니다. 둘 이상이면 대표로 지정한 것이 있어도 고르지 않으므로 직접 지정해야 합니다. 대표는 묶음 상품이 기관마다 자격증명을 고를 때만 씁니다. 등록한 자격증명이 없거나 하나를 고르지 못하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다.

형식 : UUID v4

[참고] 자격증명 등록

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

[참고] 암호화

순번변수명타입길이필수설명
etxiv_dmnr_clsf_cdstring-N공급받는자 구분 코드. 보내도 쓰지 않으며 원본 세금계산서의 값을 씁니다

예시 : 01

etxiv_knd_cdstring-N전자세금계산서 종류 코드. 보내도 쓰지 않으며 원본 세금계산서의 값을 씁니다

예시 : 01

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

형식 : YYYYMMDD

confirmation_tokenstring-N1회용 확인 토큰입니다. 처음에는 보내지 않습니다. 토큰 없이 부르면 기관에 아무것도 보내지 않고 작업도 만들지 않은 채 확인이 필요하다는 오류(WRITE_CONFIRMATION_REQUIRED)로 끝나고, 응답의 error.confirmation_token 에 토큰이 옵니다. error.message 의 안내를 사용자에게 보여 주고 동의를 받은 뒤 같은 요청에 이 토큰을 넣어 다시 부릅니다. 토큰은 10분 안에 한 번만 쓸 수 있고 처음 요청과 같은 본문, 같은 호출자, 같은 환경에서만 맞으며, 아니면 확인이 만료됐거나 내용이 달라졌다는 오류로 거절합니다
  • 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
bash
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.etax.invoice.modify",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "etxiv_dmnr_clsf_cd": "01",
    "etxiv_knd_cd": "01",
    "etxiv_mdf_rsn_cd": "<필수>",
    "old_aprv_no": "<필수>",
    "supply_date": "<필수>"
  }
}'

Response

  • 기관이 발행을 확인한 경우에만 성공합니다. result.data.outcome 은 confirmed 이고, approval_number 에 국세청 승인번호가 담깁니다.
  • 여러 JSON 타입이 함께 표시된 칸은 서버가 세부 타입을 고정하지 않는 기관 원문 또는 동적 값입니다.
순번변수명타입설명
successboolean발행 확인 여부. 성공 응답에서는 항상 true 입니다
outcomestring기관 처리 판정. 성공 응답에서는 항상 confirmed 입니다
etanstring | number | boolean | object | array | null전자세금계산서 승인번호
messagestring처리 결과 안내 문구
approval_numberstring국세청이 발번한 승인번호(apprvNo). etan 과 같은 값입니다
issue_datetimestring발행 일시. 기관 응답에 없으면 빈 문자열입니다
result_codestring기관 판정 코드(resultMsg.result). 성공 응답에서는 S 입니다
issue_datastring | number | boolean | object | array | null기관의 최종 발행 응답 본문. 기관 세션 정보 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홈택스 통신 오류 — 홈택스가 오류로 답하거나 연결이 끊겨 요청이 처리됐는지 알 수 없을 수 있으니, 다시 요청하기 전에 홈택스 화면에서 먼저 확인합니다. 홈택스가 오류 응답을 보내거나 연결이 끊긴 경우 error.message 는 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')입니다.
PROVIDER_UPSTREAM_ERROR홈택스 통신 오류 — 홈택스가 오류로 답하거나 연결이 끊겨 요청이 처리됐는지 알 수 없을 수 있으니, 다시 요청하기 전에 홈택스 화면에서 먼저 확인합니다. 홈택스가 오류 응답을 보내거나 연결이 끊긴 경우 error.message 는 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')입니다.
PROVIDER_UNAVAILABLE홈택스 통신 오류 — 홈택스가 오류로 답하거나 연결이 끊겨 요청이 처리됐는지 알 수 없을 수 있으니, 다시 요청하기 전에 홈택스 화면에서 먼저 확인합니다. 홈택스가 오류 응답을 보내거나 연결이 끊긴 경우 error.message 는 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')입니다.

7. 전자세금계산서 공급자 정보 조회hometax.etax.business_info.get

MCP 도구 이름 hometax__etax__business_info__get

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

현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.

전자세금계산서 발급 화면에 쓰이는 공급자 정보와, 이 사업자가 계산서를 발급할 수 있는 유형인지 조회합니다.

Request

순번변수명필수설명
AuthorizationYAPI 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다.

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

[참고] 인증

X-Env-ScopeY호출 환경입니다.
  • real_test데모 — 현재 데모 한도 확인 필요
  • production정식 — 현재 공개 요금제 전용

[참고] 환경

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

[참고] 재시도

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

예시 : hometax

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

예시 : hometax.etax.business_info.get

account_link_idstring36조건부등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명이 하나뿐일 때만 그것이 자동으로 선택됩니다. 둘 이상이면 대표로 지정한 것이 있어도 고르지 않으므로 직접 지정해야 합니다. 대표는 묶음 상품이 기관마다 자격증명을 고를 때만 씁니다. 등록한 자격증명이 없거나 하나를 고르지 못하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다.

형식 : UUID v4

[참고] 자격증명 등록

paramsobject-N작업 파라미터입니다. 이 API 는 빈 객체로 호출할 수 있습니다.
encrypted_fieldsobject-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: real_test' \
  --header "Idempotency-Key: get-$(date +%s)-$RANDOM" \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "hometax",
  "action": "hometax.etax.business_info.get",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {}
}'

Response

  • 이 API 가 돌려주는 데이터: 상호, 대표자명, 업태, 종목, 사업장 주소, 이메일, 사업자 구분, 납세자 상태, 간이과세자 세금계산서 발급 구분, 발급 불가 면세사업자 여부, 법인 연락사무소 여부
  • 응답 예시는 작업을 제출했을 때(POST /v1/jobs)의 응답이고, 결과는 작업이 SUCCEEDED 가 된 뒤 GET /v1/jobs/{job_id}/result 의 result.data 로 옵니다.

이 API 는 기관 응답 본문을 그대로 전달합니다. 고정 필드 목록이 없습니다.

json
{
    "job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
    "status": "QUEUED",
    "env_scope": "real_test",
    "provider": "hometax",
    "action": "hometax.etax.business_info.get",
    "submitted_at": "2026-05-27T12:34:56+09:00"
}
순번오류 코드발생 조건
AUTH_REQUIRED저장된 기관 세션이 없습니다. 같은 연동 계정으로 hometax.session.login 을 먼저 실행해 세션을 연 뒤 다시 보냅니다.
PROVIDER_SESSION_EXPIRED기관 세션이 만료됐습니다. 같은 연동 계정으로 hometax.session.login 을 다시 실행해 세션을 연 뒤 다시 보냅니다.
PROVIDER_BUSINESS_ERROR홈택스가 응답 봉투의 결과(resultMsg.result)를 비어 있지도 S 도 아닌 값으로 돌려주면 이 오류로 끝납니다. error.message 는 홈택스가 알려 준 사유이고, 사유를 주지 않으면 「기관이 요청을 처리하지 않았습니다. 사유는 알려 주지 않았습니다. 입력값을 그대로 두고 잠시 후 다시 시도해 주세요.」 입니다.
PROVIDER_UNAVAILABLE홈택스가 서비스 중지 시간이라고 답한 경우입니다. 값이 틀린 것이 아니라 시간의 문제이고 요청은 처리되지 않았습니다. error.message 는 중지 시간을 읽었으면 그 시간을 함께 알리고, 읽지 못했으면 「지금은 홈택스 서비스 중지 시간이라 요청이 처리되지 않았습니다. 중지 시간이 지난 뒤 다시 요청해 주세요.」 입니다.

8. 전자세금계산서 거래처 정보 조회hometax.etax.client_info.get

MCP 도구 이름 hometax__etax__client_info__get

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

현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.

전자세금계산서 발급 화면에 등록해 둔 거래처의 사업자번호와 상호, 대표자, 담당자 이메일을 한 번에 받아옵니다.

Request

순번변수명필수설명
AuthorizationYAPI 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다.

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

[참고] 인증

X-Env-ScopeY호출 환경입니다.
  • real_test데모 — 현재 데모 한도 확인 필요
  • production정식 — 현재 공개 요금제 전용

[참고] 환경

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

[참고] 재시도

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

예시 : hometax

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

예시 : hometax.etax.client_info.get

account_link_idstring36조건부등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명이 하나뿐일 때만 그것이 자동으로 선택됩니다. 둘 이상이면 대표로 지정한 것이 있어도 고르지 않으므로 직접 지정해야 합니다. 대표는 묶음 상품이 기관마다 자격증명을 고를 때만 씁니다. 등록한 자격증명이 없거나 하나를 고르지 못하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다.

형식 : UUID v4

[참고] 자격증명 등록

paramsobject-N작업 파라미터입니다. 이 API 는 빈 객체로 호출할 수 있습니다.
encrypted_fieldsobject-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: real_test' \
  --header "Idempotency-Key: get-$(date +%s)-$RANDOM" \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "hometax",
  "action": "hometax.etax.client_info.get",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {}
}'

Response

  • 아래 표의 칸은 작업이 SUCCEEDED 가 된 뒤 GET /v1/jobs/{job_id}/result 의 result.data 에 오고, 응답 예시는 작업을 제출했을 때(POST /v1/jobs)의 응답입니다.
  • 이 API 가 돌려주는 데이터: 거래처 사업자번호, 종사업장 번호, 상호, 대표자명, 업태, 종목, 주소, 주 담당자 이메일, 부 담당자 이메일, 주 거래처 여부, 거래처 상태, 등록 일자와 변경 일자
순번변수명타입설명
itemsarray전자세금계산서 발급 화면에 등록해 둔 거래처 행의 목록입니다. 등록된 거래처가 없으면 빈 배열입니다. 행의 칸 이름과 값은 홈택스가 정하므로 이 문서가 보장하지 않습니다(기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다).
json
{
    "job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
    "status": "QUEUED",
    "env_scope": "real_test",
    "provider": "hometax",
    "action": "hometax.etax.client_info.get",
    "submitted_at": "2026-05-27T12:34:56+09:00"
}
순번오류 코드발생 조건
AUTH_REQUIRED저장된 기관 세션이 없습니다. 같은 연동 계정으로 hometax.session.login 을 먼저 실행해 세션을 연 뒤 다시 보냅니다.
PROVIDER_SESSION_EXPIRED기관 세션이 만료됐습니다. 같은 연동 계정으로 hometax.session.login 을 다시 실행해 세션을 연 뒤 다시 보냅니다.
PROVIDER_BUSINESS_ERROR홈택스가 거래처 조회를 거절하면(응답 봉투의 resultMsg.result 가 비어 있지도 S 도 아닌 값) 빈 목록으로 돌려주지 않고 이 오류로 끝납니다. error.message 는 홈택스가 알려 준 사유이고, 사유를 주지 않으면 「기관이 요청을 처리하지 않았습니다. 사유는 알려 주지 않았습니다. 입력값을 그대로 두고 잠시 후 다시 시도해 주세요.」 입니다.
PROVIDER_UNAVAILABLE홈택스가 서비스 중지 시간이라고 답한 경우입니다. 값이 틀린 것이 아니라 시간의 문제이고 요청은 처리되지 않았습니다. error.message 는 중지 시간을 읽었으면 그 시간을 함께 알리고, 읽지 못했으면 「지금은 홈택스 서비스 중지 시간이라 요청이 처리되지 않았습니다. 중지 시간이 지난 뒤 다시 요청해 주세요.」 입니다.