전자세금계산서 - 홈택스
전자세금계산서를 발행·수정하고 목록·상세·합계·통계를 조회합니다.
1. 전자세금계산서 합계표 조회hometax. etax. invoice. search_ summary
MCP 도구 이름 hometax__
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
전자세금계산서 합계표 조회합니다.
- 홈택스 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [홈택스 로그인(세션 생성)]
- 조회 결과가 없으면 목록이 빈 배열로 돌아옵니다. 실패가 아닙니다.
Request
| 순번 | 변수명 | 필수 | 설명 |
|---|---|---|---|
| Authorization | Y | API 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다. | |
| X- | Y | 호출 환경입니다.
| |
| Idempotency- | Y | 재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다. | |
| Content- | Y | 요청 본문 형식입니다.
| |
| X- | N | 추적 아이디입니다. 지정하지 않으면 서버가 발급합니다. |
| 순번 | 변수명 | 타입 | 길이 | 필수 | 설명 |
|---|---|---|---|---|---|
| provider | string | - | Y | 호출할 기관입니다.
| |
| action | string | - | Y | 호출할 작업입니다.
| |
| account_ | string | 36 | 조건부 | 등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명 중 대표로 지정한 것이 쓰입니다. 대표가 없으면 등록한 자격증명이 하나뿐일 때만 자동으로 선택되고, 둘 이상이면 직접 지정해야 합니다. 등록한 자격증명이 없거나 하나를 고르지 못하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다. | |
| params | object | - | Y | 작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다. | |
| encrypted_ | object | - | N | 민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 길이 | 필수 | 설명 |
|---|---|---|---|---|---|
| date_ | string | - | N | 작성일자 구분 (01=일자별, 02=월별, 03=분기별) | |
| start_ | string | 8 | N | 시작일 - 일자별 조회시 필수 | |
| end_ | string | 8 | N | 종료일 - 일자별 조회시 필수 | |
| month | string | - | N | 월 (MM) - 월별 조회시 필수 | |
| page_ | number | - | N | 페이지 번호 | |
| page_ | number | - | N | 페이지당 조회건수 | |
| quarter | string | - | N | 분기 (1~6) - 분기별 조회시 필수 | |
| search_ | string | - | N | 조회 구분 (01=매출, 02=매입) | |
| year | string | 4 | N | 연도 - 월별/분기별 조회시 필수 |
curl --request POST \
--url 'https://api.xdata.kr/v1/jobs' \
--header 'Authorization: Basic {base64(client_id:client_secret)}' \
--header 'X-Env-Scope: real_test' \
--header 'Idempotency-Key: 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 는 기관 응답 본문을 그대로 전달합니다. 고정 필드 목록이 없습니다.
// result.data — 홈택스 응답 본문이 담깁니다. 화면마다 키 구성이 다르고, 기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다.
{}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| AUTH_ | 세션 없음 — 홈택스 세션이 없습니다. 홈택스 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다. | |
| PROVIDER_ | 업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다. | |
| PROVIDER_ | 업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다. | |
| PROVIDER_ | 업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다. | |
| PROVIDER_ | 업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다. |
2. 전자세금계산서 목록 조회hometax. etax. invoice. search_ list
MCP 도구 이름 hometax__
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
전자세금계산서 목록을 기간으로 조회합니다.
- 홈택스 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [홈택스 로그인(세션 생성)]
- 조회 결과가 없으면 목록이 빈 배열로 돌아옵니다. 실패가 아닙니다.
Request
| 순번 | 변수명 | 필수 | 설명 |
|---|---|---|---|
| Authorization | Y | API 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다. | |
| X- | Y | 호출 환경입니다.
| |
| Idempotency- | Y | 재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다. | |
| Content- | Y | 요청 본문 형식입니다.
| |
| X- | N | 추적 아이디입니다. 지정하지 않으면 서버가 발급합니다. |
| 순번 | 변수명 | 타입 | 길이 | 필수 | 설명 |
|---|---|---|---|---|---|
| provider | string | - | Y | 호출할 기관입니다.
| |
| action | string | - | Y | 호출할 작업입니다.
| |
| account_ | string | 36 | 조건부 | 등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명 중 대표로 지정한 것이 쓰입니다. 대표가 없으면 등록한 자격증명이 하나뿐일 때만 자동으로 선택되고, 둘 이상이면 직접 지정해야 합니다. 등록한 자격증명이 없거나 하나를 고르지 못하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다. | |
| params | object | - | Y | 작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다. | |
| encrypted_ | object | - | N | 민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 길이 | 필수 | 설명 |
|---|---|---|---|---|---|
| from_ | string | - | Y | 조회 시작일입니다. 별칭 inqr_dt_strt / trs_dt_rng_strt | |
| to_ | string | - | Y | 조회 종료일입니다. 별칭 inqr_dt_end / trs_dt_rng_end | |
| bman_ | string | - | N | 공급받는자 등록번호 구분 (00=전체, 01=사업자, 02=주민, 03=외국인) | |
| dmnr_ | string | - | N | 공급받는자 종사업장번호 | |
| dmnr_ | string | - | N | 공급받는자 등록번호 (매출 조회시, 하이픈 포함/미포함 모두 가능) | |
| dt_ | string | - | N | 조회기간 구분 (01=작성일자, 02=발급일자, 03=전송일자) | |
| etxiv_ | string | - | N | 전자세금계산서 분류 (01=건별, 02=위수탁) | |
| etxiv_ | string | - | N | 전자세금계산서 종류 (all=전체, 01=일반, 02=영세율, 03=위수탁, 04=수입, 05=위수탁영세율, 06=수입납부유예) | |
| inqr_ | string | 8 | N | 조회 시작일 | |
| inqr_ | string | 8 | N | 조회 종료일 | |
| isn_ | string | - | N | 발급유형 (all=전체, 10=인터넷발급, 20=ARS발급, 30=VAN발급, 41=ASP발급, 42=자체발급, 50=겸용서식발급, 70=모바일발급, 90=대리발급) | |
| page_ | number | - | N | 페이지 번호 (기본: 1) | |
| page_ | number | - | N | 페이지당 조회건수 (기본: 10) | |
| prh_ | string | - | N | 매출/매입 구분 (01=매출, 02=매입) | |
| resno_ | string | - | N | 주민번호 마스킹 여부 (Y/N) | |
| splr_ | string | - | N | 공급자 종사업장번호 | |
| splr_ | string | - | N | 공급자 등록번호 (매입 조회시, 하이픈 포함/미포함 모두 가능) | |
| srt_ | string | - | N | 정렬 기준 (1=작성일자, 2=승인번호, 3=발급일자, 4=전송일자, 5=사업자등록번호, 6=상호, 7=대표자명, 8=합계금액, 9=공급가액, 10=세액) | |
| srt_ | string | - | N | 정렬 방식 (01=내림차순, 02=오름차순) | |
| tnm_ | string | - | N | 상호 |
curl --request POST \
--url 'https://api.xdata.kr/v1/jobs' \
--header 'Authorization: Basic {base64(client_id:client_secret)}' \
--header 'X-Env-Scope: real_test' \
--header 'Idempotency-Key: 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_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 는 기관 응답 본문을 그대로 전달합니다. 고정 필드 목록이 없습니다.
// result.data — 홈택스 응답 본문이 담깁니다. 화면마다 키 구성이 다르고, 기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다.
{}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| AUTH_ | 세션 없음 — 홈택스 세션이 없습니다. 홈택스 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다. | |
| PROVIDER_ | 업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다. | |
| PROVIDER_ | 업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다. | |
| PROVIDER_ | 업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다. | |
| PROVIDER_ | 업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다. |
3. 전자세금계산서 통계 조회hometax. etax. invoice. search_ statistics
MCP 도구 이름 hometax__
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
전자세금계산서 통계 조회합니다.
- 홈택스 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [홈택스 로그인(세션 생성)]
- 조회 결과가 없으면 목록이 빈 배열로 돌아옵니다. 실패가 아닙니다.
Request
| 순번 | 변수명 | 필수 | 설명 |
|---|---|---|---|
| Authorization | Y | API 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다. | |
| X- | Y | 호출 환경입니다.
| |
| Idempotency- | Y | 재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다. | |
| Content- | Y | 요청 본문 형식입니다.
| |
| X- | N | 추적 아이디입니다. 지정하지 않으면 서버가 발급합니다. |
| 순번 | 변수명 | 타입 | 길이 | 필수 | 설명 |
|---|---|---|---|---|---|
| provider | string | - | Y | 호출할 기관입니다.
| |
| action | string | - | Y | 호출할 작업입니다.
| |
| account_ | string | 36 | 조건부 | 등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명 중 대표로 지정한 것이 쓰입니다. 대표가 없으면 등록한 자격증명이 하나뿐일 때만 자동으로 선택되고, 둘 이상이면 직접 지정해야 합니다. 등록한 자격증명이 없거나 하나를 고르지 못하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다. | |
| params | object | - | Y | 작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다. | |
| encrypted_ | object | - | N | 민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| dt_ | string | N | 조회기간 구분 (01=월별, 02=분기별, 03=년도별, 기본: 01) | |
| etxiv_ | string | N | 전자세금계산서 분류 (01=전자세금계산서, 03=전자계산서, 기본: 01) | |
| ht_ | string | N | 분기 시작 코드 (분기별 조회시만 사용 = 2025년 1기 예정) | |
| ht_ | string | N | 분기 종료 코드 (분기별 조회시만 사용 = 2025년 2기 확정) | |
| page_ | number | N | 페이지 번호 (기본: 1) | |
| page_ | number | N | 페이지당 조회건수 (기본: 10) | |
| wrt_ | string | Y | 작성년월 시작 (월별: YYYYMM, 분기별: YYYY+분기코드, 년도별: YYYY) | |
| wrt_ | string | Y | 작성년월 종료 (월별: YYYYMM, 분기별: YYYY+분기코드, 년도별: YYYY) |
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: 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_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 는 기관 응답 본문을 그대로 전달합니다. 고정 필드 목록이 없습니다.
// result.data — 홈택스 응답 본문이 담깁니다. 화면마다 키 구성이 다르고, 기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다.
{}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| AUTH_ | 세션 없음 — 홈택스 세션이 없습니다. 홈택스 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다. | |
| PROVIDER_ | 업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다. | |
| PROVIDER_ | 업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다. | |
| PROVIDER_ | 업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다. | |
| PROVIDER_ | 업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다. |
4. 전자세금계산서 상세 조회hometax. etax. invoice. search_ detail
MCP 도구 이름 hometax__
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
전자세금계산서 상세 조회합니다.
- 홈택스 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [홈택스 로그인(세션 생성)]
- 조회 결과가 없으면 목록이 빈 배열로 돌아옵니다. 실패가 아닙니다.
Request
| 순번 | 변수명 | 필수 | 설명 |
|---|---|---|---|
| Authorization | Y | API 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다. | |
| X- | Y | 호출 환경입니다.
| |
| Idempotency- | Y | 재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다. | |
| Content- | Y | 요청 본문 형식입니다.
| |
| X- | N | 추적 아이디입니다. 지정하지 않으면 서버가 발급합니다. |
| 순번 | 변수명 | 타입 | 길이 | 필수 | 설명 |
|---|---|---|---|---|---|
| provider | string | - | Y | 호출할 기관입니다.
| |
| action | string | - | Y | 호출할 작업입니다.
| |
| account_ | string | 36 | 조건부 | 등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명 중 대표로 지정한 것이 쓰입니다. 대표가 없으면 등록한 자격증명이 하나뿐일 때만 자동으로 선택되고, 둘 이상이면 직접 지정해야 합니다. 등록한 자격증명이 없거나 하나를 고르지 못하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다. | |
| params | object | - | Y | 작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다. | |
| encrypted_ | object | - | N | 민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| etan | string | Y | 승인번호 (24자리 영숫자, 하이픈 포함/미포함 모두 가능) |
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: 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": "123456789012345678901234"
}
}'Response
- result.data 에 담긴 홈택스 응답 본문을 확인합니다.
- result.data 에는 홈택스가 내려준 응답 본문이 담깁니다. 화면마다 키 구성이 다르고, 기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다.
이 API 는 기관 응답 본문을 그대로 전달합니다. 고정 필드 목록이 없습니다.
// result.data — 홈택스 응답 본문이 담깁니다. 화면마다 키 구성이 다르고, 기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다.
{}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| AUTH_ | 세션 없음 — 홈택스 세션이 없습니다. 홈택스 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다. | |
| PROVIDER_ | 업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다. | |
| PROVIDER_ | 업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다. | |
| PROVIDER_ | 업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다. | |
| PROVIDER_ | 업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다. |
5. 전자세금계산서 발행hometax. etax. invoice. issue
MCP 도구 이름 hometax__
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
전자세금계산서 발행합니다. 응답을 받지 못해 다시 보낼 때는 같은 Idempotency-Key를 씁니다.
- 홈택스 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [홈택스 로그인(세션 생성)]
Request
| 순번 | 변수명 | 필수 | 설명 |
|---|---|---|---|
| Authorization | Y | API 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다. | |
| X- | Y | 호출 환경입니다.
| |
| Idempotency- | Y | 재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다. | |
| Content- | Y | 요청 본문 형식입니다.
| |
| X- | N | 추적 아이디입니다. 지정하지 않으면 서버가 발급합니다. |
| 순번 | 변수명 | 타입 | 길이 | 필수 | 설명 |
|---|---|---|---|---|---|
| provider | string | - | Y | 호출할 기관입니다.
| |
| action | string | - | Y | 호출할 작업입니다.
| |
| account_ | string | 36 | 조건부 | 등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명 중 대표로 지정한 것이 쓰입니다. 대표가 없으면 등록한 자격증명이 하나뿐일 때만 자동으로 선택되고, 둘 이상이면 직접 지정해야 합니다. 등록한 자격증명이 없거나 하나를 고르지 못하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다. | |
| params | object | - | Y | 작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다. | |
| encrypted_ | object | - | N | 민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 길이 | 필수 | 설명 |
|---|---|---|---|---|---|
| bill_ | string | - | Y | 청구방법 (01: 영수, 02: 청구) | |
| confirm | boolean | - | Y | 발행 확인. 사용자에게 발행 내용을 보여주고 동의를 받았을 때만 true 로 보낸다. 자동으로 채우지 않는다 | |
| dmnr_ | string | - | Y | 공급받는자 사업자번호 | |
| etxiv_ | string | - | N | 전자세금계산서 구분 코드 | |
| etxiv_ | string | - | N | 전자세금계산서 공급받는자 구분 코드 | |
| etxiv_ | string | - | N | 전자세금계산서 종류 코드 | |
| item_ | string | - | Y | 품명 | |
| item_ | number | - | Y | 수량 | |
| item_ | number | - | Y | 단가 | |
| splr_ | string | - | N | 공급자 종사업장번호(주사업장은 0) | |
| splr_ | string | - | N | 공급자 세무서 번호 | |
| supply_ | string | 8 | Y | 공급일자 |
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: 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 에 국세청 승인번호가 담깁니다.
- 여러 JSON 타입이 함께 표시된 칸은 서버가 세부 타입을 고정하지 않는 기관 원문 또는 동적 값입니다.예시 값의 타입으로 단정하지 말고 실제 값의 타입을 확인해 주세요. null은 값이 비어 있다는 뜻이며, 필드 자체의 생략 여부는 필수 여부와 설명을 확인해 주세요.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| success | boolean | 발행 확인 여부. 성공 응답에서는 항상 true 입니다 | |
| outcome | string | 기관 처리 판정. 성공 응답에서는 항상 confirmed 입니다 | |
| etan | string | number | boolean | object | array | null | 전자세금계산서 승인번호 | |
| message | string | 처리 결과 안내 문구 | |
| approval_ | string | 국세청이 발번한 승인번호(apprvNo). etan 과 같은 값입니다 | |
| issue_ | string | 발행 일시. 기관 응답에 없으면 빈 문자열입니다 | |
| result_ | string | 기관 판정 코드(resultMsg.result). 성공 응답에서는 S 입니다 | |
| issue_ | string | number | boolean | object | array | null | 기관의 최종 발행 응답 본문. 기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다 |
// result.data
{
"success": true,
"outcome": "confirmed",
"etan": "...",
"message": "...",
"approval_number": "...",
"issue_datetime": "...",
"result_code": "S",
"issue_data": {}
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| PROVIDER_ | 처리 확인 불가 — 요청은 홈택스로 전송됐지만 처리됐는지 확인하지 못했습니다. 이미 처리됐을 수 있으므로 다시 요청하지 않고, 오류 메시지가 안내하는 홈택스 화면에서 먼저 확인합니다. | |
| AUTH_ | 세션 없음 — 홈택스 세션이 없습니다. 홈택스 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다. | |
| PROVIDER_ | 업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다. | |
| PROVIDER_ | 홈택스 통신 오류 — 홈택스가 오류로 답하거나 연결이 끊겨 요청이 처리됐는지 알 수 없을 수 있으니, 다시 요청하기 전에 홈택스 화면에서 먼저 확인합니다. 홈택스가 오류 응답을 보내거나 연결이 끊긴 경우 error.message 는 결과 확인 불가 안내('요청은 기관에 전송됐지만 처리 결과를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')입니다. | |
| PROVIDER_ | 홈택스 통신 오류 — 홈택스가 오류로 답하거나 연결이 끊겨 요청이 처리됐는지 알 수 없을 수 있으니, 다시 요청하기 전에 홈택스 화면에서 먼저 확인합니다. 홈택스가 오류 응답을 보내거나 연결이 끊긴 경우 error.message 는 결과 확인 불가 안내('요청은 기관에 전송됐지만 처리 결과를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')입니다. | |
| PROVIDER_ | 홈택스 통신 오류 — 홈택스가 오류로 답하거나 연결이 끊겨 요청이 처리됐는지 알 수 없을 수 있으니, 다시 요청하기 전에 홈택스 화면에서 먼저 확인합니다. 홈택스가 오류 응답을 보내거나 연결이 끊긴 경우 error.message 는 결과 확인 불가 안내('요청은 기관에 전송됐지만 처리 결과를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')입니다. |
6. 전자세금계산서 수정·취소hometax. etax. invoice. modify
MCP 도구 이름 hometax__
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
전자세금계산서 수정·취소합니다. 응답을 받지 못해 다시 보낼 때는 같은 Idempotency-Key를 씁니다.
- 홈택스 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [홈택스 로그인(세션 생성)]
Request
| 순번 | 변수명 | 필수 | 설명 |
|---|---|---|---|
| Authorization | Y | API 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다. | |
| X- | Y | 호출 환경입니다.
| |
| Idempotency- | Y | 재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다. | |
| Content- | Y | 요청 본문 형식입니다.
| |
| X- | N | 추적 아이디입니다. 지정하지 않으면 서버가 발급합니다. |
| 순번 | 변수명 | 타입 | 길이 | 필수 | 설명 |
|---|---|---|---|---|---|
| provider | string | - | Y | 호출할 기관입니다.
| |
| action | string | - | Y | 호출할 작업입니다.
| |
| account_ | string | 36 | 조건부 | 등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명 중 대표로 지정한 것이 쓰입니다. 대표가 없으면 등록한 자격증명이 하나뿐일 때만 자동으로 선택되고, 둘 이상이면 직접 지정해야 합니다. 등록한 자격증명이 없거나 하나를 고르지 못하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다. | |
| params | object | - | Y | 작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다. | |
| encrypted_ | object | - | N | 민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 길이 | 필수 | 설명 |
|---|---|---|---|---|---|
| confirm | boolean | - | Y | 수정발급 확인. 사용자에게 수정 내용을 보여주고 동의를 받았을 때만 true 로 보낸다. 자동으로 채우지 않는다 | |
| etxiv_ | string | - | N | 공급받는자 구분 코드 (01: 사업자) | |
| etxiv_ | string | - | N | 전자세금계산서 종류 코드 (01: 세금계산서) | |
| etxiv_ | string | - | Y | 수정사유코드. 04 계약의 해제(당초분 전액 음수 1장(계약 해제일)) - 계약 전부가 해제됐을 때만 씁니다(일부 해지는 공급가액 변동). 계약 해제일이 속한 달의 다음 달 10일까지 발급해야 하며, 넘기면 지연발급 가산세 대상입니다. / 06 착오에 의한 이중발급(당초분 전액 음수 1장(당초 작성일)) | |
| old_ | string | - | Y | 원본 세금계산서 승인번호 (24자리, 하이픈 포함 가능) | |
| prepare_ | boolean | - | N | 서명 방식. 비워 두거나 false 면 서버 서명으로 수정발행합니다. true(고객 PC 인증서 서명 준비)는 API · MCP 에서 받지 않습니다 - 준비 응답에 홈택스 세션 정보가 실립니다 | |
| supply_ | string | 8 | Y | 공급일자 |
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: 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",
"etxiv_mdf_rsn_cd": "<필수>",
"old_aprv_no": "<필수>",
"supply_date": "<필수>"
}
}'Response
- 기관이 발행을 확인한 경우에만 성공합니다. result.data.outcome 은 confirmed 이고, approval_number 에 국세청 승인번호가 담깁니다.
- 여러 JSON 타입이 함께 표시된 칸은 서버가 세부 타입을 고정하지 않는 기관 원문 또는 동적 값입니다.예시 값의 타입으로 단정하지 말고 실제 값의 타입을 확인해 주세요. null은 값이 비어 있다는 뜻이며, 필드 자체의 생략 여부는 필수 여부와 설명을 확인해 주세요.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| success | boolean | 발행 확인 여부. 성공 응답에서는 항상 true 입니다 | |
| outcome | string | 기관 처리 판정. 성공 응답에서는 항상 confirmed 입니다 | |
| etan | string | number | boolean | object | array | null | 전자세금계산서 승인번호 | |
| message | string | 처리 결과 안내 문구 | |
| approval_ | string | 국세청이 발번한 승인번호(apprvNo). etan 과 같은 값입니다 | |
| issue_ | string | 발행 일시. 기관 응답에 없으면 빈 문자열입니다 | |
| result_ | string | 기관 판정 코드(resultMsg.result). 성공 응답에서는 S 입니다 | |
| issue_ | string | number | boolean | object | array | null | 기관의 최종 발행 응답 본문. 기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다 |
// result.data
{
"success": true,
"outcome": "confirmed",
"etan": "...",
"message": "...",
"approval_number": "...",
"issue_datetime": "...",
"result_code": "S",
"issue_data": {}
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| PROVIDER_ | 처리 확인 불가 — 요청은 홈택스로 전송됐지만 처리됐는지 확인하지 못했습니다. 이미 처리됐을 수 있으므로 다시 요청하지 않고, 오류 메시지가 안내하는 홈택스 화면에서 먼저 확인합니다. | |
| AUTH_ | 세션 없음 — 홈택스 세션이 없습니다. 홈택스 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다. | |
| PROVIDER_ | 업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다. | |
| PROVIDER_ | 홈택스 통신 오류 — 홈택스가 오류로 답하거나 연결이 끊겨 요청이 처리됐는지 알 수 없을 수 있으니, 다시 요청하기 전에 홈택스 화면에서 먼저 확인합니다. 홈택스가 오류 응답을 보내거나 연결이 끊긴 경우 error.message 는 결과 확인 불가 안내('요청은 기관에 전송됐지만 처리 결과를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')입니다. | |
| PROVIDER_ | 홈택스 통신 오류 — 홈택스가 오류로 답하거나 연결이 끊겨 요청이 처리됐는지 알 수 없을 수 있으니, 다시 요청하기 전에 홈택스 화면에서 먼저 확인합니다. 홈택스가 오류 응답을 보내거나 연결이 끊긴 경우 error.message 는 결과 확인 불가 안내('요청은 기관에 전송됐지만 처리 결과를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')입니다. | |
| PROVIDER_ | 홈택스 통신 오류 — 홈택스가 오류로 답하거나 연결이 끊겨 요청이 처리됐는지 알 수 없을 수 있으니, 다시 요청하기 전에 홈택스 화면에서 먼저 확인합니다. 홈택스가 오류 응답을 보내거나 연결이 끊긴 경우 error.message 는 결과 확인 불가 안내('요청은 기관에 전송됐지만 처리 결과를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')입니다. |
7. 전자세금계산서 공급자 정보 조회hometax. etax. business_ info. get
MCP 도구 이름 hometax__
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
전자세금계산서 발급 화면에 쓰이는 공급자 정보와, 이 사업자가 계산서를 발급할 수 있는 유형인지 조회합니다.
Request
| 순번 | 변수명 | 필수 | 설명 |
|---|---|---|---|
| Authorization | Y | API 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다. | |
| X- | Y | 호출 환경입니다.
| |
| Idempotency- | Y | 재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다. | |
| Content- | Y | 요청 본문 형식입니다.
| |
| X- | N | 추적 아이디입니다. 지정하지 않으면 서버가 발급합니다. |
| 순번 | 변수명 | 타입 | 길이 | 필수 | 설명 |
|---|---|---|---|---|---|
| provider | string | - | Y | 호출할 기관입니다.
| |
| action | string | - | Y | 호출할 작업입니다.
| |
| account_ | string | 36 | 조건부 | 등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명 중 대표로 지정한 것이 쓰입니다. 대표가 없으면 등록한 자격증명이 하나뿐일 때만 자동으로 선택되고, 둘 이상이면 직접 지정해야 합니다. 등록한 자격증명이 없거나 하나를 고르지 못하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다. | |
| params | object | - | N | 작업 파라미터입니다. 이 API 는 빈 객체로 호출할 수 있습니다. | |
| encrypted_ | object | - | N | 민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. |
추가 파라미터가 없습니다. params 는 {} 로 보냅니다.
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: demo-get-001' \
--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 가 돌려주는 데이터: 상호, 대표자명, 업태, 종목, 사업장 주소, 이메일, 사업자 구분, 납세자 상태, 간이과세자 세금계산서 발급 구분, 발급 불가 면세사업자 여부, 법인 연락사무소 여부
이 API 는 기관 응답 본문을 그대로 전달합니다. 고정 필드 목록이 없습니다.
{
"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_ | 저장된 기관 세션이 없습니다. 같은 연동 계정으로 hometax.session.login 을 먼저 실행해 세션을 연 뒤 다시 보냅니다. | |
| PROVIDER_ | 기관 세션이 만료됐습니다. 같은 연동 계정으로 hometax.session.login 을 다시 실행해 세션을 연 뒤 다시 보냅니다. | |
| PROVIDER_ | 홈택스가 응답 봉투의 결과(resultMsg.result)를 비어 있지도 S 도 아닌 값으로 돌려주면 이 오류로 끝납니다. error.message 는 홈택스가 알려 준 사유이고, 사유를 주지 않으면 「기관이 요청을 처리하지 않았습니다. 사유는 알려 주지 않았습니다. 입력값을 그대로 두고 잠시 후 다시 시도해 주세요.」 입니다. | |
| PROVIDER_ | 홈택스가 서비스 중지 시간이라고 답한 경우입니다. 값이 틀린 것이 아니라 시간의 문제이고 요청은 처리되지 않았습니다. error.message 는 중지 시간을 읽었으면 그 시간을 함께 알리고, 읽지 못했으면 「지금은 홈택스 서비스 중지 시간이라 요청이 처리되지 않았습니다. 중지 시간이 지난 뒤 다시 요청해 주세요.」 입니다. |
8. 전자세금계산서 거래처 정보 조회hometax. etax. client_ info. get
MCP 도구 이름 hometax__
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
전자세금계산서 발급 화면에 등록해 둔 거래처의 사업자번호와 상호, 대표자, 담당자 이메일을 한 번에 받아옵니다.
Request
| 순번 | 변수명 | 필수 | 설명 |
|---|---|---|---|
| Authorization | Y | API 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다. | |
| X- | Y | 호출 환경입니다.
| |
| Idempotency- | Y | 재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다. | |
| Content- | Y | 요청 본문 형식입니다.
| |
| X- | N | 추적 아이디입니다. 지정하지 않으면 서버가 발급합니다. |
| 순번 | 변수명 | 타입 | 길이 | 필수 | 설명 |
|---|---|---|---|---|---|
| provider | string | - | Y | 호출할 기관입니다.
| |
| action | string | - | Y | 호출할 작업입니다.
| |
| account_ | string | 36 | 조건부 | 등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명 중 대표로 지정한 것이 쓰입니다. 대표가 없으면 등록한 자격증명이 하나뿐일 때만 자동으로 선택되고, 둘 이상이면 직접 지정해야 합니다. 등록한 자격증명이 없거나 하나를 고르지 못하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다. | |
| params | object | - | N | 작업 파라미터입니다. 이 API 는 빈 객체로 호출할 수 있습니다. | |
| encrypted_ | object | - | N | 민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. |
추가 파라미터가 없습니다. params 는 {} 로 보냅니다.
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: demo-get-001' \
--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 가 돌려주는 데이터: 거래처 사업자번호, 종사업장 번호, 상호, 대표자명, 업태, 종목, 주소, 주 담당자 이메일, 부 담당자 이메일, 주 거래처 여부, 거래처 상태, 등록 일자와 변경 일자
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| items | array | 전자세금계산서 발급 화면에 등록해 둔 거래처 행의 목록입니다. 등록된 거래처가 없으면 빈 배열입니다. 행의 칸 이름과 값은 홈택스가 정하므로 이 문서가 보장하지 않습니다(기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다). |
{
"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_ | 저장된 기관 세션이 없습니다. 같은 연동 계정으로 hometax.session.login 을 먼저 실행해 세션을 연 뒤 다시 보냅니다. | |
| PROVIDER_ | 기관 세션이 만료됐습니다. 같은 연동 계정으로 hometax.session.login 을 다시 실행해 세션을 연 뒤 다시 보냅니다. | |
| PROVIDER_ | 홈택스가 거래처 조회를 거절하면(응답 봉투의 resultMsg.result 가 비어 있지도 S 도 아닌 값) 빈 목록으로 돌려주지 않고 이 오류로 끝납니다. error.message 는 홈택스가 알려 준 사유이고, 사유를 주지 않으면 「기관이 요청을 처리하지 않았습니다. 사유는 알려 주지 않았습니다. 입력값을 그대로 두고 잠시 후 다시 시도해 주세요.」 입니다. | |
| PROVIDER_ | 홈택스가 서비스 중지 시간이라고 답한 경우입니다. 값이 틀린 것이 아니라 시간의 문제이고 요청은 처리되지 않았습니다. error.message 는 중지 시간을 읽었으면 그 시간을 함께 알리고, 읽지 못했으면 「지금은 홈택스 서비스 중지 시간이라 요청이 처리되지 않았습니다. 중지 시간이 지난 뒤 다시 요청해 주세요.」 입니다. |