세무 - 홈택스
사업자 상태, 신고 이력, 고지와 체납, 환급 등 세무 자료를 조회하고, 원천세 정기신고, 수정신고, 기한후신고, 삭제신청, 전자파일 변환신고를 단계별로 작성해 제출합니다.
1. 개인사업자등록상태 조회hometax. tax. business_ registration. search_ status
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 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| psb_ | string | N | 조회가능여부 (기본: Y, 5초 이내 중복 조회 방지용) | |
| txpr_ | string | Y | 사업자등록번호 (필수, 10자리, 하이픈 제외) |
- 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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_status-$(date +%s)-$RANDOM" \
--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 값과 응답 칸을 확인합니다.
- 여러 JSON 타입이 함께 표시된 칸은 서버가 세부 타입을 고정하지 않는 기관 원문 또는 동적 값입니다.예시 값의 타입으로 단정하지 말고 실제 값의 타입을 확인해 주세요. null은 값이 비어 있다는 뜻이며, 필드 자체의 생략 여부는 필수 여부와 설명을 확인해 주세요.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| result | string | number | boolean | object | array | null | 홈택스 응답 본문 객체. 기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다 | |
| trtCntn | string | number | boolean | object | array | null | 처리내용 | |
| trtEndCd | string | number | boolean | object | array | null | 처리종료코드 | |
| txprDscmNo | string | 납세자식별번호 | |
| success | boolean | 요청 처리 성공 여부 |
// result.data
{
"result": {},
"trtCntn": "...",
"trtEndCd": "...",
"txprDscmNo": "...",
"success": true
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| VALIDATION_ | 요청 값 오류 — 필수 값이 빠지면 홈택스에 요청하지 않고 이 코드로 끝나며, 자동 재시도 대상이 아닙니다. error.message 가 빠진 값의 이름을 알려 주니 그 값을 넣어 다시 요청합니다. txpr_dscm_no 의 값이 맞지 않을 때도 홈택스에 요청하지 않고 같은 코드로 끝나며, error.message 가 고칠 내용을 알려 주니 그 값을 고쳐 다시 요청합니다. | |
| AUTH_ | 세션 없음 — 홈택스 세션이 없습니다. 홈택스 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다. | |
| PROVIDER_ | 업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다. | |
| PROVIDER_ | 업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다. | |
| PROVIDER_ | 업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다. | |
| PROVIDER_ | 업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다. | |
| PROVIDER_ | 세션 만료 — 조회하는 도중 홈택스 로그인 세션이 끝난 것을 알게 되면 이 코드로 끝나며, error.message 안내대로 로그인 액션을 다시 실행해 세션을 연 뒤 같은 요청을 다시 보냅니다. |
2. 원천세 정기신고 1단계 시작hometax. tax. withholding. regular_ report. init
MCP 도구 이름 hometax__
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
원천세 정기신고 1단계 시작합니다.
- 홈택스 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [홈택스 로그인(세션 생성)]
- 요청 거절(HTTP 400, 작업은 만들어지지 않음).error.code=WRITE_CONFIRMATION_REQUIRED — confirmation_token 없이 이 단계를 부르면 홈택스에 아무것도 보내지 않고 이 오류로 끝납니다.error.message 에 확인할 내용이, error.confirmation_token 에 1회용 토큰이 함께 옵니다(error.preview 도 오지만 이 단계에서는 비어 있습니다).안내를 사용자에게 보여 주고 동의를 받은 뒤 같은 요청의 params.confirmation_token 에 그 토큰을 넣어 다시 보냅니다. 토큰은 10분 안에 한 번만 쓸 수 있고 처음 요청과 같은 본문에만 맞습니다.새로 쓰기(기본)는 기관에 작성 중인 신고서가 있으면 지우므로 늘 이 확인을 거치고, 작성 방식(draft_mode)이 resume(이어 쓰기)이면 확인 없이 바로 실행되어 이 오류가 나지 않습니다.
- 요청 거절(HTTP 409, 작업은 만들어지지 않음).error.code=WRITE_CONFIRMATION_INVALID — 토큰이 만료됐거나, 이미 썼거나, 다른 호출자나 다른 환경에서 받은 것이거나, 확인한 요청 본문과 달라졌으면 홈택스에 아무것도 보내지 않고 이 오류로 끝나며 어느 쪽인지는 알려 주지 않습니다.error.message 는 「확인이 만료됐거나 확인한 내용과 달라졌습니다. 다시 확인해 주세요.」 입니다. confirmation_token 없이 같은 요청을 다시 보내 새 토큰과 안내를 받은 뒤 사용자에게 다시 확인을 받습니다.
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 와 함께 쓰지 않습니다. |
- 대괄호 []는 목록의 각 항목을, 점은 객체의 속성을, {key}는 실제 키로 바꿔 넣는 사전 항목을 뜻하며, 선택인 부모를 보낼 때 하위 필수 칸은 조건부로 표시합니다.
| 순번 | 변수명 | 타입 | 길이 | 필수 | 설명 |
|---|---|---|---|---|---|
| draft_ | string | - | N | 작성 방식. new(기본값)는 새 신고서로 작성하며, 이미 작성 중인 신고서가 있으면 그것을 지우고 시작합니다. resume 은 작성 중인 신고서를 이어서 씁니다. init 과 basic_save 에 같은 값을 입력해 주세요 | |
| create_ | boolean | - | N | draft_mode 를 보내지 않았을 때만 봅니다. true 는 new, false 는 resume 과 같습니다 | |
| periods | object | - | Y | 신고 기간 3개. submit_ym(제출연월) · attr_ym(귀속연월) · pymn_ym(지급연월)을 각각 YYYYMM 6자리로 넣습니다 | |
| periods. | string | 6 | Y | 제출연월입니다. YYYYMM 형식이고 월은 01~12 입니다. 별칭 submitYm 로도 보낼 수 있습니다. 최소 길이: 6. 최대 길이: 6 | |
| periods. | string | 6 | Y | 귀속연월입니다. YYYYMM 형식이고 월은 01~12 입니다. 별칭 attrYm 로도 보낼 수 있습니다. 최소 길이: 6. 최대 길이: 6 | |
| periods. | string | 6 | Y | 지급연월입니다. YYYYMM 형식이고 월은 01~12 입니다. 별칭 pymnYm 로도 보낼 수 있습니다. 최소 길이: 6. 최대 길이: 6 | |
| confirmation_ | string | - | N | 1회용 확인 토큰입니다. 처음에는 보내지 않습니다. 토큰 없이 부르면 기관에 아무것도 보내지 않고 작업도 만들지 않은 채 확인이 필요하다는 오류(WRITE_CONFIRMATION_REQUIRED)로 끝나고, 응답의 error.confirmation_token 에 토큰이 옵니다. error.message 의 안내를 사용자에게 보여 주고 동의를 받은 뒤 같은 요청에 이 토큰을 넣어 다시 부릅니다. 토큰은 10분 안에 한 번만 쓸 수 있고 처음 요청과 같은 본문, 같은 호출자, 같은 환경에서만 맞으며, 아니면 확인이 만료됐거나 내용이 달라졌다는 오류로 거절합니다. 새로 쓰기(기본)는 기관에 작성 중인 신고서가 있으면 지우므로 늘 확인을 거칩니다. 작성 방식(draft_mode)이 resume(이어 쓰기)이면 기관에 쓰는 것이 없어 확인 없이 실행하니 토큰을 보내지 않습니다 |
- 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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: init-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "hometax",
"action": "hometax.tax.withholding.regular_report.init",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {
"periods": {
"submit_ym": "<필수>",
"attr_ym": "<필수>",
"pymn_ym": "<필수>"
}
}
}'Response
- 아래 표의 칸은 작업이 SUCCEEDED 가 된 뒤 GET /v1/jobs/{job_id}/result 의 result.data 에 오고, 응답 예시는 작업을 제출했을 때(POST /v1/jobs)의 응답입니다.
- 이 단계 처리가 끝나면 성공합니다. result.data.state 로 어느 단계까지 끝났는지, result.data.state_version 으로 다음 단계에 넣을 버전을 확인합니다.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| success | boolean | 작업이 성공하면 항상 true 로 고정된 값입니다 - 성패 판정에 쓸 수 없습니다 | |
| mode | string | 실행 모드 값. 지금 실제 홈택스로 처리될 때는 항상 문자열 "true" 가 옵니다 | |
| step | string | 이 응답이 어느 단계 결과인지 - init · basic_save · detail_save · review · preview · submit 중 하나 | |
| draft_ | string | 이 신고서 초안의 아이디. 다음 단계 호출에 그대로 넣습니다 | |
| state | string | 초안의 현재 상태. init 뒤 initialized, basic_save 뒤 basic_saved, detail_save 뒤 detail_saved, review 뒤 reviewed, preview 뒤 previewed, submit 뒤 submitted 로 차례로 바뀝니다. 건너뛰어 호출하면 오류표의 "단계 순서" 행으로 거절됩니다 | |
| state_ | number | 낙관적 동시성 버전. 다음 단계 호출의 expected_state_version 에 이 값을 그대로 넣습니다. 그사이 값이 바뀌었으면(같은 초안에 다른 요청이 먼저 반영되면) 저장하지 않고 거절합니다 | |
| data | object | 새로 연 초안의 신고 기간(periods)과 내부 처리 이력을 담은 객체입니다. | |
| warnings | array | 늘 빈 배열입니다. 이 단계는 경고를 내지 않습니다 |
{
"job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
"status": "QUEUED",
"env_scope": "real_test",
"provider": "hometax",
"action": "hometax.tax.withholding.regular_report.init",
"submitted_at": "2026-05-27T12:34:56+09:00"
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| POLICY_ | 일시 중지 — 이 기능이 일시 중지된 동안에는 여섯 단계 모두 이 코드로 끝나며, 자동 재시도 대상이 아니니 error.message 안내대로 잠시 후 직접 다시 요청합니다. 계속 같은 코드가 오면 서비스문의로 알려 주세요. | |
| VALIDATION_ | 요청 값 오류 — 필요한 값이 빠졌거나 보낸 값이 이 단계 요청 형식과 맞지 않거나 이 단계에 없는 필드를 보내면 이 코드로 끝납니다(예: periods 의 연월이 6자리가 아님). error.message 의 빠진 값은 넣고 확인할 값은 고쳐 다시 보냅니다. | |
| VALIDATION_ | 입력 값 오류 — periods 의 세 연월(submitYm, attrYm, pymnYm)이 6자리여도 월이 01부터 12 사이가 아니면 홈택스에 요청하지 않고 이 코드로 끝나며, 자동 재시도 대상이 아닙니다. error.message 는 어느 칸인지 알려 주지 않으니 세 연월을 모두 확인해 고친 뒤 다시 요청합니다. | |
| RESOURCE_ | 이어 쓸 초안 없음 — draft_mode 를 resume 으로 보냈는데 홈택스에 이어 쓸 작성 중 신고서가 없으면 아무것도 만들지 않고 이 코드로 끝나며, 자동 재시도 대상이 아닙니다. 새로 작성하려면 draft_mode 를 빼거나 new 로 바꿔 init 을 다시 요청합니다. | |
| AUTH_ | 세션 없음 — 홈택스 세션이 없습니다. 홈택스 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다. | |
| PROVIDER_ | 업무 오류 — 홈택스가 이 단계를 받지 않았다는 뜻이며, error.message 의 홈택스 사유를 해결한 뒤 같은 단계를 다시 요청합니다. 홈택스가 사유를 알려 주지 않은 경우에는 입력값을 그대로 두고 잠시 후 다시 시도하라는 안내가 담깁니다. | |
| VALIDATION_ | 신고 불가 판정 — 이 단계가 홈택스에서 신고서 상태를 확인할 때 홈택스가 지금 이 신고를 받을 수 없다고 답하면 그 자리에서 멈추고, error.message 가 까닭과 할 일을 알려 줍니다. 선택한 연월이 지금 정기신고 기간이 아니면(이 상품은 월별 정기신고만 하며, 기한이 지난 연월은 홈택스에서 직접 신고합니다), 또는 신고 기한을 확인하지 못했거나 신고서를 찾지 못했으면 신고 기간(periods)을 확인해 init 부터 다시 요청합니다. 연결된 계정의 사업자가 이 신고의 대상이 아니면 원천세를 신고할 사업자의 홈택스 계정으로 연결했는지 확인합니다. 로그인이 필요하다는 답이면 로그인 액션을 다시 실행한 뒤 init 부터 새 초안으로 진행합니다. 그 밖의 답이면 홈택스에서 같은 기간의 신고 상태를 확인합니다. | |
| RESOURCE_ | 신고 불가 판정 — 이 단계가 홈택스에서 신고서 상태를 확인할 때 홈택스가 지금 이 신고를 받을 수 없다고 답하면 그 자리에서 멈추고, error.message 가 까닭과 할 일을 알려 줍니다. 선택한 연월이 지금 정기신고 기간이 아니면(이 상품은 월별 정기신고만 하며, 기한이 지난 연월은 홈택스에서 직접 신고합니다), 또는 신고 기한을 확인하지 못했거나 신고서를 찾지 못했으면 신고 기간(periods)을 확인해 init 부터 다시 요청합니다. 연결된 계정의 사업자가 이 신고의 대상이 아니면 원천세를 신고할 사업자의 홈택스 계정으로 연결했는지 확인합니다. 로그인이 필요하다는 답이면 로그인 액션을 다시 실행한 뒤 init 부터 새 초안으로 진행합니다. 그 밖의 답이면 홈택스에서 같은 기간의 신고 상태를 확인합니다. | |
| AUTH_ | 신고 불가 판정 — 이 단계가 홈택스에서 신고서 상태를 확인할 때 홈택스가 지금 이 신고를 받을 수 없다고 답하면 그 자리에서 멈추고, error.message 가 까닭과 할 일을 알려 줍니다. 선택한 연월이 지금 정기신고 기간이 아니면(이 상품은 월별 정기신고만 하며, 기한이 지난 연월은 홈택스에서 직접 신고합니다), 또는 신고 기한을 확인하지 못했거나 신고서를 찾지 못했으면 신고 기간(periods)을 확인해 init 부터 다시 요청합니다. 연결된 계정의 사업자가 이 신고의 대상이 아니면 원천세를 신고할 사업자의 홈택스 계정으로 연결했는지 확인합니다. 로그인이 필요하다는 답이면 로그인 액션을 다시 실행한 뒤 init 부터 새 초안으로 진행합니다. 그 밖의 답이면 홈택스에서 같은 기간의 신고 상태를 확인합니다. | |
| RESOURCE_ | 신고 불가 판정 — 이 단계가 홈택스에서 신고서 상태를 확인할 때 홈택스가 지금 이 신고를 받을 수 없다고 답하면 그 자리에서 멈추고, error.message 가 까닭과 할 일을 알려 줍니다. 선택한 연월이 지금 정기신고 기간이 아니면(이 상품은 월별 정기신고만 하며, 기한이 지난 연월은 홈택스에서 직접 신고합니다), 또는 신고 기한을 확인하지 못했거나 신고서를 찾지 못했으면 신고 기간(periods)을 확인해 init 부터 다시 요청합니다. 연결된 계정의 사업자가 이 신고의 대상이 아니면 원천세를 신고할 사업자의 홈택스 계정으로 연결했는지 확인합니다. 로그인이 필요하다는 답이면 로그인 액션을 다시 실행한 뒤 init 부터 새 초안으로 진행합니다. 그 밖의 답이면 홈택스에서 같은 기간의 신고 상태를 확인합니다. | |
| PROVIDER_ | 세션 만료 — 신고 화면을 연 뒤 홈택스 로그인 세션이 끝난 것을 알게 되면 이 코드로 끝나며, error.message 안내대로 로그인 액션을 다시 실행해 세션을 연 뒤 init 을 다시 요청합니다. init 이 끝나기 전에는 초안이 저장되지 않으므로 이어 갈 draft_id 는 없습니다. | |
| INTERNAL_ | 홈택스 통신 오류 — 신고 화면을 여는 도중 연결이 끊기거나 홈택스가 정상 응답을 주지 않으면 이 코드로 끝나며, 자동 재시도 대상이 아닙니다. 홈택스 로그인 세션이 이미 끝나 있을 때도 신고 화면을 열기 전 포털 준비에서 이 코드로 끝날 수 있습니다. error.message 안내대로 잠시 후 init 을 다시 요청하고, 같은 코드가 계속되면 로그인 액션을 다시 실행해 세션을 연 뒤 요청하며, 그래도 계속되면 서비스문의로 알려 주세요. | |
| INTERNAL_ | 처리 결과 모름 — 예상하지 못한 오류나 시간 초과로 끝나면 이 단계가 홈택스에 반영됐는지 알 수 없으니, 같은 단계를 다시 실행하지 않고 서비스문의로 알려 주세요. 예상하지 못한 오류일 때 error.message 는 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')이고, 시간 초과일 때도 다시 실행하지 말라는 안내가 담깁니다. | |
| JOB_ | 처리 결과 모름 — 예상하지 못한 오류나 시간 초과로 끝나면 이 단계가 홈택스에 반영됐는지 알 수 없으니, 같은 단계를 다시 실행하지 않고 서비스문의로 알려 주세요. 예상하지 못한 오류일 때 error.message 는 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')이고, 시간 초과일 때도 다시 실행하지 말라는 안내가 담깁니다. |
3. 원천세 정기신고 준비자료 안내hometax. tax. withholding. regular_ report. requirements
MCP 도구 이름 hometax__
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
원천세 정기신고의 단계마다 필요한 입력과 준비자료를 알려 줍니다.
- 이 API 는 기관 연동과 기관 로그인이 필요 없습니다. 기관 자격증명을 등록하지 않아도 호출할 수 있고, 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 | 호출할 작업입니다.
| |
| 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: requirements-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "hometax",
"action": "hometax.tax.withholding.regular_report.requirements",
"params": {}
}'Response
- 아래 표의 칸은 작업이 SUCCEEDED 가 된 뒤 GET /v1/jobs/{job_id}/result 의 result.data 에 오고, 응답 예시는 작업을 제출했을 때(POST /v1/jobs)의 응답입니다.
- 기관에 접속하지 않고 항상 같은 안내를 돌려줍니다.result.data.data 의 inputs 로 단계마다 받는 입력과 확인하는 방법을, blocking_reasons 로 단계마다 반드시 넣어야 하는 입력을 확인한 뒤 init 부터 진행합니다.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| success | boolean | 작업이 성공하면 항상 true 로 고정된 값입니다 | |
| step | string | 이 응답이 준비자료 안내라는 표시로, 항상 requirements 입니다 | |
| data | object | 단계마다 받는 입력의 안내 객체입니다. inputs 는 입력마다 단계(action) · 칸 이름(key) · 이름(label_ko) · 필수 여부(required) · 값 종류(value_type) · 고를 수 있는 값(options) · 확인하는 방법(how_to_ko)을 담고, blocking_reasons 는 단계마다 반드시 넣어야 하는 입력(action · key · reason_ko)을 담습니다. 이 안내는 값을 받지 않으므로 blocked 는 항상 true 입니다. safety 는 아무것도 저장하거나 제출하지 않았다는 표시(input_only true · save_executed false · submit_executed false)이고, confirmation_fields 는 제출 단계에서 고객의 확인과 동의를 받아 보내야 하는 칸 이름입니다 |
{
"job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
"status": "QUEUED",
"env_scope": "real_test",
"provider": "hometax",
"action": "hometax.tax.withholding.regular_report.requirements",
"submitted_at": "2026-05-27T12:34:56+09:00"
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| VALIDATION_ | 요청 값 오류 — 이 안내는 입력을 받지 않아 params 에 값을 넣으면 이 코드로 끝나며, 자동 재시도 대상이 아닙니다. params 를 빈 객체로 고쳐 다시 보냅니다. |
4. 원천세 정기신고 2단계 기본사항 저장hometax. tax. withholding. regular_ report. basic_ save
MCP 도구 이름 hometax__
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
원천세 정기신고 2단계 기본사항 저장합니다.
- 홈택스 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [홈택스 로그인(세션 생성)]
- 요청 거절(HTTP 400, 작업은 만들어지지 않음).error.code=WRITE_CONFIRMATION_REQUIRED — confirmation_token 없이 이 단계를 부르면 홈택스에 아무것도 보내지 않고 이 오류로 끝납니다.error.message 에 확인할 내용이, error.confirmation_token 에 1회용 토큰이 함께 옵니다(error.preview 도 오지만 이 단계에서는 비어 있습니다).안내를 사용자에게 보여 주고 동의를 받은 뒤 같은 요청의 params.confirmation_token 에 그 토큰을 넣어 다시 보냅니다. 토큰은 10분 안에 한 번만 쓸 수 있고 처음 요청과 같은 본문에만 맞습니다.새로 쓰기(기본)는 기관에 작성 중인 신고서가 있으면 지우므로 늘 이 확인을 거치고, 작성 방식(draft_mode)이 resume(이어 쓰기)이면 확인 없이 바로 실행되어 이 오류가 나지 않습니다.
- 요청 거절(HTTP 409, 작업은 만들어지지 않음).error.code=WRITE_CONFIRMATION_INVALID — 토큰이 만료됐거나, 이미 썼거나, 다른 호출자나 다른 환경에서 받은 것이거나, 확인한 요청 본문과 달라졌으면 홈택스에 아무것도 보내지 않고 이 오류로 끝나며 어느 쪽인지는 알려 주지 않습니다.error.message 는 「확인이 만료됐거나 확인한 내용과 달라졌습니다. 다시 확인해 주세요.」 입니다. confirmation_token 없이 같은 요청을 다시 보내 새 토큰과 안내를 받은 뒤 사용자에게 다시 확인을 받습니다.
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 와 함께 쓰지 않습니다. |
- 대괄호 []는 목록의 각 항목을, 점은 객체의 속성을, {key}는 실제 키로 바꿔 넣는 사전 항목을 뜻하며, 선택인 부모를 보낼 때 하위 필수 칸은 조건부로 표시합니다.
| 순번 | 변수명 | 타입 | 길이 | 필수 | 설명 |
|---|---|---|---|---|---|
| draft_ | string | - | N | 작성 방식. new(기본값)는 새 신고서로 작성하며, 이미 작성 중인 신고서가 있으면 그것을 지우고 시작합니다. resume 은 작성 중인 신고서를 이어서 씁니다. init 과 basic_save 에 같은 값을 입력해 주세요 | |
| create_ | boolean | - | N | draft_mode 를 보내지 않았을 때만 봅니다. true 는 new, false 는 resume 과 같습니다 | |
| draft_ | string | - | Y | init 응답의 draft_id 를 그대로 넣습니다. 어느 신고서를 작성 중인지 가리킵니다 | |
| expected_ | number | - | Y | 직전 단계 응답의 state_version 을 그대로 넣습니다(1 이상). 그사이 신고서가 바뀌어 값이 다르면 저장하지 않고 409 로 거절합니다 | |
| idempotency_ | string | - | Y | 같은 요청을 두 번 실행하지 않기 위한 키(8~128자). 키는 초안 하나 안에서 기억하므로 같은 초안의 다른 단계에는 새 값을 입력합니다. 같은 키로 다시 요청하면 다시 실행하지 않고 처음 결과를 돌려주므로, 재시도에는 같은 값을 입력합니다 | |
| basic_ | object | - | Y | 신고서 기본사항. periods(기간 3개) · taxpayer(business_no 사업자번호 10자리 · company_name 상호 · representative 대표자) · selected_income_types(employment 근로 · retirement 퇴직 · business 사업 · other 기타 중 1개 이상, 중복 없이)가 필수입니다. report(신고 구분)는 지금 월별 정기신고만 받으므로 보내지 않아도 되고, tax_agent(세무대리인)는 선택입니다 | |
| basic_ | object | - | Y | 제출, 귀속, 지급 연월입니다 | |
| basic_ | string | 6 | Y | 제출연월입니다. YYYYMM 형식이고 월은 01~12 입니다. 별칭 submitYm 로도 보낼 수 있습니다. 최소 길이: 6. 최대 길이: 6 | |
| basic_ | string | 6 | Y | 귀속연월입니다. YYYYMM 형식이고 월은 01~12 입니다. 별칭 attrYm 로도 보낼 수 있습니다. 최소 길이: 6. 최대 길이: 6 | |
| basic_ | string | 6 | Y | 지급연월입니다. YYYYMM 형식이고 월은 01~12 입니다. 별칭 pymnYm 로도 보낼 수 있습니다. 최소 길이: 6. 최대 길이: 6 | |
| basic_ | object | - | N | 신고 주기와 유형 및 부가 선택사항입니다 | |
| basic_ | string | - | N | 신고 주기입니다. monthly 만 지원합니다. 별칭 periodType 로도 보낼 수 있습니다. 생략 시 기본값: "monthly" | |
| basic_ | string | - | N | 신고 유형입니다. regular 만 지원합니다. 별칭 reportType 로도 보낼 수 있습니다. 생략 시 기본값: "regular" | |
| basic_ | string | - | N | 연말정산 여부로 Y 또는 N 을 보냅니다. 별칭 yearEnd 로도 보낼 수 있습니다. 생략 시 기본값: "N" | |
| basic_ | string | - | N | 소득처분 여부로 Y 또는 N 을 보냅니다. 생략 시 기본값: "N" | |
| basic_ | string | - | N | 환급 신청 여부로 Y 또는 N 을 보냅니다. 별칭 refundApply 로도 보낼 수 있습니다. 생략 시 기본값: "N" | |
| basic_ | string | - | N | 일괄 납부 여부로 Y 또는 N 을 보냅니다. 별칭 bulkPayment 로도 보낼 수 있습니다. 생략 시 기본값: "N" | |
| basic_ | string | - | N | 사업자단위 과세 여부로 Y 또는 N 을 보냅니다. 별칭 businessUnit 로도 보낼 수 있습니다. 생략 시 기본값: "N" | |
| basic_ | object | - | Y | 원천징수의무자 정보입니다 | |
| basic_ | string | - | Y | 원천징수의무자 사업자등록번호입니다. 숫자만 추렸을 때 10자리여야 합니다. 별칭 businessNo 로도 보낼 수 있습니다 | |
| basic_ | string | - | Y | 원천징수의무자 상호입니다. 빈 문자열은 거절합니다. 별칭 companyName 로도 보낼 수 있습니다 | |
| basic_ | string | - | Y | 대표자 성명입니다. 빈 문자열은 거절합니다 | |
| basic_ | string | - | N | 원천징수의무자 전화번호입니다. 생략 시 기본값: "" | |
| basic_ | string | - | N | 원천징수의무자 전자우편주소입니다. 생략 시 기본값: "" | |
| basic_ | string | - | N | 원천징수의무자 도로명주소입니다. 별칭 roadAddress 로도 보낼 수 있습니다. 생략 시 기본값: "" | |
| basic_ | string | - | N | 원천징수의무자 상세주소입니다. 별칭 detailAddress 로도 보낼 수 있습니다. 생략 시 기본값: "" | |
| basic_ | object | - | N | 세무대리인 정보입니다. 별칭 taxAgent 로도 보낼 수 있습니다 | |
| basic_ | string | - | N | 세무대리인 이름입니다. 생략 시 기본값: null | |
| basic_ | string | - | N | 세무대리인 사업자등록번호입니다. 별칭 businessNo 로도 보낼 수 있습니다. 생략 시 기본값: null | |
| basic_ | string | - | N | 세무대리인 전화번호입니다. 생략 시 기본값: null | |
| basic_ | array | - | Y | 신고할 소득 종류입니다. employment, retirement, business, other 중 하나 이상을 중복 없이 보냅니다. 별칭 selectedIncomeTypes 로도 보낼 수 있습니다 | |
| confirmation_ | string | - | N | 1회용 확인 토큰입니다. 처음에는 보내지 않습니다. 토큰 없이 부르면 기관에 아무것도 보내지 않고 작업도 만들지 않은 채 확인이 필요하다는 오류(WRITE_CONFIRMATION_REQUIRED)로 끝나고, 응답의 error.confirmation_token 에 토큰이 옵니다. error.message 의 안내를 사용자에게 보여 주고 동의를 받은 뒤 같은 요청에 이 토큰을 넣어 다시 부릅니다. 토큰은 10분 안에 한 번만 쓸 수 있고 처음 요청과 같은 본문, 같은 호출자, 같은 환경에서만 맞으며, 아니면 확인이 만료됐거나 내용이 달라졌다는 오류로 거절합니다. 새로 쓰기(기본)는 기관에 작성 중인 신고서가 있으면 지우므로 늘 확인을 거칩니다. 작성 방식(draft_mode)이 resume(이어 쓰기)이면 기관에 쓰는 것이 없어 확인 없이 실행하니 토큰을 보내지 않습니다 |
- 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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: basic_save-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "hometax",
"action": "hometax.tax.withholding.regular_report.basic_save",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {
"draft_id": "<필수>",
"expected_state_version": "<필수: number>",
"idempotency_key": "<필수>",
"basic_document": {
"periods": {
"submit_ym": "<필수>",
"attr_ym": "<필수>",
"pymn_ym": "<필수>"
},
"taxpayer": {
"business_no": "<필수>",
"company_name": "<필수>",
"representative": "<필수>"
},
"selected_income_types": "<필수: array>"
}
}
}'Response
- 아래 표의 칸은 작업이 SUCCEEDED 가 된 뒤 GET /v1/jobs/{job_id}/result 의 result.data 에 오고, 응답 예시는 작업을 제출했을 때(POST /v1/jobs)의 응답입니다.
- 이 단계 처리가 끝나면 성공합니다. result.data.state 로 어느 단계까지 끝났는지, result.data.state_version 으로 다음 단계에 넣을 버전을 확인합니다.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| success | boolean | 작업이 성공하면 항상 true 로 고정된 값입니다 - 성패 판정에 쓸 수 없습니다 | |
| mode | string | 실행 모드 값. 지금 실제 홈택스로 처리될 때는 항상 문자열 "true" 가 옵니다 | |
| step | string | 이 응답이 어느 단계 결과인지 - init · basic_save · detail_save · review · preview · submit 중 하나 | |
| draft_ | string | 이 신고서 초안의 아이디. 다음 단계 호출에 그대로 넣습니다 | |
| state | string | 초안의 현재 상태. init 뒤 initialized, basic_save 뒤 basic_saved, detail_save 뒤 detail_saved, review 뒤 reviewed, preview 뒤 previewed, submit 뒤 submitted 로 차례로 바뀝니다. 건너뛰어 호출하면 오류표의 "단계 순서" 행으로 거절됩니다 | |
| state_ | number | 낙관적 동시성 버전. 다음 단계 호출의 expected_state_version 에 이 값을 그대로 넣습니다. 그사이 값이 바뀌었으면(같은 초안에 다른 요청이 먼저 반영되면) 저장하지 않고 거절합니다 | |
| data | object | 저장한 기본사항(basicDocument)과 선택한 소득종류(selectedIncomeTypes), 작성 방식(draftMode)을 담은 객체입니다. | |
| warnings | array | 늘 빈 배열입니다. 이 단계는 경고를 내지 않습니다 |
{
"job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
"status": "QUEUED",
"env_scope": "real_test",
"provider": "hometax",
"action": "hometax.tax.withholding.regular_report.basic_save",
"submitted_at": "2026-05-27T12:34:56+09:00"
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| POLICY_ | 일시 중지 — 이 기능이 일시 중지된 동안에는 여섯 단계 모두 이 코드로 끝나며, 자동 재시도 대상이 아니니 error.message 안내대로 잠시 후 직접 다시 요청합니다. 계속 같은 코드가 오면 서비스문의로 알려 주세요. | |
| RESOURCE_ | 초안 없음 — draft_id 의 초안을 찾지 못했습니다. 직전 응답의 draft_id 를 다시 확인하고, 맞는데도 없으면 init 을 다시 호출해 새 초안으로 처음 단계부터 진행합니다. 초안은 서버 프로세스 메모리에만 있어 서버가 재시작되면 사라집니다. | |
| RESOURCE_ | 단계 순서·버전 불일치 — 이 단계를 부르기 전에 바로 앞 단계가 먼저 끝나 있어야 하고, expected_state_version 은 직전 응답의 state_version 과 같아야 합니다. 초안의 지금 상태나 버전이 맞지 않으면 저장하지 않고 거절하며, error.message 가 지금 상태나 지금 버전을 알려 줍니다. 이 API 에는 초안을 따로 조회하는 동작이 없으니 그 값과 직전 응답으로 이어 갈 단계와 버전을 정해 같은 초안으로 다시 보냅니다. 다른 연동 계정으로 만든 초안을 부를 때도 같은 코드이며, 그때는 초안을 만들 때 쓴 연동 계정으로 다시 요청합니다. | |
| VALIDATION_ | 요청 값 오류 — 필요한 값이 빠졌거나 보낸 값이 이 단계 요청 형식과 맞지 않거나 이 단계에 없는 필드를 보내면 이 코드로 끝납니다(예: idempotency_key 가 8자 미만). error.message 의 빠진 값은 넣고 확인할 값은 고쳐 다시 보냅니다. | |
| VALIDATION_ | 입력 값 오류 — basic_document 가 요청 형식에 맞아도 신고 규칙에 맞지 않으면 홈택스에 요청하지 않고 이 코드로 끝나며, 자동 재시도 대상이 아닙니다. periods 연월의 월이 01부터 12 사이가 아니거나, report 의 periodType 이 monthly 가 아니거나, Y 나 N 을 받는 칸에 다른 값이 있거나, taxpayer 의 businessNo 가 10자리 숫자가 아니거나 companyName 이 비었거나, selectedIncomeTypes 가 비었거나 같은 값이 겹치거나 지원하지 않는 소득 종류이면 이 코드입니다. 소득 종류와 신고 옵션은 error.message 가 고칠 내용을 알려 주지만, 그 밖에는 어느 칸인지 알려 주지 않으니 위 규칙대로 basic_document 를 확인해 고친 뒤 다시 요청합니다. | |
| PROVIDER_ | 업무 오류 — 홈택스가 이 단계를 받지 않았다는 뜻이며, error.message 의 홈택스 사유를 해결한 뒤 같은 단계를 다시 요청합니다. 홈택스가 사유를 알려 주지 않은 경우에는 입력값을 그대로 두고 잠시 후 다시 시도하라는 안내가 담깁니다. | |
| VALIDATION_ | 신고 불가 판정 — 이 단계가 홈택스에서 신고서 상태를 확인할 때 홈택스가 지금 이 신고를 받을 수 없다고 답하면 그 자리에서 멈추고, error.message 가 까닭과 할 일을 알려 줍니다. 선택한 연월이 지금 정기신고 기간이 아니면(이 상품은 월별 정기신고만 하며, 기한이 지난 연월은 홈택스에서 직접 신고합니다), 또는 신고 기한을 확인하지 못했거나 신고서를 찾지 못했으면 신고 기간(periods)을 확인해 init 부터 다시 요청합니다. 연결된 계정의 사업자가 이 신고의 대상이 아니면 원천세를 신고할 사업자의 홈택스 계정으로 연결했는지 확인합니다. 로그인이 필요하다는 답이면 로그인 액션을 다시 실행한 뒤 init 부터 새 초안으로 진행합니다. 그 밖의 답이면 홈택스에서 같은 기간의 신고 상태를 확인합니다. | |
| RESOURCE_ | 신고 불가 판정 — 이 단계가 홈택스에서 신고서 상태를 확인할 때 홈택스가 지금 이 신고를 받을 수 없다고 답하면 그 자리에서 멈추고, error.message 가 까닭과 할 일을 알려 줍니다. 선택한 연월이 지금 정기신고 기간이 아니면(이 상품은 월별 정기신고만 하며, 기한이 지난 연월은 홈택스에서 직접 신고합니다), 또는 신고 기한을 확인하지 못했거나 신고서를 찾지 못했으면 신고 기간(periods)을 확인해 init 부터 다시 요청합니다. 연결된 계정의 사업자가 이 신고의 대상이 아니면 원천세를 신고할 사업자의 홈택스 계정으로 연결했는지 확인합니다. 로그인이 필요하다는 답이면 로그인 액션을 다시 실행한 뒤 init 부터 새 초안으로 진행합니다. 그 밖의 답이면 홈택스에서 같은 기간의 신고 상태를 확인합니다. | |
| AUTH_ | 신고 불가 판정 — 이 단계가 홈택스에서 신고서 상태를 확인할 때 홈택스가 지금 이 신고를 받을 수 없다고 답하면 그 자리에서 멈추고, error.message 가 까닭과 할 일을 알려 줍니다. 선택한 연월이 지금 정기신고 기간이 아니면(이 상품은 월별 정기신고만 하며, 기한이 지난 연월은 홈택스에서 직접 신고합니다), 또는 신고 기한을 확인하지 못했거나 신고서를 찾지 못했으면 신고 기간(periods)을 확인해 init 부터 다시 요청합니다. 연결된 계정의 사업자가 이 신고의 대상이 아니면 원천세를 신고할 사업자의 홈택스 계정으로 연결했는지 확인합니다. 로그인이 필요하다는 답이면 로그인 액션을 다시 실행한 뒤 init 부터 새 초안으로 진행합니다. 그 밖의 답이면 홈택스에서 같은 기간의 신고 상태를 확인합니다. | |
| RESOURCE_ | 신고 불가 판정 — 이 단계가 홈택스에서 신고서 상태를 확인할 때 홈택스가 지금 이 신고를 받을 수 없다고 답하면 그 자리에서 멈추고, error.message 가 까닭과 할 일을 알려 줍니다. 선택한 연월이 지금 정기신고 기간이 아니면(이 상품은 월별 정기신고만 하며, 기한이 지난 연월은 홈택스에서 직접 신고합니다), 또는 신고 기한을 확인하지 못했거나 신고서를 찾지 못했으면 신고 기간(periods)을 확인해 init 부터 다시 요청합니다. 연결된 계정의 사업자가 이 신고의 대상이 아니면 원천세를 신고할 사업자의 홈택스 계정으로 연결했는지 확인합니다. 로그인이 필요하다는 답이면 로그인 액션을 다시 실행한 뒤 init 부터 새 초안으로 진행합니다. 그 밖의 답이면 홈택스에서 같은 기간의 신고 상태를 확인합니다. | |
| PROVIDER_ | 세션 만료 — 이 단계를 부르는 도중 홈택스 로그인 세션이 끝나 있으면 이 코드로 끝나며, 로그인 액션을 다시 실행한 뒤 init 부터 새 초안으로 처음부터 진행합니다. 이미 연 초안은 처음 연 때의 세션을 계속 쓰므로 로그인을 다시 해도 같은 draft_id 는 새 세션을 쓰지 않습니다. | |
| INTERNAL_ | 홈택스 통신 오류 — 홈택스와 주고받는 도중 연결이 끊기거나 홈택스가 정상 응답을 주지 않으면 이 단계는 이 코드로 끝나며, 자동 재시도 대상이 아닙니다. error.message 안내대로 잠시 후 같은 단계를 다시 요청하고, 계속되면 서비스문의로 알려 주세요. | |
| INTERNAL_ | 처리 결과 모름 — 예상하지 못한 오류나 시간 초과로 끝나면 이 단계가 홈택스에 반영됐는지 알 수 없으니, 같은 단계를 다시 실행하지 않고 서비스문의로 알려 주세요. 예상하지 못한 오류일 때 error.message 는 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')이고, 시간 초과일 때도 다시 실행하지 말라는 안내가 담깁니다. | |
| JOB_ | 처리 결과 모름 — 예상하지 못한 오류나 시간 초과로 끝나면 이 단계가 홈택스에 반영됐는지 알 수 없으니, 같은 단계를 다시 실행하지 않고 서비스문의로 알려 주세요. 예상하지 못한 오류일 때 error.message 는 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')이고, 시간 초과일 때도 다시 실행하지 말라는 안내가 담깁니다. |
5. 원천세 정기신고 3단계 소득명세 저장hometax. tax. withholding. regular_ report. detail_ save
MCP 도구 이름 hometax__
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
원천세 정기신고 3단계 소득명세 저장합니다.
- 홈택스 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [홈택스 로그인(세션 생성)]
- 요청 예시는 basic_save 에서 employment 만 선택한 경우의 명세 구조입니다.인원과 금액의 0은 예시이므로 실제 신고 값으로 바꾸세요. 다른 소득종류를 선택했다면 income_sections 에 그 소득종류 키를 더하고 rows 를 아래 표의 규칙대로 채웁니다(employment 만 전체 코드를 표의 순서대로 보내야 합니다).draft_id 와 expected_state_version 은 직전 응답 값을 사용합니다.
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 와 함께 쓰지 않습니다. |
- 대괄호 []는 목록의 각 항목을, 점은 객체의 속성을, {key}는 실제 키로 바꿔 넣는 사전 항목을 뜻하며, 선택인 부모를 보낼 때 하위 필수 칸은 조건부로 표시합니다.
| 순번 | 변수명 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| draft_ | string | Y | init 응답의 draft_id 를 그대로 넣습니다. 어느 신고서를 작성 중인지 가리킵니다 | |
| expected_ | number | Y | 직전 단계 응답의 state_version 을 그대로 넣습니다(1 이상). 그사이 신고서가 바뀌어 값이 다르면 저장하지 않고 409 로 거절합니다 | |
| idempotency_ | string | Y | 같은 요청을 두 번 실행하지 않기 위한 키(8~128자). 키는 초안 하나 안에서 기억하므로 같은 초안의 다른 단계에는 새 값을 입력합니다. 같은 키로 다시 요청하면 다시 실행하지 않고 처음 결과를 돌려주므로, 재시도에는 같은 값을 입력합니다 | |
| detail_ | object | Y | 소득종류별 명세. income_sections 가 필수입니다 - 키는 basic_save 에서 고른 소득종류와 정확히 같아야 합니다. 근로소득(employment)의 rows 에는 그 소득종류의 행 코드(code)를 정해진 순서대로 모두 입력합니다. 그 밖의 소득종류의 rows 에는 그 소득종류에서 쓸 수 있는 행 코드 가운데 신고할 행만 입력하고, 같은 코드를 두 번 입력하지 않습니다. 행마다 인원(inc_pymn_nfp_cnt) · 총지급액(inc_pymn_tota_pymn_amt) · 세액 칸을 채웁니다. previous_refund(이번 세액에서 먼저 빼는 환급세액, 0 이상 정수, 기본 0) · annex_choices · succession_popup 은 선택입니다 | |
| detail_ | object | Y | 소득 종류를 키로 하는 객체입니다. 키는 기본정보에 저장한 selected_income_types 와 정확히 같아야 합니다(employment, retirement, business, other). 별칭 incomeSections 로도 보낼 수 있습니다 | |
| detail_ | string | N | 소득 구분 표시 이름입니다. 계산 시 소득 종류의 표준 이름을 사용합니다. 생략 시 기본값: null | |
| detail_ | string | N | 소득 구분 자료 상태입니다. 계산 시 서버의 소득 구분 정의를 사용합니다. 별칭 evidenceStatus 로도 보낼 수 있습니다. 생략 시 기본값: null | |
| detail_ | array | Y | 소득 종류별 신고 행입니다. employment 는 행을 빠짐없이 아래 순서대로 보내고, 순서를 바꾸거나 빠뜨리면 거절합니다. 다른 소득은 그 소득의 행 코드 가운데 신고할 행만 보내며 순서는 상관없고 같은 코드는 한 번만 보냅니다. employment 가 아닌 행에서 그 행에 입력란이 없는 금액 칸은 null 또는 0 으로 보냅니다. employment: A01, A02, A03, A04, A05, A06; retirement: A21, A22; business: A25, A26, A27, A28; other: A41, A43, A44, A49, A59, A42 | |
| detail_ | string | Y | 신고 행 코드입니다. 상위 rows 설명의 소득 종류별 코드를 씁니다 | |
| detail_ | string | N | 신고 행 표시 이름입니다. 계산 시 코드에 해당하는 표준 이름을 사용합니다. 생략 시 기본값: null | |
| detail_ | number | N | 소득 지급 인원수입니다. null 또는 0 이상의 정수입니다. 지급 인원 합계가 양수면 지급 총액 합계도 양수여야 합니다. employment 가 아닌 행 가운데 인원과 총액을 함께 받는 행은 둘이 함께 0 이거나 함께 양수여야 합니다. 별칭 incPymnNfpCnt 로도 보낼 수 있습니다. 생략 시 기본값: null | |
| detail_ | number | N | 소득 지급 총액입니다. null 또는 0 이상의 정수입니다. 지급 인원 합계가 양수면 지급 총액 합계도 양수여야 합니다. employment 가 아닌 행 가운데 인원과 총액을 함께 받는 행은 둘이 함께 0 이거나 함께 양수여야 합니다. 별칭 incPymnTotaPymnAmt 로도 보낼 수 있습니다. 생략 시 기본값: null | |
| detail_ | number | N | 징수 소득세액입니다. null 또는 정수입니다. 음수는 retirement(퇴직소득) A21, A22, business(사업소득) A26, A28, other(기타소득) A44 행에서만 받고, 다른 행은 0 이상이어야 합니다. 별칭 inctxLvyTxamt 로도 보낼 수 있습니다. 생략 시 기본값: null | |
| detail_ | number | N | 징수 농어촌특별세액입니다. null 또는 정수입니다. 음수는 retirement(퇴직소득) A21, A22, business(사업소득) A26, A28, other(기타소득) A44 행에서만 받고, 다른 행은 0 이상이어야 합니다. 별칭 fnftxLvyTxamt 로도 보낼 수 있습니다. 생략 시 기본값: null | |
| detail_ | number | N | 징수 가산세액입니다. null 또는 0 이상의 정수입니다. 별칭 adttxLvyTxamt 로도 보낼 수 있습니다. 생략 시 기본값: null | |
| detail_ | number | N | 당월 조정 환급세액입니다. null 또는 0 이상의 정수입니다. 별칭 tmnMetnRfndTxamt 로도 보낼 수 있습니다. 생략 시 기본값: null | |
| detail_ | number | N | 납부 소득세액입니다. null 또는 0 이상의 정수입니다. 별칭 inctxPmtTxamt 로도 보낼 수 있습니다. 생략 시 기본값: null | |
| detail_ | number | N | 납부 농어촌특별세액입니다. null 또는 0 이상의 정수입니다. 별칭 fnftxPmtTxamt 로도 보낼 수 있습니다. 생략 시 기본값: null | |
| detail_ | number | N | 전월 미환급 세액입니다. 0 이상의 정수로 보냅니다. 별칭 previousRefund 로도 보낼 수 있습니다. 생략 시 기본값: 0 | |
| detail_ | object | N | 부표 선택값을 담은 객체로 각 값은 true 또는 false 입니다. 별칭 annexChoices 로도 보낼 수 있습니다 | |
| detail_ | object | N | 승계명세 팝업 입력 객체입니다. 사용하지 않으면 생략합니다. 별칭 successionPopup 로도 보낼 수 있습니다 |
- 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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: detail_save-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "hometax",
"action": "hometax.tax.withholding.regular_report.detail_save",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {
"draft_id": "<필수>",
"expected_state_version": "<필수: number>",
"idempotency_key": "<필수>",
"detail_document": {
"income_sections": {
"employment": {
"rows": [
{
"code": "A01",
"inc_pymn_nfp_cnt": 0,
"inc_pymn_tota_pymn_amt": 0
},
{
"code": "A02",
"inc_pymn_nfp_cnt": 0,
"inc_pymn_tota_pymn_amt": 0
},
{
"code": "A03",
"inc_pymn_nfp_cnt": 0,
"inc_pymn_tota_pymn_amt": 0
},
{
"code": "A04",
"inc_pymn_nfp_cnt": 0,
"inc_pymn_tota_pymn_amt": 0
},
{
"code": "A05",
"inc_pymn_nfp_cnt": 0,
"inc_pymn_tota_pymn_amt": 0
},
{
"code": "A06",
"inc_pymn_nfp_cnt": 0,
"inc_pymn_tota_pymn_amt": 0
}
]
}
}
}
}
}'Response
- 아래 표의 칸은 작업이 SUCCEEDED 가 된 뒤 GET /v1/jobs/{job_id}/result 의 result.data 에 오고, 응답 예시는 작업을 제출했을 때(POST /v1/jobs)의 응답입니다.
- 이 단계 처리가 끝나면 성공합니다. result.data.state 로 어느 단계까지 끝났는지, result.data.state_version 으로 다음 단계에 넣을 버전을 확인합니다.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| success | boolean | 작업이 성공하면 항상 true 로 고정된 값입니다 - 성패 판정에 쓸 수 없습니다 | |
| mode | string | 실행 모드 값. 지금 실제 홈택스로 처리될 때는 항상 문자열 "true" 가 옵니다 | |
| step | string | 이 응답이 어느 단계 결과인지 - init · basic_save · detail_save · review · preview · submit 중 하나 | |
| draft_ | string | 이 신고서 초안의 아이디. 다음 단계 호출에 그대로 넣습니다 | |
| state | string | 초안의 현재 상태. init 뒤 initialized, basic_save 뒤 basic_saved, detail_save 뒤 detail_saved, review 뒤 reviewed, preview 뒤 previewed, submit 뒤 submitted 로 차례로 바뀝니다. 건너뛰어 호출하면 오류표의 "단계 순서" 행으로 거절됩니다 | |
| state_ | number | 낙관적 동시성 버전. 다음 단계 호출의 expected_state_version 에 이 값을 그대로 넣습니다. 그사이 값이 바뀌었으면(같은 초안에 다른 요청이 먼저 반영되면) 저장하지 않고 거절합니다 | |
| data | object | 저장한 명세를 담은 객체입니다. 입력으로 계산한 신고서(semanticDocument - 소득종류별 명세 incomeSections, 합계 totals, 환급 조정 refundAdjustment 등), 홈택스에 보낸 본문(providerWireDocument), 검증 요약(evidence), 홈택스 응답 기록(providerResponses, actionEvidence)과 경고(warnings)가 들어 있습니다. | |
| warnings | array | 늘 빈 배열입니다. 이 단계의 경고는 data 의 warnings 에 실리며, 경고가 있어도 처리는 성공한 것입니다 |
{
"job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
"status": "QUEUED",
"env_scope": "real_test",
"provider": "hometax",
"action": "hometax.tax.withholding.regular_report.detail_save",
"submitted_at": "2026-05-27T12:34:56+09:00"
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| POLICY_ | 일시 중지 — 이 기능이 일시 중지된 동안에는 여섯 단계 모두 이 코드로 끝나며, 자동 재시도 대상이 아니니 error.message 안내대로 잠시 후 직접 다시 요청합니다. 계속 같은 코드가 오면 서비스문의로 알려 주세요. | |
| RESOURCE_ | 초안 없음 — draft_id 의 초안을 찾지 못했습니다. 직전 응답의 draft_id 를 다시 확인하고, 맞는데도 없으면 init 을 다시 호출해 새 초안으로 처음 단계부터 진행합니다. 초안은 서버 프로세스 메모리에만 있어 서버가 재시작되면 사라집니다. | |
| RESOURCE_ | 단계 순서·버전 불일치 — 이 단계를 부르기 전에 바로 앞 단계가 먼저 끝나 있어야 하고, expected_state_version 은 직전 응답의 state_version 과 같아야 합니다. 초안의 지금 상태나 버전이 맞지 않으면 저장하지 않고 거절하며, error.message 가 지금 상태나 지금 버전을 알려 줍니다. 이 API 에는 초안을 따로 조회하는 동작이 없으니 그 값과 직전 응답으로 이어 갈 단계와 버전을 정해 같은 초안으로 다시 보냅니다. 다른 연동 계정으로 만든 초안을 부를 때도 같은 코드이며, 그때는 초안을 만들 때 쓴 연동 계정으로 다시 요청합니다. | |
| VALIDATION_ | 요청 값 오류 — 필요한 값이 빠졌거나 보낸 값이 이 단계 요청 형식과 맞지 않거나 이 단계에 없는 필드를 보내면 이 코드로 끝납니다(예: idempotency_key 가 8자 미만). error.message 의 빠진 값은 넣고 확인할 값은 고쳐 다시 보냅니다. | |
| VALIDATION_ | 입력 값 오류 — detail_document 가 요청 형식에 맞아도 신고 규칙에 맞지 않으면 명세를 저장하지 않고 이 코드로 끝나며, 자동 재시도 대상이 아닙니다(이 확인은 홈택스에서 신고서 상태를 읽은 뒤에 합니다). incomeSections 가 basic_save 에서 고른 소득 종류와 맞지 않으면 error.message 가 그렇다고 알려 주니 고른 소득 종류대로 채우고, previousRefund 가 음수인 것처럼 어느 칸인지 알려 주지 않는 경우도 있으니 요청 표의 형식대로 detail_document 를 확인해 고친 뒤 다시 요청합니다. | |
| PROVIDER_ | 업무 오류 — 홈택스가 이 단계를 받지 않았다는 뜻이며, error.message 의 홈택스 사유를 해결한 뒤 같은 단계를 다시 요청합니다. 홈택스가 사유를 알려 주지 않은 경우에는 입력값을 그대로 두고 잠시 후 다시 시도하라는 안내가 담깁니다. | |
| VALIDATION_ | 신고 불가 판정 — 이 단계가 홈택스에서 신고서 상태를 확인할 때 홈택스가 지금 이 신고를 받을 수 없다고 답하면 그 자리에서 멈추고, error.message 가 까닭과 할 일을 알려 줍니다. 선택한 연월이 지금 정기신고 기간이 아니면(이 상품은 월별 정기신고만 하며, 기한이 지난 연월은 홈택스에서 직접 신고합니다), 또는 신고 기한을 확인하지 못했거나 신고서를 찾지 못했으면 신고 기간(periods)을 확인해 init 부터 다시 요청합니다. 연결된 계정의 사업자가 이 신고의 대상이 아니면 원천세를 신고할 사업자의 홈택스 계정으로 연결했는지 확인합니다. 로그인이 필요하다는 답이면 로그인 액션을 다시 실행한 뒤 init 부터 새 초안으로 진행합니다. 그 밖의 답이면 홈택스에서 같은 기간의 신고 상태를 확인합니다. | |
| RESOURCE_ | 신고 불가 판정 — 이 단계가 홈택스에서 신고서 상태를 확인할 때 홈택스가 지금 이 신고를 받을 수 없다고 답하면 그 자리에서 멈추고, error.message 가 까닭과 할 일을 알려 줍니다. 선택한 연월이 지금 정기신고 기간이 아니면(이 상품은 월별 정기신고만 하며, 기한이 지난 연월은 홈택스에서 직접 신고합니다), 또는 신고 기한을 확인하지 못했거나 신고서를 찾지 못했으면 신고 기간(periods)을 확인해 init 부터 다시 요청합니다. 연결된 계정의 사업자가 이 신고의 대상이 아니면 원천세를 신고할 사업자의 홈택스 계정으로 연결했는지 확인합니다. 로그인이 필요하다는 답이면 로그인 액션을 다시 실행한 뒤 init 부터 새 초안으로 진행합니다. 그 밖의 답이면 홈택스에서 같은 기간의 신고 상태를 확인합니다. | |
| AUTH_ | 신고 불가 판정 — 이 단계가 홈택스에서 신고서 상태를 확인할 때 홈택스가 지금 이 신고를 받을 수 없다고 답하면 그 자리에서 멈추고, error.message 가 까닭과 할 일을 알려 줍니다. 선택한 연월이 지금 정기신고 기간이 아니면(이 상품은 월별 정기신고만 하며, 기한이 지난 연월은 홈택스에서 직접 신고합니다), 또는 신고 기한을 확인하지 못했거나 신고서를 찾지 못했으면 신고 기간(periods)을 확인해 init 부터 다시 요청합니다. 연결된 계정의 사업자가 이 신고의 대상이 아니면 원천세를 신고할 사업자의 홈택스 계정으로 연결했는지 확인합니다. 로그인이 필요하다는 답이면 로그인 액션을 다시 실행한 뒤 init 부터 새 초안으로 진행합니다. 그 밖의 답이면 홈택스에서 같은 기간의 신고 상태를 확인합니다. | |
| RESOURCE_ | 신고 불가 판정 — 이 단계가 홈택스에서 신고서 상태를 확인할 때 홈택스가 지금 이 신고를 받을 수 없다고 답하면 그 자리에서 멈추고, error.message 가 까닭과 할 일을 알려 줍니다. 선택한 연월이 지금 정기신고 기간이 아니면(이 상품은 월별 정기신고만 하며, 기한이 지난 연월은 홈택스에서 직접 신고합니다), 또는 신고 기한을 확인하지 못했거나 신고서를 찾지 못했으면 신고 기간(periods)을 확인해 init 부터 다시 요청합니다. 연결된 계정의 사업자가 이 신고의 대상이 아니면 원천세를 신고할 사업자의 홈택스 계정으로 연결했는지 확인합니다. 로그인이 필요하다는 답이면 로그인 액션을 다시 실행한 뒤 init 부터 새 초안으로 진행합니다. 그 밖의 답이면 홈택스에서 같은 기간의 신고 상태를 확인합니다. | |
| PROVIDER_ | 세션 만료 — 이 단계를 부르는 도중 홈택스 로그인 세션이 끝나 있으면 이 코드로 끝나며, 로그인 액션을 다시 실행한 뒤 init 부터 새 초안으로 처음부터 진행합니다. 이미 연 초안은 처음 연 때의 세션을 계속 쓰므로 로그인을 다시 해도 같은 draft_id 는 새 세션을 쓰지 않습니다. | |
| INTERNAL_ | 홈택스 통신 오류 — 홈택스와 주고받는 도중 연결이 끊기거나 홈택스가 정상 응답을 주지 않으면 이 단계는 이 코드로 끝나며, 자동 재시도 대상이 아닙니다. error.message 안내대로 잠시 후 같은 단계를 다시 요청하고, 계속되면 서비스문의로 알려 주세요. | |
| INTERNAL_ | 처리 결과 모름 — 예상하지 못한 오류나 시간 초과로 끝나면 이 단계가 홈택스에 반영됐는지 알 수 없으니, 같은 단계를 다시 실행하지 않고 서비스문의로 알려 주세요. 예상하지 못한 오류일 때 error.message 는 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')이고, 시간 초과일 때도 다시 실행하지 말라는 안내가 담깁니다. | |
| JOB_ | 처리 결과 모름 — 예상하지 못한 오류나 시간 초과로 끝나면 이 단계가 홈택스에 반영됐는지 알 수 없으니, 같은 단계를 다시 실행하지 않고 서비스문의로 알려 주세요. 예상하지 못한 오류일 때 error.message 는 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')이고, 시간 초과일 때도 다시 실행하지 말라는 안내가 담깁니다. |
6. 원천세 정기신고 4단계 검증hometax. tax. withholding. regular_ report. review
MCP 도구 이름 hometax__
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
원천세 정기신고 4단계 검증합니다.
- 홈택스 로그인을 먼저 호출해 세션을 만든 뒤, 같은 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 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| draft_ | string | Y | init 응답의 draft_id 를 그대로 넣습니다. 어느 신고서를 작성 중인지 가리킵니다 | |
| expected_ | number | Y | 직전 단계 응답의 state_version 을 그대로 넣습니다(1 이상). 그사이 신고서가 바뀌어 값이 다르면 저장하지 않고 409 로 거절합니다 | |
| idempotency_ | string | Y | 같은 요청을 두 번 실행하지 않기 위한 키(8~128자). 키는 초안 하나 안에서 기억하므로 같은 초안의 다른 단계에는 새 값을 입력합니다. 같은 키로 다시 요청하면 다시 실행하지 않고 처음 결과를 돌려주므로, 재시도에는 같은 값을 입력합니다 | |
| annex_ | object | N | review 단계에서만 읽습니다. choices 를 넣으면 detail_save 때의 annex_choices 를 이 값으로 바꾸고, 보내지 않으면 그 값을 그대로 씁니다 |
- 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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: review-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "hometax",
"action": "hometax.tax.withholding.regular_report.review",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {
"draft_id": "<필수>",
"expected_state_version": "<필수: number>",
"idempotency_key": "<필수>"
}
}'Response
- 아래 표의 칸은 작업이 SUCCEEDED 가 된 뒤 GET /v1/jobs/{job_id}/result 의 result.data 에 오고, 응답 예시는 작업을 제출했을 때(POST /v1/jobs)의 응답입니다.
- 이 단계 처리가 끝나면 성공합니다. result.data.state 로 어느 단계까지 끝났는지, result.data.state_version 으로 다음 단계에 넣을 버전을 확인합니다.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| success | boolean | 작업이 성공하면 항상 true 로 고정된 값입니다 - 성패 판정에 쓸 수 없습니다 | |
| mode | string | 실행 모드 값. 지금 실제 홈택스로 처리될 때는 항상 문자열 "true" 가 옵니다 | |
| step | string | 이 응답이 어느 단계 결과인지 - init · basic_save · detail_save · review · preview · submit 중 하나 | |
| draft_ | string | 이 신고서 초안의 아이디. 다음 단계 호출에 그대로 넣습니다 | |
| state | string | 초안의 현재 상태. init 뒤 initialized, basic_save 뒤 basic_saved, detail_save 뒤 detail_saved, review 뒤 reviewed, preview 뒤 previewed, submit 뒤 submitted 로 차례로 바뀝니다. 건너뛰어 호출하면 오류표의 "단계 순서" 행으로 거절됩니다 | |
| state_ | number | 낙관적 동시성 버전. 다음 단계 호출의 expected_state_version 에 이 값을 그대로 넣습니다. 그사이 값이 바뀌었으면(같은 초안에 다른 요청이 먼저 반영되면) 저장하지 않고 거절합니다 | |
| data | object | 검증 결과 신고서(review)를 담은 객체입니다. | |
| warnings | array | 늘 빈 배열입니다. 이 단계의 경고는 data 의 warnings 에 실리며, 경고가 있어도 처리는 성공한 것입니다 |
{
"job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
"status": "QUEUED",
"env_scope": "real_test",
"provider": "hometax",
"action": "hometax.tax.withholding.regular_report.review",
"submitted_at": "2026-05-27T12:34:56+09:00"
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| POLICY_ | 일시 중지 — 이 기능이 일시 중지된 동안에는 여섯 단계 모두 이 코드로 끝나며, 자동 재시도 대상이 아니니 error.message 안내대로 잠시 후 직접 다시 요청합니다. 계속 같은 코드가 오면 서비스문의로 알려 주세요. | |
| RESOURCE_ | 초안 없음 — draft_id 의 초안을 찾지 못했습니다. 직전 응답의 draft_id 를 다시 확인하고, 맞는데도 없으면 init 을 다시 호출해 새 초안으로 처음 단계부터 진행합니다. 초안은 서버 프로세스 메모리에만 있어 서버가 재시작되면 사라집니다. | |
| RESOURCE_ | 단계 순서·버전 불일치 — 이 단계를 부르기 전에 바로 앞 단계가 먼저 끝나 있어야 하고, expected_state_version 은 직전 응답의 state_version 과 같아야 합니다. 초안의 지금 상태나 버전이 맞지 않으면 저장하지 않고 거절하며, error.message 가 지금 상태나 지금 버전을 알려 줍니다. 이 API 에는 초안을 따로 조회하는 동작이 없으니 그 값과 직전 응답으로 이어 갈 단계와 버전을 정해 같은 초안으로 다시 보냅니다. 다른 연동 계정으로 만든 초안을 부를 때도 같은 코드이며, 그때는 초안을 만들 때 쓴 연동 계정으로 다시 요청합니다. | |
| VALIDATION_ | 요청 값 오류 — 필요한 값이 빠졌거나 보낸 값이 이 단계 요청 형식과 맞지 않거나 이 단계에 없는 필드를 보내면 이 코드로 끝납니다(예: idempotency_key 가 8자 미만). error.message 의 빠진 값은 넣고 확인할 값은 고쳐 다시 보냅니다. | |
| VALIDATION_ | 내용검증 오류 — 작성완료 요청 뒤 홈택스 내용검증이 오류를 찾으면 작성완료가 되지 않고 이 코드로 끝나며, error.message 가 홈택스가 적은 오류 항목을 알려 줍니다(항목을 읽지 못하면 홈택스에서 확인하는 길을 알려 줍니다). 초안은 명세 저장 상태와 버전 그대로 남으니 항목 값을 고쳐 같은 draft_id 로 detail_save 부터 다시 진행합니다. | |
| PROVIDER_ | 업무 오류 — 홈택스가 이 단계를 받지 않았다는 뜻이며, error.message 의 홈택스 사유를 해결한 뒤 같은 단계를 다시 요청합니다. 홈택스가 사유를 알려 주지 않은 경우에는 입력값을 그대로 두고 잠시 후 다시 시도하라는 안내가 담깁니다. | |
| VALIDATION_ | 신고 불가 판정 — 이 단계가 홈택스에서 신고서 상태를 확인할 때 홈택스가 지금 이 신고를 받을 수 없다고 답하면 그 자리에서 멈추고, error.message 가 까닭과 할 일을 알려 줍니다. 선택한 연월이 지금 정기신고 기간이 아니면(이 상품은 월별 정기신고만 하며, 기한이 지난 연월은 홈택스에서 직접 신고합니다), 또는 신고 기한을 확인하지 못했거나 신고서를 찾지 못했으면 신고 기간(periods)을 확인해 init 부터 다시 요청합니다. 연결된 계정의 사업자가 이 신고의 대상이 아니면 원천세를 신고할 사업자의 홈택스 계정으로 연결했는지 확인합니다. 로그인이 필요하다는 답이면 로그인 액션을 다시 실행한 뒤 init 부터 새 초안으로 진행합니다. 그 밖의 답이면 홈택스에서 같은 기간의 신고 상태를 확인합니다. | |
| RESOURCE_ | 신고 불가 판정 — 이 단계가 홈택스에서 신고서 상태를 확인할 때 홈택스가 지금 이 신고를 받을 수 없다고 답하면 그 자리에서 멈추고, error.message 가 까닭과 할 일을 알려 줍니다. 선택한 연월이 지금 정기신고 기간이 아니면(이 상품은 월별 정기신고만 하며, 기한이 지난 연월은 홈택스에서 직접 신고합니다), 또는 신고 기한을 확인하지 못했거나 신고서를 찾지 못했으면 신고 기간(periods)을 확인해 init 부터 다시 요청합니다. 연결된 계정의 사업자가 이 신고의 대상이 아니면 원천세를 신고할 사업자의 홈택스 계정으로 연결했는지 확인합니다. 로그인이 필요하다는 답이면 로그인 액션을 다시 실행한 뒤 init 부터 새 초안으로 진행합니다. 그 밖의 답이면 홈택스에서 같은 기간의 신고 상태를 확인합니다. | |
| AUTH_ | 신고 불가 판정 — 이 단계가 홈택스에서 신고서 상태를 확인할 때 홈택스가 지금 이 신고를 받을 수 없다고 답하면 그 자리에서 멈추고, error.message 가 까닭과 할 일을 알려 줍니다. 선택한 연월이 지금 정기신고 기간이 아니면(이 상품은 월별 정기신고만 하며, 기한이 지난 연월은 홈택스에서 직접 신고합니다), 또는 신고 기한을 확인하지 못했거나 신고서를 찾지 못했으면 신고 기간(periods)을 확인해 init 부터 다시 요청합니다. 연결된 계정의 사업자가 이 신고의 대상이 아니면 원천세를 신고할 사업자의 홈택스 계정으로 연결했는지 확인합니다. 로그인이 필요하다는 답이면 로그인 액션을 다시 실행한 뒤 init 부터 새 초안으로 진행합니다. 그 밖의 답이면 홈택스에서 같은 기간의 신고 상태를 확인합니다. | |
| RESOURCE_ | 신고 불가 판정 — 이 단계가 홈택스에서 신고서 상태를 확인할 때 홈택스가 지금 이 신고를 받을 수 없다고 답하면 그 자리에서 멈추고, error.message 가 까닭과 할 일을 알려 줍니다. 선택한 연월이 지금 정기신고 기간이 아니면(이 상품은 월별 정기신고만 하며, 기한이 지난 연월은 홈택스에서 직접 신고합니다), 또는 신고 기한을 확인하지 못했거나 신고서를 찾지 못했으면 신고 기간(periods)을 확인해 init 부터 다시 요청합니다. 연결된 계정의 사업자가 이 신고의 대상이 아니면 원천세를 신고할 사업자의 홈택스 계정으로 연결했는지 확인합니다. 로그인이 필요하다는 답이면 로그인 액션을 다시 실행한 뒤 init 부터 새 초안으로 진행합니다. 그 밖의 답이면 홈택스에서 같은 기간의 신고 상태를 확인합니다. | |
| PROVIDER_ | 세션 만료 — 이 단계를 부르는 도중 홈택스 로그인 세션이 끝나 있으면 이 코드로 끝나며, 로그인 액션을 다시 실행한 뒤 init 부터 새 초안으로 처음부터 진행합니다. 이미 연 초안은 처음 연 때의 세션을 계속 쓰므로 로그인을 다시 해도 같은 draft_id 는 새 세션을 쓰지 않습니다. | |
| INTERNAL_ | 홈택스 통신 오류 — 홈택스와 주고받는 도중 연결이 끊기거나 홈택스가 정상 응답을 주지 않으면 이 단계는 이 코드로 끝나며, 자동 재시도 대상이 아닙니다. error.message 안내대로 잠시 후 같은 단계를 다시 요청하고, 계속되면 서비스문의로 알려 주세요. | |
| INTERNAL_ | 처리 결과 모름 — 예상하지 못한 오류나 시간 초과로 끝나면 이 단계가 홈택스에 반영됐는지 알 수 없으니, 같은 단계를 다시 실행하지 않고 서비스문의로 알려 주세요. 예상하지 못한 오류일 때 error.message 는 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')이고, 시간 초과일 때도 다시 실행하지 말라는 안내가 담깁니다. | |
| JOB_ | 처리 결과 모름 — 예상하지 못한 오류나 시간 초과로 끝나면 이 단계가 홈택스에 반영됐는지 알 수 없으니, 같은 단계를 다시 실행하지 않고 서비스문의로 알려 주세요. 예상하지 못한 오류일 때 error.message 는 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')이고, 시간 초과일 때도 다시 실행하지 말라는 안내가 담깁니다. |
7. 원천세 정기신고 5단계 미리보기hometax. tax. withholding. regular_ report. preview
MCP 도구 이름 hometax__
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
원천세 정기신고 5단계 미리보기합니다.
- 홈택스 로그인을 먼저 호출해 세션을 만든 뒤, 같은 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 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| draft_ | string | Y | init 응답의 draft_id 를 그대로 넣습니다. 어느 신고서를 작성 중인지 가리킵니다 | |
| expected_ | number | Y | 직전 단계 응답의 state_version 을 그대로 넣습니다(1 이상). 그사이 신고서가 바뀌어 값이 다르면 저장하지 않고 409 로 거절합니다 | |
| idempotency_ | string | Y | 같은 요청을 두 번 실행하지 않기 위한 키(8~128자). 키는 초안 하나 안에서 기억하므로 같은 초안의 다른 단계에는 새 값을 입력합니다. 같은 키로 다시 요청하면 다시 실행하지 않고 처음 결과를 돌려주므로, 재시도에는 같은 값을 입력합니다 | |
| annex_ | object | N | review 단계에서만 읽습니다. choices 를 넣으면 detail_save 때의 annex_choices 를 이 값으로 바꾸고, 보내지 않으면 그 값을 그대로 씁니다 |
- 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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: preview-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "hometax",
"action": "hometax.tax.withholding.regular_report.preview",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {
"draft_id": "<필수>",
"expected_state_version": "<필수: number>",
"idempotency_key": "<필수>"
}
}'Response
- 아래 표의 칸은 작업이 SUCCEEDED 가 된 뒤 GET /v1/jobs/{job_id}/result 의 result.data 에 오고, 응답 예시는 작업을 제출했을 때(POST /v1/jobs)의 응답입니다.
- 이 단계 처리가 끝나면 성공합니다. result.data.state 로 어느 단계까지 끝났는지, result.data.state_version 으로 다음 단계에 넣을 버전을 확인합니다.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| success | boolean | 작업이 성공하면 항상 true 로 고정된 값입니다 - 성패 판정에 쓸 수 없습니다 | |
| mode | string | 실행 모드 값. 지금 실제 홈택스로 처리될 때는 항상 문자열 "true" 가 옵니다 | |
| step | string | 이 응답이 어느 단계 결과인지 - init · basic_save · detail_save · review · preview · submit 중 하나 | |
| draft_ | string | 이 신고서 초안의 아이디. 다음 단계 호출에 그대로 넣습니다 | |
| state | string | 초안의 현재 상태. init 뒤 initialized, basic_save 뒤 basic_saved, detail_save 뒤 detail_saved, review 뒤 reviewed, preview 뒤 previewed, submit 뒤 submitted 로 차례로 바뀝니다. 건너뛰어 호출하면 오류표의 "단계 순서" 행으로 거절됩니다 | |
| state_ | number | 낙관적 동시성 버전. 다음 단계 호출의 expected_state_version 에 이 값을 그대로 넣습니다. 그사이 값이 바뀌었으면(같은 초안에 다른 요청이 먼저 반영되면) 저장하지 않고 거절합니다 | |
| data | object | 제출 전 미리보기 신고서(preview)를 담은 객체입니다. | |
| warnings | array | 늘 빈 배열입니다. 이 단계의 경고는 data 의 warnings 에 실리며, 경고가 있어도 처리는 성공한 것입니다 |
{
"job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
"status": "QUEUED",
"env_scope": "real_test",
"provider": "hometax",
"action": "hometax.tax.withholding.regular_report.preview",
"submitted_at": "2026-05-27T12:34:56+09:00"
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| POLICY_ | 일시 중지 — 이 기능이 일시 중지된 동안에는 여섯 단계 모두 이 코드로 끝나며, 자동 재시도 대상이 아니니 error.message 안내대로 잠시 후 직접 다시 요청합니다. 계속 같은 코드가 오면 서비스문의로 알려 주세요. | |
| RESOURCE_ | 초안 없음 — draft_id 의 초안을 찾지 못했습니다. 직전 응답의 draft_id 를 다시 확인하고, 맞는데도 없으면 init 을 다시 호출해 새 초안으로 처음 단계부터 진행합니다. 초안은 서버 프로세스 메모리에만 있어 서버가 재시작되면 사라집니다. | |
| RESOURCE_ | 단계 순서·버전 불일치 — 이 단계를 부르기 전에 바로 앞 단계가 먼저 끝나 있어야 하고, expected_state_version 은 직전 응답의 state_version 과 같아야 합니다. 초안의 지금 상태나 버전이 맞지 않으면 저장하지 않고 거절하며, error.message 가 지금 상태나 지금 버전을 알려 줍니다. 이 API 에는 초안을 따로 조회하는 동작이 없으니 그 값과 직전 응답으로 이어 갈 단계와 버전을 정해 같은 초안으로 다시 보냅니다. 다른 연동 계정으로 만든 초안을 부를 때도 같은 코드이며, 그때는 초안을 만들 때 쓴 연동 계정으로 다시 요청합니다. | |
| VALIDATION_ | 요청 값 오류 — 필요한 값이 빠졌거나 보낸 값이 이 단계 요청 형식과 맞지 않거나 이 단계에 없는 필드를 보내면 이 코드로 끝납니다(예: idempotency_key 가 8자 미만). error.message 의 빠진 값은 넣고 확인할 값은 고쳐 다시 보냅니다. | |
| PROVIDER_ | 업무 오류 — 홈택스가 이 단계를 받지 않았다는 뜻이며, error.message 의 홈택스 사유를 해결한 뒤 같은 단계를 다시 요청합니다. 홈택스가 사유를 알려 주지 않은 경우에는 입력값을 그대로 두고 잠시 후 다시 시도하라는 안내가 담깁니다. | |
| VALIDATION_ | 신고 불가 판정 — 이 단계가 홈택스에서 신고서 상태를 확인할 때 홈택스가 지금 이 신고를 받을 수 없다고 답하면 그 자리에서 멈추고, error.message 가 까닭과 할 일을 알려 줍니다. 선택한 연월이 지금 정기신고 기간이 아니면(이 상품은 월별 정기신고만 하며, 기한이 지난 연월은 홈택스에서 직접 신고합니다), 또는 신고 기한을 확인하지 못했거나 신고서를 찾지 못했으면 신고 기간(periods)을 확인해 init 부터 다시 요청합니다. 연결된 계정의 사업자가 이 신고의 대상이 아니면 원천세를 신고할 사업자의 홈택스 계정으로 연결했는지 확인합니다. 로그인이 필요하다는 답이면 로그인 액션을 다시 실행한 뒤 init 부터 새 초안으로 진행합니다. 그 밖의 답이면 홈택스에서 같은 기간의 신고 상태를 확인합니다. | |
| RESOURCE_ | 신고 불가 판정 — 이 단계가 홈택스에서 신고서 상태를 확인할 때 홈택스가 지금 이 신고를 받을 수 없다고 답하면 그 자리에서 멈추고, error.message 가 까닭과 할 일을 알려 줍니다. 선택한 연월이 지금 정기신고 기간이 아니면(이 상품은 월별 정기신고만 하며, 기한이 지난 연월은 홈택스에서 직접 신고합니다), 또는 신고 기한을 확인하지 못했거나 신고서를 찾지 못했으면 신고 기간(periods)을 확인해 init 부터 다시 요청합니다. 연결된 계정의 사업자가 이 신고의 대상이 아니면 원천세를 신고할 사업자의 홈택스 계정으로 연결했는지 확인합니다. 로그인이 필요하다는 답이면 로그인 액션을 다시 실행한 뒤 init 부터 새 초안으로 진행합니다. 그 밖의 답이면 홈택스에서 같은 기간의 신고 상태를 확인합니다. | |
| AUTH_ | 신고 불가 판정 — 이 단계가 홈택스에서 신고서 상태를 확인할 때 홈택스가 지금 이 신고를 받을 수 없다고 답하면 그 자리에서 멈추고, error.message 가 까닭과 할 일을 알려 줍니다. 선택한 연월이 지금 정기신고 기간이 아니면(이 상품은 월별 정기신고만 하며, 기한이 지난 연월은 홈택스에서 직접 신고합니다), 또는 신고 기한을 확인하지 못했거나 신고서를 찾지 못했으면 신고 기간(periods)을 확인해 init 부터 다시 요청합니다. 연결된 계정의 사업자가 이 신고의 대상이 아니면 원천세를 신고할 사업자의 홈택스 계정으로 연결했는지 확인합니다. 로그인이 필요하다는 답이면 로그인 액션을 다시 실행한 뒤 init 부터 새 초안으로 진행합니다. 그 밖의 답이면 홈택스에서 같은 기간의 신고 상태를 확인합니다. | |
| RESOURCE_ | 신고 불가 판정 — 이 단계가 홈택스에서 신고서 상태를 확인할 때 홈택스가 지금 이 신고를 받을 수 없다고 답하면 그 자리에서 멈추고, error.message 가 까닭과 할 일을 알려 줍니다. 선택한 연월이 지금 정기신고 기간이 아니면(이 상품은 월별 정기신고만 하며, 기한이 지난 연월은 홈택스에서 직접 신고합니다), 또는 신고 기한을 확인하지 못했거나 신고서를 찾지 못했으면 신고 기간(periods)을 확인해 init 부터 다시 요청합니다. 연결된 계정의 사업자가 이 신고의 대상이 아니면 원천세를 신고할 사업자의 홈택스 계정으로 연결했는지 확인합니다. 로그인이 필요하다는 답이면 로그인 액션을 다시 실행한 뒤 init 부터 새 초안으로 진행합니다. 그 밖의 답이면 홈택스에서 같은 기간의 신고 상태를 확인합니다. | |
| PROVIDER_ | 세션 만료 — 이 단계를 부르는 도중 홈택스 로그인 세션이 끝나 있으면 이 코드로 끝나며, 로그인 액션을 다시 실행한 뒤 init 부터 새 초안으로 처음부터 진행합니다. 이미 연 초안은 처음 연 때의 세션을 계속 쓰므로 로그인을 다시 해도 같은 draft_id 는 새 세션을 쓰지 않습니다. | |
| INTERNAL_ | 홈택스 통신 오류 — 홈택스와 주고받는 도중 연결이 끊기거나 홈택스가 정상 응답을 주지 않으면 이 단계는 이 코드로 끝나며, 자동 재시도 대상이 아닙니다. error.message 안내대로 잠시 후 같은 단계를 다시 요청하고, 계속되면 서비스문의로 알려 주세요. |
8. 원천세 정기신고 6단계 제출hometax. tax. withholding. regular_ report. submit
MCP 도구 이름 hometax__
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
원천세 정기신고 6단계 제출합니다. 응답을 받지 못해 다시 보낼 때는 같은 Idempotency-Key를 씁니다.
- 홈택스 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [홈택스 로그인(세션 생성)]
- 요청 거절(HTTP 400, 작업은 만들어지지 않음).error.code=WRITE_CONFIRMATION_REQUIRED — confirmation_token 없이 이 단계를 부르면 홈택스에 아무것도 보내지 않고 이 오류로 끝납니다.error.message 에 확인할 내용이, error.confirmation_token 에 1회용 토큰이 함께 옵니다(error.preview 도 오지만 이 단계에서는 비어 있습니다).안내를 사용자에게 보여 주고 동의를 받은 뒤 같은 요청의 params.confirmation_token 에 그 토큰을 넣어 다시 보냅니다. 토큰은 10분 안에 한 번만 쓸 수 있고 처음 요청과 같은 본문에만 맞습니다.
- 요청 거절(HTTP 409, 작업은 만들어지지 않음).error.code=WRITE_CONFIRMATION_INVALID — 토큰이 만료됐거나, 이미 썼거나, 다른 호출자나 다른 환경에서 받은 것이거나, 확인한 요청 본문과 달라졌으면 홈택스에 아무것도 보내지 않고 이 오류로 끝나며 어느 쪽인지는 알려 주지 않습니다.error.message 는 「확인이 만료됐거나 확인한 내용과 달라졌습니다. 다시 확인해 주세요.」 입니다. confirmation_token 없이 같은 요청을 다시 보내 새 토큰과 안내를 받은 뒤 사용자에게 다시 확인을 받습니다.
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 파라미터 표의 필수 항목을 채우고 sbms_agreement 또는 sbms_agr 중 하나 이상을 함께 보냅니다. | |
| encrypted_ | object | - | N | 민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| draft_ | string | Y | init 응답의 draft_id 를 그대로 넣습니다. 어느 신고서를 작성 중인지 가리킵니다 | |
| expected_ | number | Y | 직전 단계 응답의 state_version 을 그대로 넣습니다(1 이상). 그사이 신고서가 바뀌어 값이 다르면 저장하지 않고 409 로 거절합니다 | |
| idempotency_ | string | Y | 같은 요청을 두 번 실행하지 않기 위한 키(8~128자). 키는 초안 하나 안에서 기억하므로 같은 초안의 다른 단계에는 새 값을 입력합니다. 같은 키로 다시 요청하면 다시 실행하지 않고 처음 결과를 돌려주므로, 재시도에는 같은 값을 입력합니다 | |
| confirm_ | boolean | Y | 제출 확인. 고객에게 preview 결과를 보여 주고 제출 동의를 받았을 때만 true 로 보냅니다. true 가 아니면 제출하지 않고 거절합니다. 제출은 되돌릴 수 없으니 자동으로 채우지 마세요 | |
| sbms_ | boolean | 조건부 | 신고 내용 동의(신고 화면의 '이에 동의합니다.' 체크와 같습니다). true 여야 제출합니다. sbms_agr 에 "1" 을 보내도 같은 뜻입니다 | |
| sbms_ | string | 조건부 | sbms_agreement 대신 쓰는 화면 값입니다. "1" 이면 동의로 봅니다 | |
| confirmation_ | string | N | 1회용 확인 토큰입니다. 처음에는 보내지 않습니다. 토큰 없이 부르면 기관에 아무것도 보내지 않고 작업도 만들지 않은 채 확인이 필요하다는 오류(WRITE_CONFIRMATION_REQUIRED)로 끝나고, 응답의 error.confirmation_token 에 토큰이 옵니다. error.message 의 안내를 사용자에게 보여 주고 동의를 받은 뒤 같은 요청에 이 토큰을 넣어 다시 부릅니다. 토큰은 10분 안에 한 번만 쓸 수 있고 처음 요청과 같은 본문, 같은 호출자, 같은 환경에서만 맞으며, 아니면 확인이 만료됐거나 내용이 달라졌다는 오류로 거절합니다 |
- 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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: submit-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "hometax",
"action": "hometax.tax.withholding.regular_report.submit",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {
"draft_id": "<필수>",
"expected_state_version": "<필수: number>",
"idempotency_key": "<필수>",
"confirm_submit": "<필수: boolean>",
"sbms_agreement": "<필수: boolean>"
}
}'Response
- 아래 표의 칸은 작업이 SUCCEEDED 가 된 뒤 GET /v1/jobs/{job_id}/result 의 result.data 에 오고, 응답 예시는 작업을 제출했을 때(POST /v1/jobs)의 응답입니다.
- 이 단계 처리가 끝나면 성공합니다. result.data.state 로 어느 단계까지 끝났는지, result.data.state_version 으로 다음 단계에 넣을 버전을 확인합니다.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| success | boolean | 작업이 성공하면 항상 true 로 고정된 값입니다 - 성패 판정에 쓸 수 없습니다 | |
| mode | string | 실행 모드 값. 지금 실제 홈택스로 처리될 때는 항상 문자열 "true" 가 옵니다 | |
| step | string | 이 응답이 어느 단계 결과인지 - init · basic_save · detail_save · review · preview · submit 중 하나 | |
| draft_ | string | 이 신고서 초안의 아이디. 다음 단계 호출에 그대로 넣습니다 | |
| state | string | 초안의 현재 상태. init 뒤 initialized, basic_save 뒤 basic_saved, detail_save 뒤 detail_saved, review 뒤 reviewed, preview 뒤 previewed, submit 뒤 submitted 로 차례로 바뀝니다. 건너뛰어 호출하면 오류표의 "단계 순서" 행으로 거절됩니다 | |
| state_ | number | 낙관적 동시성 버전. 다음 단계 호출의 expected_state_version 에 이 값을 그대로 넣습니다. 그사이 값이 바뀌었으면(같은 초안에 다른 요청이 먼저 반영되면) 저장하지 않고 거절합니다 | |
| data | object | 제출 결과(submit)를 담은 객체입니다. 접수번호 등 접수 확인 값이 여기 들어갑니다. | |
| warnings | array | 늘 빈 배열입니다. 이 단계의 경고는 data 의 warnings 에 실리며, 경고가 있어도 처리는 성공한 것입니다 |
{
"job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
"status": "QUEUED",
"env_scope": "real_test",
"provider": "hometax",
"action": "hometax.tax.withholding.regular_report.submit",
"submitted_at": "2026-05-27T12:34:56+09:00"
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| POLICY_ | 일시 중지 — 이 기능이 일시 중지된 동안에는 여섯 단계 모두 이 코드로 끝나며, 자동 재시도 대상이 아니니 error.message 안내대로 잠시 후 직접 다시 요청합니다. 계속 같은 코드가 오면 서비스문의로 알려 주세요. | |
| RESOURCE_ | 초안 없음 — draft_id 의 초안을 찾지 못했습니다. 직전 응답의 draft_id 를 다시 확인하고, 맞는데도 없으면 init 을 다시 호출해 새 초안으로 처음 단계부터 진행합니다. 초안은 서버 프로세스 메모리에만 있어 서버가 재시작되면 사라집니다. | |
| RESOURCE_ | 단계 순서·버전 불일치 — 이 단계를 부르기 전에 바로 앞 단계가 먼저 끝나 있어야 하고, expected_state_version 은 직전 응답의 state_version 과 같아야 합니다. 초안의 지금 상태나 버전이 맞지 않으면 저장하지 않고 거절하며, error.message 가 지금 상태나 지금 버전을 알려 줍니다. 이 API 에는 초안을 따로 조회하는 동작이 없으니 그 값과 직전 응답으로 이어 갈 단계와 버전을 정해 같은 초안으로 다시 보냅니다. 다른 연동 계정으로 만든 초안을 부를 때도 같은 코드이며, 그때는 초안을 만들 때 쓴 연동 계정으로 다시 요청합니다. 다만 제출 요청을 이미 보낸 초안을 다시 제출해 error.message 가 결과 확인 불가 안내로 시작하면 이 행이 아니라 제출 결과 모름 행을 따릅니다. | |
| VALIDATION_ | 제출 확인 누락 — 제출에는 confirmSubmit=true 와 (sbmsAgreement=true 또는 sbmsAgr="1") 이 모두 필요합니다. 고객에게 preview 결과를 보여 주고 동의를 받았을 때만 true 로 보냅니다 - 자동으로 채우지 않습니다. | |
| VALIDATION_ | 요청 값 오류 — 필요한 값이 빠졌거나 보낸 값이 이 단계 요청 형식과 맞지 않거나 이 단계에 없는 필드를 보내면 이 코드로 끝납니다(예: idempotency_key 가 8자 미만). error.message 의 빠진 값은 넣고 확인할 값은 고쳐 다시 보냅니다. | |
| INTERNAL_ | 제출 결과 모름 — 제출 요청이 홈택스로 나간 뒤에는 어떤 단계가 실패해도 접수 여부를 알 수 없으니, 같은 초안으로도 새 초안으로도 바로 다시 제출하지 않고 홈택스에서 접수 여부를 먼저 확인합니다. error.message 가 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')로 시작하면 이 경우이며, 안내하는 홈택스 화면에서 확인한 결과 접수되지 않았을 때만 새 초안으로 다시 진행합니다. 이미 제출 요청을 보낸 초안을 새 idempotency_key 로 다시 제출해도 같은 안내가 담긴 충돌 오류로 끝납니다. 작업이 정해진 시간 안에 끝나지 않아 시간 초과로 닫힌 경우에도 error.message 는 다시 실행하지 말라는 안내이므로 같은 방식으로 접수 여부를 먼저 확인합니다. | |
| RESOURCE_ | 제출 결과 모름 — 제출 요청이 홈택스로 나간 뒤에는 어떤 단계가 실패해도 접수 여부를 알 수 없으니, 같은 초안으로도 새 초안으로도 바로 다시 제출하지 않고 홈택스에서 접수 여부를 먼저 확인합니다. error.message 가 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')로 시작하면 이 경우이며, 안내하는 홈택스 화면에서 확인한 결과 접수되지 않았을 때만 새 초안으로 다시 진행합니다. 이미 제출 요청을 보낸 초안을 새 idempotency_key 로 다시 제출해도 같은 안내가 담긴 충돌 오류로 끝납니다. 작업이 정해진 시간 안에 끝나지 않아 시간 초과로 닫힌 경우에도 error.message 는 다시 실행하지 말라는 안내이므로 같은 방식으로 접수 여부를 먼저 확인합니다. | |
| JOB_ | 제출 결과 모름 — 제출 요청이 홈택스로 나간 뒤에는 어떤 단계가 실패해도 접수 여부를 알 수 없으니, 같은 초안으로도 새 초안으로도 바로 다시 제출하지 않고 홈택스에서 접수 여부를 먼저 확인합니다. error.message 가 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')로 시작하면 이 경우이며, 안내하는 홈택스 화면에서 확인한 결과 접수되지 않았을 때만 새 초안으로 다시 진행합니다. 이미 제출 요청을 보낸 초안을 새 idempotency_key 로 다시 제출해도 같은 안내가 담긴 충돌 오류로 끝납니다. 작업이 정해진 시간 안에 끝나지 않아 시간 초과로 닫힌 경우에도 error.message 는 다시 실행하지 말라는 안내이므로 같은 방식으로 접수 여부를 먼저 확인합니다. | |
| INTERNAL_ | 제출 전 중단 — 제출 요청이 홈택스로 나가기 전에 멈춘 경우로, error.message 안내대로 처리하고 같은 오류가 반복되면 로그인 액션을 다시 실행한 뒤 init 부터 새 초안으로 진행합니다. 이때 error.message 는 결과 확인 불가 안내로 시작하지 않으며, 홈택스 로그인 세션이 끝나 있거나 연결이 끊기면 제출 전 확인에서 이 코드로 끝나고 자동 재시도 대상이 아닙니다. | |
| RESOURCE_ | 저장 금액 불일치 — 제출 요청을 보내기 전에, preview 때 홈택스에 저장돼 있던 소득세나 농어촌특별세 납부세액이 계산한 합계와 다르면 제출하지 않고 이 코드로 끝납니다. error.message 가 두 금액을 알려 주니 값을 확인한 뒤 새 초안으로 처음부터 다시 진행합니다. 같은 차이는 preview 결과 data 의 warnings 에도 경고로 실립니다. | |
| VALIDATION_ | 제출 거절 — 제출 요청에 홈택스가 신고서를 받지 않았다고 분명히 답하면 접수되지 않은 것이라 제출 결과 모름이 아니며, error.message 가 그 까닭과 할 일을 알려 줍니다. 신고서 내용검증 오류(홈택스가 적은 오류 항목이 함께 옵니다), 신고서 오류, 제출할 신고서 없음, 검증이 완료되지 않은 채로 끝남이면 값을 확인해 새 초안으로 처음부터 다시 진행합니다. 신고 기간이 아니라는 답이면 신고 기간(periods)을 확인합니다. 검증이 아직 진행 중이거나 제출할 수 없는 시간(새벽 1시부터 6시까지)이면 잠시 후, 또는 그 시간이 지난 뒤 같은 초안으로 제출 단계를 다시 요청합니다. | |
| RESOURCE_ | 제출 거절 — 제출 요청에 홈택스가 신고서를 받지 않았다고 분명히 답하면 접수되지 않은 것이라 제출 결과 모름이 아니며, error.message 가 그 까닭과 할 일을 알려 줍니다. 신고서 내용검증 오류(홈택스가 적은 오류 항목이 함께 옵니다), 신고서 오류, 제출할 신고서 없음, 검증이 완료되지 않은 채로 끝남이면 값을 확인해 새 초안으로 처음부터 다시 진행합니다. 신고 기간이 아니라는 답이면 신고 기간(periods)을 확인합니다. 검증이 아직 진행 중이거나 제출할 수 없는 시간(새벽 1시부터 6시까지)이면 잠시 후, 또는 그 시간이 지난 뒤 같은 초안으로 제출 단계를 다시 요청합니다. | |
| AUTH_ | 제출 로그인 거절 — 제출 요청에 홈택스가 로그인 정보가 올바르지 않다고 답하면 접수되지 않은 것이며 이 코드로 끝나고, error.message 는 계정 연결을 다시 확인하라고 안내합니다. 이미 연 초안은 처음 연 때의 세션을 계속 쓰므로 로그인 액션을 다시 실행한 뒤 init 부터 새 초안으로 처음부터 진행합니다. |
9. 원천세 신고 접수 내역 조회hometax. tax. withholding. regular_ report. history
MCP 도구 이름 hometax__
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
기간을 정해 접수된 원천세 신고(정기신고, 수정신고, 기한후신고) 목록을 조회합니다.
- 홈택스 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [홈택스 로그인(세션 생성)]
- 조회 기간에 접수된 신고가 없으면 rows 가 빈 배열로 돌아옵니다. 실패가 아닙니다.
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 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 길이 | 필수 | 설명 |
|---|---|---|---|---|---|
| business_ | string | - | Y | 신고 내역을 조회할 사업자의 사업자등록번호입니다. 하이픈 없이 숫자 10자리로 보냅니다 | |
| start_ | string | 8 | Y | 조회 기간의 시작일입니다. 기간은 신고일(filing_date) 기준이며, 여덟 자리의 실제 날짜로 보내고 end_date 보다 늦으면 입력 오류로 거절합니다 | |
| end_ | string | 8 | Y | 조회 기간의 종료일입니다. 신고일(filing_date) 기준이며, 여덟 자리로 보내고 start_date 보다 빠를 수 없습니다 | |
| page_ | number | - | N | 받을 쪽 번호입니다. 1부터 세는 정수이고 보내지 않으면 1 입니다 | |
| page_ | number | - | N | 한 쪽에 받을 신고 수입니다. 1 이상 100 이하의 정수이고 보내지 않으면 10 입니다 |
- 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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: history-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "hometax",
"action": "hometax.tax.withholding.regular_report.history",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {
"business_no": "<필수>",
"start_date": "<필수>",
"end_date": "<필수>",
"page_num": 1,
"page_size": 10
}
}'Response
- 아래 표의 칸은 작업이 SUCCEEDED 가 된 뒤 GET /v1/jobs/{job_id}/result 의 result.data 에 오고, 응답 예시는 작업을 제출했을 때(POST /v1/jobs)의 응답입니다.
- result.data.data 의 rows 로 접수된 원천세 신고(정기신고, 수정신고, 기한후신고) 목록을, page 로 페이지 번호와 전체 건수를 확인합니다.이 조회는 홈택스에 아무것도 저장하거나 제출하지 않습니다.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| success | boolean | 작업이 성공하면 항상 true 로 고정된 값입니다 | |
| step | string | 이 응답이 신고 접수 내역 조회라는 표시로, 항상 history 입니다 | |
| data | object | 조회 결과 객체입니다. rows 는 요청한 기간의 원천세 신고 목록입니다. 부른 단계의 신고 종류와 관계없이 정기신고, 수정신고, 기한후신고를 가리지 않고 모두 오므로 필요한 신고는 세부 구분 코드(detail_code)로 골라 씁니다. 신고마다 담는 값은 접수번호(receipt_no), 신고 건 식별번호(filing_reference), 귀속연월(attribution_ym), 지급연월(payment_ym), 신고 종류 코드(return_kind_code), 신고 종류 이름(return_kind_name), 세부 구분 코드(detail_code), 세부 구분 이름(detail_name), 사업자등록번호(business_no), 접수일(receipt_date), 신고일(filing_date), 제출연월(submit_ym), 최종 신고 여부(is_final_filing), 차감 납부세액(payable_tax_amount), 납부 상태(payment_status), 첨부서류 접수 건수 표기(attachment_receipt_text), 삭제신청 가능 여부 안내(deletion_eligibility_reason), 상호(business_name) 입니다. 연월은 여섯 자리, 접수일과 신고일은 연월일 여덟 자리이며 값은 기관이 준 그대로이고 없는 값은 null 입니다. 최종 신고 여부만 true 또는 false 로 옮기며 기관 값이 없으면 null 입니다. page 는 페이지 번호(page_num), 페이지 크기(page_size), 전체 건수(total_count)이고 기관이 페이지 정보를 주지 않으면 세 값 모두 null 입니다 |
{
"job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
"status": "QUEUED",
"env_scope": "real_test",
"provider": "hometax",
"action": "hometax.tax.withholding.regular_report.history",
"submitted_at": "2026-05-27T12:34:56+09:00"
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| VALIDATION_ | 요청 값 오류 — 필요한 값이 빠졌거나 보낸 값이 요청 형식과 맞지 않거나 이 조회에 없는 필드를 보내면 홈택스에 요청하지 않고 이 코드로 끝나며, 자동 재시도 대상이 아닙니다(예: start_date 가 8자리가 아님). error.message 의 빠진 값은 넣고 확인할 값은 고쳐 다시 보냅니다. | |
| AUTH_ | 세션 없음 — 홈택스 세션이 없습니다. 홈택스 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다. | |
| PROVIDER_ | 업무 오류 — 홈택스가 이 조회를 받지 않았다는 뜻이며, error.message 의 홈택스 사유를 해결한 뒤 다시 요청합니다. 홈택스가 사유를 알려 주지 않은 경우에는 입력값을 그대로 두고 잠시 후 다시 시도하라는 안내가 담깁니다. | |
| PROVIDER_ | 세션 만료 — 조회하는 도중 홈택스 로그인 세션이 끝난 것을 알게 되면 이 코드로 끝나며, error.message 안내대로 로그인 액션을 다시 실행해 세션을 연 뒤 같은 요청을 다시 보냅니다. | |
| INTERNAL_ | 홈택스 통신 오류 — 홈택스와 주고받는 도중 연결이 끊기거나 홈택스가 정상 응답을 주지 않으면 이 코드로 끝나며, 자동 재시도 대상이 아닙니다. 홈택스 로그인 세션이 이미 끝나 있을 때도 조회 화면을 열기 전 준비에서 이 코드로 끝날 수 있습니다. error.message 안내대로 잠시 후 같은 요청을 다시 보내고, 같은 코드가 계속되면 로그인 액션을 다시 실행해 세션을 연 뒤 요청하며, 그래도 계속되면 서비스문의로 알려 주세요. |
10. 나의세무대리인 조회hometax. tax. my_ tax_ agent. search
MCP 도구 이름 hometax__
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
나의세무대리인을 조회합니다.
- 홈택스 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [홈택스 로그인(세션 생성)]
- 조회 결과가 없으면 목록이 빈 배열로 돌아옵니다. 실패가 아닙니다.
- params 는 빈 객체로 보내도 호출됩니다. 사용할 인증서는 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 | - | N | 작업 파라미터입니다. 이 API 는 빈 객체로 호출할 수 있습니다. | |
| encrypted_ | object | - | N | 민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| page_ | number | N | 페이지 번호 (기본: 1) | |
| output_ | array | N | 이 결과를 엑셀(xlsx) 파일로도 받으려면 적습니다. 예: ["xlsx"]. 파일은 result.artifacts 에 함께 오고, 빼면 데이터만 옵니다 |
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-$(date +%s)-$RANDOM" \
--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 값과 목록·페이지 필드를 확인합니다.
- 아래 표의 txaaInfrDVOList[] 줄은 엑셀 파일(params 의 output_formats 에 ["xlsx"])의 열로 내보내는 칸이고, 열 이름은 홈택스 화면의 표 머리글입니다.
- 기관이 내려주는 행에는 아래 표에 없는 칸도 더 있습니다.
- 여러 JSON 타입이 함께 표시된 칸은 서버가 세부 타입을 고정하지 않는 기관 원문 또는 동적 값입니다.예시 값의 타입으로 단정하지 말고 실제 값의 타입을 확인해 주세요. null은 값이 비어 있다는 뜻이며, 필드 자체의 생략 여부는 필수 여부와 설명을 확인해 주세요.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| result | string | number | boolean | object | array | null | 홈택스 응답 본문 객체. 기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다 | |
| txaaInfrDVOList | array | 세무대리인 목록 배열 | |
| txaaInfrDVOList[]. | string | number | boolean | object | array | null | 세무대리인사업자등록번호 | |
| txaaInfrDVOList[]. | string | number | boolean | object | array | null | 세무대리인상호 | |
| txaaInfrDVOList[]. | string | number | boolean | object | array | null | 세무대리인전화번호 | |
| txaaInfrDVOList[]. | string | number | boolean | object | array | null | 수임일자 | |
| txaaInfrDVOList[]. | string | number | boolean | object | array | null | 정보제공범위 | |
| txaaInfrDVOList[]. | string | number | boolean | object | array | null | 정보제공동의여부 | |
| pageInfoVO | string | number | boolean | object | array | null | 페이지 정보 객체 | |
| totalCount | string | number | boolean | object | array | null | 전체 건수 | |
| pageNum | string | number | boolean | object | array | null | 페이지 번호 | |
| pageSize | string | number | boolean | object | array | null | 페이지 크기 | |
| success | boolean | 요청 처리 성공 여부 |
// result.data
{
"result": {},
"txaaInfrDVOList": [
{
"bsno": "...",
"txaaAdmTnmNm": "...",
"txaaAdmTelno": "...",
"afaDt": "...",
"infrOfrRngCdNm": "...",
"afaInfrOfrAgrClNm": "..."
}
],
"pageInfoVO": {},
"totalCount": "...",
"pageNum": "...",
"pageSize": "...",
"success": true
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| VALIDATION_ | 숫자 값 오류 — page_num 에 1 이상의 정수가 아닌 값(0, 음수, 소수부가 있는 수, 숫자가 아닌 글자)을 보내면 홈택스에 요청하지 않고 이 코드로 끝나며, 자동 재시도 대상이 아닙니다. error.message 가 확인할 값의 이름을 알려 주니 그 값을 고쳐 다시 요청합니다. 숫자로 된 문자열도 받고, null 로 보내면 보내지 않은 것으로 보아 기본값을 씁니다. | |
| AUTH_ | 세션 없음 — 홈택스 세션이 없습니다. 홈택스 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다. | |
| PROVIDER_ | 업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다. | |
| PROVIDER_ | 업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다. | |
| PROVIDER_ | 업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다. | |
| PROVIDER_ | 업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다. | |
| PROVIDER_ | 세션 만료 — 조회하는 도중 홈택스 로그인 세션이 끝난 것을 알게 되면 이 코드로 끝나며, error.message 안내대로 로그인 액션을 다시 실행해 세션을 연 뒤 같은 요청을 다시 보냅니다. |
11. 사업자 등록사항 및 담당자 안내hometax. tax. business_ registration. search_ info
MCP 도구 이름 hometax__
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
사업자 등록사항 및 담당자 안내를 조회합니다.
- 홈택스 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [홈택스 로그인(세션 생성)]
- 조회 결과가 없으면 목록이 빈 배열로 돌아옵니다. 실패가 아닙니다.
- params 는 빈 객체로 보내도 호출됩니다. 사용할 인증서는 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 | - | N | 작업 파라미터입니다. 이 API 는 빈 객체로 호출할 수 있습니다. | |
| encrypted_ | object | - | N | 민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| output_ | array | N | 이 결과를 엑셀(xlsx) 파일로도 받으려면 적습니다. 예: ["xlsx"]. 파일은 result.artifacts 에 함께 오고, 빼면 데이터만 옵니다 |
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_info-$(date +%s)-$RANDOM" \
--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 값과 목록·페이지 필드를 확인합니다.
- 아래 표의 bmanBscInfrInqrDVOList[] 줄은 엑셀 파일(params 의 output_formats 에 ["xlsx"])의 열로 내보내는 칸이고, 열 이름은 홈택스 화면의 표 머리글입니다.
- 기관이 내려주는 행에는 아래 표에 없는 칸도 더 있습니다.
- 여러 JSON 타입이 함께 표시된 칸은 서버가 세부 타입을 고정하지 않는 기관 원문 또는 동적 값입니다.예시 값의 타입으로 단정하지 말고 실제 값의 타입을 확인해 주세요. null은 값이 비어 있다는 뜻이며, 필드 자체의 생략 여부는 필수 여부와 설명을 확인해 주세요.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| result | string | number | boolean | object | array | null | 홈택스 응답 본문 객체. 기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다 | |
| bmanBscInfrInqrDVOList | array | 사업자등록사항 목록 배열 | |
| bmanBscInfrInqrDVOList[]. | string | number | boolean | object | array | null | 사업자등록번호 | |
| bmanBscInfrInqrDVOList[]. | string | number | boolean | object | array | null | 상호(성명) | |
| bmanBscInfrInqrDVOList[]. | string | number | boolean | object | array | null | 사업상태 | |
| bmanBscInfrInqrDVOList[]. | string | number | boolean | object | array | null | 과세유형 | |
| bmanBscInfrInqrDVOList[]. | string | number | boolean | object | array | null | 주업종명(업종코드) | |
| bmanBscInfrInqrDVOList[]. | string | number | boolean | object | array | null | 관할서 | |
| bmanBscInfrInqrDVOList[]. | string | number | boolean | object | array | null | 담당자성명 | |
| bmanBscInfrInqrDVOList[]. | string | number | boolean | object | array | null | 전화번호 | |
| totalCount | number | 전체 건수 | |
| success | boolean | 요청 처리 성공 여부 |
// result.data
{
"result": {},
"bmanBscInfrInqrDVOList": [
{
"txprDscmNoEncCntn": "...",
"txprNm": "...",
"txprStatNm": "...",
"bmanClNm": "...",
"itmNm": "...",
"abftChrgTxhfOgzNm": "...",
"fnm": "...",
"zip": "..."
}
],
"totalCount": 0,
"success": true
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| AUTH_ | 세션 없음 — 홈택스 세션이 없습니다. 홈택스 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다. | |
| PROVIDER_ | 업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다. | |
| PROVIDER_ | 업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다. | |
| PROVIDER_ | 업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다. | |
| PROVIDER_ | 업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다. | |
| PROVIDER_ | 세션 만료 — 조회하는 도중 홈택스 로그인 세션이 끝난 것을 알게 되면 이 코드로 끝나며, error.message 안내대로 로그인 액션을 다시 실행해 세션을 연 뒤 같은 요청을 다시 보냅니다. |
12. 부가세 신고 이력 조회hometax. tax. return_ history. search_ vat
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 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 길이 | 필수 | 설명 |
|---|---|---|---|---|---|
| rtn_ | string | 8 | Y | 신고일자 종료일 (필수) | |
| rtn_ | string | 8 | Y | 신고일자 시작일 (필수, 2015-02-23 이후만 조회됩니다) | |
| output_ | array | - | N | 이 결과를 엑셀(xlsx) 파일로도 받으려면 적습니다. 예: ["xlsx"]. 파일은 result.artifacts 에 함께 오고, 빼면 데이터만 옵니다 |
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_vat-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "hometax",
"action": "hometax.tax.return_history.search_vat",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {
"rtn_dt_end": "20251106",
"rtn_dt_srt": "20241107"
}
}'Response
- result.data 에 담긴 홈택스 응답 본문을 확인합니다.
- result.data 에는 홈택스가 내려준 응답 본문이 담깁니다. 화면마다 키 구성이 다르고, 기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다.
- 아래 표의 myntsTaxRtnBrkdDVOList[] 줄은 엑셀 파일(params 의 output_formats 에 ["xlsx"])의 열로 내보내는 칸이고, 열 이름은 홈택스 화면의 표 머리글입니다.
- 기관이 내려주는 행에는 아래 표에 없는 칸도 더 있습니다.
- 여러 JSON 타입이 함께 표시된 칸은 서버가 세부 타입을 고정하지 않는 기관 원문 또는 동적 값입니다.예시 값의 타입으로 단정하지 말고 실제 값의 타입을 확인해 주세요. null은 값이 비어 있다는 뜻이며, 필드 자체의 생략 여부는 필수 여부와 설명을 확인해 주세요.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| myntsTaxRtnBrkdDVOList | string | number | boolean | object | array | null | 조회한 행의 목록 배열입니다. 아래 줄이 그 행의 칸입니다 기관 원문입니다. 목록 존재와 배열 여부를 확인한 뒤 행을 읽어 주세요. | |
| myntsTaxRtnBrkdDVOList[]. | string | number | boolean | object | array | null | 과세기간 기관 원문입니다. 목록 존재와 배열 여부를 확인한 뒤 행을 읽어 주세요. | |
| myntsTaxRtnBrkdDVOList[]. | string | number | boolean | object | array | null | 신고일자 기관 원문입니다. 목록 존재와 배열 여부를 확인한 뒤 행을 읽어 주세요. | |
| myntsTaxRtnBrkdDVOList[]. | string | number | boolean | object | array | null | 과세표준 및 매출세액 (금액) 기관 원문입니다. 목록 존재와 배열 여부를 확인한 뒤 행을 읽어 주세요. | |
| myntsTaxRtnBrkdDVOList[]. | string | number | boolean | object | array | null | 과세표준 및 매출세액 (세액) 기관 원문입니다. 목록 존재와 배열 여부를 확인한 뒤 행을 읽어 주세요. | |
| myntsTaxRtnBrkdDVOList[]. | string | number | boolean | object | array | null | 매입(공제)세액 (금액) 기관 원문입니다. 목록 존재와 배열 여부를 확인한 뒤 행을 읽어 주세요. | |
| myntsTaxRtnBrkdDVOList[]. | string | number | boolean | object | array | null | 매입(공제)세액 (세액) 기관 원문입니다. 목록 존재와 배열 여부를 확인한 뒤 행을 읽어 주세요. | |
| myntsTaxRtnBrkdDVOList[]. | string | number | boolean | object | array | null | 차가감 납부할세액 기관 원문입니다. 목록 존재와 배열 여부를 확인한 뒤 행을 읽어 주세요. | |
| myntsTaxRtnBrkdDVOList[]. | string | number | boolean | object | array | null | 신고구분 기관 원문입니다. 목록 존재와 배열 여부를 확인한 뒤 행을 읽어 주세요. | |
| myntsTaxRtnBrkdDVOList[]. | string | number | boolean | object | array | null | 신고서종류 기관 원문입니다. 목록 존재와 배열 여부를 확인한 뒤 행을 읽어 주세요. | |
| myntsTaxRtnBrkdDVOList[]. | string | number | boolean | object | array | null | 신고서보기 기관 원문입니다. 목록 존재와 배열 여부를 확인한 뒤 행을 읽어 주세요. | |
| myntsTaxRtnBrkdDVOList[]. | string | number | boolean | object | array | null | 신고방법 기관 원문입니다. 목록 존재와 배열 여부를 확인한 뒤 행을 읽어 주세요. |
// result.data — 홈택스 응답 본문이 담깁니다. 화면마다 키 구성이 다르고, 기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다.
{
"myntsTaxRtnBrkdDVOList": [
{
"txnrmYm": "...",
"rtnDt": "...",
"stasAmt": "...",
"cmptTxamt": "...",
"prhTxamtSumAmt": "...",
"prhTxamtSumTxamt": "...",
"ogntxSbtrPmtTxamt": "...",
"rtnClNm": "...",
"rtnClDetailNm": "...",
"stmnKndNm": "...",
"stmnWrtMthdNm": "..."
}
]
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| VALIDATION_ | 요청 값 오류 — 필수 값이 빠지면 홈택스에 요청하지 않고 이 코드로 끝나며, 자동 재시도 대상이 아닙니다. error.message 가 빠진 값의 이름을 알려 주니 그 값을 넣어 다시 요청합니다. rtn_dt_srt, rtn_dt_end 의 값이 맞지 않을 때도 홈택스에 요청하지 않고 같은 코드로 끝나며, error.message 가 고칠 내용을 알려 주니 그 값을 고쳐 다시 요청합니다. | |
| AUTH_ | 세션 없음 — 홈택스 세션이 없습니다. 홈택스 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다. | |
| PROVIDER_ | 업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다. | |
| PROVIDER_ | 업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다. | |
| PROVIDER_ | 업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다. | |
| PROVIDER_ | 업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다. | |
| PROVIDER_ | 세션 만료 — 조회하는 도중 홈택스 로그인 세션이 끝난 것을 알게 되면 이 코드로 끝나며, error.message 안내대로 로그인 액션을 다시 실행해 세션을 연 뒤 같은 요청을 다시 보냅니다. |
13. 세금 신고내역 조회hometax. tax. return_ history. search
MCP 도구 이름 hometax__
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
신고일자 기간으로 최대 6년의 세금 신고내역과 경정청구 내역을 조회합니다.
- 홈택스 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [홈택스 로그인(세션 생성)]
- 조회 기간에 신고가 없으면 rows 가 빈 배열이고 total_count 가 0 입니다. 실패가 아닙니다.
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 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 길이 | 필수 | 설명 |
|---|---|---|---|---|---|
| include_ | boolean | - | N | 경정청구 내역(claims)을 함께 조회할지 정합니다. true 나 false 로 보내며 보내지 않으면 true 입니다 | |
| page_ | number | - | N | 신고내역 행(rows)의 페이지 번호입니다. 1부터 세는 정수이고 보내지 않으면 1 입니다 | |
| page_ | number | - | N | 페이지당 신고내역 행 수입니다. 1 이상의 정수이고 보내지 않으면 10 입니다. 경정청구 내역(claims 와 claims_documents)은 페이지로 나누지 않고 모두 옵니다 | |
| rtn_ | string | 8-10 | Y | 그 기간의 종료일입니다. 기간은 시작일부터 6년 안이어야 하고, 넘기면 거절합니다 | |
| rtn_ | string | 8-10 | Y | 신고일자를 기준으로 찾는 기간의 시작일입니다. rtn_dt_end 보다 뒤일 수 없습니다 | |
| tax_ | string | - | N | 조회할 세목입니다. all 은 홈택스 신고내역 전체 목록, vat 는 부가가치세, corporate 는 법인세이며 보내지 않으면 all 입니다. 다른 값은 거절합니다 | |
| output_ | array | - | N | 이 결과를 엑셀(xlsx) 파일로도 받으려면 적습니다. 예: ["xlsx"]. 파일은 result.artifacts 에 함께 오고, 빼면 데이터만 옵니다 |
- 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "hometax",
"action": "hometax.tax.return_history.search",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {
"rtn_dt_end": "<필수>",
"rtn_dt_srt": "<필수>"
}
}'Response
- result.data.rows 로 신고내역을, claims 와 claims_documents 로 경정청구를 확인합니다.세금 신고서 상세 조회와 원문 조회에는 행의 return_document_ref 를 그대로 넣고, 그 값은 같은 환경과 같은 account_link_id 로 요청할 때만 받아들입니다.
- 아래 표의 rows[], claims[] 줄은 엑셀 파일(params 의 output_formats 에 ["xlsx"])의 열로 내보내는 칸이고, 열 이름은 엑셀 파일 맨 윗줄의 머리글입니다.
- 기관이 내려주는 행에는 아래 표에 없는 칸도 더 있습니다.
- 여러 JSON 타입이 함께 표시된 칸은 서버가 세부 타입을 고정하지 않는 기관 원문 또는 동적 값입니다.예시 값의 타입으로 단정하지 말고 실제 값의 타입을 확인해 주세요. null은 값이 비어 있다는 뜻이며, 필드 자체의 생략 여부는 필수 여부와 설명을 확인해 주세요.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| rows | array | 신고내역 행 배열입니다. 신고일자가 늦은 순으로 정렬해 page_num 과 page_size 의 페이지만 담습니다. 행마다 return_document_ref(세금 신고서 상세 조회와 원문 조회에 넣는 문서 참조)가 함께 옵니다. 부가가치세와 법인세가 아닌 신고이거나 홈택스가 신고서를 열 값을 주지 않은 행은 return_document_ref 가 null 이고 document_link_status 가 NOT_OBSERVED 입니다 | |
| rows[]. | string | number | boolean | object | array | null | 과세기간 | |
| rows[]. | string | number | boolean | object | array | null | 신고일자 | |
| rows[]. | string | number | boolean | object | array | null | 과세표준 및 매출세액 (금액) | |
| rows[]. | string | number | boolean | object | array | null | 과세표준 및 매출세액 (세액) | |
| rows[]. | string | number | boolean | object | array | null | 매입(공제)세액 (금액) | |
| rows[]. | string | number | boolean | object | array | null | 매입(공제)세액 (세액) | |
| rows[]. | string | number | boolean | object | array | null | 차가감 납부할세액 | |
| rows[]. | string | number | boolean | object | array | null | 신고구분 | |
| rows[]. | string | number | boolean | object | array | null | 신고서종류 | |
| rows[]. | string | number | boolean | object | array | null | 신고서보기 | |
| rows[]. | string | number | boolean | object | array | null | 신고방법 | |
| total_ | number | 조회 기간에 찾은 신고내역 전체 건수입니다. rows 는 그 가운데 요청한 페이지만 담습니다 | |
| page_ | number | 요청한 페이지 번호입니다. 보내지 않으면 1 입니다 | |
| page_ | number | 한 페이지의 행 수입니다. 보내지 않으면 10 입니다 | |
| claims | array | 경정청구 내역 행 배열입니다. 페이지로 나누지 않고 한 번에 담으며, include_correction_claims 가 false 면 빈 배열입니다. 이 행으로는 신고서를 열 수 없으니 상세 조회와 원문 조회에는 claims_documents 의 return_document_ref 를 씁니다 | |
| claims[]. | string | 세목 | |
| claims[]. | string | number | boolean | object | array | null | 과세기간 | |
| claims[]. | string | number | boolean | object | array | null | 신청일자 | |
| claims[]. | string | number | boolean | object | array | null | 청구세액 | |
| claims[]. | string | number | boolean | object | array | null | 신고서구분 | |
| claims[]. | string | 신청방법 | |
| claims_ | object | 경정청구 신고서를 열 수 있는지 알려 주는 객체입니다. status 는 DOCUMENTS_AVAILABLE(claims_documents 로 열 수 있음), DISPLAY_ONLY(claims 는 있지만 열 수 있는 신고서가 확인되지 않음), VERIFIED_EMPTY(조회 범위에 경정청구가 없음), NOT_REQUESTED(include_correction_claims 가 false 라 찾아보지 않음, 자료가 없다는 뜻이 아님) 가운데 하나이고, message 는 그 안내 문장입니다. document_count 는 claims_documents 의 건수, display_row_count 는 claims 의 건수, additional_lookup_requested 는 include_correction_claims 값입니다 | |
| claims_ | string | claims_documents 를 찾은 곳입니다. include_correction_claims 가 true 면 electronic_and_written_filing_results(전자신고와 서면접수 결과), false 면 electronic_filing_results(전자신고 결과)입니다 | |
| claims_ | string | claims_documents 에 행이 있으면 ROWS_RETURNED, 없으면 include_correction_claims 가 true 일 때 EMPTY_RESPONSE, false 일 때 NOT_REQUESTED 입니다 | |
| claims_ | array | 상세 조회와 원문 조회로 열 수 있는 경정청구 신고서 행 배열입니다. 페이지로 나누지 않으며 행마다 return_document_ref 가 함께 오고, 서면접수 결과에서 찾은 행은 document_receipt_mode 가 written 입니다 | |
| claims_ | string | 서면접수 결과에서 경정청구를 찾았는지입니다. include_correction_claims 가 false 면 NOT_REQUESTED, 찾았으면 ROWS_RETURNED, 없으면 EMPTY_RESPONSE 입니다 | |
| written_ | number | include_correction_claims 가 true 일 때 서면접수 결과에서 받은 행 수입니다. 경정청구가 아닌 행도 셉니다. false 면 0 입니다 | |
| claims_ | number | claims 의 건수입니다 | |
| claims_ | string | claims 에 tax_kind 를 적용한 결과입니다. APPLIED(적용함), APPLIED_WITH_UNCLASSIFIED_PRESERVED(적용했고 세목 코드가 없는 행은 남김), NOT_REQUIRED_ALL(tax_kind 가 all 이라 거르지 않음), NOT_APPLIED_NO_ITRF_CD(세목 코드가 있는 행이 없어 거르지 않음, claims 가 빈 배열일 때도 이 값) 가운데 하나입니다 | |
| claims_ | number | claims 가운데 세목 코드가 없는 행 수입니다 | |
| claims_ | string | claims 를 찾았는지입니다. include_correction_claims 가 false 면 NOT_REQUESTED, 행이 있으면 ROWS_RETURNED, 없으면 EMPTY_RESPONSE 입니다 |
// result.data
{
"rows": [
{
"txnrmYm": "...",
"rtnDt": "...",
"stasAmt": "...",
"cmptTxamt": "...",
"prhTxamtSumAmt": "...",
"prhTxamtSumTxamt": "...",
"ogntxSbtrPmtTxamt": "...",
"rtnClNm": "...",
"rtnClDetailNm": "...",
"stmnKndNm": "...",
"stmnWrtMthdNm": "..."
}
],
"claims": [
{
"itrfNm": "...",
"txnrmYm": "...",
"rcatDt": "...",
"apeTxamt": "...",
"rtnClNm": "...",
"stmnWrtMthdNm": "..."
}
]
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| VALIDATION_ | 요청 값 오류 — rtn_dt_srt, rtn_dt_end 가 빠졌거나 날짜, 기간, tax_kind, include_correction_claims, page_num, page_size 가운데 맞지 않는 값이 있으면 홈택스에 요청하지 않고 이 코드로 끝나며, 자동 재시도 대상이 아니니 error.message 의 빠진 값은 넣고 확인할 값은 고쳐 다시 요청합니다. tax_kind 나 include_correction_claims 가 맞지 않으면 error.message 가 그 칸에 넣을 수 있는 값을 알려 주니 그 값으로 고쳐 다시 요청합니다. 기간은 시작일부터 6년 안이어야 하고 시작일이 종료일보다 늦으면 안 되며, 기간이 맞지 않을 때 확인할 값은 rtn_dt_srt 로 오니 두 날짜를 함께 확인합니다. | |
| VALIDATION_ | 사업자 계정 아님 — 연결된 홈택스 계정이 사업자 계정이 아님을 세션 정보로 알 수 있으면 홈택스에 조회하지 않고 멈추는 경우이며, 다시 조회해도 같은 결과라 자동 재시도 대상이 아닙니다. 사업자로 연결된 계정의 account_link_id 로 다시 요청합니다. error.message 는 「신고내역 조회는 사업자 계정으로만 이용할 수 있습니다. 사업자로 연결된 계정을 선택한 뒤 다시 시도해 주세요.」 입니다. | |
| AUTH_ | 세션 없음 — 홈택스 세션이 없습니다. 홈택스 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다. | |
| PROVIDER_ | 업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다. | |
| PROVIDER_ | 업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다. | |
| PROVIDER_ | 업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다. | |
| PROVIDER_ | 업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다. | |
| PROVIDER_ | 세션 만료 — 조회하는 도중 홈택스 로그인 세션이 끝난 것을 알게 되면 이 코드로 끝나며, error.message 안내대로 로그인 액션을 다시 실행해 세션을 연 뒤 같은 요청을 다시 보냅니다. |
14. 세금 신고서 상세 조회hometax. tax. return_ document. detail
MCP 도구 이름 hometax__
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
신고내역에서 고른 신고서의 서식별 항목과 값, 표를 조회합니다.
- 홈택스 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [홈택스 로그인(세션 생성)]
- 요청 거절(HTTP 400, 작업은 만들어지지 않음).error.code=VALIDATION_INVALID_FIELD — return_document_ref 를 빼거나 문서 참조 모양이 아닌 값을 보내면 작업을 만들기 전에 거절하니, 세금 신고내역 조회를 다시 실행해 결과 행의 return_document_ref 를 그대로 넣어 보냅니다.
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 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| form_ | array | N | 받을 서식 코드 목록입니다. 중복 없이 하나 이상 보내며, 보내지 않으면 출력할 수 있는 서식을 모두 받습니다. 코드는 신고서 상세 조회 결과의 forms 에 있는 form_code 이고, 그 신고서의 서식 목록에 없는 코드를 담으면 거절합니다 | |
| return_ | string | Y | 열어 볼 신고서의 문서 참조입니다. 세금 신고내역 조회 결과의 rows 나 claims_documents 에서 고른 행의 return_document_ref 값을 그대로 보냅니다. 같은 계정 연결로 성공한 신고내역 조회에서 받은 값만 받고, 값이 null 인 행은 열 수 없습니다 | |
| output_ | array | N | 이 결과를 엑셀(xlsx) 파일로도 받으려면 적습니다. 예: ["xlsx"]. 파일은 result.artifacts 에 함께 오고, 빼면 데이터만 옵니다 |
- 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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: detail-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "hometax",
"action": "hometax.tax.return_document.detail",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {
"return_document_ref": "<필수>"
}
}'Response
- result.data.forms 로 서식별 항목과 표를, cells 로 모든 서식의 칸을 한 줄씩 확인합니다.collection_status 가 PARTIAL_AVAILABILITY 이면 서면접수 신고라 별도 첨부를 확인하지 못한 것입니다.
- 아래 표의 cells[] 줄은 엑셀 파일(params 의 output_formats 에 ["xlsx"])의 열로 내보내는 칸이고, 열 이름은 엑셀 파일 맨 윗줄의 머리글입니다.
- 아래 표의 줄은 엑셀로 내보내는 열이라 응답 행의 칸 전부가 아닐 수 있습니다.
- 여러 JSON 타입이 함께 표시된 칸은 서버가 세부 타입을 고정하지 않는 기관 원문 또는 동적 값입니다.예시 값의 타입으로 단정하지 말고 실제 값의 타입을 확인해 주세요. null은 값이 비어 있다는 뜻이며, 필드 자체의 생략 여부는 필수 여부와 설명을 확인해 주세요.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| return_ | string | 요청에 넣은 문서 참조 그대로입니다 | |
| return | object | 고른 신고서의 기본 정보 객체입니다. 세금 신고내역 조회 결과 행에서 옮긴 값으로 itrfNm(세목), rcatNo(접수번호), rtnDt(신고일자), txnrmYm(과세기간) 등이 담기고, 그 행에 없던 값은 null 입니다 | |
| forms | array | 서식별 결과 배열입니다. 서식마다 form_index(순번), form_code(서식 코드), form_name(서식 이름), form_group(main 은 본 신고서, attachment 는 부속 서식), fields(표 밖 항목의 key, label, value), tables(표마다 name, columns, rows)가 옵니다. form_codes 를 보내면 그 서식만, 보내지 않으면 출력할 수 있는 서식을 모두 담습니다 | |
| form_ | number | forms 의 건수입니다 | |
| form_ | string | ALL_PRINTABLE_FORMS(form_codes 를 보내지 않아 출력할 수 있는 서식 전부) 또는 SELECTED_FORMS(form_codes 로 고른 서식)입니다 | |
| collection_ | string | 보통 COMPLETE 이고, 서면접수 신고라 별도 첨부를 확인할 수 없으면 PARTIAL_AVAILABILITY 입니다 | |
| cells | array | 모든 서식의 칸을 한 줄씩 펼친 배열입니다. 서식마다 칸이 달라도 아래 cells[] 줄의 일곱 칸으로 옵니다 | |
| cells[]. | string | 서식코드 | |
| cells[]. | string | 서식명 | |
| cells[]. | string | 원문표위치 | |
| cells[]. | number | null | 행번호 | |
| cells[]. | string | 기관항목명 | |
| cells[]. | string | number | boolean | object | array | null | 원문값 | |
| cells[]. | string | 항목구분 | |
| separate_ | object | 신고서와 함께 제출된 별도 첨부의 목록 객체입니다. present 는 첨부가 있으면 true, 없으면 false, 서면접수 신고라 확인할 수 없으면 null 이고, verification 은 VERIFIED, VERIFIED_EMPTY, NOT_AVAILABLE_IN_WRITTEN_VIEW 가운데 하나입니다. files 는 첨부마다 archive_id, attachment_submission_id, file_uuid, file_name, page_count, link_treatment_code, registered_at 을 담고, download_status 는 NOT_REQUESTED(첨부 있음), NOT_APPLICABLE(첨부 없음), UNAVAILABLE(확인할 수 없음) 가운데 하나이며 message 는 그 안내 문장입니다. 첨부 원문 PDF 는 세금 신고서 원문 조회로 받습니다 |
// result.data
{
"cells": [
{
"form_code": "...",
"form_name": "...",
"table_name": "...",
"row_no": "...",
"label": "...",
"value": "...",
"role": "..."
}
]
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| VALIDATION_ | 요청 값 오류 — 문서 참조나 서식 코드가 맞지 않은 경우이며, 자동 재시도 대상이 아니니 error.message 가 알리는 값을 고쳐 다시 요청합니다. error.message 가 문서 참조가 필요하다고 알리면 return_document_ref 가 같은 회사 연결의 성공한 신고내역 조회에서 온 것이 아니거나 지금 연결된 회사의 신고서가 아닌 것이니, 같은 account_link_id 로 세금 신고내역 조회를 다시 실행해 받은 return_document_ref 로 요청합니다. error.message 가 서식 코드(form_codes)를 알리면 form_codes 없이 부른 세금 신고서 상세 조회의 forms[].form_code 가운데서 중복 없이 고르거나, form_codes 를 빼고 다시 요청하면 출력할 수 있는 서식을 모두 받습니다. | |
| AUTH_ | 세션 없음 — 홈택스 세션이 없습니다. 홈택스 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다. | |
| PROVIDER_ | 업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다. | |
| PROVIDER_ | 업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다. | |
| PROVIDER_ | 업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 신고서나 별도 첨부를 끝까지 확인하지 못한 경우이며, 재시도 가능으로 표시되니 잠시 후 같은 요청을 다시 보냅니다. error.message 가 해당 신고내역을 다시 조회하라고 알리면 세금 신고내역 조회를 다시 실행해 받은 새 return_document_ref 로 요청합니다. | |
| PROVIDER_ | 업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 신고서나 별도 첨부를 끝까지 확인하지 못한 경우이며, 재시도 가능으로 표시되니 잠시 후 같은 요청을 다시 보냅니다. error.message 가 해당 신고내역을 다시 조회하라고 알리면 세금 신고내역 조회를 다시 실행해 받은 새 return_document_ref 로 요청합니다. | |
| PROVIDER_ | 세션 만료 — 조회하는 도중 홈택스 로그인 세션이 끝난 것을 알게 되면 이 코드로 끝나며, error.message 안내대로 로그인 액션을 다시 실행해 세션을 연 뒤 같은 요청을 다시 보냅니다. |
15. 세금 신고서 원문 조회hometax. tax. return_ document. pdf
MCP 도구 이름 hometax__
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
신고내역에서 고른 신고서의 원문을 서식별 PDF 로 받습니다.
- 홈택스 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [홈택스 로그인(세션 생성)]
- 요청 거절(HTTP 400, 작업은 만들어지지 않음).error.code=VALIDATION_INVALID_FIELD — return_document_ref 를 빼거나 문서 참조 모양이 아닌 값을 보내면 작업을 만들기 전에 거절하니, 세금 신고내역 조회를 다시 실행해 결과 행의 return_document_ref 를 그대로 넣어 보냅니다.
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 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| form_ | array | N | 받을 서식 코드 목록입니다. 중복 없이 하나 이상 보내며, 보내지 않으면 출력할 수 있는 서식을 모두 받습니다. 코드는 신고서 상세 조회 결과의 forms 에 있는 form_code 이고, 그 신고서의 서식 목록에 없는 코드를 담으면 거절합니다 | |
| return_ | string | Y | 열어 볼 신고서의 문서 참조입니다. 세금 신고내역 조회 결과의 rows 나 claims_documents 에서 고른 행의 return_document_ref 값을 그대로 보냅니다. 같은 계정 연결로 성공한 신고내역 조회에서 받은 값만 받고, 값이 null 인 행은 열 수 없습니다 |
- 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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: pdf-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "hometax",
"action": "hometax.tax.return_document.pdf",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {
"return_document_ref": "<필수>"
}
}'Response
- 아래 표의 칸은 작업이 SUCCEEDED 가 된 뒤 GET /v1/jobs/{job_id}/result 의 result.data 에 오고, 응답 예시는 작업을 제출했을 때(POST /v1/jobs)의 응답입니다.
- 원문 PDF 는 result.artifacts 에 파일마다 download_url 과 함께 옵니다.result.data.forms 와 separate_attachments.files 의 artifact_qualifier 는 그 파일 이름(name)의 .pdf 앞 끝 부분이라 이 값으로 어느 서식이나 첨부의 파일인지 맞춥니다.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| return_ | string | 요청에 넣은 문서 참조 그대로입니다 | |
| return | object | 고른 신고서의 기본 정보 객체입니다. 세금 신고내역 조회 결과 행에서 옮긴 값으로 itrfNm(세목), rcatNo(접수번호), rtnDt(신고일자), txnrmYm(과세기간) 등이 담기고, 그 행에 없던 값은 null 입니다 | |
| forms | array | 서식 PDF 파일마다 한 행인 배열입니다. 행마다 form_code, form_name, form_index, form_group, data_page, page_start, page_end, page_count, document_page_count, artifact_qualifier(result.artifacts 의 파일 이름 끝 부분), size_bytes, sha256 등이 옵니다. 쪽이 많은 서식은 여러 파일로 나뉘어 여러 행이 됩니다 | |
| form_ | number | 고른 서식 수입니다. 서식 하나가 여러 PDF 로 나뉠 수 있어 forms 의 건수와 다를 수 있습니다 | |
| artifact_ | number | 이 작업이 만든 PDF 파일 수입니다. 서식 PDF 와 별도 첨부 PDF 를 모두 셉니다 | |
| form_ | string | ALL_PRINTABLE_FORMS(form_codes 를 보내지 않아 출력할 수 있는 서식 전부) 또는 SELECTED_FORMS(form_codes 로 고른 서식)입니다 | |
| collection_ | string | 보통 COMPLETE 이고, 서면접수 신고라 별도 첨부를 확인할 수 없으면 PARTIAL_AVAILABILITY 입니다 | |
| separate_ | object | 신고서와 함께 제출된 별도 첨부 객체입니다. form_codes 와 상관없이 늘 함께 받습니다. 첨부가 있으면 모두 PDF 로 받아 download_status 가 DOWNLOADED 이고, files 의 행마다 artifact_qualifier(별도첨부1 부터), size_bytes, sha256 등이 더해지며, 이 객체의 artifact_count 는 받은 첨부 PDF 수입니다. 첨부가 없거나 서면접수 신고라 확인할 수 없으면 이 객체의 artifact_count 가 0 이고, present, verification, message 의 뜻은 세금 신고서 상세 조회와 같습니다 |
{
"job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
"status": "QUEUED",
"env_scope": "real_test",
"provider": "hometax",
"action": "hometax.tax.return_document.pdf",
"submitted_at": "2026-05-27T12:34:56+09:00"
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| VALIDATION_ | 요청 값 오류 — 문서 참조나 서식 코드가 맞지 않은 경우이며, 자동 재시도 대상이 아니니 error.message 가 알리는 값을 고쳐 다시 요청합니다. error.message 가 문서 참조가 필요하다고 알리면 return_document_ref 가 같은 회사 연결의 성공한 신고내역 조회에서 온 것이 아니거나 지금 연결된 회사의 신고서가 아닌 것이니, 같은 account_link_id 로 세금 신고내역 조회를 다시 실행해 받은 return_document_ref 로 요청합니다. error.message 가 서식 코드(form_codes)를 알리면 form_codes 없이 부른 세금 신고서 상세 조회의 forms[].form_code 가운데서 중복 없이 고르거나, form_codes 를 빼고 다시 요청하면 출력할 수 있는 서식을 모두 받습니다. | |
| PROVIDER_ | 크기 상한 — 서식 PDF 의 한 쪽이나 별도 첨부 파일 하나가 내려받을 수 있는 크기 상한을 넘은 경우이며, 다시 요청해도 같아 자동 재시도 대상이 아닙니다. error.message 가 어느 쪽인지 알려 주니, 서식이면 form_codes 로 그 서식을 빼고 요청하거나 세금 신고서 상세 조회로 신고서 내용을 받고, 별도 첨부면 서식을 빼도 같으니 세금 신고서 상세 조회로 신고서 내용과 별도 첨부 목록을 받습니다. | |
| AUTH_ | 세션 없음 — 홈택스 세션이 없습니다. 홈택스 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다. | |
| PROVIDER_ | 업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다. | |
| PROVIDER_ | 업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다. | |
| PROVIDER_ | 업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 신고서나 별도 첨부를 끝까지 확인하지 못한 경우이며, 재시도 가능으로 표시되니 잠시 후 같은 요청을 다시 보냅니다. error.message 가 해당 신고내역을 다시 조회하라고 알리면 세금 신고내역 조회를 다시 실행해 받은 새 return_document_ref 로 요청합니다. | |
| PROVIDER_ | 업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 신고서나 별도 첨부를 끝까지 확인하지 못한 경우이며, 재시도 가능으로 표시되니 잠시 후 같은 요청을 다시 보냅니다. error.message 가 해당 신고내역을 다시 조회하라고 알리면 세금 신고내역 조회를 다시 실행해 받은 새 return_document_ref 로 요청합니다. | |
| PROVIDER_ | 세션 만료 — 조회하는 도중 홈택스 로그인 세션이 끝난 것을 알게 되면 이 코드로 끝나며, error.message 안내대로 로그인 액션을 다시 실행해 세션을 연 뒤 같은 요청을 다시 보냅니다. |
16. 납부할 세액 조회hometax. tax. payment_ due. search_ or_ pay
MCP 도구 이름 hometax__
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
납부할 세액을 조회합니다. 조회만 하며 납부는 하지 않습니다.
- 홈택스 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [홈택스 로그인(세션 생성)]
- 조회 결과가 없으면 목록이 빈 배열로 돌아옵니다. 실패가 아닙니다.
- params 는 빈 객체로 보내도 호출됩니다. 사용할 인증서는 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 | - | N | 작업 파라미터입니다. 이 API 는 빈 객체로 호출할 수 있습니다. | |
| encrypted_ | object | - | N | 민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| inqr_ | string | N | 조회구분코드 (선택, '01'=신고 납부기한이 지난 내역 보기) | |
| page_ | number | N | 페이지 번호 (기본: 1) | |
| page_ | number | N | 페이지당 조회건수 (기본: 10) | |
| output_ | array | N | 이 결과를 엑셀(xlsx) 파일로도 받으려면 적습니다. 예: ["xlsx"]. 파일은 result.artifacts 에 함께 오고, 빼면 데이터만 옵니다 |
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_or_pay-$(date +%s)-$RANDOM" \
--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 값과 목록·페이지 필드를 확인합니다.
- 아래 표의 pubcRomCmnDVOList[] 줄은 엑셀 파일(params 의 output_formats 에 ["xlsx"])의 열로 내보내는 칸이고, 열 이름은 홈택스 화면의 표 머리글입니다.
- 기관이 내려주는 행에는 아래 표에 없는 칸도 더 있습니다.
- 여러 JSON 타입이 함께 표시된 칸은 서버가 세부 타입을 고정하지 않는 기관 원문 또는 동적 값입니다.예시 값의 타입으로 단정하지 말고 실제 값의 타입을 확인해 주세요. null은 값이 비어 있다는 뜻이며, 필드 자체의 생략 여부는 필수 여부와 설명을 확인해 주세요.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| result | string | number | boolean | object | array | null | 홈택스 응답 본문 객체. 기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다 | |
| pubcRomCmnDVOList | array | 납부할 세액 목록 배열 | |
| pubcRomCmnDVOList[]. | string | number | boolean | object | array | null | 과세구분 | |
| pubcRomCmnDVOList[]. | string | number | boolean | object | array | null | 세목 | |
| pubcRomCmnDVOList[]. | string | number | boolean | object | array | null | (직전)납부기한 | |
| pubcRomCmnDVOList[]. | string | number | boolean | object | array | null | 납부할 세액 | |
| pubcRomCmnDVOList[]. | string | number | boolean | object | array | null | 전자납부번호 | |
| pubcRomCmnDVOList[]. | string | number | boolean | object | array | null | 기납부세액 | |
| pubcRomCmnDVOList[]. | string | number | boolean | object | array | null | 귀속연월 | |
| pubcRomCmnDVOList[]. | string | number | boolean | object | array | null | 관서명(코드) | |
| pubcRomCmnDVOList[]. | string | number | boolean | object | array | null | 담당자 | |
| amtSum | string | number | boolean | object | array | null | 납부 세액 합계 | |
| pageInfoVO | string | number | boolean | object | array | null | 페이지 정보 객체 | |
| totalCount | string | number | boolean | object | array | null | 전체 건수 | |
| pageNum | string | number | boolean | object | array | null | 페이지 번호 | |
| pageSize | string | number | boolean | object | array | null | 페이지 크기 | |
| success | boolean | 요청 처리 성공 여부 |
// result.data
{
"result": {},
"pubcRomCmnDVOList": [
{
"txtnClNm": "...",
"itrfNm": "...",
"pmtDdt": "...",
"romAmt": "...",
"bankElctPmtPblNo": "...",
"nowTotaRomAmt": "...",
"attrYr": "...",
"txhfOgzNm": "...",
"dutsNm": "..."
}
],
"amtSum": "...",
"pageInfoVO": {},
"totalCount": "...",
"pageNum": "...",
"pageSize": "...",
"success": true
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| VALIDATION_ | 숫자 값 오류 — page_num, page_size 에 1 이상의 정수가 아닌 값(0, 음수, 소수부가 있는 수, 숫자가 아닌 글자)을 보내면 홈택스에 요청하지 않고 이 코드로 끝나며, 자동 재시도 대상이 아닙니다. error.message 가 확인할 값의 이름을 알려 주니 그 값을 고쳐 다시 요청합니다. 숫자로 된 문자열도 받고, null 로 보내면 보내지 않은 것으로 보아 기본값을 씁니다. | |
| AUTH_ | 세션 없음 — 홈택스 세션이 없습니다. 홈택스 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다. | |
| PROVIDER_ | 업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다. | |
| PROVIDER_ | 업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다. | |
| PROVIDER_ | 업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다. | |
| PROVIDER_ | 업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다. | |
| PROVIDER_ | 세션 만료 — 조회하는 도중 홈택스 로그인 세션이 끝난 것을 알게 되면 이 코드로 끝나며, error.message 안내대로 로그인 액션을 다시 실행해 세션을 연 뒤 같은 요청을 다시 보냅니다. |
17. 전자고지 수신동의 상태 조회hometax. tax. electronic_ notice. check_ status
MCP 도구 이름 hometax__
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
전자고지 수신동의 상태 조회합니다.
- 홈택스 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [홈택스 로그인(세션 생성)]
- params 는 빈 객체로 보내도 호출됩니다. 사용할 인증서는 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 | - | N | 작업 파라미터입니다. 이 API 는 빈 객체로 호출할 수 있습니다. | |
| encrypted_ | object | - | N | 민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| user_ | string | N | 사용자서비스구분코드 (기본: '03'=전자고지 사용자) |
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: check_status-$(date +%s)-$RANDOM" \
--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 값과 응답 칸을 확인합니다.
- 여러 JSON 타입이 함께 표시된 칸은 서버가 세부 타입을 고정하지 않는 기관 원문 또는 동적 값입니다.예시 값의 타입으로 단정하지 말고 실제 값의 타입을 확인해 주세요. null은 값이 비어 있다는 뜻이며, 필드 자체의 생략 여부는 필수 여부와 설명을 확인해 주세요.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| result | string | number | boolean | object | array | null | 홈택스 응답 본문 객체. 기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다 | |
| pubcUserInqrDVO | string | number | boolean | object | array | null | 전자고지 조회 객체 | |
| elctNtfYn | string | number | boolean | object | array | null | 전자고지 여부 | |
| userSrvcApplcStrtDtm | string | number | boolean | object | array | null | 서비스 적용 시작일시 | |
| userSrvcApplcEndDtm | string | number | boolean | object | array | null | 서비스 적용 종료일시 | |
| success | boolean | 요청 처리 성공 여부 |
// result.data
{
"result": {},
"pubcUserInqrDVO": {},
"elctNtfYn": "...",
"userSrvcApplcStrtDtm": "...",
"userSrvcApplcEndDtm": "...",
"success": true
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| AUTH_ | 세션 없음 — 홈택스 세션이 없습니다. 홈택스 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다. | |
| PROVIDER_ | 업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다. | |
| PROVIDER_ | 업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다. | |
| PROVIDER_ | 업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다. | |
| PROVIDER_ | 업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다. | |
| PROVIDER_ | 세션 만료 — 조회하는 도중 홈택스 로그인 세션이 끝난 것을 알게 되면 이 코드로 끝나며, error.message 안내대로 로그인 액션을 다시 실행해 세션을 연 뒤 같은 요청을 다시 보냅니다. |
18. 환급금 상세 조회hometax. tax. refund. 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 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 길이 | 필수 | 설명 |
|---|---|---|---|---|---|
| strt_ | string | 8 | Y | 조회기간 시작일자 (조회일로부터 5년 이내만 조회 가능) | |
| end_ | string | 8 | Y | 조회기간 종료일자 | |
| inqr_ | string | - | N | 조회구분코드 (선택, '00'=전체, '1'=지급완료, '2'=미수령, '3'=1년경과 미수령) | |
| page_ | number | - | N | 페이지 번호 (기본: 1) | |
| page_ | number | - | N | 페이지당 조회건수 (기본: 10) | |
| txaa_ | string | - | N | 세무대리인ID (세무대리인인 경우 필수) | |
| txaa_ | string | - | N | 세무대리인 여부 (기본: N) | |
| txpr_ | string | - | N | 납세자식별번호 (주민등록번호 또는 사업자등록번호, 세무대리인인 경우 필수) | |
| output_ | array | - | N | 이 결과를 엑셀(xlsx) 파일로도 받으려면 적습니다. 예: ["xlsx"]. 파일은 result.artifacts 에 함께 오고, 빼면 데이터만 옵니다 |
- 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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.tax.refund.search_detail",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {
"strt_dt": "<필수>",
"end_dt": "<필수>",
"page_num": 1,
"page_size": 10,
"txaa_yn": "N"
}
}'Response
- result.data 의 success 값과 목록·페이지 필드를 확인합니다.
- 아래 표의 unpdNtltxRfamtBrkdSVOList[] 줄은 엑셀 파일(params 의 output_formats 에 ["xlsx"])의 열로 내보내는 칸이고, 열 이름은 홈택스 화면의 표 머리글입니다.
- 기관이 내려주는 행에는 아래 표에 없는 칸도 더 있습니다.
- 여러 JSON 타입이 함께 표시된 칸은 서버가 세부 타입을 고정하지 않는 기관 원문 또는 동적 값입니다.예시 값의 타입으로 단정하지 말고 실제 값의 타입을 확인해 주세요. null은 값이 비어 있다는 뜻이며, 필드 자체의 생략 여부는 필수 여부와 설명을 확인해 주세요.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| result | string | number | boolean | object | array | null | 홈택스 응답 본문 객체. 기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다 | |
| unpdNtltxRfamtBrkdSVOList | array | 환급 상세 목록 배열 | |
| unpdNtltxRfamtBrkdSVOList[]. | string | number | boolean | object | array | null | 세무서 | |
| unpdNtltxRfamtBrkdSVOList[]. | string | number | boolean | object | array | null | 세목 | |
| unpdNtltxRfamtBrkdSVOList[]. | string | number | boolean | object | array | null | 귀속년월 | |
| unpdNtltxRfamtBrkdSVOList[]. | string | number | boolean | object | array | null | 환급결정일자 | |
| unpdNtltxRfamtBrkdSVOList[]. | string | number | boolean | object | array | null | 지급구분 | |
| unpdNtltxRfamtBrkdSVOList[]. | string | number | boolean | object | array | null | 한국은행처리결과코드 | |
| unpdNtltxRfamtBrkdSVOList[]. | string | number | boolean | object | array | null | 환급금액 | |
| unpdNtltxRfamtBrkdSVOList[]. | string | number | boolean | object | array | null | 지급일 | |
| unpdNtltxRfamtBrkdSVOList[]. | string | number | boolean | object | array | null | 은행 | |
| unpdNtltxRfamtBrkdSVOList[]. | string | number | boolean | object | array | null | 압류대상자 | |
| unpdNtltxRfamtBrkdSVOList[]. | string | number | boolean | object | array | null | 환급ID | |
| unpdNtltxRfamtBrkdSVOList[]. | string | number | boolean | object | array | null | 송금ID | |
| unpdNtltxRfamtBrkdSVOList[]. | string | number | boolean | object | array | null | 신청대상여부 | |
| pageInfoVO | string | number | boolean | object | array | null | 페이지 정보 객체 | |
| totalCount | string | number | boolean | object | array | null | 전체 건수 | |
| pageNum | string | number | boolean | object | array | null | 페이지 번호 | |
| pageSize | string | number | boolean | object | array | null | 페이지 크기 | |
| success | boolean | 요청 처리 성공 여부 |
// result.data
{
"result": {},
"unpdNtltxRfamtBrkdSVOList": [
{
"txhfOgzNm": "...",
"itrfNm": "...",
"attrYm": "...",
"rfndDcsDfntDt": "...",
"inqrClCdNm": "...",
"bokTrtRsltCd": "...",
"rfamtPymnAmt": "...",
"pymnDt": "...",
"bankNm": "...",
"szrSbjs": "...",
"rfndId": "...",
"rmtnBrkdId": "...",
"aplnTrgtYn": "..."
}
],
"pageInfoVO": {},
"totalCount": "...",
"pageNum": "...",
"pageSize": "...",
"success": true
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| VALIDATION_ | 요청 값 오류 — 필수 값이 빠지면 홈택스에 요청하지 않고 이 코드로 끝나며, 자동 재시도 대상이 아닙니다. error.message 가 빠진 값의 이름을 알려 주니 그 값을 넣어 다시 요청합니다. txaa_yn, txaa_id, txpr_dscm_no 의 값이 맞지 않을 때도 홈택스에 요청하지 않고 같은 코드로 끝나며, error.message 가 고칠 내용을 알려 주니 그 값을 고쳐 다시 요청합니다. | |
| VALIDATION_ | 숫자 값 오류 — page_num, page_size 에 1 이상의 정수가 아닌 값(0, 음수, 소수부가 있는 수, 숫자가 아닌 글자)을 보내면 홈택스에 요청하지 않고 이 코드로 끝나며, 자동 재시도 대상이 아닙니다. error.message 가 확인할 값의 이름을 알려 주니 그 값을 고쳐 다시 요청합니다. 숫자로 된 문자열도 받고, null 로 보내면 보내지 않은 것으로 보아 기본값을 씁니다. | |
| AUTH_ | 세션 없음 — 홈택스 세션이 없습니다. 홈택스 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다. | |
| PROVIDER_ | 업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다. | |
| PROVIDER_ | 업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다. | |
| PROVIDER_ | 업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다. | |
| PROVIDER_ | 업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다. | |
| PROVIDER_ | 세션 만료 — 조회하는 도중 홈택스 로그인 세션이 끝난 것을 알게 되면 이 코드로 끝나며, error.message 안내대로 로그인 액션을 다시 실행해 세션을 연 뒤 같은 요청을 다시 보냅니다. |
19. 미수령 환급금 조회hometax. tax. unclaimed_ refund. search
MCP 도구 이름 hometax__
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
미수령 환급금을 조회합니다.
- 홈택스 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [홈택스 로그인(세션 생성)]
- 미수령 환급금이 없어도 실패가 아니며, exists 가 false 이고 unpdRfndScnt 가 0 으로 돌아옵니다.
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 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| nnf_ | string | N | 내외국인구분. 입력하지 않아도 됩니다. 기관 조회 요청에는 이 칸이 없어 값을 입력해도 조회 결과는 같습니다 | |
| txpr_ | string | Y | 납세자식별번호 (주민등록번호 또는 사업자등록번호, 하이픈 없이 숫자만 입력) | |
| txpr_ | string | 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: search-$(date +%s)-$RANDOM" \
--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 값과 응답 칸을 확인합니다.
- 여러 JSON 타입이 함께 표시된 칸은 서버가 세부 타입을 고정하지 않는 기관 원문 또는 동적 값입니다.예시 값의 타입으로 단정하지 말고 실제 값의 타입을 확인해 주세요. null은 값이 비어 있다는 뜻이며, 필드 자체의 생략 여부는 필수 여부와 설명을 확인해 주세요.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| result | string | number | boolean | object | array | null | 홈택스 응답 본문 객체. 기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다 | |
| unpdRfndScnt | number | 미수령 환급 건수 | |
| txprNm | string | number | boolean | object | array | null | 납세자명 | |
| chrgTelNo1 | string | number | boolean | object | array | null | 담당 전화번호1 | |
| chrgTelNo2 | string | number | boolean | object | array | null | 담당 전화번호2 | |
| exists | boolean | 존재 여부 | |
| message | string | 결과 메시지 | |
| success | boolean | 요청 처리 성공 여부 |
// result.data
{
"result": {},
"unpdRfndScnt": 0,
"txprNm": "...",
"chrgTelNo1": "...",
"chrgTelNo2": "...",
"exists": false,
"message": "미수령 환급금이 존재하지 않습니다.",
"success": true
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| VALIDATION_ | 요청 값 오류 — 필수 값이 빠지면 홈택스에 요청하지 않고 이 코드로 끝나며, 자동 재시도 대상이 아닙니다. error.message 가 빠진 값의 이름을 알려 주니 그 값을 넣어 다시 요청합니다. | |
| AUTH_ | 세션 없음 — 홈택스 세션이 없습니다. 홈택스 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다. | |
| PROVIDER_ | 업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다. | |
| PROVIDER_ | 업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다. | |
| PROVIDER_ | 업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다. | |
| PROVIDER_ | 업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다. | |
| PROVIDER_ | 세션 만료 — 조회하는 도중 홈택스 로그인 세션이 끝난 것을 알게 되면 이 코드로 끝나며, error.message 안내대로 로그인 액션을 다시 실행해 세션을 연 뒤 같은 요청을 다시 보냅니다. |
20. 고지 내역 조회hometax. tax. notice. search_ history
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 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 길이 | 필수 | 설명 |
|---|---|---|---|---|---|
| strt_ | string | 8 | Y | 발송시작일자 (최근 10년전부터 입력 가능) | |
| end_ | string | 8 | Y | 발송종료일자 | |
| ntpl_ | string | - | N | 개인법인구분코드 (기본: '01'=개인) | |
| page_ | number | - | N | 페이지 번호 (기본: 1) | |
| page_ | number | - | N | 페이지당 조회건수 (기본: 3) | |
| surv_ | string | - | N | 서비스제목 (선택) | |
| output_ | array | - | N | 이 결과를 엑셀(xlsx) 파일로도 받으려면 적습니다. 예: ["xlsx"]. 파일은 result.artifacts 에 함께 오고, 빼면 데이터만 옵니다 |
- 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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_history-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "hometax",
"action": "hometax.tax.notice.search_history",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {
"strt_dt": "<필수>",
"end_dt": "<필수>",
"ntpl_crp_cl_cd": "01",
"page_num": 1,
"page_size": 3
}
}'Response
- result.data 의 success 값과 목록·페이지 필드를 확인합니다.
- 아래 표의 ntfBrkdDVOList[] 줄은 엑셀 파일(params 의 output_formats 에 ["xlsx"])의 열로 내보내는 칸이고, 열 이름은 홈택스 화면의 표 머리글입니다.
- 기관이 내려주는 행에는 아래 표에 없는 칸도 더 있습니다.
- 여러 JSON 타입이 함께 표시된 칸은 서버가 세부 타입을 고정하지 않는 기관 원문 또는 동적 값입니다.예시 값의 타입으로 단정하지 말고 실제 값의 타입을 확인해 주세요. null은 값이 비어 있다는 뜻이며, 필드 자체의 생략 여부는 필수 여부와 설명을 확인해 주세요.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| result | string | number | boolean | object | array | null | 홈택스 응답 본문 객체. 기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다 | |
| ntfBrkdDVOList | array | 고지 내역 목록 배열 | |
| ntfBrkdDVOList[]. | string | number | boolean | object | array | null | 전자납부번호 | |
| ntfBrkdDVOList[]. | string | number | boolean | object | array | null | 고지세액 | |
| ntfBrkdDVOList[]. | string | number | boolean | object | array | null | 납세자명 | |
| ntfBrkdDVOList[]. | string | number | boolean | object | array | null | 납부기한 | |
| ntfBrkdDVOList[]. | string | number | boolean | object | array | null | 고지송달일 | |
| ntfBrkdDVOList[]. | string | number | boolean | object | array | null | 납부유무 | |
| ntfBrkdDVOList[]. | string | number | boolean | object | array | null | 고지서유형 | |
| ntfBrkdDVOList[]. | string | number | boolean | object | array | null | 분납/연부연납세액 | |
| ntfBrkdDVOList[]. | string | number | boolean | object | array | null | 납부할 세액 | |
| ntfBrkdDVOList[]. | string | number | boolean | object | array | null | 과세기간/세목 | |
| ntfBrkdDVOList[]. | string | number | boolean | object | array | null | 감액세액 | |
| ntfBrkdDVOList[]. | string | number | boolean | object | array | null | 등기번호 | |
| ntfBrkdDVOList[]. | string | number | boolean | object | array | null | 기납부세액 | |
| ntfBrkdDVOList[]. | string | number | boolean | object | array | null | 가산세(가산금) | |
| pageInfoVO | string | number | boolean | object | array | null | 페이지 정보 객체 | |
| totalCount | string | number | boolean | object | array | null | 전체 건수 | |
| pageNum | string | number | boolean | object | array | null | 페이지 번호 | |
| pageSize | string | number | boolean | object | array | null | 페이지 크기 | |
| success | boolean | 요청 처리 성공 여부 |
// result.data
{
"result": {},
"ntfBrkdDVOList": [
{
"elctPmtNo": "...",
"ntfTxamt": "...",
"txprNm": "...",
"pmtDt": "...",
"ntcpDlvDt": "...",
"pmtYn": "...",
"ntcpType": "...",
"iprdYirdAmt": "...",
"pmtSchuTxamt": "...",
"txnrmHt": "...",
"rdcTxamt": "...",
"rgsNo": "...",
"romAmt": "...",
"adtTxamt": "..."
}
],
"pageInfoVO": {},
"totalCount": "...",
"pageNum": "...",
"pageSize": "...",
"success": true
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| VALIDATION_ | 요청 값 오류 — 필수 값이 빠지면 홈택스에 요청하지 않고 이 코드로 끝나며, 자동 재시도 대상이 아닙니다. error.message 가 빠진 값의 이름을 알려 주니 그 값을 넣어 다시 요청합니다. strt_dt, end_dt 의 값이 맞지 않을 때도 홈택스에 요청하지 않고 같은 코드로 끝나며, error.message 가 고칠 내용을 알려 주니 그 값을 고쳐 다시 요청합니다. | |
| VALIDATION_ | 숫자 값 오류 — page_num, page_size 에 1 이상의 정수가 아닌 값(0, 음수, 소수부가 있는 수, 숫자가 아닌 글자)을 보내면 홈택스에 요청하지 않고 이 코드로 끝나며, 자동 재시도 대상이 아닙니다. error.message 가 확인할 값의 이름을 알려 주니 그 값을 고쳐 다시 요청합니다. 숫자로 된 문자열도 받고, null 로 보내면 보내지 않은 것으로 보아 기본값을 씁니다. | |
| AUTH_ | 세션 없음 — 홈택스 세션이 없습니다. 홈택스 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다. | |
| PROVIDER_ | 업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다. | |
| PROVIDER_ | 업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다. | |
| PROVIDER_ | 업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다. | |
| PROVIDER_ | 업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다. | |
| PROVIDER_ | 세션 만료 — 조회하는 도중 홈택스 로그인 세션이 끝난 것을 알게 되면 이 코드로 끝나며, error.message 안내대로 로그인 액션을 다시 실행해 세션을 연 뒤 같은 요청을 다시 보냅니다. |
21. 체납(연체) 내역 조회hometax. tax. overdue. search_ history
MCP 도구 이름 hometax__
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
체납(연체) 내역을 조회합니다.
- 홈택스 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [홈택스 로그인(세션 생성)]
- 조회 결과가 없으면 목록이 빈 배열로 돌아옵니다. 실패가 아닙니다.
- params 는 빈 객체로 보내도 호출됩니다. 사용할 인증서는 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 | - | N | 작업 파라미터입니다. 이 API 는 빈 객체로 호출할 수 있습니다. | |
| encrypted_ | object | - | N | 민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 길이 | 필수 | 설명 |
|---|---|---|---|---|---|
| strt_ | string | 8 | N | 발송시작일자 (선택) | |
| end_ | string | 8 | N | 발송종료일자 (선택) | |
| ntpl_ | string | - | N | 개인법인구분코드 (기본: '01'=개인) | |
| page_ | number | - | N | 페이지 번호 (기본: 1) | |
| page_ | number | - | N | 페이지당 조회건수 (기본: 3) | |
| surv_ | string | - | N | 서비스제목 (선택) | |
| output_ | array | - | N | 이 결과를 엑셀(xlsx) 파일로도 받으려면 적습니다. 예: ["xlsx"]. 파일은 result.artifacts 에 함께 오고, 빼면 데이터만 옵니다 |
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_history-$(date +%s)-$RANDOM" \
--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 값과 목록·페이지 필드를 확인합니다.
- 아래 표의 aftBrkdDVOList[] 줄은 엑셀 파일(params 의 output_formats 에 ["xlsx"])의 열로 내보내는 칸이고, 열 이름은 홈택스 화면의 표 머리글입니다.
- 기관이 내려주는 행에는 아래 표에 없는 칸도 더 있습니다.
- 여러 JSON 타입이 함께 표시된 칸은 서버가 세부 타입을 고정하지 않는 기관 원문 또는 동적 값입니다.예시 값의 타입으로 단정하지 말고 실제 값의 타입을 확인해 주세요. null은 값이 비어 있다는 뜻이며, 필드 자체의 생략 여부는 필수 여부와 설명을 확인해 주세요.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| result | string | number | boolean | object | array | null | 홈택스 응답 본문 객체. 기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다 | |
| aftBrkdDVOList | array | 체납 내역 목록 배열 | |
| aftBrkdDVOList[]. | string | number | boolean | object | array | null | 납세자명 | |
| aftBrkdDVOList[]. | string | number | boolean | object | array | null | 고지세액 | |
| aftBrkdDVOList[]. | string | number | boolean | object | array | null | 일부납부한세액 | |
| aftBrkdDVOList[]. | string | number | boolean | object | array | null | 체납세목명 | |
| aftBrkdDVOList[]. | string | number | boolean | object | array | null | 납부유무코드 | |
| aftBrkdDVOList[]. | string | number | boolean | object | array | null | 체납세목코드 | |
| aftBrkdDVOList[]. | string | number | boolean | object | array | null | 잔여납부할세액 | |
| aftBrkdDVOList[]. | string | number | boolean | object | array | null | 과세기간/세목 | |
| aftBrkdDVOList[]. | string | number | boolean | object | array | null | 감액세액 | |
| aftBrkdDVOList[]. | string | number | boolean | object | array | null | 가산세액 | |
| aftBrkdDVOList[]. | string | number | boolean | object | array | null | 전자납부번호 | |
| pageInfoVO | string | number | boolean | object | array | null | 페이지 정보 객체 | |
| totalCount | string | number | boolean | object | array | null | 전체 건수 | |
| pageNum | string | number | boolean | object | array | null | 페이지 번호 | |
| pageSize | string | number | boolean | object | array | null | 페이지 크기 | |
| success | boolean | 요청 처리 성공 여부 |
// result.data
{
"result": {},
"aftBrkdDVOList": [
{
"txprNm": "...",
"nftam": "...",
"poonPmtTxamt": "...",
"aftItrfNm": "...",
"pmtYnCd": "...",
"aftItrfCd": "...",
"rsdPmtTxamt": "...",
"txnrmHt": "...",
"rdcTxamt": "...",
"adtTxamt": "...",
"itrfCdPblNo": "..."
}
],
"pageInfoVO": {},
"totalCount": "...",
"pageNum": "...",
"pageSize": "...",
"success": true
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| VALIDATION_ | 숫자 값 오류 — page_num, page_size 에 1 이상의 정수가 아닌 값(0, 음수, 소수부가 있는 수, 숫자가 아닌 글자)을 보내면 홈택스에 요청하지 않고 이 코드로 끝나며, 자동 재시도 대상이 아닙니다. error.message 가 확인할 값의 이름을 알려 주니 그 값을 고쳐 다시 요청합니다. 숫자로 된 문자열도 받고, null 로 보내면 보내지 않은 것으로 보아 기본값을 씁니다. | |
| AUTH_ | 세션 없음 — 홈택스 세션이 없습니다. 홈택스 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다. | |
| PROVIDER_ | 업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다. | |
| PROVIDER_ | 업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다. | |
| PROVIDER_ | 업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다. | |
| PROVIDER_ | 업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다. | |
| PROVIDER_ | 세션 만료 — 조회하는 도중 홈택스 로그인 세션이 끝난 것을 알게 되면 이 코드로 끝나며, error.message 안내대로 로그인 액션을 다시 실행해 세션을 연 뒤 같은 요청을 다시 보냅니다. |
22. 지급명세서 조회hometax. tax. payment_ statement. search
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 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 길이 | 필수 | 설명 |
|---|---|---|---|---|---|
| attr_ | string | 4 | N | 귀속년도. txtn_ym_strt 와 txtn_ym_end 를 둘 다 보내지 않았을 때만 그 둘을 YYYY01/YYYY12 로 채웁니다 | |
| bman_ | string | - | N | 사업자등록번호 (10자리, 하이픈 제외) | |
| infp_ | string | - | N | 정보공개여부 (Y/N, 기본: Y) | |
| mate_ | string | - | Y | 자료종류코드 (A0051=근로소득, A0053=퇴직소득, A0086=사업소득 등) | |
| rcat_ | string | - | N | 접수번호 | |
| sbms_ | string | 6 | Y | 제출년월 시작 | |
| sbms_ | string | 6 | Y | 제출년월 종료 | |
| txtn_ | string | 6 | N | 과세년월 시작 (선택) | |
| txtn_ | string | 6 | 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: search-$(date +%s)-$RANDOM" \
--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": "<필수>",
"sbms_ym_strt": "202509",
"sbms_ym_end": "202510"
}
}'Response
- result.data 에 담긴 홈택스 응답 본문을 확인합니다.
- result.data 에는 홈택스가 내려준 응답 본문이 담깁니다. 화면마다 키 구성이 다르고, 기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다.
이 API 는 기관 응답 본문을 그대로 전달합니다. 고정 필드 목록이 없습니다.
// result.data — 홈택스 응답 본문이 담깁니다. 화면마다 키 구성이 다르고, 기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다.
{}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| VALIDATION_ | 요청 값 오류 — 필수 값이 빠지면 홈택스에 요청하지 않고 이 코드로 끝나며, 자동 재시도 대상이 아닙니다. error.message 가 빠진 값의 이름을 알려 주니 그 값을 넣어 다시 요청합니다. | |
| AUTH_ | 세션 없음 — 홈택스 세션이 없습니다. 홈택스 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다. | |
| PROVIDER_ | 업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다. | |
| PROVIDER_ | 업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다. | |
| PROVIDER_ | 업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다. | |
| PROVIDER_ | 업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다. | |
| PROVIDER_ | 세션 만료 — 조회하는 도중 홈택스 로그인 세션이 끝난 것을 알게 되면 이 코드로 끝나며, error.message 안내대로 로그인 액션을 다시 실행해 세션을 연 뒤 같은 요청을 다시 보냅니다. |
23. 지급명세서 등 제출내역hometax. tax. payment_ statement. search_ submit_ history
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 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 길이 | 필수 | 설명 |
|---|---|---|---|---|---|
| mate_ | string | - | N | 자료종류코드 (A0161=일용근로소득 간이지급명세서, A0162=연말정산 간이지급명세서, F0025=사업장 제공자 등의 과세자료 제출명세서 등) | |
| page_ | number | - | N | 페이지 번호 (기본: 1) | |
| page_ | number | - | N | 페이지당 조회건수 (기본: 10) | |
| sbms_ | string | 6 | Y | 제출년월 시작 | |
| sbms_ | string | 6 | Y | 제출년월 종료 | |
| txpr_ | string | - | N | 납세자번호/사업자번호 (세무대리인 조회시, 하이픈 포함/미포함 모두 가능) | |
| txtn_ | string | 6 | N | 지급(귀속)연월 시작 (선택) | |
| txtn_ | string | 6 | 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: search_submit_history-$(date +%s)-$RANDOM" \
--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_strt": "202510",
"sbms_ym_end": "202510"
}
}'Response
- result.data 에 담긴 홈택스 응답 본문을 확인합니다.
- result.data 에는 홈택스가 내려준 응답 본문이 담깁니다. 화면마다 키 구성이 다르고, 기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다.
이 API 는 기관 응답 본문을 그대로 전달합니다. 고정 필드 목록이 없습니다.
// result.data — 홈택스 응답 본문이 담깁니다. 화면마다 키 구성이 다르고, 기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다.
{}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| VALIDATION_ | 요청 값 오류 — 필수 값이 빠지면 홈택스에 요청하지 않고 이 코드로 끝나며, 자동 재시도 대상이 아닙니다. error.message 가 빠진 값의 이름을 알려 주니 그 값을 넣어 다시 요청합니다. | |
| VALIDATION_ | 숫자 값 오류 — page_num, page_size 에 1 이상의 정수가 아닌 값(0, 음수, 소수부가 있는 수, 숫자가 아닌 글자)을 보내면 홈택스에 요청하지 않고 이 코드로 끝나며, 자동 재시도 대상이 아닙니다. error.message 가 확인할 값의 이름을 알려 주니 그 값을 고쳐 다시 요청합니다. 숫자로 된 문자열도 받고, null 로 보내면 보내지 않은 것으로 보아 기본값을 씁니다. | |
| AUTH_ | 세션 없음 — 홈택스 세션이 없습니다. 홈택스 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다. | |
| PROVIDER_ | 업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다. | |
| PROVIDER_ | 업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다. | |
| PROVIDER_ | 업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다. | |
| PROVIDER_ | 업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다. | |
| PROVIDER_ | 세션 만료 — 조회하는 도중 홈택스 로그인 세션이 끝난 것을 알게 되면 이 코드로 끝나며, error.message 안내대로 로그인 액션을 다시 실행해 세션을 연 뒤 같은 요청을 다시 보냅니다. |
24. 전자세금계산서 거래처 관리hometax. tax. trade_ partner. search_ list
MCP 도구 이름 hometax__
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
관리용으로 등록한 거래처 목록을 조회합니다.
- 홈택스 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [홈택스 로그인(세션 생성)]
- 조회 결과가 없으면 목록이 빈 배열로 돌아옵니다. 실패가 아닙니다.
- params 는 빈 객체로 보내도 호출됩니다. 사용할 인증서는 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 | - | N | 작업 파라미터입니다. 이 API 는 빈 객체로 호출할 수 있습니다. | |
| encrypted_ | object | - | N | 민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| page_ | number | N | 페이지 번호 (기본: 1) | |
| page_ | number | N | 페이지당 조회건수 (기본: 10) | |
| rprs_ | string | N | 대표자명 | |
| srt_ | string | N | 정렬 기준 (1=거래처명, 2=거래처등록번호, 3=대표자명, 4=등록일자, 기본: 1) | |
| srt_ | string | N | 정렬 방식 (01=오름차순, 02=내림차순, 기본: 01) | |
| txpr_ | string | N | 거래처 등록번호 (하이픈 포함/미포함 모두 가능, 10자리=사업자, 13자리=주민) | |
| txpr_ | 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: search_list-$(date +%s)-$RANDOM" \
--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 는 기관 응답 본문을 그대로 전달합니다. 고정 필드 목록이 없습니다.
// result.data — 홈택스 응답 본문이 담깁니다. 화면마다 키 구성이 다르고, 기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다.
{}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| VALIDATION_ | 요청 값 오류 — txpr_dscm_no 의 값이 맞지 않으면 홈택스에 요청하지 않고 이 코드로 끝나며, 자동 재시도 대상이 아닙니다. error.message 가 고칠 내용을 알려 주니 그 값을 고쳐 다시 요청합니다. | |
| VALIDATION_ | 숫자 값 오류 — page_num, page_size 에 1 이상의 정수가 아닌 값(0, 음수, 소수부가 있는 수, 숫자가 아닌 글자)을 보내면 홈택스에 요청하지 않고 이 코드로 끝나며, 자동 재시도 대상이 아닙니다. error.message 가 확인할 값의 이름을 알려 주니 그 값을 고쳐 다시 요청합니다. 숫자로 된 문자열도 받고, null 로 보내면 보내지 않은 것으로 보아 기본값을 씁니다. | |
| AUTH_ | 세션 없음 — 홈택스 세션이 없습니다. 홈택스 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다. | |
| PROVIDER_ | 업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다. | |
| PROVIDER_ | 업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다. | |
| PROVIDER_ | 업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다. | |
| PROVIDER_ | 업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다. | |
| PROVIDER_ | 세션 만료 — 조회하는 도중 홈택스 로그인 세션이 끝난 것을 알게 되면 이 코드로 끝나며, error.message 안내대로 로그인 액션을 다시 실행해 세션을 연 뒤 같은 요청을 다시 보냅니다. |
25. 신용카드 매출자료 조회hometax. tax. credit_ card. search_ sales_ data
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 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 길이 | 필수 | 설명 |
|---|---|---|---|---|---|
| bsno | string | - | Y | 사업자등록번호 (10자리, 하이픈 제외) | |
| page_ | number | - | N | 페이지 번호 | |
| page_ | number | - | N | 페이지당 조회건수 | |
| qrt_ | string | - | Y | 분기 시작 (1~4) | |
| qrt_ | string | - | Y | 분기 종료 (1~4) | |
| stl_ | string | 4 | 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: search_sales_data-$(date +%s)-$RANDOM" \
--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 는 기관 응답 본문을 그대로 전달합니다. 고정 필드 목록이 없습니다.
// result.data — 홈택스 응답 본문이 담깁니다. 화면마다 키 구성이 다르고, 기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다.
{}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| VALIDATION_ | 요청 값 오류 — 필수 값이 빠지면 홈택스에 요청하지 않고 이 코드로 끝나며, 자동 재시도 대상이 아닙니다. error.message 가 빠진 값의 이름을 알려 주니 그 값을 넣어 다시 요청합니다. | |
| VALIDATION_ | 숫자 값 오류 — page_num, page_size 에 1 이상의 정수가 아닌 값(0, 음수, 소수부가 있는 수, 숫자가 아닌 글자)을 보내면 홈택스에 요청하지 않고 이 코드로 끝나며, 자동 재시도 대상이 아닙니다. error.message 가 확인할 값의 이름을 알려 주니 그 값을 고쳐 다시 요청합니다. 숫자로 된 문자열도 받고, null 로 보내면 보내지 않은 것으로 보아 기본값을 씁니다. | |
| AUTH_ | 세션 없음 — 홈택스 세션이 없습니다. 홈택스 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다. | |
| PROVIDER_ | 업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다. | |
| PROVIDER_ | 업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다. | |
| PROVIDER_ | 업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다. | |
| PROVIDER_ | 업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다. | |
| PROVIDER_ | 세션 만료 — 조회하는 도중 홈택스 로그인 세션이 끝난 것을 알게 되면 이 코드로 끝나며, error.message 안내대로 로그인 액션을 다시 실행해 세션을 연 뒤 같은 요청을 다시 보냅니다. |
26. 원천세 수정신고 부표 저장hometax. tax. withholding. amendment_ report. annex_ save
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 와 함께 쓰지 않습니다. |
- 대괄호 []는 목록의 각 항목을, 점은 객체의 속성을, {key}는 실제 키로 바꿔 넣는 사전 항목을 뜻하며, 선택인 부모를 보낼 때 하위 필수 칸은 조건부로 표시합니다.
| 순번 | 변수명 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| source_ | string | Y | 이어서 진행할 이전 단계 작업의 job_id 를 그대로 입력합니다(job_ 으로 시작하는 작업 번호). 명세 저장(detail_save)이나 부표 저장(annex_save) 결과, 또는 그 상태에서 실행한 조회(lookup) 결과를 받습니다. 부표 종류가 승계명세(refund_succession)이면 기본정보 저장(basic_save) 결과도 받습니다. 같은 조직과 환경, 같은 기관 연결에서 이 신고 유형으로 성공한 작업이어야 하고 아니면 진행하지 않고 거절하며, 받지 않는 작성 상태의 결과이면 409 로 거절합니다 | |
| expected_ | string | Y | source_job_id 작업 결과의 snapshot_hash 를 그대로 입력합니다(소문자 16진수 64자리). 그 작업의 내용과 맞지 않으면 진행하지 않고 작성 내용이 바뀌었다는 오류(409)로 거절합니다 | |
| annex_ | object | Y | 저장할 부표를 담는 객체입니다. kind 에 부표 종류를 입력하고, 값을 바꿀 때는 datasets 에, 행을 추가하거나 수정하거나 삭제할 때는 row_operations 에 담습니다. 같은 목록을 두 곳에 함께 입력하면 입력 오류로 거절합니다. 행을 수정하거나 삭제할 때는 query.kind 가 annex_rows 이고 query.annex_kind 에 같은 부표 종류를 입력한 조회(lookup) 결과의 row_targets 에서 받은 row_index 와 expected_row_hash 를 함께 입력하며, 기관의 지금 행과 다르면 409 로 거절합니다. 행을 추가할 때는 그 둘을 입력하지 않고, 삭제할 때는 values 를 입력하지 않습니다. 환급신청 부표(refund)는 이 신고 유형에서 받지 않고 거절합니다. 승계명세(refund_succession)는 바뀐 행이 없으면 거절하고, 저장한 뒤에는 명세 저장(detail_save)을 다시 해야 합니다. 안쪽 칸은 요구사항 조회(requirements) 결과의 actions 아래 annex_save 항목 schema 에 있습니다. JSON 문자열이 아니라 객체로 입력하며 문자열이면 입력 오류로 거절합니다 | |
| annex_ | string | Y | refund_succession은 승계명세 저장 후 본표 detail_save가 필요합니다. refund는 환급신청을 선택한 대화형에서만 지원합니다. 허용값: ["income_persons", "annex", "refund", "previous_refund", "paid_tax", "refund_succession"] | |
| annex_ | object | N | 부표의 값을 바꿀 때 쓰는 객체입니다. 키는 그 부표에서 바꿀 수 있는 기관 데이터 이름이고, 값은 바꿀 칸만 담은 객체나 행 객체 목록입니다. 행 목록은 기관 행과 개수가 같아야 하며, 행 수를 바꾸려면 row_operations 를 씁니다. 바꿀 수 없는 데이터 이름은 입력 오류로 거절합니다 | |
| annex_ | object | N | 명세 조회 결과의 행을 추가, 수정, 삭제합니다. 한 묶음의 행 번호는 변경 전 조회 기준입니다 | |
| annex_ | string | 조건부 | 행 작업의 종류입니다. 새 행은 add, 기존 행 수정은 update, 기존 행 삭제는 delete 로 입력합니다. 허용값: ["add", "update", "delete"] | |
| annex_ | number | N | 수정하거나 삭제할 행의 위치입니다. 부표 행 조회(lookup 의 query.kind 가 annex_rows) 결과의 row_targets 에서 받은 값을 그대로 입력하며 add 에는 입력하지 않습니다. 조회 결과의 범위를 벗어나거나 기관의 지금 행과 다르면 거절합니다. 최솟값: 0. 생략 시 기본값: null | |
| annex_ | string | N | 수정하거나 삭제할 행의 확인값입니다(소문자 16진수 64자리). row_index 와 같은 row_targets 항목에서 받은 값을 그대로 입력하며 add 에는 입력하지 않습니다. 기관의 지금 행과 다르면 409 로 거절합니다. 문자열 패턴: "^[0-9a-f]{64}$". 생략 시 기본값: null | |
| annex_ | object | 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: annex_save-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "hometax",
"action": "hometax.tax.withholding.amendment_report.annex_save",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {
"source_job_id": "<필수>",
"expected_snapshot_hash": "<필수>",
"annex_document": {
"kind": "<필수>"
}
}
}'Response
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| success | boolean | 단계가 끝났는지입니다. 응답으로 돌아왔다면 항상 true 입니다. 실패는 이 모양이 아니라 오류 응답으로 옵니다. | |
| step | string | 응답이 어느 단계의 결과인지입니다. 이 액션은 항상 `annex_save` 입니다. | |
| state | string | 이 단계가 끝난 뒤 작업이 놓인 상태입니다. `basic_saved` 또는 `annex_saved` 중 하나입니다. 앞의 상태는 승계명세를 저장해 상위 신고의 소득 명세 저장을 다시 불러야 하는 경우이고 뒤의 상태는 그 밖의 부표를 저장한 경우입니다. | |
| snapshot | object | 이 단계가 끝난 작업 상태의 사본입니다. 다음 단계가 이어받는 값이라 직접 고치지 않습니다. | |
| snapshot_ | string | snapshot 의 해시(SHA-256, 16진수 64자)입니다. 다음 단계를 부를 때 expected_snapshot_hash 에 그대로 넣고, 이 작업의 job_id 는 source_job_id 에 넣습니다. 그 사이 작업 상태가 바뀌었으면 거절됩니다. | |
| data | object | 기관이 부표 저장 요청에 돌려준 응답 본문입니다. 저장한 행이 기관 재조회 결과와 같음을 확인한 뒤에만 이 응답이 돌아오고, 다르면 오류로 끝납니다. | |
| data. | object | 승계명세(부표 종류 `refund_succession`)를 저장했을 때만 응답 본문에 더해지는 묶음입니다. 그 밖의 부표에는 이 칸이 없습니다. | |
| data. | string | 저장한 승계명세의 환급액 합계(원)입니다. 숫자를 문자열로 담고, 상위 신고의 소득 명세 저장이 이 값을 이어받습니다. | |
| data. | boolean | 상위 신고의 소득 명세 저장을 다시 불러야 하는지입니다. 승계명세를 저장하면 상위 신고에 합계가 반영되므로 항상 true 입니다. | |
| warnings | array | 경고 문장의 목록입니다. 이 상품은 경고를 싣지 않아 항상 빈 배열입니다. | |
| outcome | string | 기관 쓰기가 확인됐는지를 가르는 판정입니다. 응답으로 돌아왔다면 항상 `confirmed` 입니다. 결과를 확인하지 못한 경우는 이 모양이 아니라 오류로 끝납니다. 작업 결과 판정이 이 자리를 읽습니다. | |
| action | string | 쓰기 액션의 이름입니다. 이 액션은 항상 `hometax.tax.withholding.amendment_report.annex_save` 입니다. 작업 결과 판정이 이 자리를 읽습니다. |
// result.data - 값 자리에는 각 칸의 형식을 적었습니다 (실제 값이 아닙니다)
{
"success": "<boolean>",
"step": "<string>",
"state": "<string>",
"snapshot": {},
"snapshot_hash": "<string>",
"data": {
"refund_succession": {
"amount": "<string>",
"parent_detail_save_required": "<boolean>"
}
},
"warnings": [],
"outcome": "<string>",
"action": "<string>"
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| VALIDATION_ | 요청 칸이 빠졌거나 칸 값이 이 단계의 요청 형식에 맞지 않으면 홈택스에 아무것도 보내지 않고 이 오류로 끝납니다. 빠진 칸이 있으면 error.message 는 「요청에 필요한 값이 빠졌습니다. 빠진 값: 칸 이름. 그 값을 넣어 다시 요청해 주세요.」 꼴이고, 그 밖의 검사에 걸린 칸이 있으면 「요청 값이 올바르지 않습니다. 확인할 값: 칸 이름. 값을 고쳐 다시 요청해 주세요.」 꼴이며, 둘 다 있으면 두 문장이 차례로 이어집니다. 칸 이름 자리에는 걸린 칸이 다섯까지 쉼표로 이어지고 더 있으면 「외 N개」 가 붙으며, 목록이나 객체 안의 칸은 「바깥 칸.0.안쪽 칸」 처럼 위치를 점으로 이은 경로로 적습니다. 걸린 검사가 모두 칸 하나를 짚지 않고 요청 전체를 보는 것이면 「요청 값이 올바르지 않습니다.」 만 옵니다. | |
| RESOURCE_ | 이어 받을 이전 작업(source_job_id)이 같은 조직과 환경에서 성공한 이 신고 유형의 작업이 아니거나, 그 결과를 읽을 수 없거나, 결과에 작성 스냅샷이 없거나 스냅샷이 expected_snapshot_hash 와 다르면 홈택스에 보내기 전에 이 오류로 끝납니다. error.message 는 걸린 확인의 문장 하나이고, BE 문장은 「이 신고 유형에서 성공한 이전 단계 작업이 필요합니다」, 「이전 작업의 작성 스냅샷이 없습니다」, 「작성 내용이 바뀌었습니다. 최신 결과를 다시 확인해 주세요」, 「같은 조직·환경에서 성공한 이전 단계의 작업이 필요합니다」, 「이전 작업의 JSON 결과를 읽을 수 없습니다」 입니다. | |
| RESOURCE_ | 작업 상태나 이어 받은 내용, 또는 홈택스에 있는 신고서의 상태가 이 단계와 맞지 않으면 이 오류로 끝납니다. 이 단계에서 이 코드로 끝나는 확인의 BE 문장은 「현재 작성 상태에서는 이 단계를 실행할 수 없습니다. 최신 결과를 확인해 주세요」, 「기관이 현재 신고서의 불러오기를 허용하지 않았습니다」, 「기관이 다른 작성 건을 반환했습니다」, 「불러온 신고서의 식별자가 다릅니다」, 「불러온 신고서의 기간·유형이 다릅니다」, 「불러온 신고서의 사업자가 다릅니다」, 「기관의 수정신고 원신고 연결이 변경됐습니다」, 「수정신고가 원신고를 덮어쓸 수 없습니다」, 「기관의 신고서가 다른 작성 건으로 바뀌었습니다」, 「승인한 뒤 기관 작성 내용이 변경됐습니다. 최신 내용을 다시 확인해 주세요」, 「명세 조회 결과의 신고서 식별자가 다릅니다」, 「명세의 행 번호·해시가 현재 기관 자료와 다릅니다」, 「대상 행이 조회 후 변경됐습니다」, 「다른 신고서의 행은 수정할 수 없습니다」, 「다른 신고서의 신규 행은 추가할 수 없습니다」, 「저장 후 명세 재조회가 다른 신고서를 가리킵니다」, 「저장한 명세의 거래·금액이 기관 재조회와 일치하지 않습니다. 재저장하지 말고 처리 결과를 확인해 주세요」, 「승계 환급액 합계가 저장 후 재조회와 다릅니다」 이고, 걸린 확인의 문장 하나가 error.message 로 실립니다. | |
| AUTH_ | 저장된 기관 세션이 없습니다. 같은 연동 계정으로 hometax.session.login 을 먼저 실행해 세션을 연 뒤 다시 보냅니다. |
27. 원천세 수정신고 기본정보 저장hometax. tax. withholding. amendment_ report. basic_ save
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 와 함께 쓰지 않습니다. |
- 대괄호 []는 목록의 각 항목을, 점은 객체의 속성을, {key}는 실제 키로 바꿔 넣는 사전 항목을 뜻하며, 선택인 부모를 보낼 때 하위 필수 칸은 조건부로 표시합니다.
| 순번 | 변수명 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| source_ | string | Y | 이어서 진행할 이전 단계 작업의 job_id 를 그대로 입력합니다(job_ 으로 시작하는 작업 번호). 작성 준비(init)나 기본정보 저장(basic_save) 결과, 또는 그 상태에서 실행한 조회(lookup) 결과를 받습니다. 같은 조직과 환경, 같은 기관 연결에서 이 신고 유형으로 성공한 작업이어야 하고 아니면 진행하지 않고 거절하며, 받지 않는 작성 상태의 결과이면 409 로 거절합니다 | |
| expected_ | string | Y | source_job_id 작업 결과의 snapshot_hash 를 그대로 입력합니다(소문자 16진수 64자리). 그 작업의 내용과 맞지 않으면 진행하지 않고 작성 내용이 바뀌었다는 오류(409)로 거절합니다 | |
| basic_ | object | N | 기관에서 불러온 기본정보 중 바꿀 값만 입력합니다. 생략한 값은 유지합니다 | |
| basic_ | object | N | 원천징수의무자 정보(사업자등록번호, 상호, 대표자 성명) 가운데 바꿀 값만 담는 객체입니다. 생략한 값은 기관 값을 그대로 쓰고, null 로 입력하면 입력 오류로 거절합니다 | |
| basic_ | string | N | 원천징수의무자의 사업자등록번호입니다. 하이픈 없이 숫자 10자리로 입력합니다. 별칭 businessNo 로도 보낼 수 있습니다. 문자열 패턴: "^\\d{10}$". 생략 시 기본값: null | |
| basic_ | string | N | 원천징수의무자의 상호입니다. 1자 이상으로 입력합니다. 별칭 companyName 로도 보낼 수 있습니다. 최소 길이: 1. 생략 시 기본값: null | |
| basic_ | string | N | 대표자 성명입니다. 1자 이상으로 입력합니다. 최소 길이: 1. 생략 시 기본값: null | |
| basic_ | object | N | 신고 선택 사항(신고 주기, 연말정산, 소득처분, 환급 신청, 일괄 납부, 사업자단위 과세) 가운데 바꿀 값만 담는 객체입니다. 생략한 값은 기관 값을 그대로 쓰고, null 로 입력하면 입력 오류로 거절합니다 | |
| basic_ | string | N | 신고 주기입니다. 매월 신고는 monthly, 반기 신고는 semiannual 로 입력합니다. 별칭 periodType 로도 보낼 수 있습니다. 허용값: ["monthly", "semiannual"]. 생략 시 기본값: null | |
| basic_ | string | N | 연말정산 포함 여부(Y/N). 기한후 신고에서 Y 이면 귀속월이 2월, 3월, 4월 가운데 하나여야 합니다. 별칭 yearEnd 로도 보낼 수 있습니다. 허용값: ["Y", "N"]. 생략 시 기본값: null | |
| basic_ | string | N | 소득처분 신고 여부입니다. Y 또는 N 으로 입력합니다. 수정신고는 Y 를 받지 않고 입력 오류로 거절합니다. 허용값: ["Y", "N"]. 생략 시 기본값: null | |
| basic_ | string | N | 환급 신청 여부입니다. Y 또는 N 으로 입력합니다. 기한후 신고와 수정신고는 Y 를 받지 않고 입력 오류로 거절합니다. 별칭 refundApply 로도 보낼 수 있습니다. 허용값: ["Y", "N"]. 생략 시 기본값: null | |
| basic_ | string | N | 일괄 납부 여부입니다. Y 또는 N 으로 입력합니다. 별칭 bulkPayment 로도 보낼 수 있습니다. 허용값: ["Y", "N"]. 생략 시 기본값: null | |
| basic_ | string | N | 사업자단위 과세 여부입니다. Y 또는 N 으로 입력합니다. 별칭 businessUnit 로도 보낼 수 있습니다. 허용값: ["Y", "N"]. 생략 시 기본값: null | |
| basic_ | array | N | 신고할 소득 종류의 목록입니다. 기관 소득구분 코드 F01 부터 F11 가운데 하나 이상을 중복 없이 입력하며, employment(근로소득, F01), retirement(퇴직소득, F02), business(사업소득, F03), other(기타소득, F04) 이름도 받습니다. 목록에 없는 코드나 중복은 입력 오류로 거절하고, 생략하면 기관 값을 그대로 씁니다. 별칭 selectedIncomeTypes 로도 보낼 수 있습니다. 최소 항목 수: 1. 생략 시 기본값: null |
- 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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: basic_save-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "hometax",
"action": "hometax.tax.withholding.amendment_report.basic_save",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {
"source_job_id": "<필수>",
"expected_snapshot_hash": "<필수>"
}
}'Response
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| success | boolean | 단계가 끝났는지입니다. 응답으로 돌아왔다면 항상 true 입니다. 실패는 이 모양이 아니라 오류 응답으로 옵니다. | |
| step | string | 응답이 어느 단계의 결과인지입니다. 이 액션은 항상 `basic_save` 입니다. | |
| state | string | 이 단계가 끝난 뒤 작업이 놓인 상태입니다. `basic_saved` 입니다. | |
| snapshot | object | 이 단계가 끝난 작업 상태의 사본입니다. 다음 단계가 이어받는 값이라 직접 고치지 않습니다. | |
| snapshot_ | string | snapshot 의 해시(SHA-256, 16진수 64자)입니다. 다음 단계를 부를 때 expected_snapshot_hash 에 그대로 넣고, 이 작업의 job_id 는 source_job_id 에 넣습니다. 그 사이 작업 상태가 바뀌었으면 거절됩니다. | |
| data | object | 기관이 기본정보 저장 요청에 돌려준 응답 본문입니다. 저장한 신고 옵션이 기관 재조회 결과와 같음을 확인한 뒤에만 이 응답이 돌아오고, 다르면 오류로 끝납니다. | |
| warnings | array | 경고 문장의 목록입니다. 이 상품은 경고를 싣지 않아 항상 빈 배열입니다. | |
| outcome | string | 기관 쓰기가 확인됐는지를 가르는 판정입니다. 응답으로 돌아왔다면 항상 `confirmed` 입니다. 결과를 확인하지 못한 경우는 이 모양이 아니라 오류로 끝납니다. 작업 결과 판정이 이 자리를 읽습니다. | |
| action | string | 쓰기 액션의 이름입니다. 이 액션은 항상 `hometax.tax.withholding.amendment_report.basic_save` 입니다. 작업 결과 판정이 이 자리를 읽습니다. |
// result.data - 값 자리에는 각 칸의 형식을 적었습니다 (실제 값이 아닙니다)
{
"success": "<boolean>",
"step": "<string>",
"state": "<string>",
"snapshot": {},
"snapshot_hash": "<string>",
"data": {},
"warnings": [],
"outcome": "<string>",
"action": "<string>"
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| VALIDATION_ | 요청 칸이 빠졌거나 칸 값이 이 단계의 요청 형식에 맞지 않으면 홈택스에 아무것도 보내지 않고 이 오류로 끝납니다. 빠진 칸이 있으면 error.message 는 「요청에 필요한 값이 빠졌습니다. 빠진 값: 칸 이름. 그 값을 넣어 다시 요청해 주세요.」 꼴이고, 그 밖의 검사에 걸린 칸이 있으면 「요청 값이 올바르지 않습니다. 확인할 값: 칸 이름. 값을 고쳐 다시 요청해 주세요.」 꼴이며, 둘 다 있으면 두 문장이 차례로 이어집니다. 칸 이름 자리에는 걸린 칸이 다섯까지 쉼표로 이어지고 더 있으면 「외 N개」 가 붙으며, 목록이나 객체 안의 칸은 「바깥 칸.0.안쪽 칸」 처럼 위치를 점으로 이은 경로로 적습니다. 걸린 검사가 모두 칸 하나를 짚지 않고 요청 전체를 보는 것이면 「요청 값이 올바르지 않습니다.」 만 옵니다. | |
| RESOURCE_ | 이어 받을 이전 작업(source_job_id)이 같은 조직과 환경에서 성공한 이 신고 유형의 작업이 아니거나, 그 결과를 읽을 수 없거나, 결과에 작성 스냅샷이 없거나 스냅샷이 expected_snapshot_hash 와 다르면 홈택스에 보내기 전에 이 오류로 끝납니다. error.message 는 걸린 확인의 문장 하나이고, BE 문장은 「이 신고 유형에서 성공한 이전 단계 작업이 필요합니다」, 「이전 작업의 작성 스냅샷이 없습니다」, 「작성 내용이 바뀌었습니다. 최신 결과를 다시 확인해 주세요」, 「같은 조직·환경에서 성공한 이전 단계의 작업이 필요합니다」, 「이전 작업의 JSON 결과를 읽을 수 없습니다」 입니다. | |
| RESOURCE_ | 작업 상태나 이어 받은 내용, 또는 홈택스에 있는 신고서의 상태가 이 단계와 맞지 않으면 이 오류로 끝납니다. 이 단계에서 이 코드로 끝나는 확인의 BE 문장은 「현재 작성 상태에서는 이 단계를 실행할 수 없습니다. 최신 결과를 확인해 주세요」, 「마감된 원신고가 없어 수정신고를 시작하지 않았습니다」, 「수정할 원신고를 기관 신고 목록에서 선택해 주세요」, 「기관이 현재 신고 기간·유형으로 작성을 허용하지 않았습니다 (판정 코드)」, 「재작성할 제출 신고서의 식별자를 현재 기관 조회 결과에서 선택해 주세요」, 「불러온 신고서의 식별자가 다릅니다」, 「불러온 신고서의 기간·유형이 다릅니다」, 「불러온 신고서의 사업자가 다릅니다」, 「기관의 수정신고 원신고 연결이 변경됐습니다」, 「수정신고가 원신고를 덮어쓸 수 없습니다」, 「작성 중인 신고가 있습니다. 이어서 작성하거나 작성 취소 후 새로 시작해 주세요」, 「기관에서 원신고에 대한 수정신고 시작을 확인하지 못했습니다 (판정 코드)」, 「기관의 수정신고 원신고 연결이 확인되지 않았습니다」, 「선택한 원신고와 기관의 수정 대상이 다릅니다」, 「이어서 작성할 신고서가 없습니다. 새로 시작해 주세요.」, 「지금 상태에서는 진행할 수 없습니다. 신고서 상태를 확인한 뒤 다시 시도해 주세요.」, 「기관에서 다른 신고 식별자를 반환했습니다」, 「기관 조회 회사와 작성 중인 회사의 사업자등록번호가 다릅니다」, 「신규 작성 상태가 변경됐습니다. 작성 중 신고서를 확인해 주세요」, 「기관이 현재 신고서의 불러오기를 허용하지 않았습니다」, 「작성 식별자가 바뀌었습니다」, 「신규 신고서 준비 상태가 아닙니다」, 「작성 중인 회사와 기본정보의 회사가 다릅니다」, 「기관이 다른 작성 건을 반환했습니다」, 「기관의 신고서가 다른 작성 건으로 바뀌었습니다」, 「저장한 신고 옵션이 기관 재조회 결과와 다릅니다. 재저장하지 말고 작성 내용을 확인해 주세요」 이고, 걸린 확인의 문장 하나가 error.message 로 실립니다. 문장의 판정 코드 자리에는 홈택스가 신고서 상태 확인에서 돌려준 판정 코드가 들어가고, 판정이 비어 있으면 「기관 상태 없음」 이 들어갑니다. | |
| AUTH_ | 저장된 기관 세션이 없습니다. 같은 연동 계정으로 hometax.session.login 을 먼저 실행해 세션을 연 뒤 다시 보냅니다. |
28. 원천세 수정신고 작성 취소hometax. tax. withholding. amendment_ report. cancel_ draft
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 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| source_ | string | Y | 이어서 진행할 이전 단계 작업의 job_id 를 그대로 입력합니다(job_ 으로 시작하는 작업 번호). 작성 준비(init)부터 미리보기(preview)까지 작성 중인 상태의 결과, 또는 그 상태에서 실행한 조회(lookup) 결과를 받습니다. 제출(submit)이 끝난 신고서는 작성 취소할 수 없어 409 로 거절합니다. 같은 조직과 환경, 같은 기관 연결에서 이 신고 유형으로 성공한 작업이어야 하고 아니면 진행하지 않고 거절하며, 받지 않는 작성 상태의 결과이면 409 로 거절합니다 | |
| expected_ | string | Y | source_job_id 작업 결과의 snapshot_hash 를 그대로 입력합니다(소문자 16진수 64자리). 그 작업의 내용과 맞지 않으면 진행하지 않고 작성 내용이 바뀌었다는 오류(409)로 거절합니다 | |
| confirmation_ | string | N | 1회용 확인 토큰입니다. 처음에는 보내지 않습니다. 토큰 없이 부르면 기관에 아무것도 보내지 않고 작업도 만들지 않은 채 확인이 필요하다는 오류(WRITE_CONFIRMATION_REQUIRED)로 끝나고, 응답의 error.confirmation_token 에 토큰이 옵니다. error.message 의 안내를 사용자에게 보여 주고 동의를 받은 뒤 같은 요청에 이 토큰을 넣어 다시 부릅니다. 토큰은 10분 안에 한 번만 쓸 수 있고 처음 요청과 같은 본문, 같은 호출자, 같은 환경에서만 맞으며, 아니면 확인이 만료됐거나 내용이 달라졌다는 오류로 거절합니다 |
- 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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: cancel_draft-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "hometax",
"action": "hometax.tax.withholding.amendment_report.cancel_draft",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {
"source_job_id": "<필수>",
"expected_snapshot_hash": "<필수>"
}
}'Response
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| success | boolean | 단계가 끝났는지입니다. 응답으로 돌아왔다면 항상 true 입니다. 실패는 이 모양이 아니라 오류 응답으로 옵니다. | |
| step | string | 응답이 어느 단계의 결과인지입니다. 이 액션은 항상 `cancel_draft` 입니다. | |
| state | string | 이 단계가 끝난 뒤 작업이 놓인 상태입니다. `cancelled` 입니다. | |
| snapshot | object | 이 단계가 끝난 작업 상태의 사본입니다. 다음 단계가 이어받는 값이라 직접 고치지 않습니다. | |
| snapshot_ | string | snapshot 의 해시(SHA-256, 16진수 64자)입니다. 다음 단계를 부를 때 expected_snapshot_hash 에 그대로 넣고, 이 작업의 job_id 는 source_job_id 에 넣습니다. 그 사이 작업 상태가 바뀌었으면 거절됩니다. | |
| data | object | 기관이 작성 취소 요청에 돌려준 응답 본문입니다. 기관이 취소 완료를 확인하고 응답이 다른 작성 신고서를 가리키지 않을 때만 이 응답이 돌아오고, 아니면 오류로 끝납니다. | |
| warnings | array | 경고 문장의 목록입니다. 이 상품은 경고를 싣지 않아 항상 빈 배열입니다. | |
| outcome | string | 기관 쓰기가 확인됐는지를 가르는 판정입니다. 응답으로 돌아왔다면 항상 `confirmed` 입니다. 결과를 확인하지 못한 경우는 이 모양이 아니라 오류로 끝납니다. 작업 결과 판정이 이 자리를 읽습니다. | |
| action | string | 쓰기 액션의 이름입니다. 이 액션은 항상 `hometax.tax.withholding.amendment_report.cancel_draft` 입니다. 작업 결과 판정이 이 자리를 읽습니다. |
// result.data - 값 자리에는 각 칸의 형식을 적었습니다 (실제 값이 아닙니다)
{
"success": "<boolean>",
"step": "<string>",
"state": "<string>",
"snapshot": {},
"snapshot_hash": "<string>",
"data": {},
"warnings": [],
"outcome": "<string>",
"action": "<string>"
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| WRITE_ | 요청에 확인 토큰(confirmation_token)이 없으면 홈택스에 아무것도 보내지 않고 작업도 만들지 않은 채 이 오류로 끝납니다. error.message 는 「작성 중인 원천세 수정신고서를 기관에서 작성 취소하면 되돌릴 수 없어 취소 전 확인이 필요합니다. 아래 내용을 사용자에게 보여주고 동의를 받으세요.」 로 시작하고 error.confirmation_token 에 1회용 토큰이 옵니다. 이 단계의 확인에는 미리보기 내용이 없어 error.preview 는 빈 객체입니다. 이 내용을 고객에게 그대로 보여 주고 확인을 받은 뒤, 같은 요청의 params.confirmation_token 에 응답의 error.confirmation_token 값을 넣어 다시 호출해 주세요. 토큰은 10분 안에 한 번만 쓸 수 있고, 확인한 요청 본문과 같은 본문에만 맞습니다. | |
| WRITE_ | 토큰이 만료됐거나, 이미 썼거나, 다른 호출자나 다른 환경에서 받은 것이거나, 확인한 요청 본문과 달라졌으면 홈택스에 아무것도 보내지 않고 작업도 만들지 않은 채 이 오류로 끝납니다. error.message 는 「확인이 만료됐거나 확인한 내용과 달라졌습니다. 다시 확인해 주세요.」 입니다. 토큰 없이 다시 요청하면 새 토큰을 받습니다. | |
| VALIDATION_ | 요청 칸이 빠졌거나 칸 값이 이 단계의 요청 형식에 맞지 않으면 홈택스에 아무것도 보내지 않고 이 오류로 끝납니다. 빠진 칸이 있으면 error.message 는 「요청에 필요한 값이 빠졌습니다. 빠진 값: 칸 이름. 그 값을 넣어 다시 요청해 주세요.」 꼴이고, 그 밖의 검사에 걸린 칸이 있으면 「요청 값이 올바르지 않습니다. 확인할 값: 칸 이름. 값을 고쳐 다시 요청해 주세요.」 꼴이며, 둘 다 있으면 두 문장이 차례로 이어집니다. 칸 이름 자리에는 걸린 칸이 다섯까지 쉼표로 이어지고 더 있으면 「외 N개」 가 붙으며, 목록이나 객체 안의 칸은 「바깥 칸.0.안쪽 칸」 처럼 위치를 점으로 이은 경로로 적습니다. 걸린 검사가 모두 칸 하나를 짚지 않고 요청 전체를 보는 것이면 「요청 값이 올바르지 않습니다.」 만 옵니다. | |
| RESOURCE_ | 이어 받을 이전 작업(source_job_id)이 같은 조직과 환경에서 성공한 이 신고 유형의 작업이 아니거나, 그 결과를 읽을 수 없거나, 결과에 작성 스냅샷이 없거나 스냅샷이 expected_snapshot_hash 와 다르면 홈택스에 보내기 전에 이 오류로 끝납니다. error.message 는 걸린 확인의 문장 하나이고, BE 문장은 「이 신고 유형에서 성공한 이전 단계 작업이 필요합니다」, 「이전 작업의 작성 스냅샷이 없습니다」, 「작성 내용이 바뀌었습니다. 최신 결과를 다시 확인해 주세요」, 「같은 조직·환경에서 성공한 이전 단계의 작업이 필요합니다」, 「이전 작업의 JSON 결과를 읽을 수 없습니다」 입니다. | |
| RESOURCE_ | 작업 상태나 이어 받은 내용, 또는 홈택스에 있는 신고서의 상태가 이 단계와 맞지 않으면 이 오류로 끝납니다. 이 단계에서 이 코드로 끝나는 확인의 BE 문장은 「현재 작성 상태에서는 이 단계를 실행할 수 없습니다. 최신 결과를 확인해 주세요」, 「기관이 현재 신고서의 불러오기를 허용하지 않았습니다」, 「기관이 다른 작성 건을 반환했습니다」, 「불러온 신고서의 식별자가 다릅니다」, 「불러온 신고서의 기간·유형이 다릅니다」, 「불러온 신고서의 사업자가 다릅니다」, 「기관의 수정신고 원신고 연결이 변경됐습니다」, 「수정신고가 원신고를 덮어쓸 수 없습니다」, 「기관의 신고서가 다른 작성 건으로 바뀌었습니다」, 「승인한 뒤 기관 작성 내용이 변경됐습니다. 최신 내용을 다시 확인해 주세요」, 「기관에서 작성 취소 완료가 확인되지 않았습니다」, 「취소 응답이 다른 작성 신고서를 가리킵니다」 이고, 걸린 확인의 문장 하나가 error.message 로 실립니다. | |
| AUTH_ | 저장된 기관 세션이 없습니다. 같은 연동 계정으로 hometax.session.login 을 먼저 실행해 세션을 연 뒤 다시 보냅니다. |
29. 원천세 수정신고 소득별 상세 저장hometax. tax. withholding. amendment_ report. detail_ save
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 와 함께 쓰지 않습니다. |
- 대괄호 []는 목록의 각 항목을, 점은 객체의 속성을, {key}는 실제 키로 바꿔 넣는 사전 항목을 뜻하며, 선택인 부모를 보낼 때 하위 필수 칸은 조건부로 표시합니다.
| 순번 | 변수명 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| source_ | string | Y | 이어서 진행할 이전 단계 작업의 job_id 를 그대로 입력합니다(job_ 으로 시작하는 작업 번호). 기본정보가 저장된 상태의 결과를 받습니다. 기본정보 저장(basic_save), 명세 저장(detail_save), 부표 저장(annex_save) 결과와 query.kind 가 prefill 인 조회(lookup)에서 빠진 항목(missing_fields)이 없던 결과가 그렇고, 작성 준비(init) 결과는 받지 않습니다. 같은 조직과 환경, 같은 기관 연결에서 이 신고 유형으로 성공한 작업이어야 하고 아니면 진행하지 않고 거절하며, 받지 않는 작성 상태의 결과이면 409 로 거절합니다 | |
| expected_ | string | Y | source_job_id 작업 결과의 snapshot_hash 를 그대로 입력합니다(소문자 16진수 64자리). 그 작업의 내용과 맞지 않으면 진행하지 않고 작성 내용이 바뀌었다는 오류(409)로 거절합니다 | |
| detail_ | object | Y | 저장할 소득 명세를 담는 객체입니다. 안쪽 칸과 필수 여부는 요구사항 조회(requirements) 결과의 actions 아래 detail_save 항목 schema 에 있습니다. JSON 문자열이 아니라 객체로 입력하며 문자열이면 입력 오류로 거절합니다 | |
| detail_ | object | Y | 소득 명세 구분별로 바꿀 소득행을 담는 객체입니다. 키는 employment, retirement, business, other 같은 소득 이름이나 기관 명세 구분 번호이고, 값은 그 구분의 소득행 목록입니다. 하나 이상 입력하며 기관 화면에 없는 구분은 입력 오류로 거절합니다. 소득행에는 code 와 바꿀 칸만 넣고, 생략한 칸은 기관 값을 그대로 씁니다. 합계 행과 납부세액은 서버가 다시 계산합니다. JSON 문자열이 아니라 객체로 입력하며 문자열이면 입력 오류로 거절합니다. 별칭 incomeSections 로도 보낼 수 있습니다 | |
| detail_ | string | Y | 바꿀 소득행의 원천징수소득코드입니다. A 나 C 로 시작하는 세 자리(예 A01)이고, 기관 명세에 이미 있는 행이어야 하며 같은 구분에서 같은 코드를 두 번 입력하면 입력 오류로 거절합니다. 문자열 패턴: "^[AC]\\d{2}$" | |
| detail_ | number | N | 소득 지급 인원수입니다. 0 이상의 정수로 입력하며, 지급 총액이나 징수세액이 있는 행은 인원이 있어야 합니다. 별칭 incPymnNfpCnt 로도 보낼 수 있습니다. 최솟값: 0. 생략 시 기본값: null | |
| detail_ | number | N | 소득 지급 총액(원)입니다. 정수로 입력하며, 인원이 있는 행은 0 보다 커야 합니다. 별칭 incPymnTotaPymnAmt 로도 보낼 수 있습니다. 생략 시 기본값: null | |
| detail_ | number | N | 징수 소득세액(원)입니다. 정수로 입력합니다. 별칭 inctxLvyTxamt 로도 보낼 수 있습니다. 생략 시 기본값: null | |
| detail_ | number | N | 징수 농어촌특별세액(원)입니다. 정수로 입력합니다. 별칭 fnftxLvyTxamt 로도 보낼 수 있습니다. 생략 시 기본값: null | |
| detail_ | number | N | 징수 가산세액(원)입니다. 0 이상의 정수로 입력합니다. 별칭 adttxLvyTxamt 로도 보낼 수 있습니다. 최솟값: 0. 생략 시 기본값: null | |
| detail_ | number | N | 당월 조정 환급세액(원)입니다. 정수로 입력합니다. 별칭 tmnMetnRfndTxamt 로도 보낼 수 있습니다. 생략 시 기본값: null | |
| detail_ | number | N | 납부 소득세액(원)입니다. 서버가 행의 값으로 다시 계산하므로 생략하고, 입력하면 계산값과 같아야 하며 다르면 입력 오류로 거절합니다. 별칭 inctxPmtTxamt 로도 보낼 수 있습니다. 생략 시 기본값: null | |
| detail_ | number | N | 납부 농어촌특별세액(원)입니다. 서버가 행의 값으로 다시 계산하므로 생략하고, 입력하면 계산값과 같아야 하며 다르면 입력 오류로 거절합니다. 별칭 fnftxPmtTxamt 로도 보낼 수 있습니다. 생략 시 기본값: null | |
| detail_ | object | N | 기관에서 불러온 환급 입력값 중 바꿀 항목만 보냅니다. 합계와 차감잔액은 자동 계산합니다. 별칭 refundAdjustment 로도 보낼 수 있습니다 | |
| detail_ | number | N | 전월 미환급세액(원)입니다. 0 이상의 정수로 입력합니다. 별칭 pvmnNrfnTxamt 로도 보낼 수 있습니다. 최솟값: 0. 생략 시 기본값: null | |
| detail_ | number | N | 기환급 신청세액(원)입니다. 0 이상의 정수이고 전월 미환급세액보다 크면 입력 오류로 거절합니다. 별칭 pvmnArefAplnTxamt 로도 보낼 수 있습니다. 최솟값: 0. 생략 시 기본값: null | |
| detail_ | number | N | 신탁재산(금융회사 등) 환급세액(원)입니다. 0 이상의 정수로 입력합니다. 별칭 trstPrpFnnOrgnTxamt 로도 보낼 수 있습니다. 최솟값: 0. 생략 시 기본값: null | |
| detail_ | number | N | 그 밖의 환급세액(금융회사 등, 원)입니다. 0 이상의 정수로 입력합니다. 별칭 fnnEtcRfndTxamt 로도 보낼 수 있습니다. 최솟값: 0. 생략 시 기본값: null | |
| detail_ | number | N | 환급 신청액(원)입니다. 0 이상의 정수이고 차월 이월 환급세액보다 크면 입력 오류로 거절합니다. 수정신고가 아닌 신고서에서 기본정보의 환급 신청이 Y 이면 환급 신청액과 차월 이월 환급세액이 모두 0 보다 커야 합니다. 별칭 rfndAplnAmt 로도 보낼 수 있습니다. 최솟값: 0. 생략 시 기본값: null |
- 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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: detail_save-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "hometax",
"action": "hometax.tax.withholding.amendment_report.detail_save",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {
"source_job_id": "<필수>",
"expected_snapshot_hash": "<필수>",
"detail_document": {
"income_sections": {
"{key}": [
{
"code": "<필수>"
}
]
}
}
}
}'Response
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| success | boolean | 단계가 끝났는지입니다. 응답으로 돌아왔다면 항상 true 입니다. 실패는 이 모양이 아니라 오류 응답으로 옵니다. | |
| step | string | 응답이 어느 단계의 결과인지입니다. 이 액션은 항상 `detail_save` 입니다. | |
| state | string | 이 단계가 끝난 뒤 작업이 놓인 상태입니다. `detail_saved` 입니다. | |
| snapshot | object | 이 단계가 끝난 작업 상태의 사본입니다. 다음 단계가 이어받는 값이라 직접 고치지 않습니다. | |
| snapshot_ | string | snapshot 의 해시(SHA-256, 16진수 64자)입니다. 다음 단계를 부를 때 expected_snapshot_hash 에 그대로 넣고, 이 작업의 job_id 는 source_job_id 에 넣습니다. 그 사이 작업 상태가 바뀌었으면 거절됩니다. | |
| data | object | 기관이 소득 명세 저장 요청에 돌려준 응답 본문입니다. 저장한 금액과 환급 계산값이 기관 재조회 결과와 같음을 확인한 뒤에만 이 응답이 돌아오고, 다르면 오류로 끝납니다. | |
| warnings | array | 경고 문장의 목록입니다. 이 상품은 경고를 싣지 않아 항상 빈 배열입니다. | |
| outcome | string | 기관 쓰기가 확인됐는지를 가르는 판정입니다. 응답으로 돌아왔다면 항상 `confirmed` 입니다. 결과를 확인하지 못한 경우는 이 모양이 아니라 오류로 끝납니다. 작업 결과 판정이 이 자리를 읽습니다. | |
| action | string | 쓰기 액션의 이름입니다. 이 액션은 항상 `hometax.tax.withholding.amendment_report.detail_save` 입니다. 작업 결과 판정이 이 자리를 읽습니다. |
// result.data - 값 자리에는 각 칸의 형식을 적었습니다 (실제 값이 아닙니다)
{
"success": "<boolean>",
"step": "<string>",
"state": "<string>",
"snapshot": {},
"snapshot_hash": "<string>",
"data": {},
"warnings": [],
"outcome": "<string>",
"action": "<string>"
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| VALIDATION_ | 요청 칸이 빠졌거나 칸 값이 이 단계의 요청 형식에 맞지 않으면 홈택스에 아무것도 보내지 않고 이 오류로 끝납니다. 빠진 칸이 있으면 error.message 는 「요청에 필요한 값이 빠졌습니다. 빠진 값: 칸 이름. 그 값을 넣어 다시 요청해 주세요.」 꼴이고, 그 밖의 검사에 걸린 칸이 있으면 「요청 값이 올바르지 않습니다. 확인할 값: 칸 이름. 값을 고쳐 다시 요청해 주세요.」 꼴이며, 둘 다 있으면 두 문장이 차례로 이어집니다. 칸 이름 자리에는 걸린 칸이 다섯까지 쉼표로 이어지고 더 있으면 「외 N개」 가 붙으며, 목록이나 객체 안의 칸은 「바깥 칸.0.안쪽 칸」 처럼 위치를 점으로 이은 경로로 적습니다. 걸린 검사가 모두 칸 하나를 짚지 않고 요청 전체를 보는 것이면 「요청 값이 올바르지 않습니다.」 만 옵니다. | |
| RESOURCE_ | 이어 받을 이전 작업(source_job_id)이 같은 조직과 환경에서 성공한 이 신고 유형의 작업이 아니거나, 그 결과를 읽을 수 없거나, 결과에 작성 스냅샷이 없거나 스냅샷이 expected_snapshot_hash 와 다르면 홈택스에 보내기 전에 이 오류로 끝납니다. error.message 는 걸린 확인의 문장 하나이고, BE 문장은 「이 신고 유형에서 성공한 이전 단계 작업이 필요합니다」, 「이전 작업의 작성 스냅샷이 없습니다」, 「작성 내용이 바뀌었습니다. 최신 결과를 다시 확인해 주세요」, 「같은 조직·환경에서 성공한 이전 단계의 작업이 필요합니다」, 「이전 작업의 JSON 결과를 읽을 수 없습니다」 입니다. | |
| RESOURCE_ | 작업 상태나 이어 받은 내용, 또는 홈택스에 있는 신고서의 상태가 이 단계와 맞지 않으면 이 오류로 끝납니다. 이 단계에서 이 코드로 끝나는 확인의 BE 문장은 「현재 작성 상태에서는 이 단계를 실행할 수 없습니다. 최신 결과를 확인해 주세요」, 「기관이 현재 신고서의 불러오기를 허용하지 않았습니다」, 「기관이 다른 작성 건을 반환했습니다」, 「불러온 신고서의 식별자가 다릅니다」, 「불러온 신고서의 기간·유형이 다릅니다」, 「불러온 신고서의 사업자가 다릅니다」, 「기관의 수정신고 원신고 연결이 변경됐습니다」, 「수정신고가 원신고를 덮어쓸 수 없습니다」, 「기관의 신고서가 다른 작성 건으로 바뀌었습니다」, 「승인한 뒤 기관 작성 내용이 변경됐습니다. 최신 내용을 다시 확인해 주세요」, 「저장한 금액이 기관 재조회 결과와 다릅니다. 재저장하지 말고 작성 내용을 확인해 주세요」, 「저장한 환급 계산값이 기관 재조회 결과와 다릅니다. 재저장하지 말고 작성 내용을 확인해 주세요」 이고, 걸린 확인의 문장 하나가 error.message 로 실립니다. | |
| AUTH_ | 저장된 기관 세션이 없습니다. 같은 연동 계정으로 hometax.session.login 을 먼저 실행해 세션을 연 뒤 다시 보냅니다. |
30. 원천세 수정신고 신고 내역 조회hometax. tax. withholding. amendment_ report. history
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 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 길이 | 필수 | 설명 |
|---|---|---|---|---|---|
| business_ | string | - | Y | 신고 내역을 조회할 사업자의 사업자등록번호입니다. 하이픈 없이 숫자 10자리로 입력합니다 | |
| start_ | string | 8 | Y | 조회 기간의 시작일입니다. 여덟 자리의 실제 날짜로 입력하며 end_date 보다 늦으면 입력 오류로 거절합니다 | |
| end_ | string | - | Y | 조회 기간의 종료일입니다. 형식은 start_date 와 같고 start_date 보다 빠를 수 없습니다 | |
| page_ | number | - | N | 받을 쪽 번호입니다. 1부터 세는 정수이고 입력하지 않으면 1 입니다 | |
| page_ | number | - | N | 한 쪽에 받을 신고 수입니다. 1 이상 100 이하의 정수이고 입력하지 않으면 10 입니다 |
- 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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: history-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "hometax",
"action": "hometax.tax.withholding.amendment_report.history",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {
"business_no": "<필수>",
"start_date": "<필수>",
"end_date": "<필수>"
}
}'Response
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| success | boolean | 단계가 끝났는지입니다. 응답으로 돌아왔다면 항상 true 입니다. 실패는 이 모양이 아니라 오류 응답으로 옵니다. | |
| step | string | 응답이 어느 단계의 결과인지입니다. 이 액션은 항상 `history` 입니다. | |
| data | object | 조회 결과 객체입니다. rows 는 요청한 기간의 원천세 신고 목록입니다. 부른 단계의 신고 종류와 관계없이 정기신고, 수정신고, 기한후신고를 가리지 않고 모두 오므로 필요한 신고는 세부 구분 코드(detail_code)로 골라 씁니다. 신고마다 담는 값은 접수번호(receipt_no), 신고 건 식별번호(filing_reference), 귀속연월(attribution_ym), 지급연월(payment_ym), 신고 종류 코드(return_kind_code), 신고 종류 이름(return_kind_name), 세부 구분 코드(detail_code), 세부 구분 이름(detail_name), 사업자등록번호(business_no), 접수일(receipt_date), 신고일(filing_date), 제출연월(submit_ym), 최종 신고 여부(is_final_filing), 차감 납부세액(payable_tax_amount), 납부 상태(payment_status), 첨부서류 접수 건수 표기(attachment_receipt_text), 삭제신청 가능 여부 안내(deletion_eligibility_reason), 상호(business_name) 입니다. 연월은 여섯 자리, 접수일과 신고일은 연월일 여덟 자리이며 값은 기관이 준 그대로이고 없는 값은 null 입니다. 최종 신고 여부만 true 또는 false 로 옮기며 기관 값이 없으면 null 입니다. page 는 페이지 번호(page_num), 페이지 크기(page_size), 전체 건수(total_count)이고 기관이 페이지 정보를 주지 않으면 세 값 모두 null 입니다. |
// result.data - 값 자리에는 각 칸의 형식을 적었습니다 (실제 값이 아닙니다)
{
"success": "<boolean>",
"step": "<string>",
"data": {}
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| VALIDATION_ | 요청 칸이 빠졌거나 칸 값이 이 단계의 요청 형식에 맞지 않으면 홈택스에 아무것도 보내지 않고 이 오류로 끝납니다. 빠진 칸이 있으면 error.message 는 「요청에 필요한 값이 빠졌습니다. 빠진 값: 칸 이름. 그 값을 넣어 다시 요청해 주세요.」 꼴이고, 그 밖의 검사에 걸린 칸이 있으면 「요청 값이 올바르지 않습니다. 확인할 값: 칸 이름. 값을 고쳐 다시 요청해 주세요.」 꼴이며, 둘 다 있으면 두 문장이 차례로 이어집니다. 칸 이름 자리에는 걸린 칸이 다섯까지 쉼표로 이어지고 더 있으면 「외 N개」 가 붙으며, 목록이나 객체 안의 칸은 「바깥 칸.0.안쪽 칸」 처럼 위치를 점으로 이은 경로로 적습니다. 걸린 검사가 모두 칸 하나를 짚지 않고 요청 전체를 보는 것이면 「요청 값이 올바르지 않습니다.」 만 옵니다. | |
| AUTH_ | 저장된 기관 세션이 없습니다. 같은 연동 계정으로 hometax.session.login 을 먼저 실행해 세션을 연 뒤 다시 보냅니다. |
31. 원천세 수정신고 초안 초기화hometax. tax. withholding. amendment_ report. init
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 와 함께 쓰지 않습니다. |
- 대괄호 []는 목록의 각 항목을, 점은 객체의 속성을, {key}는 실제 키로 바꿔 넣는 사전 항목을 뜻하며, 선택인 부모를 보낼 때 하위 필수 칸은 조건부로 표시합니다.
| 순번 | 변수명 | 타입 | 길이 | 필수 | 설명 |
|---|---|---|---|---|---|
| business_ | string | - | Y | 신고할 사업자등록번호 10자리 | |
| periods | object | - | Y | 신고 기간 세 값을 담은 객체입니다. submitYm(제출연월), attrYm(귀속연월), pymnYm(지급연월)을 각각 YYYYMM 여섯 자리로 입력하고, 귀속연월이 지급연월보다 늦거나 지급연월이 제출연월보다 늦으면 입력 오류로 거절합니다. JSON 문자열이 아니라 객체로 입력하며 문자열이면 입력 오류로 거절합니다 | |
| periods. | string | 6 | Y | 제출연월입니다. 신고서를 제출하는 연월을 여섯 자리로 입력합니다. 별칭 submitYm 로도 보낼 수 있습니다. 문자열 패턴: "^\\d{4}(0[1-9]|1[0-2])$" | |
| periods. | string | 6 | Y | 귀속연월입니다. 소득이 귀속되는 연월을 여섯 자리로 입력합니다. 작성 준비(init)에서는 지급연월보다 늦으면 입력 오류로 거절합니다. 별칭 attrYm 로도 보낼 수 있습니다. 문자열 패턴: "^\\d{4}(0[1-9]|1[0-2])$" | |
| periods. | string | 6 | Y | 지급연월입니다. 소득을 지급한 연월을 여섯 자리로 입력합니다. 작성 준비(init)에서는 제출연월보다 늦으면 입력 오류로 거절합니다. 별칭 pymnYm 로도 보낼 수 있습니다. 문자열 패턴: "^\\d{4}(0[1-9]|1[0-2])$" | |
| draft_ | string | - | N | 작성 방식입니다. new(기본값)는 수정신고를 새로 작성합니다. 이미 제출한 수정신고가 있으면 그것을 복사해 다시 작성하고, 없으면 마감된 원래 신고를 바탕으로 처음 작성합니다. resume 은 기관에 저장해 둔 작성 중 수정신고를 이어서 씁니다. new 인데 작성 중인 수정신고가 이미 있으면 그것을 지우지 않고 409 로 거절합니다. 다른 값은 입력 오류로 거절합니다 | |
| originalReturnId | string | - | N | 수정할 기관 신고서 ID 입니다. 신고 내역 조회(history) 결과 rows 의 신고 건 식별번호(filing_reference)에서 고릅니다. 이미 제출한 수정신고를 다시 고칠 때(draft_mode 가 new)는 기관이 돌려준 그 제출 신고서의 ID 와 같아야 하고 빠지거나 다르면 409 로 거절합니다. 수정신고를 처음 작성할 때는 수정할 원래 신고의 ID 이며, 수정할 수 있는 원래 신고가 하나뿐이면 생략할 수 있고 여럿인데 고르지 않으면 409 로 거절합니다. resume 으로 이어 쓸 때 입력하면 기관이 그 작성 중 신고서에 연결해 둔 원신고 ID 와 같아야 하며 다르면 409 로 거절합니다 |
- 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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: init-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "hometax",
"action": "hometax.tax.withholding.amendment_report.init",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {
"business_no": "<필수>",
"periods": {
"submit_ym": "<필수>",
"attr_ym": "<필수>",
"pymn_ym": "<필수>"
}
}
}'Response
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| success | boolean | 단계가 끝났는지입니다. 응답으로 돌아왔다면 항상 true 입니다. 실패는 이 모양이 아니라 오류 응답으로 옵니다. | |
| step | string | 응답이 어느 단계의 결과인지입니다. 이 액션은 항상 `init` 입니다. | |
| state | string | 이 단계가 끝난 뒤 작업이 놓인 상태입니다. `initialized` 입니다. | |
| snapshot | object | 이 단계가 끝난 작업 상태의 사본입니다. 다음 단계가 이어받는 값이라 직접 고치지 않습니다. | |
| snapshot_ | string | snapshot 의 해시(SHA-256, 16진수 64자)입니다. 다음 단계를 부를 때 expected_snapshot_hash 에 그대로 넣고, 이 작업의 job_id 는 source_job_id 에 넣습니다. 그 사이 작업 상태가 바뀌었으면 거절됩니다. | |
| data | object | 작성 시작 결과 묶음입니다. 기관에서 작성 건을 준비하고 그 식별자와 읽어 온 값을 담습니다. 기관이 작성을 확인하지 않으면 이 모양이 아니라 오류로 끝납니다. | |
| data. | string | 기관이 이 작성 건에 붙인 신고서 식별자입니다. 새로 작성하는 건은 기관이 첫 기본정보 저장 때 식별자를 주므로 그전에는 빈 문자열입니다. | |
| data. | object | 기관에서 읽어 채운 기본정보와 소득 명세 초안입니다. 조회의 `prefill` 종류와 같은 칸을 가집니다. | |
| data. | object | 기관에서 읽은 신고 기본사항입니다. 사업자 정보(taxpayer), 선택한 소득종류(selectedIncomeTypes), 신고 구분(report)을 담고, 기관 응답에 없는 값은 비어 있습니다. 기본정보를 저장할 때 그대로 쓸 수 있습니다. | |
| data. | object | 기관에서 읽은 소득 명세 초안입니다. incomeSections 아래에 소득종류별로 행(code 와 금액 칸)을 담습니다. | |
| data. | array | 더 받아야 하는 칸의 경로 목록입니다. 비어 있는 기본정보 항목의 경로와, 금액을 숫자로 읽지 못한 항목의 경로가 함께 들어 있습니다. 모두 갖췄으면 빈 배열입니다. | |
| data. | array | 고객에게 물어볼 질문의 목록입니다. 작성 시작과 자동채움 조회에서는 missing_fields 마다 한 문장씩입니다. 저장 신고서 조회가 입력이 모자라거나 선택을 요청하는 응답에서는 문장이 아니라 `key`, `label_ko`, `required` 칸을 가진 객체의 목록입니다. | |
| data. | object | 읽은 값이 어디서 왔는지의 표입니다. 칸 경로가 키이고 출처 경로가 값입니다. 기관 데이터셋에서 읽었으면 `datasets.` 로, 요청으로 정했으면 `request.` 로 시작하고, 작업 정보에서 온 값은 `snapshot.` 으로 시작합니다. | |
| data. | object | 금액을 숫자로 읽지 못한 값의 표입니다. 칸 경로가 키이고 기관이 준 원래 값이 값입니다. 없으면 빈 객체입니다. | |
| data. | array | 아직 기관에서 읽지 못한 소득종류의 이름 목록입니다. 선택한 소득종류의 명세가 현재 작성 건에 아직 없을 때 들어갑니다. | |
| data. | boolean | 소득 명세를 모두 읽었는지입니다. unread_sections 가 비어 있으면 true 입니다. | |
| warnings | array | 경고 문장의 목록입니다. 이 상품은 경고를 싣지 않아 항상 빈 배열입니다. | |
| outcome | string | 기관 쓰기가 확인됐는지를 가르는 판정입니다. 응답으로 돌아왔다면 항상 `confirmed` 입니다. 결과를 확인하지 못한 경우는 이 모양이 아니라 오류로 끝납니다. 작업 결과 판정이 이 자리를 읽습니다. | |
| action | string | 쓰기 액션의 이름입니다. 이 액션은 항상 `hometax.tax.withholding.amendment_report.init` 입니다. 작업 결과 판정이 이 자리를 읽습니다. |
// result.data - 값 자리에는 각 칸의 형식을 적었습니다 (실제 값이 아닙니다)
{
"success": "<boolean>",
"step": "<string>",
"state": "<string>",
"snapshot": {},
"snapshot_hash": "<string>",
"data": {
"rtnCvaId": "<string>",
"prefill": {
"basic_document": {},
"detail_document": {},
"missing_fields": [],
"inputs": [],
"field_sources": {},
"unresolved_values": {},
"unread_sections": [],
"detail_loaded": "<boolean>"
}
},
"warnings": [],
"outcome": "<string>",
"action": "<string>"
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| VALIDATION_ | 요청 칸이 빠졌거나 칸 값이 이 단계의 요청 형식에 맞지 않으면 홈택스에 아무것도 보내지 않고 이 오류로 끝납니다. 빠진 칸이 있으면 error.message 는 「요청에 필요한 값이 빠졌습니다. 빠진 값: 칸 이름. 그 값을 넣어 다시 요청해 주세요.」 꼴이고, 그 밖의 검사에 걸린 칸이 있으면 「요청 값이 올바르지 않습니다. 확인할 값: 칸 이름. 값을 고쳐 다시 요청해 주세요.」 꼴이며, 둘 다 있으면 두 문장이 차례로 이어집니다. 칸 이름 자리에는 걸린 칸이 다섯까지 쉼표로 이어지고 더 있으면 「외 N개」 가 붙으며, 목록이나 객체 안의 칸은 「바깥 칸.0.안쪽 칸」 처럼 위치를 점으로 이은 경로로 적습니다. 걸린 검사가 모두 칸 하나를 짚지 않고 요청 전체를 보는 것이면 「요청 값이 올바르지 않습니다.」 만 옵니다. | |
| RESOURCE_ | 작업 상태나 이어 받은 내용, 또는 홈택스에 있는 신고서의 상태가 이 단계와 맞지 않으면 이 오류로 끝납니다. 이 단계에서 이 코드로 끝나는 확인의 BE 문장은 「마감된 원신고가 없어 수정신고를 시작하지 않았습니다」, 「수정할 원신고를 기관 신고 목록에서 선택해 주세요」, 「기관이 현재 신고 기간·유형으로 작성을 허용하지 않았습니다 (판정 코드)」, 「재작성할 제출 신고서의 식별자를 현재 기관 조회 결과에서 선택해 주세요」, 「불러온 신고서의 식별자가 다릅니다」, 「불러온 신고서의 기간·유형이 다릅니다」, 「불러온 신고서의 사업자가 다릅니다」, 「기관의 수정신고 원신고 연결이 변경됐습니다」, 「수정신고가 원신고를 덮어쓸 수 없습니다」, 「작성 중인 신고가 있습니다. 이어서 작성하거나 작성 취소 후 새로 시작해 주세요」, 「기관에서 원신고에 대한 수정신고 시작을 확인하지 못했습니다 (판정 코드)」, 「기관의 수정신고 원신고 연결이 확인되지 않았습니다」, 「선택한 원신고와 기관의 수정 대상이 다릅니다」, 「이어서 작성할 신고서가 없습니다. 새로 시작해 주세요.」, 「지금 상태에서는 진행할 수 없습니다. 신고서 상태를 확인한 뒤 다시 시도해 주세요.」, 「기관에서 다른 신고 식별자를 반환했습니다」, 「기관 조회 회사와 작성 중인 회사의 사업자등록번호가 다릅니다」 이고, 걸린 확인의 문장 하나가 error.message 로 실립니다. 문장의 판정 코드 자리에는 홈택스가 신고서 상태 확인에서 돌려준 판정 코드가 들어가고, 판정이 비어 있으면 「기관 상태 없음」 이 들어갑니다. | |
| AUTH_ | 저장된 기관 세션이 없습니다. 같은 연동 계정으로 hometax.session.login 을 먼저 실행해 세션을 연 뒤 다시 보냅니다. |
32. 원천세 수정신고 작성 참고자료 조회hometax. tax. withholding. amendment_ report. lookup
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 와 함께 쓰지 않습니다. |
- 대괄호 []는 목록의 각 항목을, 점은 객체의 속성을, {key}는 실제 키로 바꿔 넣는 사전 항목을 뜻하며, 선택인 부모를 보낼 때 하위 필수 칸은 조건부로 표시합니다.
| 순번 | 변수명 | 타입 | 길이 | 필수 | 설명 |
|---|---|---|---|---|---|
| source_ | string | - | N | 현재 신고서의 이전 단계 작업 job_id 입니다(job_ 으로 시작하는 작업 번호). query.kind 가 saved_returns 이면 생략할 수 있고 다른 조회에는 필요하며, 입력할 때는 expected_snapshot_hash 와 함께 입력해야 하고 하나만 입력하면 입력 오류로 거절합니다. 같은 조직과 환경, 같은 기관 연결에서 이 신고 유형으로 성공한 작업이어야 하고 아니면 진행하지 않고 거절하며, 받지 않는 작성 상태의 결과이면 409 로 거절합니다 | |
| expected_ | string | - | N | source_job_id 와 함께 입력하는 값입니다. source_job_id 작업 결과의 snapshot_hash 를 그대로 입력합니다(소문자 16진수 64자리). 그 작업의 내용과 맞지 않으면 진행하지 않고 작성 내용이 바뀌었다는 오류(409)로 거절합니다 | |
| query | object | - | Y | 조회 종류와 조건을 담은 객체입니다. kind 로 종류를 고르며, saved_returns 는 기관에 저장해 둔 작성 중 신고서를 찾거나 불러오고, prefill 은 현재 신고서를 기관에서 다시 읽어 자동 채움 값을 돌려주고, paid_tax 는 기납부 명세를, surcharge 는 미납세액의 가산세를 조회하고, annex_rows 는 현재 신고서의 부표 행을 읽습니다. 어느 종류도 기관에 저장하거나 제출하지 않습니다. 종류마다 받는 칸은 요구사항 조회(requirements) 결과의 actions 아래 lookup 항목 schema 에 있고, 모르는 kind 는 입력 오류로 거절합니다. JSON 문자열이 아니라 객체로 입력하며 문자열이면 입력 오류로 거절합니다 | |
| query. | string | - | Y | 조회 종류입니다. paid_tax 로 입력하면 기납부 명세를 조회합니다. 고정값: "paid_tax" | |
| query. | string | 6 | Y | 조회할 귀속연월입니다. 여섯 자리로 입력하며, 현재 신고서 제출연도의 5년 전 1월보다 이르면 입력 오류로 거절합니다. 별칭 txnrmYm 로도 보낼 수 있습니다. 문자열 패턴: "^\\d{4}(0[1-9]|1[0-2])$" | |
| query. | string | 6 | Y | 조회할 지급연월입니다. 여섯 자리로 입력하며, 귀속연월보다 이르면 입력 오류로 거절합니다. 별칭 pymnYm 로도 보낼 수 있습니다. 문자열 패턴: "^\\d{4}(0[1-9]|1[0-2])$" | |
| query. | string | - | Y | 조회할 소득구분 코드입니다. 현재 신고서의 기관 코드 목록에 있는 값이어야 하고 없으면 입력 오류로 거절합니다. 별칭 whtxIncClCd 로도 보낼 수 있습니다. 최소 길이: 1 | |
| query. | string | - | Y | 조회할 원천징수소득코드입니다. 고른 소득구분에 속한 기관 코드여야 하고 A05, A06, A27, A28 은 받지 않으며, 아니면 입력 오류로 거절합니다. 별칭 whtxIncCd 로도 보낼 수 있습니다. 최소 길이: 1 | |
| query. | string | - | Y | 조회 종류입니다. surcharge 로 입력하면 미납세액의 가산세를 조회합니다. 고정값: "surcharge" | |
| query. | number | - | Y | 가산세를 계산할 미납세액(원)입니다. 0 보다 큰 10원 단위 정수로 입력하며, 10원 단위가 아니면 값을 바꾸지 않고 입력 오류로 거절합니다. 별칭 npmtTxamt 로도 보낼 수 있습니다 | |
| query. | string | 8 | Y | 미납세액의 원래 납부기한입니다. 여덟 자리의 실제 날짜로 입력하며, 오늘보다 이전이고 최근 10년 이내이며 납부일보다 이전이어야 합니다. 아니면 입력 오류로 거절합니다. 별칭 pmtDdt 로도 보낼 수 있습니다. 문자열 패턴: "^\\d{8}$" | |
| query. | string | 8 | Y | 실제로 납부할 날짜입니다. 여덟 자리의 실제 날짜로 입력하며, 오늘이거나 그 뒤여야 하고 아니면 입력 오류로 거절합니다. 별칭 pmtDt 로도 보낼 수 있습니다. 문자열 패턴: "^\\d{8}$" | |
| query. | string | - | Y | 조회 종류입니다. prefill 로 입력하면 현재 신고서를 기관에서 다시 읽어 자동 채움 값을 돌려주며, 다른 칸은 받지 않습니다. 고정값: "prefill" | |
| query. | string | - | Y | 조회 종류입니다. saved_returns 로 입력하면 기관에 저장해 둔 작성 중 신고서를 찾고, load 를 true 로 주거나 returnId 를 주면 불러옵니다. 고정값: "saved_returns" | |
| query. | string | - | N | 이전 작업에 있으면 생략합니다. 문자열 패턴: "^\\d{10}$". 생략 시 기본값: null | |
| query. | object | - | N | 찾을 신고서의 제출연월, 귀속연월, 지급연월입니다. 이전 작업에 있으면 생략하고, 함께 입력하면 이전 작업의 기간과 같아야 하며 다르면 409 로 거절합니다. 생략 시 기본값: null | |
| query. | string | 6 | 조건부 | 제출연월입니다. 신고서를 제출하는 연월을 여섯 자리로 입력합니다. 별칭 submitYm 로도 보낼 수 있습니다. 문자열 패턴: "^\\d{4}(0[1-9]|1[0-2])$" | |
| query. | string | 6 | 조건부 | 귀속연월입니다. 소득이 귀속되는 연월을 여섯 자리로 입력합니다. 작성 준비(init)에서는 지급연월보다 늦으면 입력 오류로 거절합니다. 별칭 attrYm 로도 보낼 수 있습니다. 문자열 패턴: "^\\d{4}(0[1-9]|1[0-2])$" | |
| query. | string | 6 | 조건부 | 지급연월입니다. 소득을 지급한 연월을 여섯 자리로 입력합니다. 작성 준비(init)에서는 제출연월보다 늦으면 입력 오류로 거절합니다. 별칭 pymnYm 로도 보낼 수 있습니다. 문자열 패턴: "^\\d{4}(0[1-9]|1[0-2])$" | |
| query. | string | - | N | 신고서 작성월 검색 시작. 생략하면 홈택스처럼 현재 월을 조회합니다. 문자열 패턴: "^\\d{4}(0[1-9]|1[0-2])$". 생략 시 기본값: null | |
| query. | string | - | N | 신고서 작성월 검색 종료. 귀속연월, 지급연월과 별개입니다. 문자열 패턴: "^\\d{4}(0[1-9]|1[0-2])$". 생략 시 기본값: null | |
| query. | string | - | N | 불러올 작성 중 신고서의 식별값입니다. load 없이 먼저 조회한 결과 choices 의 rtnCvaId 를 그대로 입력하면 그 신고서를 불러오고, 같은 사업자와 기간, 신고 유형의 목록에 없으면 409 로 거절합니다. 별칭 returnId 로도 보낼 수 있습니다. 최소 길이: 1. 최대 길이: 100. 생략 시 기본값: null | |
| query. | boolean | - | N | 불러올 신고서가 하나면 자동 선택합니다. 여러 개면 목록에서 선택합니다. 생략 시 기본값: false | |
| query. | string | - | Y | 조회 종류입니다. annex_rows 로 입력하면 현재 신고서의 부표 행을 읽습니다. 고정값: "annex_rows" | |
| query. | string | - | Y | 현재 작성 건의 부표를 읽습니다. 반환한 row_targets의 row_index와 expected_row_hash로 수정하거나 삭제할 대상을 지정합니다. 허용값: ["income_persons", "annex", "refund", "previous_refund", "paid_tax", "refund_succession"] |
- 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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: lookup-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "hometax",
"action": "hometax.tax.withholding.amendment_report.lookup",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {
"query": {
"kind": "<필수>",
"txnrm_ym": "<필수>",
"pymn_ym": "<필수>",
"whtx_inc_cl_cd": "<필수>",
"whtx_inc_cd": "<필수>",
"npmt_txamt": "<필수: number>",
"pmt_ddt": "<필수>",
"pmt_dt": "<필수>",
"annex_kind": "<필수>"
}
}
}'Response
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| success | boolean | 단계가 끝났는지입니다. 응답으로 돌아왔다면 항상 true 입니다. 실패는 이 모양이 아니라 오류 응답으로 옵니다. | |
| step | string | 응답이 어느 단계의 결과인지입니다. 이 액션은 항상 `lookup` 입니다. | |
| state | string | 조회가 끝난 뒤 작업이 놓인 상태입니다. 입력이 모자라 기관에 가지 않았으면 `needs_input`, 후보 신고서 목록을 돌려주면 `selection_required`, 그 밖에는 이어받은 작업의 현재 상태입니다. | |
| snapshot | object | 조회가 끝난 작업 상태의 사본입니다. 다음 단계가 이어받는 값이라 직접 고치지 않습니다. 입력이 모자라 기관에 가지 않은 응답(state 가 `needs_input`)에는 이 칸이 없습니다. | |
| snapshot_ | string | snapshot 의 해시(SHA-256, 16진수 64자)입니다. 다음 단계를 부를 때 expected_snapshot_hash 에 그대로 넣고, 이 작업의 job_id 는 source_job_id 에 넣습니다. 입력이 모자라 기관에 가지 않은 응답(state 가 `needs_input`)에는 이 칸이 없습니다. | |
| data | object | 조회 결과 묶음입니다. 칸은 조회 종류(kind)마다 다릅니다. 아래 칸마다 어느 종류에서 오는지 적었습니다. | |
| data. | string | 조회 종류입니다. `saved_returns`, `prefill`, `paid_tax`, `annex_rows`, `surcharge` 중 하나이고, 요청한 query.kind 와 같습니다. | |
| data. | object | 기관의 응답 본문입니다. 기납부세액 조회(`paid_tax`), 가산세 계산(`surcharge`), 부표 행 조회(`annex_rows`)에만 있습니다. | |
| data. | number | 계산한 가산세 합계(원)입니다. 가산세 계산(`surcharge`)에만 있습니다. 기관이 준 계산 행의 가산세액을 더해 10원 미만을 버린 값이고, 기관이 한도를 적용했으면 한도액에서 10원 미만을 버린 값입니다. | |
| data. | string | 읽은 부표의 종류입니다. `income_persons`, `annex`, `refund`, `previous_refund`, `paid_tax`, `refund_succession` 중 하나이고 요청한 값과 같습니다. 부표 행 조회(`annex_rows`)에만 있습니다. | |
| data. | object | 읽은 부표의 기관 데이터셋입니다. 데이터셋 이름이 키인 객체입니다. 부표 행 조회(`annex_rows`)에만 있습니다. | |
| data. | object | 수정하거나 지울 수 있는 부표 행의 표입니다. 데이터셋 이름이 키이고 행의 목록이 값이며, 행마다 `row_index`, `expected_row_hash`, `values` 를 가집니다. 부표를 저장할 때 row_index 와 expected_row_hash 로 대상 행을 지정합니다. 부표 행 조회(`annex_rows`)에만 있습니다. | |
| data. | object | 기관에서 읽은 신고 기본사항입니다. 사업자 정보(taxpayer), 선택한 소득종류(selectedIncomeTypes), 신고 구분(report)을 담고, 기관 응답에 없는 값은 비어 있습니다. 기본정보를 저장할 때 그대로 쓸 수 있습니다. | |
| data. | object | 기관에서 읽은 소득 명세 초안입니다. incomeSections 아래에 소득종류별로 행(code 와 금액 칸)을 담습니다. | |
| data. | array | 더 받아야 하는 칸의 경로 목록입니다. 비어 있는 기본정보 항목의 경로와, 금액을 숫자로 읽지 못한 항목의 경로가 함께 들어 있습니다. 모두 갖췄으면 빈 배열입니다. | |
| data. | array | 고객에게 물어볼 질문의 목록입니다. 작성 시작과 자동채움 조회에서는 missing_fields 마다 한 문장씩입니다. 저장 신고서 조회가 입력이 모자라거나 선택을 요청하는 응답에서는 문장이 아니라 `key`, `label_ko`, `required` 칸을 가진 객체의 목록입니다. | |
| data. | object | 읽은 값이 어디서 왔는지의 표입니다. 칸 경로가 키이고 출처 경로가 값입니다. 기관 데이터셋에서 읽었으면 `datasets.` 로, 요청으로 정했으면 `request.` 로 시작하고, 작업 정보에서 온 값은 `snapshot.` 으로 시작합니다. | |
| data. | object | 금액을 숫자로 읽지 못한 값의 표입니다. 칸 경로가 키이고 기관이 준 원래 값이 값입니다. 없으면 빈 객체입니다. | |
| data. | array | 아직 기관에서 읽지 못한 소득종류의 이름 목록입니다. 선택한 소득종류의 명세가 현재 작성 건에 아직 없을 때 들어갑니다. | |
| data. | boolean | 소득 명세를 모두 읽었는지입니다. unread_sections 가 비어 있으면 true 입니다. | |
| data. | boolean | 기관에 저장을 실행했는지입니다. 조회는 저장하지 않아 항상 false 입니다. 자동채움 조회(`prefill`)와 저장 신고서 조회(`saved_returns`)에만 있습니다. | |
| data. | boolean | 기관에 제출을 실행했는지입니다. 조회는 제출하지 않아 항상 false 입니다. 자동채움 조회(`prefill`)와, 신고서를 불러온 저장 신고서 조회(`saved_returns`)에만 있습니다. | |
| data. | string | 읽어 온 작성 건의 신고서 식별자입니다. 자동채움 조회(`prefill`)와, 신고서를 불러온 저장 신고서 조회(`saved_returns`)에만 있습니다. | |
| data. | array | 저장 신고서 조회에서 조건에 맞는 작성 중 신고서의 목록입니다. 기관이 준 행을 그대로 담습니다. 후보 목록을 돌려주는 응답(state 가 `selection_required`)에만 있습니다. | |
| data. | boolean | 고객이 신고서 하나를 골라야 하는지입니다. choices 가 둘 이상이면 true 입니다. 후보 목록을 돌려주는 응답(state 가 `selection_required`)에만 있습니다. | |
| data. | boolean | 기관을 불렀는지입니다. 입력이 모자라 기관에 가지 않은 응답(state 가 `needs_input`)에만 있고 항상 false 입니다. | |
| data. | boolean | 이미 있던 저장 신고서를 불러왔는지입니다. 신고서를 불러온 저장 신고서 조회(`saved_returns`)에만 있고 항상 true 입니다. | |
| warnings | array | 경고 문장의 목록입니다. 이 조회는 경고를 싣지 않아 항상 빈 배열입니다. 입력이 모자라 기관에 가지 않은 응답(state 가 `needs_input`)에는 이 칸이 없습니다. |
// result.data - 값 자리에는 각 칸의 형식을 적었습니다 (실제 값이 아닙니다)
{
"success": "<boolean>",
"step": "<string>",
"state": "<string>",
"snapshot": {},
"snapshot_hash": "<string>",
"data": {
"kind": "<string>",
"provider": {},
"calculated_surcharge": "<number>",
"annex_kind": "<string>",
"datasets": {},
"row_targets": {},
"basic_document": {},
"detail_document": {},
"missing_fields": [],
"inputs": [],
"field_sources": {},
"unresolved_values": {},
"unread_sections": [],
"detail_loaded": "<boolean>",
"save_executed": "<boolean>",
"submit_executed": "<boolean>",
"loaded_return_id": "<string>",
"choices": [],
"selection_required": "<boolean>",
"institution_called": "<boolean>",
"reused_existing_return": "<boolean>"
},
"warnings": []
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| VALIDATION_ | 요청 칸이 빠졌거나 칸 값이 이 단계의 요청 형식에 맞지 않으면 홈택스에 아무것도 보내지 않고 이 오류로 끝납니다. 빠진 칸이 있으면 error.message 는 「요청에 필요한 값이 빠졌습니다. 빠진 값: 칸 이름. 그 값을 넣어 다시 요청해 주세요.」 꼴이고, 그 밖의 검사에 걸린 칸이 있으면 「요청 값이 올바르지 않습니다. 확인할 값: 칸 이름. 값을 고쳐 다시 요청해 주세요.」 꼴이며, 둘 다 있으면 두 문장이 차례로 이어집니다. 칸 이름 자리에는 걸린 칸이 다섯까지 쉼표로 이어지고 더 있으면 「외 N개」 가 붙으며, 목록이나 객체 안의 칸은 「바깥 칸.0.안쪽 칸」 처럼 위치를 점으로 이은 경로로 적습니다. 걸린 검사가 모두 칸 하나를 짚지 않고 요청 전체를 보는 것이면 「요청 값이 올바르지 않습니다.」 만 옵니다. | |
| RESOURCE_ | 이어 받을 이전 작업(source_job_id)이 같은 조직과 환경에서 성공한 이 신고 유형의 작업이 아니거나, 그 결과를 읽을 수 없거나, 결과에 작성 스냅샷이 없거나 스냅샷이 expected_snapshot_hash 와 다르면 홈택스에 보내기 전에 이 오류로 끝납니다. error.message 는 걸린 확인의 문장 하나이고, BE 문장은 「이 신고 유형에서 성공한 이전 단계 작업이 필요합니다」, 「이전 작업의 작성 스냅샷이 없습니다」, 「작성 내용이 바뀌었습니다. 최신 결과를 다시 확인해 주세요」, 「같은 조직·환경에서 성공한 이전 단계의 작업이 필요합니다」, 「이전 작업의 JSON 결과를 읽을 수 없습니다」 입니다. | |
| RESOURCE_ | 작업 상태나 이어 받은 내용, 또는 홈택스에 있는 신고서의 상태가 이 단계와 맞지 않으면 이 오류로 끝납니다. 이 단계에서 이 코드로 끝나는 확인의 BE 문장은 「이전 작업과 사업자가 다릅니다」, 「이전 작업과 신고기간이 다릅니다」, 「조회 중 기관의 전체 건수가 변경됐습니다」, 「현재 회사·기간·유형의 작성 중 신고서를 찾지 못했습니다」, 「기관이 해당 저장 신고서의 불러오기를 허용하지 않았습니다」, 「기관이 다른 신고서를 반환했습니다」, 「현재 작성 상태에서는 이 단계를 실행할 수 없습니다. 최신 결과를 확인해 주세요」, 「기관이 현재 신고서의 불러오기를 허용하지 않았습니다」, 「기관이 다른 작성 건을 반환했습니다」, 「불러온 신고서의 식별자가 다릅니다」, 「불러온 신고서의 기간·유형이 다릅니다」, 「불러온 신고서의 사업자가 다릅니다」, 「기관의 수정신고 원신고 연결이 변경됐습니다」, 「수정신고가 원신고를 덮어쓸 수 없습니다」, 「기관의 신고서가 다른 작성 건으로 바뀌었습니다」, 「승인한 뒤 기관 작성 내용이 변경됐습니다. 최신 내용을 다시 확인해 주세요」, 「기관 조회 회사와 작성 중인 회사의 사업자등록번호가 다릅니다」, 「목록과 불러온 신고서의 납세자가 다릅니다」, 「명세 조회 결과의 신고서 식별자가 다릅니다」, 「기납부 명세의 신고서가 현재 작성 건과 다릅니다」 이고, 걸린 확인의 문장 하나가 error.message 로 실립니다. | |
| AUTH_ | 저장된 기관 세션이 없습니다. 같은 연동 계정으로 hometax.session.login 을 먼저 실행해 세션을 연 뒤 다시 보냅니다. |
33. 원천세 수정신고 제출 전 미리보기hometax. tax. withholding. amendment_ report. preview
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 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| source_ | string | Y | 이어서 진행할 이전 단계 작업의 job_id 를 그대로 입력합니다(job_ 으로 시작하는 작업 번호). 검토(review) 결과를 받고, 다시 볼 때는 미리보기(preview) 결과도 받습니다. 같은 조직과 환경, 같은 기관 연결에서 이 신고 유형으로 성공한 작업이어야 하고 아니면 진행하지 않고 거절하며, 받지 않는 작성 상태의 결과이면 409 로 거절합니다 | |
| expected_ | string | Y | source_job_id 작업 결과의 snapshot_hash 를 그대로 입력합니다(소문자 16진수 64자리). 그 작업의 내용과 맞지 않으면 진행하지 않고 작성 내용이 바뀌었다는 오류(409)로 거절합니다 |
- 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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: preview-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "hometax",
"action": "hometax.tax.withholding.amendment_report.preview",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {
"source_job_id": "<필수>",
"expected_snapshot_hash": "<필수>"
}
}'Response
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| success | boolean | 단계가 끝났는지입니다. 응답으로 돌아왔다면 항상 true 입니다. 실패는 이 모양이 아니라 오류 응답으로 옵니다. | |
| step | string | 응답이 어느 단계의 결과인지입니다. 이 액션은 항상 `preview` 입니다. | |
| state | string | 이 단계가 끝난 뒤 작업이 놓인 상태입니다. `previewed` 입니다. | |
| snapshot | object | 이 단계가 끝난 작업 상태의 사본입니다. 다음 단계가 이어받는 값이라 직접 고치지 않습니다. | |
| snapshot_ | string | snapshot 의 해시(SHA-256, 16진수 64자)입니다. 다음 단계를 부를 때 expected_snapshot_hash 에 그대로 넣고, 이 작업의 job_id 는 source_job_id 에 넣습니다. 그 사이 작업 상태가 바뀌었으면 거절됩니다. | |
| data | object | 미리보기 결과 묶음입니다. | |
| data. | object | 기관의 신고 금액 요약 응답 본문입니다. 제출 전에 고객에게 보여 줍니다. | |
| data. | boolean | 제출 전에 고객 확인이 필요한지입니다. 항상 true 입니다. | |
| warnings | array | 경고 문장의 목록입니다. 이 상품은 경고를 싣지 않아 항상 빈 배열입니다. |
// result.data - 값 자리에는 각 칸의 형식을 적었습니다 (실제 값이 아닙니다)
{
"success": "<boolean>",
"step": "<string>",
"state": "<string>",
"snapshot": {},
"snapshot_hash": "<string>",
"data": {
"summary": {},
"requires_confirmation": "<boolean>"
},
"warnings": []
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| VALIDATION_ | 요청 칸이 빠졌거나 칸 값이 이 단계의 요청 형식에 맞지 않으면 홈택스에 아무것도 보내지 않고 이 오류로 끝납니다. 빠진 칸이 있으면 error.message 는 「요청에 필요한 값이 빠졌습니다. 빠진 값: 칸 이름. 그 값을 넣어 다시 요청해 주세요.」 꼴이고, 그 밖의 검사에 걸린 칸이 있으면 「요청 값이 올바르지 않습니다. 확인할 값: 칸 이름. 값을 고쳐 다시 요청해 주세요.」 꼴이며, 둘 다 있으면 두 문장이 차례로 이어집니다. 칸 이름 자리에는 걸린 칸이 다섯까지 쉼표로 이어지고 더 있으면 「외 N개」 가 붙으며, 목록이나 객체 안의 칸은 「바깥 칸.0.안쪽 칸」 처럼 위치를 점으로 이은 경로로 적습니다. 걸린 검사가 모두 칸 하나를 짚지 않고 요청 전체를 보는 것이면 「요청 값이 올바르지 않습니다.」 만 옵니다. | |
| RESOURCE_ | 이어 받을 이전 작업(source_job_id)이 같은 조직과 환경에서 성공한 이 신고 유형의 작업이 아니거나, 그 결과를 읽을 수 없거나, 결과에 작성 스냅샷이 없거나 스냅샷이 expected_snapshot_hash 와 다르면 홈택스에 보내기 전에 이 오류로 끝납니다. error.message 는 걸린 확인의 문장 하나이고, BE 문장은 「이 신고 유형에서 성공한 이전 단계 작업이 필요합니다」, 「이전 작업의 작성 스냅샷이 없습니다」, 「작성 내용이 바뀌었습니다. 최신 결과를 다시 확인해 주세요」, 「같은 조직·환경에서 성공한 이전 단계의 작업이 필요합니다」, 「이전 작업의 JSON 결과를 읽을 수 없습니다」 입니다. | |
| RESOURCE_ | 작업 상태나 이어 받은 내용, 또는 홈택스에 있는 신고서의 상태가 이 단계와 맞지 않으면 이 오류로 끝납니다. 이 단계에서 이 코드로 끝나는 확인의 BE 문장은 「현재 작성 상태에서는 이 단계를 실행할 수 없습니다. 최신 결과를 확인해 주세요」, 「기관이 현재 신고서의 불러오기를 허용하지 않았습니다」, 「기관이 다른 작성 건을 반환했습니다」, 「불러온 신고서의 식별자가 다릅니다」, 「불러온 신고서의 기간·유형이 다릅니다」, 「불러온 신고서의 사업자가 다릅니다」, 「기관의 수정신고 원신고 연결이 변경됐습니다」, 「수정신고가 원신고를 덮어쓸 수 없습니다」, 「기관의 신고서가 다른 작성 건으로 바뀌었습니다」, 「승인한 뒤 기관 작성 내용이 변경됐습니다. 최신 내용을 다시 확인해 주세요」 이고, 걸린 확인의 문장 하나가 error.message 로 실립니다. | |
| AUTH_ | 저장된 기관 세션이 없습니다. 같은 연동 계정으로 hometax.session.login 을 먼저 실행해 세션을 연 뒤 다시 보냅니다. |
34. 원천세 수정신고 접수증 조회hometax. tax. withholding. amendment_ report. receipt
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 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| source_ | string | Y | 이어서 진행할 이전 단계 작업의 job_id 를 그대로 입력합니다(job_ 으로 시작하는 작업 번호). 접수 결과를 찾을 신고서의 작업이면 작성 상태는 묻지 않으므로 제출(submit) 결과나, 제출 결과를 확인하지 못했을 때는 미리보기(preview) 결과를 입력합니다. 같은 조직과 환경, 같은 기관 연결에서 이 신고 유형으로 성공한 작업이어야 하고 아니면 진행하지 않고 거절합니다 | |
| expected_ | string | Y | source_job_id 작업 결과의 snapshot_hash 를 그대로 입력합니다(소문자 16진수 64자리). 그 작업의 내용과 맞지 않으면 진행하지 않고 작성 내용이 바뀌었다는 오류(409)로 거절합니다 |
- 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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: receipt-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "hometax",
"action": "hometax.tax.withholding.amendment_report.receipt",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {
"source_job_id": "<필수>",
"expected_snapshot_hash": "<필수>"
}
}'Response
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| success | boolean | 단계가 끝났는지입니다. 응답으로 돌아왔다면 항상 true 입니다. 실패는 이 모양이 아니라 오류 응답으로 옵니다. | |
| step | string | 응답이 어느 단계의 결과인지입니다. 이 액션은 항상 `receipt` 입니다. | |
| state | string | 이 단계가 끝난 뒤 작업이 놓인 상태입니다. `submitted` 입니다. | |
| snapshot | object | 이 단계가 끝난 작업 상태의 사본입니다. 다음 단계가 이어받는 값이라 직접 고치지 않습니다. | |
| snapshot_ | string | snapshot 의 해시(SHA-256, 16진수 64자)입니다. 다음 단계를 부를 때 expected_snapshot_hash 에 그대로 넣고, 이 작업의 job_id 는 source_job_id 에 넣습니다. 그 사이 작업 상태가 바뀌었으면 거절됩니다. | |
| data | object | 접수증 조회 결과 묶음입니다. 같은 사업자의 해당 월 접수 목록에서 이 신고서의 접수번호를 확인한 뒤에만 돌아옵니다. | |
| data. | object | 기관 접수증 본문입니다. 해당 신고서의 접수번호와 접수일이 확인된 경우에만 돌아옵니다. 확인하지 못하면 오류로 끝납니다. | |
| warnings | array | 경고 문장의 목록입니다. 이 상품은 경고를 싣지 않아 항상 빈 배열입니다. |
// result.data - 값 자리에는 각 칸의 형식을 적었습니다 (실제 값이 아닙니다)
{
"success": "<boolean>",
"step": "<string>",
"state": "<string>",
"snapshot": {},
"snapshot_hash": "<string>",
"data": {
"receipt": {}
},
"warnings": []
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| VALIDATION_ | 요청 칸이 빠졌거나 칸 값이 이 단계의 요청 형식에 맞지 않으면 홈택스에 아무것도 보내지 않고 이 오류로 끝납니다. 빠진 칸이 있으면 error.message 는 「요청에 필요한 값이 빠졌습니다. 빠진 값: 칸 이름. 그 값을 넣어 다시 요청해 주세요.」 꼴이고, 그 밖의 검사에 걸린 칸이 있으면 「요청 값이 올바르지 않습니다. 확인할 값: 칸 이름. 값을 고쳐 다시 요청해 주세요.」 꼴이며, 둘 다 있으면 두 문장이 차례로 이어집니다. 칸 이름 자리에는 걸린 칸이 다섯까지 쉼표로 이어지고 더 있으면 「외 N개」 가 붙으며, 목록이나 객체 안의 칸은 「바깥 칸.0.안쪽 칸」 처럼 위치를 점으로 이은 경로로 적습니다. 걸린 검사가 모두 칸 하나를 짚지 않고 요청 전체를 보는 것이면 「요청 값이 올바르지 않습니다.」 만 옵니다. | |
| RESOURCE_ | 이어 받을 이전 작업(source_job_id)이 같은 조직과 환경에서 성공한 이 신고 유형의 작업이 아니거나, 그 결과를 읽을 수 없거나, 결과에 작성 스냅샷이 없거나 스냅샷이 expected_snapshot_hash 와 다르면 홈택스에 보내기 전에 이 오류로 끝납니다. error.message 는 걸린 확인의 문장 하나이고, BE 문장은 「이 신고 유형에서 성공한 이전 단계 작업이 필요합니다」, 「이전 작업의 작성 스냅샷이 없습니다」, 「작성 내용이 바뀌었습니다. 최신 결과를 다시 확인해 주세요」, 「같은 조직·환경에서 성공한 이전 단계의 작업이 필요합니다」, 「이전 작업의 JSON 결과를 읽을 수 없습니다」 입니다. | |
| RESOURCE_ | 작업 상태나 이어 받은 내용, 또는 홈택스에 있는 신고서의 상태가 이 단계와 맞지 않으면 이 오류로 끝납니다. 이 단계에서 이 코드로 끝나는 확인의 BE 문장은 「조회 중 접수 목록이 변경됐습니다」, 「동일 회사·기간의 접수 내역을 확인하지 못했습니다」, 「해당 신고의 접수번호·접수일을 확인하지 못했습니다. 재제출하지 말고 접수 목록을 확인해 주세요」 이고, 걸린 확인의 문장 하나가 error.message 로 실립니다. | |
| AUTH_ | 저장된 기관 세션이 없습니다. 같은 연동 계정으로 hometax.session.login 을 먼저 실행해 세션을 연 뒤 다시 보냅니다. |
35. 원천세 수정신고 준비자료 안내hometax. tax. withholding. amendment_ report. requirements
MCP 도구 이름 hometax__
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
원천세 수정신고에 필요한 입력과 준비자료를 단계별로 알려 드립니다. 기관에 접속하지 않습니다.
- 이 API 는 기관 연동과 기관 로그인이 필요 없습니다. 기관 자격증명을 등록하지 않아도 호출할 수 있고, 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 | 호출할 작업입니다.
| |
| 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: requirements-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "hometax",
"action": "hometax.tax.withholding.amendment_report.requirements",
"params": {}
}'Response
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| success | boolean | 단계가 끝났는지입니다. 응답으로 돌아왔다면 항상 true 입니다. 실패는 이 모양이 아니라 오류 응답으로 옵니다. | |
| step | string | 응답이 어느 단계의 결과인지입니다. 이 액션은 항상 `requirements` 입니다. | |
| data | object | 필요입력 안내 묶음입니다. 기관에 가지 않고 이 신고의 요청 계약에서 바로 만들며, 저장이나 제출은 일어나지 않습니다. | |
| data. | array | 단계마다 받아야 하는 입력의 목록입니다. 이 신고의 모든 단계(액션)의 요청 계약에서 입력 칸마다 한 줄씩 만듭니다. 안쪽 칸을 가진 객체 입력은 안쪽 칸마다 한 줄이고, 그 key 는 점으로 이은 경로입니다. | |
| data. | string | 이 입력을 받는 단계의 이름입니다. 단계 이름은 actions 의 키와 같습니다. | |
| data. | string | 입력 칸의 이름입니다. 요청 본문에 이 이름으로 보냅니다. 안쪽 칸이면 `상위.하위` 꼴입니다. | |
| data. | string | 입력 칸의 한국어 이름입니다. | |
| data. | string | 입력을 누가 채우는지 구분입니다. `institution` 또는 `customer` 중 하나입니다. 앞의 값은 사업자 정보처럼 기관 조회로 확인하는 칸이고 뒤의 값은 고객이 정하는 칸입니다. | |
| data. | boolean | 꼭 보내야 하는 입력인지입니다. 안쪽 칸은 바깥 객체와 안쪽 칸이 모두 필수일 때만 true 입니다. | |
| data. | string | 입력 값의 종류입니다. `string` 또는 `choice` 또는 `number` 또는 `date` 또는 `array` 또는 `object` 또는 `file` 중 하나입니다. `choice` 는 true 나 false 같은 정해진 선택지 중 하나를 뜻합니다. | |
| data. | null | 이미 채워 둔 값입니다. 이 안내는 값을 채우지 않아 항상 null 입니다. | |
| data. | array | 고를 수 있는 값의 목록입니다. 선택지가 정해진 입력에만 있고 아니면 빈 배열입니다. | |
| data. | boolean | 이 입력에 별도 동의가 필요한지입니다. 이 안내는 항상 false 로 돌려줍니다. | |
| data. | string | 입력 값의 출처 문구입니다. `기관 조회` 또는 `사용자 입력` 중 하나입니다. 앞의 값은 tier 가 기관 조회로 확인하는 칸일 때 쓰입니다. | |
| data. | string | 이 입력을 어떻게 채우는지 알리는 한국어 안내 문장입니다. | |
| data. | boolean | 이 입력이 없으면 진행이 막히는지입니다. required 와 같은 값입니다. | |
| data. | boolean | 채워야 하는데 비어 있는 입력이 있는지입니다. blocking_reasons 가 하나라도 있으면 true 입니다. 이 안내는 값을 채우지 않아 필수 입력이 있으면 항상 true 입니다. | |
| data. | array | 진행을 막는 입력마다 한 줄씩 담은 목록입니다. 필수이면서 채워 둔 값이 없는 입력이 대상입니다. | |
| data. | string | 막힌 입력을 받는 단계의 이름입니다. | |
| data. | string | 막힌 입력의 이름입니다. inputs 의 key 와 같습니다. | |
| data. | string | 막힌 까닭을 알리는 한국어 문장입니다. 입력 이름 뒤에 「입력이 필요합니다.」 가 붙는 꼴입니다. | |
| data. | object | 이 안내가 아무것도 실행하지 않았다는 표시 묶음입니다. | |
| data. | boolean | 이 안내가 입력 설명만 한다는 표시입니다. 항상 true 입니다. | |
| data. | boolean | 기관에 저장을 실행했는지입니다. 이 안내는 저장하지 않아 항상 false 입니다. | |
| data. | boolean | 기관에 제출을 실행했는지입니다. 이 안내는 제출하지 않아 항상 false 입니다. | |
| data. | string | 신고 가족 이름입니다. 이 액션은 항상 `amendment_report` 입니다. | |
| data. | string | 신고 상세 구분 코드입니다. 이 액션은 항상 `02` 입니다. | |
| data. | object | 단계(액션)마다 요청 계약을 담은 객체입니다. 단계 이름이 키이고, 값은 필수 입력 이름의 목록(required)과 요청 본문의 JSON 스키마(schema)입니다. | |
| data. | array | 제출할 때 고객에게 받아야 하는 확인 입력의 이름 목록입니다. `confirmSubmit`, `sbmsAgreement` 가 들어 있습니다. | |
| data. | array | 기관에서 아직 동작을 확인하지 못해 쓰지 못하는 쓰기 액션의 전체 이름 목록입니다. 쓰기 액션에서 열려 있는 것을 뺀 나머지를 이름순으로 담습니다. | |
| data. | boolean | 기관에서 실제 동작 확인이 더 필요한 신고인지를 알리는 표시입니다. 수정 신고에만 있고 항상 true 입니다. | |
| data. | boolean | 기관에 쓰는 단계가 기본으로 열려 있는지를 알리는 표시입니다. 이 안내는 항상 false 로 돌려줍니다. |
// result.data - 값 자리에는 각 칸의 형식을 적었습니다 (실제 값이 아닙니다)
{
"success": "<boolean>",
"step": "<string>",
"data": {
"inputs": [
{
"action": "<string>",
"key": "<string>",
"label_ko": "<string>",
"tier": "<string>",
"required": "<boolean>",
"value_type": "<string>",
"provided_value": null,
"options": [],
"consent_required": "<boolean>",
"source": "<string>",
"how_to_ko": "<string>",
"blocks_progress": "<boolean>"
}
],
"blocked": "<boolean>",
"blocking_reasons": [
{
"action": "<string>",
"key": "<string>",
"reason_ko": "<string>"
}
],
"safety": {
"input_only": "<boolean>",
"save_executed": "<boolean>",
"submit_executed": "<boolean>"
},
"family": "<string>",
"detail_code": "<string>",
"actions": {},
"confirmation_fields": [],
"unmeasured_actions": [],
"institution_runtime_verification_required": "<boolean>",
"institution_writes_enabled_by_default": "<boolean>"
}
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| VALIDATION_ | 요청 칸이 빠졌거나 칸 값이 이 단계의 요청 형식에 맞지 않으면 홈택스에 아무것도 보내지 않고 이 오류로 끝납니다. 빠진 칸이 있으면 error.message 는 「요청에 필요한 값이 빠졌습니다. 빠진 값: 칸 이름. 그 값을 넣어 다시 요청해 주세요.」 꼴이고, 그 밖의 검사에 걸린 칸이 있으면 「요청 값이 올바르지 않습니다. 확인할 값: 칸 이름. 값을 고쳐 다시 요청해 주세요.」 꼴이며, 둘 다 있으면 두 문장이 차례로 이어집니다. 칸 이름 자리에는 걸린 칸이 다섯까지 쉼표로 이어지고 더 있으면 「외 N개」 가 붙으며, 목록이나 객체 안의 칸은 「바깥 칸.0.안쪽 칸」 처럼 위치를 점으로 이은 경로로 적습니다. 걸린 검사가 모두 칸 하나를 짚지 않고 요청 전체를 보는 것이면 「요청 값이 올바르지 않습니다.」 만 옵니다. |
36. 원천세 수정신고 저장 내용 검토hometax. tax. withholding. amendment_ report. review
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 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| source_ | string | Y | 이어서 진행할 이전 단계 작업의 job_id 를 그대로 입력합니다(job_ 으로 시작하는 작업 번호). 기본정보 저장(basic_save), 명세 저장(detail_save), 부표 저장(annex_save) 결과처럼 기본정보가 저장된 상태의 결과를 받고, 다시 검토할 때는 검토(review) 결과도 받습니다. 같은 조직과 환경, 같은 기관 연결에서 이 신고 유형으로 성공한 작업이어야 하고 아니면 진행하지 않고 거절하며, 받지 않는 작성 상태의 결과이면 409 로 거절합니다 | |
| expected_ | string | Y | source_job_id 작업 결과의 snapshot_hash 를 그대로 입력합니다(소문자 16진수 64자리). 그 작업의 내용과 맞지 않으면 진행하지 않고 작성 내용이 바뀌었다는 오류(409)로 거절합니다 | |
| refund_ | string | N | 환급받을 은행의 코드입니다. 숫자 세 자리로 입력합니다. 기본정보의 환급신청 여부가 Y 인 신고서를 검토할 때만 쓰며, 그때 은행 코드와 계좌번호가 모두 있어야 하고 없으면 거절합니다 | |
| refund_ | string | N | 환급받을 계좌번호입니다. 하이픈 없이 숫자만 1자리에서 20자리까지 입력합니다. 기본정보의 환급신청 여부가 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: review-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "hometax",
"action": "hometax.tax.withholding.amendment_report.review",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {
"source_job_id": "<필수>",
"expected_snapshot_hash": "<필수>"
}
}'Response
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| success | boolean | 단계가 끝났는지입니다. 응답으로 돌아왔다면 항상 true 입니다. 실패는 이 모양이 아니라 오류 응답으로 옵니다. | |
| step | string | 응답이 어느 단계의 결과인지입니다. 이 액션은 항상 `review` 입니다. | |
| state | string | 이 단계가 끝난 뒤 작업이 놓인 상태입니다. `reviewed` 입니다. | |
| snapshot | object | 이 단계가 끝난 작업 상태의 사본입니다. 다음 단계가 이어받는 값이라 직접 고치지 않습니다. | |
| snapshot_ | string | snapshot 의 해시(SHA-256, 16진수 64자)입니다. 다음 단계를 부를 때 expected_snapshot_hash 에 그대로 넣고, 이 작업의 job_id 는 source_job_id 에 넣습니다. 그 사이 작업 상태가 바뀌었으면 거절됩니다. | |
| data | object | 검증 결과 묶음입니다. 기관의 내용검증이 끝났을 때만 돌아오고, 끝나지 않았으면 오류로 끝납니다. | |
| data. | object | 기관의 신고서 요약 응답 본문입니다. | |
| data. | object | 기관의 내용검증 응답 본문입니다. 검증 결과 코드가 `10` 이거나 `30` 일 때만 돌아옵니다. | |
| data. | object | 다음 단계로 가도 되는지를 알리는 묶음입니다. | |
| data. | boolean | 경고 없이 제출 단계로 갈 수 있는지입니다. 검증 결과 코드가 `10` 이면 true 입니다. | |
| data. | boolean | 기관의 검증 경고를 고객이 확인해야 하는지입니다. 검증 결과 코드가 `30` 이면 true 이고, 이때 제출 단계에 confirmWarnings 를 true 로 보내야 합니다. | |
| warnings | array | 경고 문장의 목록입니다. 이 상품은 경고를 싣지 않아 항상 빈 배열입니다. | |
| outcome | string | 기관 쓰기가 확인됐는지를 가르는 판정입니다. 응답으로 돌아왔다면 항상 `confirmed` 입니다. 결과를 확인하지 못한 경우는 이 모양이 아니라 오류로 끝납니다. 작업 결과 판정이 이 자리를 읽습니다. | |
| action | string | 쓰기 액션의 이름입니다. 이 액션은 항상 `hometax.tax.withholding.amendment_report.review` 입니다. 작업 결과 판정이 이 자리를 읽습니다. |
// result.data - 값 자리에는 각 칸의 형식을 적었습니다 (실제 값이 아닙니다)
{
"success": "<boolean>",
"step": "<string>",
"state": "<string>",
"snapshot": {},
"snapshot_hash": "<string>",
"data": {
"summary": {},
"validation": {},
"workflow_gate": {
"can_submit": "<boolean>",
"warnings_confirmation_required": "<boolean>"
}
},
"warnings": [],
"outcome": "<string>",
"action": "<string>"
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| VALIDATION_ | 요청 칸이 빠졌거나 칸 값이 이 단계의 요청 형식에 맞지 않으면 홈택스에 아무것도 보내지 않고 이 오류로 끝납니다. 빠진 칸이 있으면 error.message 는 「요청에 필요한 값이 빠졌습니다. 빠진 값: 칸 이름. 그 값을 넣어 다시 요청해 주세요.」 꼴이고, 그 밖의 검사에 걸린 칸이 있으면 「요청 값이 올바르지 않습니다. 확인할 값: 칸 이름. 값을 고쳐 다시 요청해 주세요.」 꼴이며, 둘 다 있으면 두 문장이 차례로 이어집니다. 칸 이름 자리에는 걸린 칸이 다섯까지 쉼표로 이어지고 더 있으면 「외 N개」 가 붙으며, 목록이나 객체 안의 칸은 「바깥 칸.0.안쪽 칸」 처럼 위치를 점으로 이은 경로로 적습니다. 걸린 검사가 모두 칸 하나를 짚지 않고 요청 전체를 보는 것이면 「요청 값이 올바르지 않습니다.」 만 옵니다. | |
| RESOURCE_ | 이어 받을 이전 작업(source_job_id)이 같은 조직과 환경에서 성공한 이 신고 유형의 작업이 아니거나, 그 결과를 읽을 수 없거나, 결과에 작성 스냅샷이 없거나 스냅샷이 expected_snapshot_hash 와 다르면 홈택스에 보내기 전에 이 오류로 끝납니다. error.message 는 걸린 확인의 문장 하나이고, BE 문장은 「이 신고 유형에서 성공한 이전 단계 작업이 필요합니다」, 「이전 작업의 작성 스냅샷이 없습니다」, 「작성 내용이 바뀌었습니다. 최신 결과를 다시 확인해 주세요」, 「같은 조직·환경에서 성공한 이전 단계의 작업이 필요합니다」, 「이전 작업의 JSON 결과를 읽을 수 없습니다」 입니다. | |
| RESOURCE_ | 작업 상태나 이어 받은 내용, 또는 홈택스에 있는 신고서의 상태가 이 단계와 맞지 않으면 이 오류로 끝납니다. 이 단계에서 이 코드로 끝나는 확인의 BE 문장은 「현재 작성 상태에서는 이 단계를 실행할 수 없습니다. 최신 결과를 확인해 주세요」, 「기관이 현재 신고서의 불러오기를 허용하지 않았습니다」, 「기관이 다른 작성 건을 반환했습니다」, 「불러온 신고서의 식별자가 다릅니다」, 「불러온 신고서의 기간·유형이 다릅니다」, 「불러온 신고서의 사업자가 다릅니다」, 「기관의 수정신고 원신고 연결이 변경됐습니다」, 「수정신고가 원신고를 덮어쓸 수 없습니다」, 「기관의 신고서가 다른 작성 건으로 바뀌었습니다」, 「승인한 뒤 기관 작성 내용이 변경됐습니다. 최신 내용을 다시 확인해 주세요」, 「명세 조회 결과의 신고서 식별자가 다릅니다」, 「기관 내용검증이 완료되지 않았습니다. 검증 오류를 확인해 주세요」 이고, 걸린 확인의 문장 하나가 error.message 로 실립니다. | |
| AUTH_ | 저장된 기관 세션이 없습니다. 같은 연동 계정으로 hometax.session.login 을 먼저 실행해 세션을 연 뒤 다시 보냅니다. |
37. 원천세 수정신고 제출hometax. tax. withholding. amendment_ report. submit
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 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| source_ | string | Y | 이어서 진행할 이전 단계 작업의 job_id 를 그대로 입력합니다(job_ 으로 시작하는 작업 번호). 미리보기(preview) 결과를 받습니다. 같은 조직과 환경, 같은 기관 연결에서 이 신고 유형으로 성공한 작업이어야 하고 아니면 진행하지 않고 거절하며, 받지 않는 작성 상태의 결과이면 409 로 거절합니다 | |
| expected_ | string | Y | source_job_id 작업 결과의 snapshot_hash 를 그대로 입력합니다(소문자 16진수 64자리). 그 작업의 내용과 맞지 않으면 진행하지 않고 작성 내용이 바뀌었다는 오류(409)로 거절합니다 | |
| confirmSubmit | boolean | Y | 신고서를 실제로 제출한다는 확인값입니다. 미리보기(preview) 결과를 사용자에게 보여 주고 제출 동의를 받았을 때 true 로 입력합니다. true 가 아니면(빠지거나 false) 기관에 아무것도 보내지 않고 신고서 제출 확인이 필요하다는 오류(400)로 거절합니다. 이 값도 확인 토큰이 가리키는 요청 본문에 들어가므로 확인 토큰을 받는 첫 요청부터 함께 입력합니다. 나중에 더하면 본문이 달라져 확인 토큰을 다시 받아야 합니다. 1 이나 yes, on 처럼 true 로 읽히는 값도 true 로 받고, true 나 false 로 읽을 수 없는 값은 입력 오류로 거절합니다 | |
| sbmsAgreement | boolean | Y | 신고 내용에 동의한다는 확인값입니다. 사용자에게 신고 내용 동의를 받았을 때 true 로 입력하며, true 가 아니면(빠지거나 false) 기관에 아무것도 보내지 않고 신고서 제출 동의가 필요하다는 오류(400)로 거절합니다. 이 값은 기관에 보내지 않고 제출 전 확인에만 씁니다. 이 값도 확인 토큰이 가리키는 요청 본문에 들어가므로 확인 토큰을 받는 첫 요청부터 함께 입력합니다. 나중에 더하면 본문이 달라져 확인 토큰을 다시 받아야 합니다. 1 이나 yes, on 처럼 true 로 읽히는 값도 true 로 받고, true 나 false 로 읽을 수 없는 값은 입력 오류로 거절합니다 | |
| confirmWarnings | boolean | N | 기관 검증 경고를 확인했다는 값입니다. 검토(review) 결과의 workflow_gate.warnings_confirmation_required 가 true 였던 신고서는 이 값이 true 여야 제출하고, 아니면 기관에 아무것도 보내지 않고 검증 경고를 확인해 달라는 오류(422)로 거절합니다. 경고 없이 검토를 통과한 신고서(workflow_gate.can_submit 이 true)에는 필요 없습니다. 이 값도 확인 토큰이 가리키는 요청 본문에 들어가므로 확인 토큰을 받는 첫 요청부터 함께 입력합니다. 나중에 더하면 본문이 달라져 확인 토큰을 다시 받아야 합니다. 1 이나 yes, on 처럼 true 로 읽히는 값도 true 로 받고, true 나 false 로 읽을 수 없는 값은 입력 오류로 거절합니다 | |
| confirmation_ | string | N | 1회용 확인 토큰입니다. 처음에는 보내지 않습니다. 토큰 없이 부르면 기관에 아무것도 보내지 않고 작업도 만들지 않은 채 확인이 필요하다는 오류(WRITE_CONFIRMATION_REQUIRED)로 끝나고, 응답의 error.confirmation_token 에 토큰이 옵니다. error.message 의 안내를 사용자에게 보여 주고 동의를 받은 뒤 같은 요청에 이 토큰을 넣어 다시 부릅니다. 토큰은 10분 안에 한 번만 쓸 수 있고 처음 요청과 같은 본문, 같은 호출자, 같은 환경에서만 맞으며, 아니면 확인이 만료됐거나 내용이 달라졌다는 오류로 거절합니다 |
- 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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: submit-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "hometax",
"action": "hometax.tax.withholding.amendment_report.submit",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {
"source_job_id": "<필수>",
"expected_snapshot_hash": "<필수>",
"confirmSubmit": "<필수: boolean>",
"sbmsAgreement": "<필수: boolean>"
}
}'Response
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| success | boolean | 단계가 끝났는지입니다. 응답으로 돌아왔다면 항상 true 입니다. 실패는 이 모양이 아니라 오류 응답으로 옵니다. | |
| step | string | 응답이 어느 단계의 결과인지입니다. 이 액션은 항상 `submit` 입니다. | |
| state | string | 이 단계가 끝난 뒤 작업이 놓인 상태입니다. `submitted` 입니다. | |
| snapshot | object | 이 단계가 끝난 작업 상태의 사본입니다. 다음 단계가 이어받는 값이라 직접 고치지 않습니다. | |
| snapshot_ | string | snapshot 의 해시(SHA-256, 16진수 64자)입니다. 다음 단계를 부를 때 expected_snapshot_hash 에 그대로 넣고, 이 작업의 job_id 는 source_job_id 에 넣습니다. 그 사이 작업 상태가 바뀌었으면 거절됩니다. | |
| data | object | 제출 결과 묶음입니다. 기관에서 접수번호를 확인한 뒤에만 돌아옵니다. | |
| data. | object | 기관 접수증 본문입니다. 해당 신고서의 접수번호와 접수일이 확인된 경우에만 돌아옵니다. 확인하지 못하면 오류로 끝납니다. | |
| data. | object | 제출 때 받은 고객 확인의 기록 묶음입니다. | |
| data. | boolean | 제출 확인을 받았는지입니다. 응답으로 돌아왔다면 항상 true 입니다. | |
| data. | boolean | 신고 내용 동의를 받았는지입니다. 응답으로 돌아왔다면 항상 true 입니다. | |
| data. | boolean | 신고 내용 동의를 기관 제출 본문에 실었는지입니다. 동의는 서버에서 확인하고 기관 제출 본문에는 싣지 않아 항상 false 입니다. | |
| data. | boolean | 고객이 기관의 검증 경고를 확인했는지입니다. 요청의 confirmWarnings 를 그대로 옮긴 값입니다. | |
| warnings | array | 경고 문장의 목록입니다. 이 상품은 경고를 싣지 않아 항상 빈 배열입니다. | |
| outcome | string | 기관 쓰기가 확인됐는지를 가르는 판정입니다. 응답으로 돌아왔다면 항상 `confirmed` 입니다. 결과를 확인하지 못한 경우는 이 모양이 아니라 오류로 끝납니다. 작업 결과 판정이 이 자리를 읽습니다. | |
| action | string | 쓰기 액션의 이름입니다. 이 액션은 항상 `hometax.tax.withholding.amendment_report.submit` 입니다. 작업 결과 판정이 이 자리를 읽습니다. |
// result.data - 값 자리에는 각 칸의 형식을 적었습니다 (실제 값이 아닙니다)
{
"success": "<boolean>",
"step": "<string>",
"state": "<string>",
"snapshot": {},
"snapshot_hash": "<string>",
"data": {
"receipt": {},
"submitUserAcknowledgements": {
"confirmSubmit": "<boolean>",
"sbmsAgreement": "<boolean>",
"sbmsAgreementInSubmitBody": "<boolean>",
"confirmWarnings": "<boolean>"
}
},
"warnings": [],
"outcome": "<string>",
"action": "<string>"
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| WRITE_ | 요청에 확인 토큰(confirmation_token)이 없으면 홈택스에 아무것도 보내지 않고 작업도 만들지 않은 채 이 오류로 끝납니다. error.message 는 「원천세 수정신고서 제출은 되돌릴 수 없어 제출 전 확인이 필요합니다. 아래 내용을 사용자에게 보여주고 동의를 받으세요.」 로 시작하고 error.confirmation_token 에 1회용 토큰이 옵니다. 이 단계의 확인에는 미리보기 내용이 없어 error.preview 는 빈 객체입니다. 이 내용을 고객에게 그대로 보여 주고 확인을 받은 뒤, 같은 요청의 params.confirmation_token 에 응답의 error.confirmation_token 값을 넣어 다시 호출해 주세요. 토큰은 10분 안에 한 번만 쓸 수 있고, 확인한 요청 본문과 같은 본문에만 맞습니다. | |
| WRITE_ | 토큰이 만료됐거나, 이미 썼거나, 다른 호출자나 다른 환경에서 받은 것이거나, 확인한 요청 본문과 달라졌으면 홈택스에 아무것도 보내지 않고 작업도 만들지 않은 채 이 오류로 끝납니다. error.message 는 「확인이 만료됐거나 확인한 내용과 달라졌습니다. 다시 확인해 주세요.」 입니다. 토큰 없이 다시 요청하면 새 토큰을 받습니다. | |
| VALIDATION_ | 요청 칸이 빠졌거나 칸 값이 이 단계의 요청 형식에 맞지 않으면 홈택스에 아무것도 보내지 않고 이 오류로 끝납니다. 빠진 칸이 있으면 error.message 는 「요청에 필요한 값이 빠졌습니다. 빠진 값: 칸 이름. 그 값을 넣어 다시 요청해 주세요.」 꼴이고, 그 밖의 검사에 걸린 칸이 있으면 「요청 값이 올바르지 않습니다. 확인할 값: 칸 이름. 값을 고쳐 다시 요청해 주세요.」 꼴이며, 둘 다 있으면 두 문장이 차례로 이어집니다. 칸 이름 자리에는 걸린 칸이 다섯까지 쉼표로 이어지고 더 있으면 「외 N개」 가 붙으며, 목록이나 객체 안의 칸은 「바깥 칸.0.안쪽 칸」 처럼 위치를 점으로 이은 경로로 적습니다. 걸린 검사가 모두 칸 하나를 짚지 않고 요청 전체를 보는 것이면 「요청 값이 올바르지 않습니다.」 만 옵니다. | |
| RESOURCE_ | 이어 받을 이전 작업(source_job_id)이 같은 조직과 환경에서 성공한 이 신고 유형의 작업이 아니거나, 그 결과를 읽을 수 없거나, 결과에 작성 스냅샷이 없거나 스냅샷이 expected_snapshot_hash 와 다르면 홈택스에 보내기 전에 이 오류로 끝납니다. error.message 는 걸린 확인의 문장 하나이고, BE 문장은 「이 신고 유형에서 성공한 이전 단계 작업이 필요합니다」, 「이전 작업의 작성 스냅샷이 없습니다」, 「작성 내용이 바뀌었습니다. 최신 결과를 다시 확인해 주세요」, 「같은 조직·환경에서 성공한 이전 단계의 작업이 필요합니다」, 「이전 작업의 JSON 결과를 읽을 수 없습니다」 입니다. | |
| RESOURCE_ | 작업 상태나 이어 받은 내용, 또는 홈택스에 있는 신고서의 상태가 이 단계와 맞지 않으면 이 오류로 끝납니다. 이 단계에서 이 코드로 끝나는 확인의 BE 문장은 「현재 작성 상태에서는 이 단계를 실행할 수 없습니다. 최신 결과를 확인해 주세요」, 「기관이 현재 신고서의 불러오기를 허용하지 않았습니다」, 「기관이 다른 작성 건을 반환했습니다」, 「불러온 신고서의 식별자가 다릅니다」, 「불러온 신고서의 기간·유형이 다릅니다」, 「불러온 신고서의 사업자가 다릅니다」, 「기관의 수정신고 원신고 연결이 변경됐습니다」, 「수정신고가 원신고를 덮어쓸 수 없습니다」, 「기관의 신고서가 다른 작성 건으로 바뀌었습니다」, 「승인한 뒤 기관 작성 내용이 변경됐습니다. 최신 내용을 다시 확인해 주세요」, 「미리 본 금액과 현재 신고 내용이 다릅니다」, 「이미 접수번호가 있는 신고입니다. 다시 제출하지 말고 접수 결과를 조회해 주세요」 이고, 걸린 확인의 문장 하나가 error.message 로 실립니다. | |
| AUTH_ | 저장된 기관 세션이 없습니다. 같은 연동 계정으로 hometax.session.login 을 먼저 실행해 세션을 연 뒤 다시 보냅니다. | |
| PROVIDER_ | 제출 요청을 보내는 중이거나 보낸 뒤 홈택스의 접수 여부를 확인하지 못한 경우입니다. 자동으로 다시 시도하지 않습니다. error.message 는 「기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.」 입니다. |
38. 원천세 신고 삭제신청 대상 조회hometax. tax. withholding. delete_ request. candidates
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 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 길이 | 필수 | 설명 |
|---|---|---|---|---|---|
| businessNo | string | - | Y | 삭제신청할 원천세 신고의 사업자등록번호입니다. 하이픈 없이 숫자 10자리로 입력합니다 | |
| taxCode | string | - | N | 세목 코드입니다. 원천세를 뜻하는 14 만 받으며 입력하지 않으면 14 입니다 | |
| attrYm | string | 6 | 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: candidates-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "hometax",
"action": "hometax.tax.withholding.delete_request.candidates",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {
"businessNo": "<필수>"
}
}'Response
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| success | boolean | 단계가 끝났는지입니다. 응답으로 돌아왔다면 항상 true 입니다. 실패는 이 모양이 아니라 오류 응답으로 옵니다. | |
| step | string | 응답이 어느 단계의 결과인지입니다. 이 액션은 항상 `candidates` 입니다. | |
| state | string | 이 단계가 끝난 뒤 작업이 놓인 상태입니다. `targets_listed` 중 하나입니다. | |
| snapshot | object | 이 단계가 끝난 작업 상태의 사본입니다. 다음 단계가 이어받는 값이라 직접 고치지 않습니다. | |
| snapshot_ | string | snapshot 의 해시(SHA-256, 16진수 64자)입니다. 다음 단계를 부를 때 expectedSnapshotHash 에 그대로 넣고, 이 작업의 job_id 는 sourceJobId 에 넣습니다. 그 사이 작업 상태가 바뀌었으면 거절됩니다. | |
| data | object | 후보 조회 결과 묶음입니다. | |
| data. | array | 삭제신청을 낼 수 있는 후보 신고의 목록입니다. 기관의 대상 목록에서 세목 `14`, 서식 `C103900` 신고를 담고 attrYm 을 보냈으면 그 귀속월의 신고만 담습니다. 요청한 사업자가 아닌 신고가 섞여 있으면 오류로 끝납니다. 신고 주체 식별번호(tin)는 싣지 않고 해시만 싣습니다. | |
| data. | string | 사업자등록번호입니다. 하이픈 없는 숫자 10자리이고 요청한 사업자와 같은 신고만 담깁니다. | |
| data. | string | 세목 코드입니다. 항상 `14` 입니다. | |
| data. | string | 서식 코드입니다. 항상 `C103900` 입니다. | |
| data. | string | 원 신고의 민원 ID(기관이 신고마다 붙인 식별자)입니다. 준비와 접수증 단계의 originalFilingReference 입력에 넣습니다. | |
| data. | string | 원 신고의 접수번호입니다. 준비와 접수증 단계의 originalReceiptNo 입력에 넣습니다. | |
| data. | string | 신고 귀속월입니다. YYYYMM 여섯 자리이고 형식이 맞지 않으면 오류로 끝납니다. | |
| data. | string | 귀속월입니다. period_yyyymm 과 같은 값입니다. | |
| data. | string | null | 지급월입니다. 기관 응답에 있을 때만 YYYYMM 여섯 자리가 들어 있고 없으면 null 입니다. 원 신고 접수증을 넣어 준비하면 그 접수증의 지급월이 준비 단계의 대상에 채워집니다. | |
| data. | string | 지급월을 어디서 확인했는지입니다. `TARGET_RESPONSE` 또는 `NOT_PROVIDED_BY_TARGET_SCREEN` 중 하나입니다. payment_ym 이 있으면 기관 대상 목록 응답에서 온 것이고 없으면 그 화면이 지급월을 주지 않은 것입니다. | |
| data. | string | null | 신고 구분 코드입니다. 기관이 준 값을 그대로 담고 없으면 null 입니다. | |
| data. | string | null | 신고 구분 이름입니다. 기관이 준 값을 그대로 담고 없으면 null 입니다. | |
| data. | string | null | 신고 상세 구분 코드입니다. 기관이 준 값을 그대로 담고 없으면 null 입니다. `04` 는 경정청구 신고서라 삭제신청을 낼 수 없습니다. | |
| data. | string | null | 신고 상세 구분 이름입니다. 기관이 준 값을 그대로 담고 없으면 null 입니다. | |
| data. | boolean | 삭제신청을 낼 수 있는 신고인지입니다. 상세 구분 코드가 `04`(경정청구 신고서)가 아니면 true 입니다. false 인 신고를 준비 단계에서 고르면 거절됩니다. | |
| data. | string | null | 기관이 준 제출 정보 문구입니다. 그대로 담고 없으면 null 입니다. | |
| data. | string | 기관의 삭제 대상 업무 코드입니다. 기관 설정에서 읽은 값이고 제출에 쓰입니다. | |
| data. | string | 기관의 업무 구분 코드입니다. 기관 설정에서 읽은 값이고 제출에 쓰입니다. | |
| data. | string | 기관의 삭제 대상 선택 화면 주소입니다. 기관 설정에서 읽은 값입니다. | |
| data. | string | 신고 주체 식별번호(tin)의 SHA-256 해시입니다. 식별번호 자체는 응답에 싣지 않습니다. | |
| data. | number | 후보 신고의 개수입니다. candidates 의 길이와 같습니다. | |
| warnings | array | 경고 문장의 목록입니다. 이 상품은 경고를 싣지 않아 항상 빈 배열입니다. |
// result.data - 값 자리에는 각 칸의 형식을 적었습니다 (실제 값이 아닙니다)
{
"success": "<boolean>",
"step": "<string>",
"state": "<string>",
"snapshot": {},
"snapshot_hash": "<string>",
"data": {
"candidates": [
{
"business_no": "<string>",
"tax_code": "<string>",
"form_code": "<string>",
"filing_reference": "<string>",
"receipt_no": "<string>",
"period_yyyymm": "<string>",
"attribution_ym": "<string>",
"payment_ym": "<string | null>",
"payment_period_evidence": "<string>",
"return_kind_code": "<string | null>",
"return_kind_name": "<string | null>",
"detail_code": "<string | null>",
"detail_name": "<string | null>",
"selectable": "<boolean>",
"submission_info": "<string | null>",
"target_code": "<string>",
"business_code": "<string>",
"target_popup_url": "<string>",
"tin_hash": "<string>"
}
],
"candidate_count": "<number>"
},
"warnings": []
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| VALIDATION_ | 요청 칸이 빠졌거나 칸 값이 이 단계의 요청 형식에 맞지 않으면 홈택스에 아무것도 보내지 않고 이 오류로 끝납니다. error.message 는 어느 칸인지 적지 않고 「원천세 삭제신청 입력 항목을 확인해 주세요」 입니다. | |
| AUTH_ | 저장된 기관 세션이 없습니다. 같은 연동 계정으로 hometax.session.login 을 먼저 실행해 세션을 연 뒤 다시 보냅니다. |
39. 원천세 신고 삭제신청 내역 조회hometax. tax. withholding. delete_ request. history
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 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 길이 | 필수 | 설명 |
|---|---|---|---|---|---|
| businessNo | string | - | Y | 삭제신청 내역을 조회할 사업자의 사업자등록번호입니다. 하이픈 없이 숫자 10자리로 입력합니다 | |
| taxCode | string | - | N | 세목 코드입니다. 원천세를 뜻하는 14 만 받으며 입력하지 않으면 14 입니다 | |
| dateFrom | string | 8 | Y | 삭제신청 내역을 찾을 기간의 시작일입니다. 여덟 자리의 실제 날짜로 입력하며, dateTo 보다 늦거나 dateTo 와 31일 넘게 떨어지면 입력 오류로 거절합니다 | |
| dateTo | string | - | Y | 조회 기간의 종료일입니다. 형식은 dateFrom 과 같고 dateFrom 보다 빠를 수 없으며 dateFrom 과 31일 넘게 떨어질 수 없습니다 | |
| pageNum | number | - | N | 받을 쪽 번호입니다. 1 이상 10000 이하의 정수이고 입력하지 않으면 1 입니다 | |
| pageSize | number | - | N | 한 쪽에 받을 내역 수입니다. 1 이상 500 이하의 정수이고 입력하지 않으면 100 입니다 |
- 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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: history-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "hometax",
"action": "hometax.tax.withholding.delete_request.history",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {
"businessNo": "<필수>",
"dateFrom": "<필수>",
"dateTo": "<필수>"
}
}'Response
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| success | boolean | 단계가 끝났는지입니다. 응답으로 돌아왔다면 항상 true 입니다. 실패는 이 모양이 아니라 오류 응답으로 옵니다. | |
| step | string | 응답이 어느 단계의 결과인지입니다. 이 액션은 항상 `history` 입니다. | |
| state | string | 이 단계가 끝난 뒤 작업이 놓인 상태입니다. `history_read` 중 하나입니다. | |
| snapshot | object | 이 단계가 끝난 작업 상태의 사본입니다. 다음 단계가 이어받는 값이라 직접 고치지 않습니다. | |
| snapshot_ | string | snapshot 의 해시(SHA-256, 16진수 64자)입니다. 다음 단계를 부를 때 expectedSnapshotHash 에 그대로 넣고, 이 작업의 job_id 는 sourceJobId 에 넣습니다. 그 사이 작업 상태가 바뀌었으면 거절됩니다. | |
| data | object | 처리내역 조회 결과 묶음입니다. | |
| data. | object | 삭제신청 처리내역입니다. 기관의 삭제신청 내역 중 세목 `14` 의 원천세 삭제신청 행만 담습니다. | |
| data. | string | 기관 응답의 처리 결과 표시입니다. 성공으로 확인된 응답만 여기까지 오므로 성공을 뜻하는 값입니다. | |
| data. | string | null | 기관 응답의 결과 코드입니다. 기관이 준 값을 그대로 담고 없으면 null 입니다. | |
| data. | number | 처리내역 행의 개수입니다. rows 의 길이와 같습니다. | |
| data. | array | 처리내역 행의 목록입니다. 요청한 날짜 범위와 페이지의 삭제신청 건이 들어 있습니다. 다른 사업자의 행이 섞여 있으면 오류로 끝납니다. | |
| data. | string | 삭제요청의 민원 ID 입니다. 접수증을 부를 때 requestReference 에 넣습니다. 없으면 빈 문자열입니다. | |
| data. | string | 삭제요청의 접수번호입니다. 없으면 빈 문자열입니다. | |
| data. | string | 삭제 대상이 된 원 신고의 민원 ID 입니다. 없으면 빈 문자열입니다. | |
| data. | string | 삭제 대상이 된 원 신고의 접수번호입니다. 없으면 빈 문자열입니다. | |
| data. | string | 삭제요청 처리 상태 코드입니다. 기관이 준 값이고 없으면 빈 문자열입니다. | |
| data. | string | 삭제요청 처리 상태 이름입니다. 기관이 준 값이고 없으면 빈 문자열입니다. | |
| data. | string | 삭제 대상 신고의 현재 상태 코드입니다. 기관이 준 값이고 `02` 이면 삭제가 확정된 것입니다. 없으면 빈 문자열입니다. | |
| data. | boolean | 삭제가 확정됐는지입니다. target_status_code 가 `02` 이면 true 입니다. | |
| data. | string | 신고 귀속월입니다. 기관이 준 값이고 없으면 빈 문자열입니다. | |
| data. | string | 삭제신청 일시입니다. 기관이 준 문자열을 그대로 담고 없으면 빈 문자열입니다. | |
| data. | object | 이 삭제신청을 낸 주체가 지금 로그인한 주체와 같은지 가리는 근거입니다. | |
| data. | boolean | null | 기관 공개 사용자 번호가 지금 주체와 같은지입니다. 행이나 지금 주체에 그 번호가 없어 비교하지 못하면 null 입니다. | |
| data. | boolean | null | 기관 사용자 ID 가 지금 주체와 같은지입니다. 행이나 지금 주체에 그 ID 가 없어 비교하지 못하면 null 입니다. | |
| data. | object | 기관이 준 페이지 정보입니다. | |
| data. | string | number | null | 현재 페이지 번호입니다. 기관이 준 값을 그대로 담고 없으면 null 입니다. | |
| data. | string | number | null | 한 페이지의 행 수입니다. 기관이 준 값을 그대로 담고 없으면 null 입니다. | |
| data. | string | number | null | 조건에 맞는 전체 건수입니다. 기관이 준 값을 그대로 담고 없으면 null 입니다. | |
| data. | number | 기관이 이 조회에서 돌려준 행의 총수입니다. 원천세가 아닌 행까지 센 수입니다. | |
| data. | number | 기관 행 중 세목이나 대상 코드가 비어 있어 원천세인지 가르지 못한 행의 수입니다. 이 행들은 history 에 담지 않습니다. | |
| warnings | array | 경고 문장의 목록입니다. 이 상품은 경고를 싣지 않아 항상 빈 배열입니다. |
// result.data - 값 자리에는 각 칸의 형식을 적었습니다 (실제 값이 아닙니다)
{
"success": "<boolean>",
"step": "<string>",
"state": "<string>",
"snapshot": {},
"snapshot_hash": "<string>",
"data": {
"history": {
"result": "<string>",
"code": "<string | null>",
"count": "<number>",
"rows": [
{
"request_reference": "<string>",
"request_receipt_no": "<string>",
"target_filing_reference": "<string>",
"target_receipt_no": "<string>",
"status_code": "<string>",
"status_name": "<string>",
"target_status_code": "<string>",
"deletion_confirmed": "<boolean>",
"period": "<string>",
"applied_at": "<string>",
"request_identity_evidence": {
"public_user_matches_current": "<boolean | null>",
"user_id_matches_current": "<boolean | null>"
}
}
],
"page": {
"page_num": "<string | number | null>",
"page_size": "<string | number | null>",
"total_count": "<string | number | null>"
}
},
"provider_row_count": "<number>",
"unclassified_row_count": "<number>"
},
"warnings": []
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| VALIDATION_ | 요청 칸이 빠졌거나 칸 값이 이 단계의 요청 형식에 맞지 않으면 홈택스에 아무것도 보내지 않고 이 오류로 끝납니다. error.message 는 어느 칸인지 적지 않고 「원천세 삭제신청 입력 항목을 확인해 주세요」 입니다. | |
| AUTH_ | 저장된 기관 세션이 없습니다. 같은 연동 계정으로 hometax.session.login 을 먼저 실행해 세션을 연 뒤 다시 보냅니다. |
40. 원천세 신고 삭제신청 준비hometax. tax. withholding. delete_ request. prepare
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 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| businessNo | string | Y | 삭제신청할 원천세 신고의 사업자등록번호입니다. 하이픈 없이 숫자 10자리로 입력하며 이전 단계 작업의 사업자와 다르면 403 으로 거절합니다 | |
| taxCode | string | N | 세목 코드입니다. 원천세를 뜻하는 14 만 받으며 입력하지 않으면 14 입니다 | |
| sourceJobId | string | Y | 이어서 진행할 이전 단계 작업의 job_id 를 그대로 입력합니다(job_ 으로 시작하는 작업 번호). 삭제 대상 후보 조회(candidates) 결과를 받습니다. 같은 조직과 환경, 같은 기관 연결에서 성공한 원천세 삭제신청 작업이어야 하고 아니면 진행하지 않고 거절하며, 받지 않는 상태의 결과이면 409 로 거절합니다 | |
| expectedSnapshotHash | string | Y | sourceJobId 작업 결과의 snapshot_hash 를 그대로 입력합니다(소문자 16진수 64자리). 그 작업의 내용과 맞지 않으면 진행하지 않고 작성 내용이 바뀌었다는 오류(409)로 거절합니다 | |
| originalFilingReference | string | Y | 삭제를 신청할 원 신고의 민원 ID 입니다. 후보 조회(candidates) 결과 candidates 항목의 filing_reference 를 그대로 입력합니다. 비어 있으면 입력 오류로 거절하고, originalReceiptNo 와 함께 후보 하나로 정해지지 않으면 409 로 거절하며, 경정청구 신고서는 삭제신청할 수 없어 거절합니다. 후보 조회 뒤 기관의 신고 정보가 바뀌었으면 거절하므로 후보 조회(candidates)부터 다시 합니다 | |
| originalReceiptNo | string | Y | 삭제를 신청할 원 신고의 접수번호입니다. originalFilingReference 와 같은 후보 항목의 receipt_no 를 그대로 입력하며 비어 있으면 입력 오류로 거절합니다 | |
| applicantName | string | N | 삭제신청에 함께 입력하는 신청인 이름입니다. 1자에서 100자까지이고 공백만 입력하면 입력 오류로 거절합니다. 이 값이 없으면 준비 결과의 required_inputs 에 빠진 항목으로 나오고 그 결과로는 제출(submit)할 수 없으므로, 값을 채워 같은 후보 조회(candidates) 결과로 prepare 를 다시 부릅니다 | |
| applicantPhone | string | N | 신청인 연락처입니다. 하이픈 없이 숫자 9자리에서 11자리로 입력하며 다른 모양이면 입력 오류로 거절합니다. 이 값이 없으면 준비 결과의 required_inputs 에 빠진 항목으로 나오고 그 결과로는 제출(submit)할 수 없으므로, 값을 채워 같은 후보 조회(candidates) 결과로 prepare 를 다시 부릅니다 | |
| consent | boolean | N | 개인정보 동의 여부입니다. 사용자 동의를 받았을 때만 JSON 불리언 true 로 입력하며 문자열로 쓴 true 는 입력 오류로 거절하고, false 는 입력하지 않은 것과 같습니다. 제출할 때 이 동의가 기록으로 남습니다. 이 값이 없으면 준비 결과의 required_inputs 에 빠진 항목으로 나오고 그 결과로는 제출(submit)할 수 없으므로, 값을 채워 같은 후보 조회(candidates) 결과로 prepare 를 다시 부릅니다 | |
| receiptJobId | string | N | 선택. 원 신고의 접수 결과와 대조할 때만 입력합니다. 성공한 원천세 전자파일 변환신고, 수정신고, 기한후신고의 제출 또는 접수증 조회 작업 ID 입니다. 정기신고 제출 작업 ID 는 입력하지 않습니다 | |
| receiptSnapshotHash | string | N | 선택. receiptJobId 를 입력할 때 함께 입력하는 그 작업 결과의 해시입니다 |
- 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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: prepare-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "hometax",
"action": "hometax.tax.withholding.delete_request.prepare",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {
"businessNo": "<필수>",
"sourceJobId": "<필수>",
"expectedSnapshotHash": "<필수>",
"originalFilingReference": "<필수>",
"originalReceiptNo": "<필수>"
}
}'Response
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| success | boolean | 단계가 끝났는지입니다. 응답으로 돌아왔다면 항상 true 입니다. 실패는 이 모양이 아니라 오류 응답으로 옵니다. | |
| step | string | 응답이 어느 단계의 결과인지입니다. 이 액션은 항상 `prepare` 입니다. | |
| state | string | 이 단계가 끝난 뒤 작업이 놓인 상태입니다. `target_ready` 또는 `waiting_input` 중 하나입니다. 신청인 이름, 연락처, 동의가 모두 있으면 제출 단계를 부를 수 있는 상태가 되고, 빠진 것이 있으면 입력을 기다리는 상태가 됩니다. | |
| snapshot | object | 이 단계가 끝난 작업 상태의 사본입니다. 다음 단계가 이어받는 값이라 직접 고치지 않습니다. | |
| snapshot_ | string | snapshot 의 해시(SHA-256, 16진수 64자)입니다. 다음 단계를 부를 때 expectedSnapshotHash 에 그대로 넣고, 이 작업의 job_id 는 sourceJobId 에 넣습니다. 그 사이 작업 상태가 바뀌었으면 거절됩니다. | |
| data | object | 준비 결과 묶음입니다. 이 단계는 기관에 신청을 보내지 않습니다. | |
| data. | object | 삭제신청 대상으로 고른 신고입니다. 후보 행과 같은 칸입니다(tin 제외). 기관에서 다시 읽은 값이 고른 뒤 바뀌었으면 오류로 끝납니다. | |
| data. | string | 사업자등록번호입니다. 하이픈 없는 숫자 10자리이고 요청한 사업자와 같은 신고만 담깁니다. | |
| data. | string | 세목 코드입니다. 항상 `14` 입니다. | |
| data. | string | 서식 코드입니다. 항상 `C103900` 입니다. | |
| data. | string | 원 신고의 민원 ID(기관이 신고마다 붙인 식별자)입니다. 준비와 접수증 단계의 originalFilingReference 입력에 넣습니다. | |
| data. | string | 원 신고의 접수번호입니다. 준비와 접수증 단계의 originalReceiptNo 입력에 넣습니다. | |
| data. | string | 신고 귀속월입니다. YYYYMM 여섯 자리이고 형식이 맞지 않으면 오류로 끝납니다. | |
| data. | string | 귀속월입니다. period_yyyymm 과 같은 값입니다. | |
| data. | string | null | 지급월입니다. 기관 응답에 있으면 YYYYMM 여섯 자리이고, 원 신고 접수증(receiptJobId, receiptSnapshotHash)을 넣었으면 그 접수증의 지급월로 채워집니다. 둘 다 없으면 null 입니다. | |
| data. | string | 지급월을 어디서 확인했는지입니다. `TARGET_RESPONSE` 또는 `NOT_PROVIDED_BY_TARGET_SCREEN` 또는 `ORIGINAL_RECEIPT` 중 하나입니다. 마지막 값은 원 신고 접수증에서 지급월을 가져왔다는 뜻입니다. | |
| data. | string | null | 신고 구분 코드입니다. 기관이 준 값을 그대로 담고 없으면 null 입니다. | |
| data. | string | null | 신고 구분 이름입니다. 기관이 준 값을 그대로 담고 없으면 null 입니다. | |
| data. | string | null | 신고 상세 구분 코드입니다. 기관이 준 값을 그대로 담고 없으면 null 입니다. `04` 는 경정청구 신고서라 삭제신청을 낼 수 없습니다. | |
| data. | string | null | 신고 상세 구분 이름입니다. 기관이 준 값을 그대로 담고 없으면 null 입니다. | |
| data. | boolean | 삭제신청을 낼 수 있는 신고인지입니다. 상세 구분 코드가 `04`(경정청구 신고서)가 아니면 true 입니다. false 인 신고를 준비 단계에서 고르면 거절됩니다. | |
| data. | string | null | 기관이 준 제출 정보 문구입니다. 그대로 담고 없으면 null 입니다. | |
| data. | string | 기관의 삭제 대상 업무 코드입니다. 기관 설정에서 읽은 값이고 제출에 쓰입니다. | |
| data. | string | 기관의 업무 구분 코드입니다. 기관 설정에서 읽은 값이고 제출에 쓰입니다. | |
| data. | string | 기관의 삭제 대상 선택 화면 주소입니다. 기관 설정에서 읽은 값입니다. | |
| data. | string | 신고 주체 식별번호(tin)의 SHA-256 해시입니다. 식별번호 자체는 응답에 싣지 않습니다. | |
| data. | boolean | 제출할 준비가 됐는지입니다. 신청인 이름, 연락처, 동의가 모두 있으면 true 입니다. | |
| data. | array | 아직 비어 있어 더 받아야 하는 입력의 목록입니다. 확인하는 항목은 `applicant_name`, `applicant_phone`, `consent` 이고 모두 있으면 빈 배열입니다. | |
| data. | boolean | 기관에 삭제신청을 보냈는지입니다. 이 단계는 보내지 않아 항상 false 입니다. | |
| data. | boolean | 삭제가 확정됐는지입니다. 이 단계에서 확정된 것은 없어 항상 false 입니다. | |
| warnings | array | 경고 문장의 목록입니다. 이 상품은 경고를 싣지 않아 항상 빈 배열입니다. |
// result.data - 값 자리에는 각 칸의 형식을 적었습니다 (실제 값이 아닙니다)
{
"success": "<boolean>",
"step": "<string>",
"state": "<string>",
"snapshot": {},
"snapshot_hash": "<string>",
"data": {
"target": {
"business_no": "<string>",
"tax_code": "<string>",
"form_code": "<string>",
"filing_reference": "<string>",
"receipt_no": "<string>",
"period_yyyymm": "<string>",
"attribution_ym": "<string>",
"payment_ym": "<string | null>",
"payment_period_evidence": "<string>",
"return_kind_code": "<string | null>",
"return_kind_name": "<string | null>",
"detail_code": "<string | null>",
"detail_name": "<string | null>",
"selectable": "<boolean>",
"submission_info": "<string | null>",
"target_code": "<string>",
"business_code": "<string>",
"target_popup_url": "<string>",
"tin_hash": "<string>"
},
"ready_for_submission": "<boolean>",
"required_inputs": [],
"institution_request_sent": "<boolean>",
"deletion_confirmed": "<boolean>"
},
"warnings": []
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| VALIDATION_ | 요청 칸이 빠졌거나 칸 값이 이 단계의 요청 형식에 맞지 않으면 홈택스에 아무것도 보내지 않고 이 오류로 끝납니다. error.message 는 어느 칸인지 적지 않고 「원천세 삭제신청 입력 항목을 확인해 주세요」 입니다. | |
| AUTH_ | 저장된 기관 세션이 없습니다. 같은 연동 계정으로 hometax.session.login 을 먼저 실행해 세션을 연 뒤 다시 보냅니다. |
41. 원천세 신고 삭제신청 접수증 조회hometax. tax. withholding. delete_ request. receipt
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 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| businessNo | string | Y | 삭제신청할 원천세 신고의 사업자등록번호입니다. 하이픈 없이 숫자 10자리로 입력하며 이전 단계 작업의 사업자와 다르면 403 으로 거절합니다 | |
| taxCode | string | N | 세목 코드입니다. 원천세를 뜻하는 14 만 받으며 입력하지 않으면 14 입니다 | |
| sourceJobId | string | Y | 이어서 진행할 이전 단계 작업의 job_id 를 그대로 입력합니다(job_ 으로 시작하는 작업 번호). 삭제신청 제출(submit)이 접수된 결과를 받고, 제출에서 이미 신청된 건으로 나왔다면 삭제신청 내역 조회(history) 결과를 입력합니다. 같은 조직과 환경, 같은 기관 연결에서 성공한 원천세 삭제신청 작업이어야 하고 아니면 진행하지 않고 거절하며, 받지 않는 상태의 결과이면 409 로 거절합니다 | |
| expectedSnapshotHash | string | Y | sourceJobId 작업 결과의 snapshot_hash 를 그대로 입력합니다(소문자 16진수 64자리). 그 작업의 내용과 맞지 않으면 진행하지 않고 작성 내용이 바뀌었다는 오류(409)로 거절합니다 | |
| requestReference | string | Y | 삭제신청의 민원 ID 입니다. 제출(submit) 결과의 request_reference 를 입력하고, 내역 조회(history) 결과를 sourceJobId 로 쓸 때는 그 결과 history.rows 항목의 request_reference 를 입력합니다. 비어 있으면 입력 오류로 거절하고 이전 단계 결과의 삭제신청과 맞지 않으면 409 로 거절합니다 | |
| originalFilingReference | string | Y | 삭제신청한 원 신고의 민원 ID 입니다. 준비(prepare)에 입력했던 값을 그대로 입력하며 비어 있으면 입력 오류로, 이전 단계 결과의 원 신고와 다르면 409 로 거절합니다 | |
| originalReceiptNo | string | Y | 삭제신청한 원 신고의 접수번호입니다. 준비(prepare)에 입력했던 값을 그대로 입력하며 비어 있으면 입력 오류로, 이전 단계 결과의 원 신고와 다르면 409 로 거절합니다 |
- 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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: receipt-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "hometax",
"action": "hometax.tax.withholding.delete_request.receipt",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {
"businessNo": "<필수>",
"sourceJobId": "<필수>",
"expectedSnapshotHash": "<필수>",
"requestReference": "<필수>",
"originalFilingReference": "<필수>",
"originalReceiptNo": "<필수>"
}
}'Response
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| success | boolean | 단계가 끝났는지입니다. 응답으로 돌아왔다면 항상 true 입니다. 실패는 이 모양이 아니라 오류 응답으로 옵니다. | |
| step | string | 응답이 어느 단계의 결과인지입니다. 이 액션은 항상 `receipt` 입니다. | |
| state | string | 이 단계가 끝난 뒤 작업이 놓인 상태입니다. `receipt_read` 중 하나입니다. | |
| snapshot | object | 이 단계가 끝난 작업 상태의 사본입니다. 다음 단계가 이어받는 값이라 직접 고치지 않습니다. | |
| snapshot_ | string | snapshot 의 해시(SHA-256, 16진수 64자)입니다. 다음 단계를 부를 때 expectedSnapshotHash 에 그대로 넣고, 이 작업의 job_id 는 sourceJobId 에 넣습니다. 그 사이 작업 상태가 바뀌었으면 거절됩니다. | |
| data | object | 접수증 조회 결과 묶음입니다. | |
| data. | object | 삭제요청 접수증입니다. 기관의 접수증 조회에서 요청한 requestReference 와 같은 행 하나만 담습니다. | |
| data. | string | 삭제요청의 민원 ID 입니다. 요청에 보낸 값 그대로입니다. | |
| data. | string | 삭제요청의 접수번호입니다. 없으면 빈 문자열입니다. | |
| data. | string | 삭제요청이 접수된 일시입니다. 기관이 준 문자열을 그대로 담고 없으면 빈 문자열입니다. | |
| data. | boolean | 접수번호와 접수 일시가 모두 있어 접수가 확인됐는지입니다. | |
| data. | string | 삭제요청의 처리 상태 이름입니다. 기관이 준 값이고 없으면 빈 문자열입니다. | |
| data. | string | 삭제 대상이 된 원 신고의 민원 ID 입니다. 없으면 빈 문자열입니다. | |
| data. | string | 삭제 대상이 된 원 신고의 접수번호입니다. 없으면 빈 문자열입니다. | |
| data. | boolean | 삭제가 확정됐는지입니다. 접수증은 접수를 보여 줄 뿐이라 항상 false 입니다. 확정 여부는 처리내역 조회로 봅니다. | |
| warnings | array | 경고 문장의 목록입니다. 이 상품은 경고를 싣지 않아 항상 빈 배열입니다. |
// result.data - 값 자리에는 각 칸의 형식을 적었습니다 (실제 값이 아닙니다)
{
"success": "<boolean>",
"step": "<string>",
"state": "<string>",
"snapshot": {},
"snapshot_hash": "<string>",
"data": {
"receipt": {
"request_reference": "<string>",
"request_receipt_no": "<string>",
"received_at": "<string>",
"request_receipt_confirmed": "<boolean>",
"status_name": "<string>",
"target_filing_reference": "<string>",
"target_receipt_no": "<string>"
},
"deletion_confirmed": "<boolean>"
},
"warnings": []
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| VALIDATION_ | 요청 칸이 빠졌거나 칸 값이 이 단계의 요청 형식에 맞지 않으면 홈택스에 아무것도 보내지 않고 이 오류로 끝납니다. error.message 는 어느 칸인지 적지 않고 「원천세 삭제신청 입력 항목을 확인해 주세요」 입니다. | |
| AUTH_ | 저장된 기관 세션이 없습니다. 같은 연동 계정으로 hometax.session.login 을 먼저 실행해 세션을 연 뒤 다시 보냅니다. |
42. 원천세 신고 삭제신청 준비자료 안내hometax. tax. withholding. delete_ request. requirements
MCP 도구 이름 hometax__
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
원천세 신고 삭제신청에 필요한 입력과 준비자료를 단계별로 알려 드립니다. 기관에 접속하지 않습니다.
- 이 API 는 기관 연동과 기관 로그인이 필요 없습니다. 기관 자격증명을 등록하지 않아도 호출할 수 있고, 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 | 호출할 작업입니다.
| |
| 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: requirements-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "hometax",
"action": "hometax.tax.withholding.delete_request.requirements",
"params": {}
}'Response
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| success | boolean | 단계가 끝났는지입니다. 응답으로 돌아왔다면 항상 true 입니다. 실패는 이 모양이 아니라 오류 응답으로 옵니다. | |
| step | string | 응답이 어느 단계의 결과인지입니다. 이 액션은 항상 `requirements` 입니다. | |
| data | object | 삭제신청 흐름의 안내 값 묶음입니다. 기관에 가지 않고 바로 돌려줍니다. | |
| data. | string | 세목 코드입니다. 항상 `14` 입니다. | |
| data. | string | 서식 코드입니다. 항상 `C103900` 입니다. | |
| data. | boolean | 삭제신청 제출이 지금 열려 있는지입니다. false 이면 제출 단계는 기관에 가지 않고 쓰기 차단 오류로 끝납니다. | |
| data. | array | 삭제신청을 진행하는 단계 순서입니다. `candidates`, `prepare`, `submit`, `history`, `receipt` 순서로 들어 있습니다. | |
| data. | boolean | 준비 단계가 기관에 신청을 보내지 않는지입니다. 항상 true 입니다. 기관에 신청을 보내는 단계는 제출뿐입니다. | |
| data. | boolean | 제출이 삭제 요청의 접수일 뿐 삭제 확정이 아니라는 표시입니다. 항상 true 입니다. 삭제가 확정됐는지는 처리내역 조회의 deletion_confirmed 로 봅니다. | |
| data. | array | 제출하려면 꼭 갖춰야 하는 항목의 목록입니다. `selected_return`, `applicant_name`, `applicant_phone`, `consent`, `confirm_delete_request` 가 들어 있습니다. | |
| data. | string | 기간을 어떻게 표시하는지 알리는 안내 문장입니다. 귀속월은 기관이 준 값을 쓰고, 지급월은 기관 응답이나 같은 신고의 접수증에서 확인된 경우에만 보입니다. |
// result.data - 값 자리에는 각 칸의 형식을 적었습니다 (실제 값이 아닙니다)
{
"success": "<boolean>",
"step": "<string>",
"data": {
"tax_code": "<string>",
"form_code": "<string>",
"writes_enabled": "<boolean>",
"sequence": [],
"prepare_is_read_only": "<boolean>",
"submission_is_deletion_request_not_confirmed_deletion": "<boolean>",
"required_to_submit": [],
"period_basis": "<string>"
}
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| VALIDATION_ | 요청 칸이 빠졌거나 칸 값이 이 단계의 요청 형식에 맞지 않으면 홈택스에 아무것도 보내지 않고 이 오류로 끝납니다. error.message 는 어느 칸인지 적지 않고 「원천세 삭제신청 입력 항목을 확인해 주세요」 입니다. |
43. 원천세 신고 삭제신청 제출hometax. tax. withholding. delete_ request. submit
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 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| businessNo | string | Y | 삭제신청할 원천세 신고의 사업자등록번호입니다. 하이픈 없이 숫자 10자리로 입력하며 이전 단계 작업의 사업자와 다르면 403 으로 거절합니다 | |
| taxCode | string | N | 세목 코드입니다. 원천세를 뜻하는 14 만 받으며 입력하지 않으면 14 입니다 | |
| sourceJobId | string | Y | 이어서 진행할 이전 단계 작업의 job_id 를 그대로 입력합니다(job_ 으로 시작하는 작업 번호). 제출 준비(prepare) 결과 가운데 신청인 이름과 연락처, 개인정보 동의가 모두 들어가 준비가 끝난 결과(ready_for_submission 이 true)를 받습니다. 같은 조직과 환경, 같은 기관 연결에서 성공한 원천세 삭제신청 작업이어야 하고 아니면 진행하지 않고 거절하며, 받지 않는 상태의 결과이면 409 로 거절합니다 | |
| expectedSnapshotHash | string | Y | sourceJobId 작업 결과의 snapshot_hash 를 그대로 입력합니다(소문자 16진수 64자리). 그 작업의 내용과 맞지 않으면 진행하지 않고 작성 내용이 바뀌었다는 오류(409)로 거절합니다 | |
| confirmDeleteRequest | boolean | Y | 삭제신청을 실제로 제출한다는 최종 확인값입니다. 접수된 삭제신청은 되돌릴 수 없으므로 사용자 동의를 받았을 때 JSON 불리언 true 로 입력합니다. 빠지거나 false 이면 기관에 아무것도 보내지 않고 최종 확인이 필요하다는 오류(422)로 거절하고, 문자열로 쓴 true 나 숫자 1 은 입력 오류로 거절합니다. 제출 결과는 삭제신청 접수이고 삭제가 확정된 것은 아닙니다. 이 값도 확인 토큰이 가리키는 요청 본문에 들어가므로 확인 토큰을 받는 첫 요청부터 함께 입력합니다. 나중에 더하면 본문이 달라져 확인 토큰을 다시 받아야 합니다 | |
| confirmation_ | string | N | 1회용 확인 토큰입니다. 처음에는 보내지 않습니다. 토큰 없이 부르면 기관에 아무것도 보내지 않고 작업도 만들지 않은 채 확인이 필요하다는 오류(WRITE_CONFIRMATION_REQUIRED)로 끝나고, 응답의 error.confirmation_token 에 토큰이 옵니다. error.message 의 안내를 사용자에게 보여 주고 동의를 받은 뒤 같은 요청에 이 토큰을 넣어 다시 부릅니다. 토큰은 10분 안에 한 번만 쓸 수 있고 처음 요청과 같은 본문, 같은 호출자, 같은 환경에서만 맞으며, 아니면 확인이 만료됐거나 내용이 달라졌다는 오류로 거절합니다 |
- 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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: submit-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "hometax",
"action": "hometax.tax.withholding.delete_request.submit",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {
"businessNo": "<필수>",
"sourceJobId": "<필수>",
"expectedSnapshotHash": "<필수>",
"confirmDeleteRequest": "<필수: boolean>"
}
}'Response
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| success | boolean | 단계가 끝났는지입니다. 응답으로 돌아왔다면 항상 true 입니다. 실패는 이 모양이 아니라 오류 응답으로 옵니다. | |
| step | string | 응답이 어느 단계의 결과인지입니다. 이 액션은 항상 `submit` 입니다. | |
| state | string | 이 단계가 끝난 뒤 작업이 놓인 상태입니다. `request_accepted` 또는 `already_requested` 중 하나입니다. 앞의 상태는 이번에 새로 접수됐다는 뜻이고 뒤의 상태는 이미 신청돼 있었다는 뜻입니다. | |
| snapshot | object | 이 단계가 끝난 작업 상태의 사본입니다. 다음 단계가 이어받는 값이라 직접 고치지 않습니다. | |
| snapshot_ | string | snapshot 의 해시(SHA-256, 16진수 64자)입니다. 다음 단계를 부를 때 expectedSnapshotHash 에 그대로 넣고, 이 작업의 job_id 는 sourceJobId 에 넣습니다. 그 사이 작업 상태가 바뀌었으면 거절됩니다. | |
| data | object | 제출 결과 묶음입니다. 삭제신청이 접수됐다는 뜻이지 삭제가 확정됐다는 뜻이 아닙니다. | |
| data. | string | null | 기관이 만든 삭제요청의 민원 ID 입니다. 새로 접수됐을 때만 값이 있고 이미 신청된 신고이면 null 입니다. 접수증을 부를 때 requestReference 에 넣습니다. | |
| data. | string | 삭제요청이 어떻게 처리됐는지입니다. `REQUEST_ACCEPTED` 또는 `ALREADY_REQUESTED` 중 하나입니다. 이번에 새로 접수됐는지 이미 접수돼 있던 신청인지를 가릅니다. | |
| data. | boolean | 삭제가 확정됐는지입니다. 제출은 삭제 요청의 접수이므로 항상 false 입니다. 확정 여부는 처리내역 조회로 봅니다. | |
| data. | string | 기관 쓰기가 확인됐는지를 가르는 판정입니다. 응답으로 돌아왔다면 항상 `confirmed` 입니다. 결과를 확인하지 못한 경우는 이 모양이 아니라 오류로 끝납니다. | |
| data. | string | 제출 액션의 이름입니다. 항상 `hometax.tax.withholding.delete_request.submit` 입니다. | |
| data. | string | 이어서 부를 단계입니다. `receipt` 또는 `history` 중 하나입니다. 새로 접수됐으면 접수증 조회를, 이미 신청돼 있었으면 처리내역 조회를 가리킵니다. | |
| warnings | array | 경고 문장의 목록입니다. 이 상품은 경고를 싣지 않아 항상 빈 배열입니다. | |
| outcome | string | data.outcome 과 같은 값을 응답 바깥으로 올린 것입니다. 작업 결과 판정이 이 자리를 읽습니다. | |
| action | string | data.action 과 같은 값을 응답 바깥으로 올린 것입니다. 작업 결과 판정이 이 자리를 읽습니다. |
// result.data - 값 자리에는 각 칸의 형식을 적었습니다 (실제 값이 아닙니다)
{
"success": "<boolean>",
"step": "<string>",
"state": "<string>",
"snapshot": {},
"snapshot_hash": "<string>",
"data": {
"request_reference": "<string | null>",
"request_outcome": "<string>",
"deletion_confirmed": "<boolean>",
"outcome": "<string>",
"action": "<string>",
"next_step": "<string>"
},
"warnings": [],
"outcome": "<string>",
"action": "<string>"
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| WRITE_ | 요청에 확인 토큰(confirmation_token)이 없으면 홈택스에 아무것도 보내지 않고 작업도 만들지 않은 채 이 오류로 끝납니다. error.message 는 「원천세 신고 삭제신청은 접수되면 되돌릴 수 없어 제출 전 확인이 필요합니다. 아래 내용을 사용자에게 보여주고 동의를 받으세요.」 로 시작하고 error.confirmation_token 에 1회용 토큰이 옵니다. 이 단계의 확인에는 미리보기 내용이 없어 error.preview 는 빈 객체입니다. 이 내용을 고객에게 그대로 보여 주고 확인을 받은 뒤, 같은 요청의 params.confirmation_token 에 응답의 error.confirmation_token 값을 넣어 다시 호출해 주세요. 토큰은 10분 안에 한 번만 쓸 수 있고, 확인한 요청 본문과 같은 본문에만 맞습니다. | |
| WRITE_ | 토큰이 만료됐거나, 이미 썼거나, 다른 호출자나 다른 환경에서 받은 것이거나, 확인한 요청 본문과 달라졌으면 홈택스에 아무것도 보내지 않고 작업도 만들지 않은 채 이 오류로 끝납니다. error.message 는 「확인이 만료됐거나 확인한 내용과 달라졌습니다. 다시 확인해 주세요.」 입니다. 토큰 없이 다시 요청하면 새 토큰을 받습니다. | |
| VALIDATION_ | 요청 칸이 빠졌거나 칸 값이 이 단계의 요청 형식에 맞지 않으면 홈택스에 아무것도 보내지 않고 이 오류로 끝납니다. error.message 는 어느 칸인지 적지 않고 「원천세 삭제신청 입력 항목을 확인해 주세요」 입니다. | |
| AUTH_ | 저장된 기관 세션이 없습니다. 같은 연동 계정으로 hometax.session.login 을 먼저 실행해 세션을 연 뒤 다시 보냅니다. | |
| PROVIDER_ | 제출 요청을 보내는 중이거나 보낸 뒤 홈택스의 접수 여부를 확인하지 못한 경우입니다. 자동으로 다시 시도하지 않습니다. error.message 는 「기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.」 입니다. 같은 신고에 앞서 보낸 삭제신청이 접수를 확인하지 못한 채 기록에 남아 있으면(아직 처리 중인 경우 포함) 홈택스에 다시 보내지 않고 같은 오류로 끝납니다. 앞서 보낸 삭제신청이 접수로 확인돼 있으면 그 결과를 그대로 돌려줍니다. |
44. 원천세 전자파일 변환신고 내용검증 요청hometax. tax. withholding. file_ conversion. content_ validate
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 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| source_ | string | Y | 이어서 진행할 이전 단계 작업의 job_id 를 그대로 입력합니다(job_ 으로 시작하는 작업 번호). 형식검증을 통과해 내용검증을 할 수 있는 상태의 결과를 받습니다. 그 상태가 아니면 409 로 거절합니다. 같은 조직과 환경, 같은 기관 연결에서 성공한 원천세 파일변환 작업이어야 하고 아니면 진행하지 않고 거절합니다 | |
| expected_ | string | Y | source_job_id 작업 결과의 snapshot_hash 를 그대로 입력합니다(소문자 16진수 64자리). 그 작업의 내용과 맞지 않으면 진행하지 않고 작성 내용이 바뀌었다는 오류(409)로 거절합니다 | |
| confirmation_ | string | N | 1회용 확인 토큰입니다. 처음에는 보내지 않습니다. 토큰 없이 부르면 기관에 아무것도 보내지 않고 작업도 만들지 않은 채 확인이 필요하다는 오류(WRITE_CONFIRMATION_REQUIRED)로 끝나고, 응답의 error.confirmation_token 에 토큰이 옵니다. error.message 의 안내를 사용자에게 보여 주고 동의를 받은 뒤 같은 요청에 이 토큰을 넣어 다시 부릅니다. 토큰은 10분 안에 한 번만 쓸 수 있고 처음 요청과 같은 본문, 같은 호출자, 같은 환경에서만 맞으며, 아니면 확인이 만료됐거나 내용이 달라졌다는 오류로 거절합니다 |
- 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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: content_validate-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "hometax",
"action": "hometax.tax.withholding.file_conversion.content_validate",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {
"source_job_id": "<필수>",
"expected_snapshot_hash": "<필수>"
}
}'Response
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| success | boolean | 단계가 끝났는지입니다. 응답으로 돌아왔다면 항상 true 입니다. 실패는 이 모양이 아니라 오류 응답으로 옵니다. | |
| step | string | 응답이 어느 단계의 결과인지입니다. 이 액션은 항상 `content_validate` 입니다. | |
| state | string | 이 단계가 끝난 뒤 작업이 놓인 상태입니다. 기관의 변환 진행 상태 코드이고 다음 중 하나입니다. `00`(진행 중인 검증이 없는 처음 상태), `10`(형식검증 진행 중), `11`(형식검증이 끝났고 오류만 있어 내용검증할 자료가 없음), `12`(형식검증이 끝났고 내용검증을 시작할 수 있음), `20`(내용검증 진행 중), `21`(내용검증이 끝났고 오류만 있어 제출할 자료가 없음), `22`(내용검증이 끝났고 제출 대상이 있음), `23`(내용검증 대상 건수가 한도를 넘어 내용검증이 취소됨). | |
| snapshot | object | 이 단계가 끝난 작업 상태의 사본입니다. 다음 단계가 이어받는 값이라 직접 고치지 않습니다. | |
| snapshot_ | string | snapshot 의 해시(SHA-256, 16진수 64자)입니다. 다음 단계를 부를 때 expected_snapshot_hash 에 그대로 넣고, 이 작업의 job_id 는 source_job_id 에 넣습니다. 그 사이 작업 상태가 바뀌었으면 거절됩니다. | |
| data | object | 내용검증 요청 결과 묶음입니다. 기관에 내용검증을 요청하고 받은 답을 담습니다. 검증 결과 자체는 이 응답이 아니라 진행현황으로 확인합니다. 형식검증이 끝난 상태(`12`)가 아니거나 기관이 요청을 받지 않으면 이 모양이 아니라 오류로 끝납니다. | |
| data. | object | 기관이 내용검증 요청에 답한 묶음 그대로입니다. 안쪽 칸은 기관이 정합니다. | |
| data. | string | 기관 쓰기가 확인됐는지를 가르는 판정입니다. 봉투 바깥의 outcome 과 같은 값이고, 응답으로 돌아왔다면 항상 `confirmed` 입니다. | |
| data. | string | 쓰기 액션의 이름입니다. 봉투 바깥의 action 과 같은 값이고, 이 액션은 항상 `hometax.tax.withholding.file_conversion.content_validate` 입니다. | |
| warnings | array | 경고 문장의 목록입니다. 이 상품은 경고를 싣지 않아 항상 빈 배열입니다. | |
| outcome | string | 기관 쓰기가 확인됐는지를 가르는 판정입니다. 응답으로 돌아왔다면 항상 `confirmed` 입니다. 결과를 확인하지 못한 경우는 이 모양이 아니라 오류로 끝납니다. 작업 결과 판정이 이 자리를 읽습니다. | |
| action | string | 쓰기 액션의 이름입니다. 이 액션은 항상 `hometax.tax.withholding.file_conversion.content_validate` 입니다. 작업 결과 판정이 이 자리를 읽습니다. |
// result.data - 값 자리에는 각 칸의 형식을 적었습니다 (실제 값이 아닙니다)
{
"success": "<boolean>",
"step": "<string>",
"state": "<string>",
"snapshot": {},
"snapshot_hash": "<string>",
"data": {
"response": {},
"outcome": "<string>",
"action": "<string>"
},
"warnings": [],
"outcome": "<string>",
"action": "<string>"
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| WRITE_ | 요청에 확인 토큰(confirmation_token)이 없으면 홈택스에 아무것도 보내지 않고 작업도 만들지 않은 채 이 오류로 끝납니다. error.message 는 「원천세 전자파일 내용검증을 기관에 요청하면 되돌릴 수 없어 요청 전 확인이 필요합니다. 아래 내용을 사용자에게 보여주고 동의를 받으세요.」 로 시작하고 error.confirmation_token 에 1회용 토큰이 옵니다. 이 단계의 확인에는 미리보기 내용이 없어 error.preview 는 빈 객체입니다. 이 내용을 고객에게 그대로 보여 주고 확인을 받은 뒤, 같은 요청의 params.confirmation_token 에 응답의 error.confirmation_token 값을 넣어 다시 호출해 주세요. 토큰은 10분 안에 한 번만 쓸 수 있고, 확인한 요청 본문과 같은 본문에만 맞습니다. | |
| WRITE_ | 토큰이 만료됐거나, 이미 썼거나, 다른 호출자나 다른 환경에서 받은 것이거나, 확인한 요청 본문과 달라졌으면 홈택스에 아무것도 보내지 않고 작업도 만들지 않은 채 이 오류로 끝납니다. error.message 는 「확인이 만료됐거나 확인한 내용과 달라졌습니다. 다시 확인해 주세요.」 입니다. 토큰 없이 다시 요청하면 새 토큰을 받습니다. | |
| VALIDATION_ | 요청 칸이 빠졌거나 칸 값이 이 단계의 요청 형식에 맞지 않으면 홈택스에 아무것도 보내지 않고 이 오류로 끝납니다. error.message 는 「파일변환 요청 값이 올바르지 않습니다(확인할 항목: 칸 경로). 준비자료 안내에서 이 단계에 넣을 값을 확인한 뒤 다시 요청해 주세요.」 꼴입니다. 칸 경로 자리에는 걸린 칸의 위치를 점으로 이은 경로가 다섯까지 쉼표로 이어지고 더 있으면 끝에 「외」 가 붙으며, 칸 하나를 짚지 않고 요청 전체를 보는 검사에 걸리면 그 자리에 「요청 본문」 이 들어갑니다. | |
| RESOURCE_ | 이어 받을 이전 작업(source_job_id)이 같은 조직과 환경에서 성공한 이 신고 유형의 작업이 아니거나, 그 결과를 읽을 수 없거나, 결과에 작성 스냅샷이 없거나 스냅샷이 expected_snapshot_hash 와 다르면 홈택스에 보내기 전에 이 오류로 끝납니다. error.message 는 걸린 확인의 문장 하나이고, BE 문장은 「같은 조직·환경에서 성공한 이전 단계의 작업이 필요합니다」, 「이전 작업의 JSON 결과를 읽을 수 없습니다」, 「이 신고 유형에서 성공한 이전 단계 작업이 필요합니다」, 「이전 작업의 작성 스냅샷이 없습니다」, 「작성 내용이 바뀌었습니다. 최신 결과를 다시 확인해 주세요」 입니다. | |
| RESOURCE_ | 작업 상태나 이어 받은 내용이 이 단계와 맞지 않으면 이 오류로 끝납니다. 이 단계에서 이 코드로 끝나는 확인의 BE 문장은 「홈택스에서 새 변환 작업을 확인하지 못했습니다. 업로드를 반복하지 말고 진행현황을 확인해 주세요」, 「다른 변환 작업으로 바뀌었습니다. 재전송하지 말고 진행현황을 확인해 주세요」, 「형식검증 결과가 내용검증 가능한 상태여야 합니다」 이고, 걸린 확인의 문장 하나가 error.message 로 실립니다. | |
| AUTH_ | 저장된 기관 세션이 없습니다. 같은 연동 계정으로 hometax.session.login 을 먼저 실행해 세션을 연 뒤 다시 보냅니다. |
45. 원천세 전자파일 변환신고 암호 입력 형식검증hometax. tax. withholding. file_ conversion. format_ validate
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
기관이 암호 입력을 요청한 전자파일에 암호를 넣어 형식검증을 다시 요청합니다. 원본을 다시 올리지 않습니다.
- 홈택스 세션 로그인을 먼저 호출해 세션을 등록한 뒤, 같은 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 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| source_ | string | Y | 이어서 진행할 이전 단계 작업의 job_id 를 그대로 입력합니다(job_ 으로 시작하는 작업 번호). 원본 올리기(upload) 결과 가운데 기관이 암호를 요구해 password_required 상태로 끝난 결과를 받습니다. 그 밖의 상태이면 409 로 거절합니다. 같은 조직과 환경, 같은 기관 연결에서 성공한 원천세 파일변환 작업이어야 하고 아니면 진행하지 않고 거절합니다 | |
| expected_ | string | Y | source_job_id 작업 결과의 snapshot_hash 를 그대로 입력합니다(소문자 16진수 64자리). 그 작업의 내용과 맞지 않으면 진행하지 않고 작성 내용이 바뀌었다는 오류(409)로 거절합니다 | |
| password | string | N | 원본 파일에 걸린 암호입니다. 1자 이상 200자 이하이며 기관이 암호를 요구한 파일을 다시 형식검증할 때 입력합니다. 암호는 기관에 보내는 형식으로만 쓰고 작업 결과에 저장하지 않습니다. 이 값은 params 에 입력하지 않고 encrypted_fields.password 에 공개키로 암호화해 입력합니다. params 에 입력하면 작업을 만들지 않고 400 VALIDATION_INVALID_FIELD 로 거절합니다 | |
| confirmation_ | string | N | 1회용 확인 토큰입니다. 처음에는 보내지 않습니다. 토큰 없이 부르면 기관에 아무것도 보내지 않고 작업도 만들지 않은 채 확인이 필요하다는 오류(WRITE_CONFIRMATION_REQUIRED)로 끝나고, 응답의 error.confirmation_token 에 토큰이 옵니다. error.message 의 안내를 사용자에게 보여 주고 동의를 받은 뒤 같은 요청에 이 토큰을 넣어 다시 부릅니다. 토큰은 10분 안에 한 번만 쓸 수 있고 처음 요청과 같은 본문, 같은 호출자, 같은 환경에서만 맞으며, 아니면 확인이 만료됐거나 내용이 달라졌다는 오류로 거절합니다 |
- 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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: format_validate-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "hometax",
"action": "hometax.tax.withholding.file_conversion.format_validate",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {
"source_job_id": "<필수>",
"expected_snapshot_hash": "<필수>"
}
}'Response
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| success | boolean | 단계가 끝났는지입니다. 응답으로 돌아왔다면 항상 true 입니다. 실패는 이 모양이 아니라 오류 응답으로 옵니다. | |
| step | string | 응답이 어느 단계의 결과인지입니다. 이 액션은 항상 `format_validate` 입니다. | |
| state | string | 이 단계가 끝난 뒤 작업이 놓인 상태입니다. 기관의 변환 진행 상태 코드 `00`(진행 중인 검증이 없는 처음 상태), `10`(형식검증 진행 중), `11`(형식검증이 끝났고 오류만 있어 내용검증할 자료가 없음), `12`(형식검증이 끝났고 내용검증을 시작할 수 있음), `20`(내용검증 진행 중), `21`(내용검증이 끝났고 오류만 있어 제출할 자료가 없음), `22`(내용검증이 끝났고 제출 대상이 있음), `23`(내용검증 대상 건수가 한도를 넘어 내용검증이 취소됨) 중 하나이거나, 파일에 비밀번호가 필요하면 `password_required`(파일에 비밀번호가 필요해 멈춘 상태, 비밀번호를 넣어 형식검증 단계를 다시 부름) 입니다. | |
| snapshot | object | 이 단계가 끝난 작업 상태의 사본입니다. 다음 단계가 이어받는 값이라 직접 고치지 않습니다. | |
| snapshot_ | string | snapshot 의 해시(SHA-256, 16진수 64자)입니다. 다음 단계를 부를 때 expected_snapshot_hash 에 그대로 넣고, 이 작업의 job_id 는 source_job_id 에 넣습니다. 그 사이 작업 상태가 바뀌었으면 거절됩니다. | |
| data | object | 형식검증 결과 묶음입니다. 비밀번호가 필요해 멈춘 파일에 비밀번호를 넣어 형식검증을 다시 요청한 결과입니다. 비밀번호가 멈춘 상태가 아닌데 부르면 이 모양이 아니라 오류로 끝납니다. | |
| data. | string | 기관이 형식검증에 붙인 결과 코드입니다. 기관이 파일의 비밀번호를 요구해 멈췄을 때(상태가 `password_required`)만 있습니다. | |
| data. | string | 위 결과 코드에 기관이 붙인 안내 문장입니다. provider_code 와 함께 있고, 기관이 문장을 주지 않았으면 빈 문자열입니다. | |
| data. | string | 파일 암호를 넣어 이어 가는 방법을 적은 서버의 안내 문장입니다. 상태가 `password_required` 일 때만 있습니다. 원본은 다시 올리지 않고, 같은 형식검증 요청에 encrypted_fields.password 로 암호를 넣습니다. | |
| data. | object | 기관이 형식검증 요청에 답한 묶음 그대로입니다. 안쪽 칸은 기관이 정하고, 비밀번호 칸은 서버가 지우고 돌려줍니다. 비밀번호 요구로 멈춘 경우에는 이 칸 대신 provider_code, provider_message, how_to_ko 가 옵니다. | |
| data. | string | 기관 쓰기가 확인됐는지를 가르는 판정입니다. 봉투 바깥의 outcome 과 같은 값이고, 응답으로 돌아왔다면 항상 `confirmed` 입니다. | |
| data. | string | 쓰기 액션의 이름입니다. 봉투 바깥의 action 과 같은 값이고, 이 액션은 항상 `hometax.tax.withholding.file_conversion.format_validate` 입니다. | |
| warnings | array | 경고 문장의 목록입니다. 이 상품은 경고를 싣지 않아 항상 빈 배열입니다. | |
| outcome | string | 기관 쓰기가 확인됐는지를 가르는 판정입니다. 응답으로 돌아왔다면 항상 `confirmed` 입니다. 결과를 확인하지 못한 경우는 이 모양이 아니라 오류로 끝납니다. 작업 결과 판정이 이 자리를 읽습니다. | |
| action | string | 쓰기 액션의 이름입니다. 이 액션은 항상 `hometax.tax.withholding.file_conversion.format_validate` 입니다. 작업 결과 판정이 이 자리를 읽습니다. |
// result.data - 값 자리에는 각 칸의 형식을 적었습니다 (실제 값이 아닙니다)
{
"success": "<boolean>",
"step": "<string>",
"state": "<string>",
"snapshot": {},
"snapshot_hash": "<string>",
"data": {
"provider_code": "<string>",
"provider_message": "<string>",
"how_to_ko": "<string>",
"response": {},
"outcome": "<string>",
"action": "<string>"
},
"warnings": [],
"outcome": "<string>",
"action": "<string>"
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| WRITE_ | 요청에 확인 토큰(confirmation_token)이 없으면 홈택스에 아무것도 보내지 않고 작업도 만들지 않은 채 이 오류로 끝납니다. error.message 는 「원천세 전자파일 형식검증을 기관에 요청하면 되돌릴 수 없어 요청 전 확인이 필요합니다. 아래 내용을 사용자에게 보여주고 동의를 받으세요.」 로 시작하고 error.confirmation_token 에 1회용 토큰이 옵니다. 이 단계의 확인에는 미리보기 내용이 없어 error.preview 는 빈 객체입니다. 이 내용을 고객에게 그대로 보여 주고 확인을 받은 뒤, 같은 요청의 params.confirmation_token 에 응답의 error.confirmation_token 값을 넣어 다시 호출해 주세요. 토큰은 10분 안에 한 번만 쓸 수 있고, 확인한 요청 본문과 같은 본문에만 맞습니다. | |
| WRITE_ | 토큰이 만료됐거나, 이미 썼거나, 다른 호출자나 다른 환경에서 받은 것이거나, 확인한 요청 본문과 달라졌으면 홈택스에 아무것도 보내지 않고 작업도 만들지 않은 채 이 오류로 끝납니다. error.message 는 「확인이 만료됐거나 확인한 내용과 달라졌습니다. 다시 확인해 주세요.」 입니다. 토큰 없이 다시 요청하면 새 토큰을 받습니다. | |
| VALIDATION_ | 요청 칸이 빠졌거나 칸 값이 이 단계의 요청 형식에 맞지 않으면 홈택스에 아무것도 보내지 않고 이 오류로 끝납니다. error.message 는 「파일변환 요청 값이 올바르지 않습니다(확인할 항목: 칸 경로). 준비자료 안내에서 이 단계에 넣을 값을 확인한 뒤 다시 요청해 주세요.」 꼴입니다. 칸 경로 자리에는 걸린 칸의 위치를 점으로 이은 경로가 다섯까지 쉼표로 이어지고 더 있으면 끝에 「외」 가 붙으며, 칸 하나를 짚지 않고 요청 전체를 보는 검사에 걸리면 그 자리에 「요청 본문」 이 들어갑니다. | |
| RESOURCE_ | 이어 받을 이전 작업(source_job_id)이 같은 조직과 환경에서 성공한 이 신고 유형의 작업이 아니거나, 그 결과를 읽을 수 없거나, 결과에 작성 스냅샷이 없거나 스냅샷이 expected_snapshot_hash 와 다르면 홈택스에 보내기 전에 이 오류로 끝납니다. error.message 는 걸린 확인의 문장 하나이고, BE 문장은 「같은 조직·환경에서 성공한 이전 단계의 작업이 필요합니다」, 「이전 작업의 JSON 결과를 읽을 수 없습니다」, 「이 신고 유형에서 성공한 이전 단계 작업이 필요합니다」, 「이전 작업의 작성 스냅샷이 없습니다」, 「작성 내용이 바뀌었습니다. 최신 결과를 다시 확인해 주세요」 입니다. | |
| RESOURCE_ | 작업 상태나 이어 받은 내용이 이 단계와 맞지 않으면 이 오류로 끝납니다. 이 단계에서 이 코드로 끝나는 확인의 BE 문장은 「기관에서 암호 입력을 요청한 파일만 다시 형식검증할 수 있습니다」, 「확보된 기관 파일 메타데이터가 없습니다」, 「기관이 요구하는 암호화 파일이 필요합니다」, 「홈택스에서 새 변환 작업을 확인하지 못했습니다. 업로드를 반복하지 말고 진행현황을 확인해 주세요」, 「다른 변환 작업으로 바뀌었습니다. 재전송하지 말고 진행현황을 확인해 주세요」 이고, 걸린 확인의 문장 하나가 error.message 로 실립니다. | |
| AUTH_ | 저장된 기관 세션이 없습니다. 같은 연동 계정으로 hometax.session.login 을 먼저 실행해 세션을 연 뒤 다시 보냅니다. |
46. 원천세 전자파일 변환신고 작업 시작hometax. tax. withholding. file_ conversion. init
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 | - | N | 작업 파라미터입니다. 이 API 는 빈 객체로 호출할 수 있습니다. | |
| encrypted_ | object | - | N | 민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| filing_ | string | N | 변환할 신고의 종류입니다. regular(정기신고), amendment(수정신고), late(기한후신고) 가운데 하나를 입력하며 입력하지 않으면 regular 입니다. 이 값은 이어지는 단계에 그대로 이어지고, 이미 접수된 신고를 다시 올리는 재신고는 regular 에서만 할 수 있습니다 | |
| resume_ | string | N | 기관에 이미 진행 중인 변환 작업을 이어갈 때 그 작업의 식별자입니다. 진행현황에 나온 작업 ID 를 그대로 입력하며 1자 이상 100자 이하입니다. 입력하지 않으면 새 변환 작업으로 시작하고, 기관에 진행 중인 변환 작업이 있는데 이 값을 입력하지 않으면 기존 변환 작업이 있다는 오류(409)로 거절합니다 |
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: init-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "hometax",
"action": "hometax.tax.withholding.file_conversion.init",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {}
}'Response
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| success | boolean | 단계가 끝났는지입니다. 응답으로 돌아왔다면 항상 true 입니다. 실패는 이 모양이 아니라 오류 응답으로 옵니다. | |
| step | string | 응답이 어느 단계의 결과인지입니다. 이 액션은 항상 `init` 입니다. | |
| state | string | 이 단계가 끝난 뒤 작업이 놓인 상태입니다. 기관의 변환 진행 상태 코드이고 다음 중 하나입니다. `00`(진행 중인 검증이 없는 처음 상태), `10`(형식검증 진행 중), `11`(형식검증이 끝났고 오류만 있어 내용검증할 자료가 없음), `12`(형식검증이 끝났고 내용검증을 시작할 수 있음), `20`(내용검증 진행 중), `21`(내용검증이 끝났고 오류만 있어 제출할 자료가 없음), `22`(내용검증이 끝났고 제출 대상이 있음), `23`(내용검증 대상 건수가 한도를 넘어 내용검증이 취소됨). | |
| snapshot | object | 이 단계가 끝난 작업 상태의 사본입니다. 다음 단계가 이어받는 값이라 직접 고치지 않습니다. | |
| snapshot_ | string | snapshot 의 해시(SHA-256, 16진수 64자)입니다. 다음 단계를 부를 때 expected_snapshot_hash 에 그대로 넣고, 이 작업의 job_id 는 source_job_id 에 넣습니다. 그 사이 작업 상태가 바뀌었으면 거절됩니다. | |
| data | object | 시작 결과 묶음입니다. 기관에서 이 신고 유형의 변환 작업이 이미 있는지 확인하고 지금 상태를 담습니다. 이미 진행 중인 작업이 있는데 이어 하기(resume_batch_id)를 지정하지 않았다면 이 모양이 아니라 오류로 끝납니다. | |
| data. | object | 기관이 알려 준 변환 진행 상태 묶음 그대로입니다. 봉투의 state 가 읽는 진행 상태 코드(trnsPrgrStat)가 들어 있고, 안쪽 칸은 기관이 정합니다. | |
| warnings | array | 경고 문장의 목록입니다. 이 상품은 경고를 싣지 않아 항상 빈 배열입니다. |
// result.data - 값 자리에는 각 칸의 형식을 적었습니다 (실제 값이 아닙니다)
{
"success": "<boolean>",
"step": "<string>",
"state": "<string>",
"snapshot": {},
"snapshot_hash": "<string>",
"data": {
"status": {}
},
"warnings": []
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| VALIDATION_ | 요청 칸이 빠졌거나 칸 값이 이 단계의 요청 형식에 맞지 않으면 홈택스에 아무것도 보내지 않고 이 오류로 끝납니다. error.message 는 「파일변환 요청 값이 올바르지 않습니다(확인할 항목: 칸 경로). 준비자료 안내에서 이 단계에 넣을 값을 확인한 뒤 다시 요청해 주세요.」 꼴입니다. 칸 경로 자리에는 걸린 칸의 위치를 점으로 이은 경로가 다섯까지 쉼표로 이어지고 더 있으면 끝에 「외」 가 붙으며, 칸 하나를 짚지 않고 요청 전체를 보는 검사에 걸리면 그 자리에 「요청 본문」 이 들어갑니다. | |
| RESOURCE_ | 작업 상태나 이어 받은 내용이 이 단계와 맞지 않으면 이 오류로 끝납니다. 이 단계에서 이 코드로 끝나는 확인의 BE 문장은 「홈택스에서 새 변환 작업을 확인하지 못했습니다. 업로드를 반복하지 말고 진행현황을 확인해 주세요」, 「다른 변환 작업으로 바뀌었습니다. 재전송하지 말고 진행현황을 확인해 주세요」, 「기존 변환 작업이 있습니다. 진행현황의 작업 ID로 이어서 진행해 주세요」 이고, 걸린 확인의 문장 하나가 error.message 로 실립니다. | |
| AUTH_ | 저장된 기관 세션이 없습니다. 같은 연동 계정으로 hometax.session.login 을 먼저 실행해 세션을 연 뒤 다시 보냅니다. |
47. 원천세 전자파일 변환신고 제출 전 미리보기hometax. tax. withholding. file_ conversion. preview
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 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| source_ | string | Y | 이어서 진행할 이전 단계 작업의 job_id 를 그대로 입력합니다(job_ 으로 시작하는 작업 번호). 변환이 끝나 제출할 수 있는 상태의 결과를 받습니다. 기관에서 제출 가능한 변환 결과가 없으면 409 로 거절합니다. 같은 조직과 환경, 같은 기관 연결에서 성공한 원천세 파일변환 작업이어야 하고 아니면 진행하지 않고 거절합니다 | |
| expected_ | string | Y | source_job_id 작업 결과의 snapshot_hash 를 그대로 입력합니다(소문자 16진수 64자리). 그 작업의 내용과 맞지 않으면 진행하지 않고 작성 내용이 바뀌었다는 오류(409)로 거절합니다 |
- 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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: preview-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "hometax",
"action": "hometax.tax.withholding.file_conversion.preview",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {
"source_job_id": "<필수>",
"expected_snapshot_hash": "<필수>"
}
}'Response
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| success | boolean | 단계가 끝났는지입니다. 응답으로 돌아왔다면 항상 true 입니다. 실패는 이 모양이 아니라 오류 응답으로 옵니다. | |
| step | string | 응답이 어느 단계의 결과인지입니다. 이 액션은 항상 `preview` 입니다. | |
| state | string | 이 단계가 끝난 뒤 작업이 놓인 상태입니다. 항상 `previewed`(제출 대상 확인을 마친 상태) 입니다. | |
| snapshot | object | 이 단계가 끝난 작업 상태의 사본입니다. 다음 단계가 이어받는 값이라 직접 고치지 않습니다. | |
| snapshot_ | string | snapshot 의 해시(SHA-256, 16진수 64자)입니다. 다음 단계를 부를 때 expected_snapshot_hash 에 그대로 넣고, 이 작업의 job_id 는 source_job_id 에 넣습니다. 그 사이 작업 상태가 바뀌었으면 거절됩니다. | |
| data | object | 제출 대상 확인 결과 묶음입니다. 변환이 끝나 제출할 수 있는 상태(`22`)에서만 만들 수 있고, 제출 대상이 없거나 상태가 맞지 않으면 이 모양이 아니라 오류로 끝납니다. | |
| data. | array | 제출 대상 목록입니다. 기관이 알려 준 행을 모든 쪽에서 이어 붙여 그대로 담고, 행의 칸은 기관이 정합니다. 제출 단계는 이 목록이 확인할 때와 같을 때만 진행합니다. | |
| warnings | array | 경고 문장의 목록입니다. 이 상품은 경고를 싣지 않아 항상 빈 배열입니다. |
// result.data - 값 자리에는 각 칸의 형식을 적었습니다 (실제 값이 아닙니다)
{
"success": "<boolean>",
"step": "<string>",
"state": "<string>",
"snapshot": {},
"snapshot_hash": "<string>",
"data": {
"targets": []
},
"warnings": []
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| VALIDATION_ | 요청 칸이 빠졌거나 칸 값이 이 단계의 요청 형식에 맞지 않으면 홈택스에 아무것도 보내지 않고 이 오류로 끝납니다. error.message 는 「파일변환 요청 값이 올바르지 않습니다(확인할 항목: 칸 경로). 준비자료 안내에서 이 단계에 넣을 값을 확인한 뒤 다시 요청해 주세요.」 꼴입니다. 칸 경로 자리에는 걸린 칸의 위치를 점으로 이은 경로가 다섯까지 쉼표로 이어지고 더 있으면 끝에 「외」 가 붙으며, 칸 하나를 짚지 않고 요청 전체를 보는 검사에 걸리면 그 자리에 「요청 본문」 이 들어갑니다. | |
| RESOURCE_ | 이어 받을 이전 작업(source_job_id)이 같은 조직과 환경에서 성공한 이 신고 유형의 작업이 아니거나, 그 결과를 읽을 수 없거나, 결과에 작성 스냅샷이 없거나 스냅샷이 expected_snapshot_hash 와 다르면 홈택스에 보내기 전에 이 오류로 끝납니다. error.message 는 걸린 확인의 문장 하나이고, BE 문장은 「같은 조직·환경에서 성공한 이전 단계의 작업이 필요합니다」, 「이전 작업의 JSON 결과를 읽을 수 없습니다」, 「이 신고 유형에서 성공한 이전 단계 작업이 필요합니다」, 「이전 작업의 작성 스냅샷이 없습니다」, 「작성 내용이 바뀌었습니다. 최신 결과를 다시 확인해 주세요」 입니다. | |
| RESOURCE_ | 작업 상태나 이어 받은 내용이 이 단계와 맞지 않으면 이 오류로 끝납니다. 이 단계에서 이 코드로 끝나는 확인의 BE 문장은 「홈택스에서 새 변환 작업을 확인하지 못했습니다. 업로드를 반복하지 말고 진행현황을 확인해 주세요」, 「다른 변환 작업으로 바뀌었습니다. 재전송하지 말고 진행현황을 확인해 주세요」, 「제출 가능한 변환 결과가 없습니다」, 「정상 변환된 제출 대상이 없습니다」 이고, 걸린 확인의 문장 하나가 error.message 로 실립니다. | |
| AUTH_ | 저장된 기관 세션이 없습니다. 같은 연동 계정으로 hometax.session.login 을 먼저 실행해 세션을 연 뒤 다시 보냅니다. |
48. 원천세 전자파일 변환신고 접수증 조회hometax. tax. withholding. file_ conversion. receipt
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 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| source_ | string | Y | 이어서 진행할 이전 단계 작업의 job_id 를 그대로 입력합니다(job_ 으로 시작하는 작업 번호). 접수 결과를 찾을 변환 작업의 결과입니다. 작업 상태는 묻지 않으므로 제출(submit) 결과나, 제출 결과를 확인하지 못했을 때는 미리보기(preview) 결과를 입력합니다. 같은 조직과 환경, 같은 기관 연결에서 성공한 원천세 파일변환 작업이어야 하고 아니면 진행하지 않고 거절합니다 | |
| expected_ | string | Y | source_job_id 작업 결과의 snapshot_hash 를 그대로 입력합니다(소문자 16진수 64자리). 그 작업의 내용과 맞지 않으면 진행하지 않고 작성 내용이 바뀌었다는 오류(409)로 거절합니다 |
- 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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: receipt-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "hometax",
"action": "hometax.tax.withholding.file_conversion.receipt",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {
"source_job_id": "<필수>",
"expected_snapshot_hash": "<필수>"
}
}'Response
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| success | boolean | 단계가 끝났는지입니다. 응답으로 돌아왔다면 항상 true 입니다. 실패는 이 모양이 아니라 오류 응답으로 옵니다. | |
| step | string | 응답이 어느 단계의 결과인지입니다. 이 액션은 항상 `receipt` 입니다. | |
| state | string | 이 단계가 끝난 뒤 작업이 놓인 상태입니다. 항상 `receipt`(접수번호를 확인한 상태) 입니다. | |
| snapshot | object | 이 단계가 끝난 작업 상태의 사본입니다. 다음 단계가 이어받는 값이라 직접 고치지 않습니다. | |
| snapshot_ | string | snapshot 의 해시(SHA-256, 16진수 64자)입니다. 다음 단계를 부를 때 expected_snapshot_hash 에 그대로 넣고, 이 작업의 job_id 는 source_job_id 에 넣습니다. 그 사이 작업 상태가 바뀌었으면 거절됩니다. | |
| data | object | 접수증 조회 결과 묶음입니다. 접수번호를 확인하지 못하면 이 모양이 아니라 오류로 끝납니다. | |
| data. | array | 접수내역 목록입니다. 행마다 접수번호(rcatNo)가 있고, 나머지 칸은 기관이 정합니다. | |
| warnings | array | 경고 문장의 목록입니다. 이 상품은 경고를 싣지 않아 항상 빈 배열입니다. |
// result.data - 값 자리에는 각 칸의 형식을 적었습니다 (실제 값이 아닙니다)
{
"success": "<boolean>",
"step": "<string>",
"state": "<string>",
"snapshot": {},
"snapshot_hash": "<string>",
"data": {
"receipt": []
},
"warnings": []
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| VALIDATION_ | 요청 칸이 빠졌거나 칸 값이 이 단계의 요청 형식에 맞지 않으면 홈택스에 아무것도 보내지 않고 이 오류로 끝납니다. error.message 는 「파일변환 요청 값이 올바르지 않습니다(확인할 항목: 칸 경로). 준비자료 안내에서 이 단계에 넣을 값을 확인한 뒤 다시 요청해 주세요.」 꼴입니다. 칸 경로 자리에는 걸린 칸의 위치를 점으로 이은 경로가 다섯까지 쉼표로 이어지고 더 있으면 끝에 「외」 가 붙으며, 칸 하나를 짚지 않고 요청 전체를 보는 검사에 걸리면 그 자리에 「요청 본문」 이 들어갑니다. | |
| RESOURCE_ | 이어 받을 이전 작업(source_job_id)이 같은 조직과 환경에서 성공한 이 신고 유형의 작업이 아니거나, 그 결과를 읽을 수 없거나, 결과에 작성 스냅샷이 없거나 스냅샷이 expected_snapshot_hash 와 다르면 홈택스에 보내기 전에 이 오류로 끝납니다. error.message 는 걸린 확인의 문장 하나이고, BE 문장은 「같은 조직·환경에서 성공한 이전 단계의 작업이 필요합니다」, 「이전 작업의 JSON 결과를 읽을 수 없습니다」, 「이 신고 유형에서 성공한 이전 단계 작업이 필요합니다」, 「이전 작업의 작성 스냅샷이 없습니다」, 「작성 내용이 바뀌었습니다. 최신 결과를 다시 확인해 주세요」 입니다. | |
| RESOURCE_ | 작업 상태나 이어 받은 내용이 이 단계와 맞지 않으면 이 오류로 끝납니다. 이 단계에서 이 코드로 끝나는 확인의 BE 문장은 「파일 제출 작업 식별자가 없습니다」, 「접수번호를 확인하지 못했습니다. 다시 제출하지 마세요」, 「접수 전체 건수를 확인할 기관 페이지 정보가 필요합니다. 다시 제출하지 마세요」 이고, 걸린 확인의 문장 하나가 error.message 로 실립니다. | |
| AUTH_ | 저장된 기관 세션이 없습니다. 같은 연동 계정으로 hometax.session.login 을 먼저 실행해 세션을 연 뒤 다시 보냅니다. |
49. 원천세 전자파일 변환신고 준비자료 안내hometax. tax. withholding. file_ conversion. requirements
MCP 도구 이름 hometax__
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
원천세 전자파일 변환신고에 필요한 입력과 준비자료를 단계별로 알려 드립니다. 기관에 접속하지 않습니다.
- 이 API 는 기관 연동과 기관 로그인이 필요 없습니다. 기관 자격증명을 등록하지 않아도 호출할 수 있고, 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 | 호출할 작업입니다.
| |
| 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: requirements-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "hometax",
"action": "hometax.tax.withholding.file_conversion.requirements",
"params": {}
}'Response
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| success | boolean | 단계가 끝났는지입니다. 응답으로 돌아왔다면 항상 true 입니다. 실패는 이 모양이 아니라 오류 응답으로 옵니다. | |
| step | string | 응답이 어느 단계의 결과인지입니다. 이 액션은 항상 `requirements` 입니다. | |
| data | object | 필요입력 안내 묶음입니다. 기관에 가지 않고 이 신고의 요청 계약에서 바로 만들며, 저장이나 제출은 일어나지 않습니다. | |
| data. | array | 단계마다 받아야 하는 입력의 목록입니다. 이 신고의 모든 단계(액션)의 요청 계약에서 입력 칸마다 한 줄씩 만듭니다. 안쪽 칸을 가진 객체 입력은 안쪽 칸마다 한 줄이고, 그 key 는 점으로 이은 경로입니다. | |
| data. | string | 이 입력을 받는 단계의 이름입니다. 단계 이름은 actions 의 키와 같습니다. | |
| data. | string | 입력 칸의 이름입니다. 요청 본문에 이 이름으로 보냅니다. 안쪽 칸이면 `상위.하위` 꼴입니다. | |
| data. | string | 입력 칸의 한국어 이름입니다. | |
| data. | string | 입력을 누가 채우는지 구분입니다. `institution` 또는 `customer` 중 하나입니다. 앞의 값은 사업자 정보처럼 기관 조회로 확인하는 칸이고 뒤의 값은 고객이 정하는 칸입니다. | |
| data. | boolean | 꼭 보내야 하는 입력인지입니다. 안쪽 칸은 바깥 객체와 안쪽 칸이 모두 필수일 때만 true 입니다. | |
| data. | string | 입력 값의 종류입니다. `string` 또는 `choice` 또는 `number` 또는 `date` 또는 `array` 또는 `object` 또는 `file` 중 하나입니다. `choice` 는 true 나 false 같은 정해진 선택지 중 하나를 뜻합니다. | |
| data. | null | 이미 채워 둔 값입니다. 이 안내는 값을 채우지 않아 항상 null 입니다. | |
| data. | array | 고를 수 있는 값의 목록입니다. 선택지가 정해진 입력에만 있고 아니면 빈 배열입니다. | |
| data. | boolean | 이 입력에 별도 동의가 필요한지입니다. 이 안내는 항상 false 로 돌려줍니다. | |
| data. | string | 입력 값의 출처 문구입니다. `기관 조회` 또는 `사용자 입력` 중 하나입니다. 앞의 값은 tier 가 기관 조회로 확인하는 칸일 때 쓰입니다. | |
| data. | string | 이 입력을 어떻게 채우는지 알리는 한국어 안내 문장입니다. | |
| data. | boolean | 이 입력이 없으면 진행이 막히는지입니다. required 와 같은 값입니다. | |
| data. | boolean | 채워야 하는데 비어 있는 입력이 있는지입니다. blocking_reasons 가 하나라도 있으면 true 입니다. 이 안내는 값을 채우지 않아 필수 입력이 있으면 항상 true 입니다. | |
| data. | array | 진행을 막는 입력마다 한 줄씩 담은 목록입니다. 필수이면서 채워 둔 값이 없는 입력이 대상입니다. | |
| data. | string | 막힌 입력을 받는 단계의 이름입니다. | |
| data. | string | 막힌 입력의 이름입니다. inputs 의 key 와 같습니다. | |
| data. | string | 막힌 까닭을 알리는 한국어 문장입니다. 입력 이름 뒤에 「입력이 필요합니다.」 가 붙는 꼴입니다. | |
| data. | object | 이 안내가 아무것도 실행하지 않았다는 표시 묶음입니다. | |
| data. | boolean | 이 안내가 입력 설명만 한다는 표시입니다. 항상 true 입니다. | |
| data. | boolean | 기관에 저장을 실행했는지입니다. 이 안내는 저장하지 않아 항상 false 입니다. | |
| data. | boolean | 기관에 제출을 실행했는지입니다. 이 안내는 제출하지 않아 항상 false 입니다. | |
| data. | string | 신고 가족 이름입니다. 이 액션은 항상 `file_conversion` 입니다. | |
| data. | string | 신고 상세 구분 코드입니다. 이 액션은 항상 `04` 입니다. | |
| data. | object | 단계(액션)마다 요청 본문의 JSON 스키마를 담은 객체입니다. 단계 이름이 키이고, 값은 그 단계가 받는 요청 본문의 스키마입니다. | |
| data. | string | 기관에 보내는 신고서 작성 방식 코드입니다. 이 신고는 항상 `03` 입니다. | |
| data. | string | 기관 변환 작업의 종류 코드입니다. 이 신고는 항상 `FF000` 입니다. | |
| data. | string | 원본을 기관으로 올릴 때 쓰는 전송 설정의 이름입니다. 항상 `rn/rnBatch` 입니다. | |
| data. | object | 원본 파일을 먼저 등록하는 REST 요청의 모양입니다. 원본 파일은 단계의 요청 본문(JSON)에 담아 보낼 수 없어서, 이 요청으로 등록해 받은 파일 정보를 원본 올리기 단계의 file 로 넘깁니다. 원본 한 건은 20 MiB 까지 보낼 수 있고, 변환 작업 하나에 등록할 수 있는 원본은 4개까지입니다. 기관이 받는 파일 크기의 범위는 시작 단계 결과의 snapshot 에 담긴 upload_limits 를 따르며, 그 범위를 벗어나면 원본 올리기 단계가 멈춥니다. 파일 형식을 미리 걸러 주는 허용 목록은 없고, 기관의 형식검증 단계가 가립니다. 등록에 성공하면 응답 상태 코드는 201 입니다. 등록이 거절되면 응답 상태 코드는 본문 형식이 octet-stream 이 아닐 때 415, 크기가 한도를 넘을 때 413, 본문이 비었거나 파일 이름이 맞지 않을 때 422, 시작 단계 결과가 아니거나(`HOMETAX_WITHHOLDING_SOURCE_JOB_INVALID`) 원본 수가 한도를 넘을 때(`HOMETAX_WITHHOLDING_FILE_INPUT_LIMIT`) 또는 시작 단계 뒤 작성 내용이 바뀌어 expected_snapshot_hash 가 맞지 않을 때(`HOMETAX_WITHHOLDING_SNAPSHOT_CHANGED`) 409, 다른 조직이나 환경, 기관 연결에서 만든 시작 단계 결과일 때(`HOMETAX_WITHHOLDING_SCOPE_MISMATCH`) 403, 원천세 파일변환 쓰기가 잠시 막혀 있을 때(`HOMETAX_WITHHOLDING_FILE_CONVERSION_WRITE_DISABLED`) 503, 저장에 실패했을 때 503 입니다. | |
| data. | string | 등록 요청의 HTTP 메서드입니다. 항상 `POST` 입니다. | |
| data. | string | 등록 요청의 경로입니다. `/v1/hometax/withholding/file-conversion/{source_job_id}/original` 이고, 경로의 source_job_id 자리에는 시작 단계 결과의 job_id 를 넣습니다. | |
| data. | string | 등록 요청 본문의 형식입니다. 항상 `application/octet-stream` 이고, 본문은 원본 파일의 바이트 그대로입니다. | |
| data. | array | 등록 요청의 쿼리 인자 이름 목록입니다. `account_link_id`, `expected_snapshot_hash`, `filename` 가 들어 있고 모두 필수입니다. account_link_id 는 시작 단계를 부른 것과 같은 기관 연결의 ID 이고, expected_snapshot_hash 는 시작 단계 결과의 snapshot_hash(소문자 16진수 64자)이며, filename 은 기관에 전달할 원본 파일 이름으로 원본 올리기 단계의 file 에 적는 filename 과 같은 규칙을 따릅니다. | |
| data. | string | 등록 요청이 돌려주는 칸의 이름입니다. 항상 `file` 입니다. 그 안의 file_job_id, filename, sha256 을 원본 올리기 단계의 file 로 그대로 넘깁니다. 등록에 성공하면 이 칸 옆에 `size_bytes`, `expires_at` 도 함께 돌아옵니다. | |
| data. | boolean | 이 안내가 기관을 불렀는지입니다. 안내는 기관에 가지 않아 항상 false 입니다. | |
| data. | array | 기관에서 아직 동작을 확인하지 못한 쓰기 단계의 이름 목록입니다. |
// result.data - 값 자리에는 각 칸의 형식을 적었습니다 (실제 값이 아닙니다)
{
"success": "<boolean>",
"step": "<string>",
"data": {
"inputs": [
{
"action": "<string>",
"key": "<string>",
"label_ko": "<string>",
"tier": "<string>",
"required": "<boolean>",
"value_type": "<string>",
"provided_value": null,
"options": [],
"consent_required": "<boolean>",
"source": "<string>",
"how_to_ko": "<string>",
"blocks_progress": "<boolean>"
}
],
"blocked": "<boolean>",
"blocking_reasons": [
{
"action": "<string>",
"key": "<string>",
"reason_ko": "<string>"
}
],
"safety": {
"input_only": "<boolean>",
"save_executed": "<boolean>",
"submit_executed": "<boolean>"
},
"family": "<string>",
"detail_code": "<string>",
"schemas": {},
"method": "<string>",
"cva_kind": "<string>",
"upload_profile": "<string>",
"original_registration": {
"method": "<string>",
"path": "<string>",
"content_type": "<string>",
"query": [],
"returns": "<string>"
},
"institution_called": "<boolean>",
"unmeasured_steps": []
}
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| VALIDATION_ | 요청 칸이 빠졌거나 칸 값이 이 단계의 요청 형식에 맞지 않으면 홈택스에 아무것도 보내지 않고 이 오류로 끝납니다. error.message 는 「파일변환 요청 값이 올바르지 않습니다(확인할 항목: 칸 경로). 준비자료 안내에서 이 단계에 넣을 값을 확인한 뒤 다시 요청해 주세요.」 꼴입니다. 칸 경로 자리에는 걸린 칸의 위치를 점으로 이은 경로가 다섯까지 쉼표로 이어지고 더 있으면 끝에 「외」 가 붙으며, 칸 하나를 짚지 않고 요청 전체를 보는 검사에 걸리면 그 자리에 「요청 본문」 이 들어갑니다. |
50. 원천세 전자파일 변환신고 진행현황 조회hometax. tax. withholding. file_ conversion. status
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 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| source_ | string | Y | 이어서 진행할 이전 단계 작업의 job_id 를 그대로 입력합니다(job_ 으로 시작하는 작업 번호). 이 신고의 변환 작업을 거친 이전 단계 결과를 받습니다. 같은 조직과 환경, 같은 기관 연결에서 성공한 원천세 파일변환 작업이어야 하고 아니면 진행하지 않고 거절합니다 | |
| expected_ | string | Y | source_job_id 작업 결과의 snapshot_hash 를 그대로 입력합니다(소문자 16진수 64자리). 그 작업의 내용과 맞지 않으면 진행하지 않고 작성 내용이 바뀌었다는 오류(409)로 거절합니다 | |
| view | string | N | 무엇을 조회할지 고르는 값입니다. summary(진행 요약, 기본값), format_errors(형식검증 오류 목록), format_error_detail(형식검증 오류 한 건의 상세), content_errors(내용검증 오류), warnings(내용검증 경고) 가운데 하나이며 입력하지 않으면 summary 입니다. 어느 종류도 기관에 저장하거나 제출하지 않고 읽기만 하며, 모르는 값은 입력 오류로 거절합니다 | |
| format_ | string | N | view 가 format_error_detail 일 때 형식검증 오류 목록(format_errors)에서 한 행을 고르는 값입니다. 목록에 행이 하나뿐이면 입력하지 않아도 되고, 고른 값으로 한 행이 정해지지 않으면 409 로 거절합니다. 1자 이상 50자 이하이고 형식검증 오류 목록 행의 rowNum 값입니다 | |
| orc_ | string | N | view 가 format_error_detail 일 때 형식검증 오류 목록(format_errors)에서 한 행을 고르는 값입니다. 목록에 행이 하나뿐이면 입력하지 않아도 되고, 고른 값으로 한 행이 정해지지 않으면 409 로 거절합니다. 1자 이상 100자 이하이고 형식검증 오류 목록 행의 orcFleRcvnSn 값입니다 | |
| trns_ | string | N | view 가 format_error_detail 일 때 형식검증 오류 목록(format_errors)에서 한 행을 고르는 값입니다. 목록에 행이 하나뿐이면 입력하지 않아도 되고, 고른 값으로 한 행이 정해지지 않으면 409 로 거절합니다. 1자 이상 100자 이하이고 형식검증 오류 목록 행의 trnsFleSn 값입니다 |
- 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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: status-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "hometax",
"action": "hometax.tax.withholding.file_conversion.status",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {
"source_job_id": "<필수>",
"expected_snapshot_hash": "<필수>"
}
}'Response
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| success | boolean | 단계가 끝났는지입니다. 응답으로 돌아왔다면 항상 true 입니다. 실패는 이 모양이 아니라 오류 응답으로 옵니다. | |
| step | string | 응답이 어느 단계의 결과인지입니다. 이 액션은 항상 `status` 입니다. | |
| state | string | 이 단계가 끝난 뒤 작업이 놓인 상태입니다. 기관의 변환 진행 상태 코드이고 다음 중 하나입니다. `00`(진행 중인 검증이 없는 처음 상태), `10`(형식검증 진행 중), `11`(형식검증이 끝났고 오류만 있어 내용검증할 자료가 없음), `12`(형식검증이 끝났고 내용검증을 시작할 수 있음), `20`(내용검증 진행 중), `21`(내용검증이 끝났고 오류만 있어 제출할 자료가 없음), `22`(내용검증이 끝났고 제출 대상이 있음), `23`(내용검증 대상 건수가 한도를 넘어 내용검증이 취소됨). | |
| snapshot | object | 이 단계가 끝난 작업 상태의 사본입니다. 다음 단계가 이어받는 값이라 직접 고치지 않습니다. | |
| snapshot_ | string | snapshot 의 해시(SHA-256, 16진수 64자)입니다. 다음 단계를 부를 때 expected_snapshot_hash 에 그대로 넣고, 이 작업의 job_id 는 source_job_id 에 넣습니다. 그 사이 작업 상태가 바뀌었으면 거절됩니다. | |
| data | object | 진행현황 결과 묶음입니다. 요청한 보기(view)에 따라 담기는 칸이 다릅니다. summary(기본)는 status 만, format_errors 는 view, status, items, format_error_detail 은 view, status, items, selected, content_errors 와 warnings 는 view, items, page_count 입니다. | |
| data. | string | 요청한 보기의 이름입니다. summary 가 아닌 보기를 요청했을 때만 있고 요청한 값과 같습니다. 보기는 `summary`, `format_errors`, `format_error_detail`, `content_errors`, `warnings` 가운데 하나입니다. | |
| data. | object | 기관이 알려 준 응답 묶음 그대로입니다. summary 에서는 변환 진행 상태이고 format_errors 와 format_error_detail 에서는 형식검증 오류를 조회한 응답입니다. 안쪽 칸은 기관이 정합니다. | |
| data. | array | 오류나 경고의 목록입니다. format_errors 는 형식검증 오류 행, format_error_detail 은 고른 오류의 상세 행, content_errors 는 내용검증 오류 행, warnings 는 경고와 안내 행입니다. 쪽이 여럿이면 모두 이어 붙여 담고, 행의 칸은 기관이 정합니다. summary 에서는 없습니다. | |
| data. | object | 형식 오류 상세 보기(format_error_detail)에서 상세를 읽은 오류 행입니다. 요청의 format_error_row_num, orc_fle_rcvn_sn, trns_fle_sn 으로 고른 행이고, 고르지 않았을 때는 오류 행이 하나뿐일 때만 그 행입니다. 다른 보기에서는 없습니다. | |
| data. | number | items 의 전체 건수입니다. 기관이 알려 준 건수와 모아 온 행 수가 같을 때만 성공으로 칩니다. content_errors 와 warnings 에서만 있습니다. | |
| warnings | array | 경고 문장의 목록입니다. 이 상품은 경고를 싣지 않아 항상 빈 배열입니다. |
// result.data - 값 자리에는 각 칸의 형식을 적었습니다 (실제 값이 아닙니다)
{
"success": "<boolean>",
"step": "<string>",
"state": "<string>",
"snapshot": {},
"snapshot_hash": "<string>",
"data": {
"view": "<string>",
"status": {},
"items": [],
"selected": {},
"page_count": "<number>"
},
"warnings": []
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| VALIDATION_ | 요청 칸이 빠졌거나 칸 값이 이 단계의 요청 형식에 맞지 않으면 홈택스에 아무것도 보내지 않고 이 오류로 끝납니다. error.message 는 「파일변환 요청 값이 올바르지 않습니다(확인할 항목: 칸 경로). 준비자료 안내에서 이 단계에 넣을 값을 확인한 뒤 다시 요청해 주세요.」 꼴입니다. 칸 경로 자리에는 걸린 칸의 위치를 점으로 이은 경로가 다섯까지 쉼표로 이어지고 더 있으면 끝에 「외」 가 붙으며, 칸 하나를 짚지 않고 요청 전체를 보는 검사에 걸리면 그 자리에 「요청 본문」 이 들어갑니다. | |
| RESOURCE_ | 이어 받을 이전 작업(source_job_id)이 같은 조직과 환경에서 성공한 이 신고 유형의 작업이 아니거나, 그 결과를 읽을 수 없거나, 결과에 작성 스냅샷이 없거나 스냅샷이 expected_snapshot_hash 와 다르면 홈택스에 보내기 전에 이 오류로 끝납니다. error.message 는 걸린 확인의 문장 하나이고, BE 문장은 「같은 조직·환경에서 성공한 이전 단계의 작업이 필요합니다」, 「이전 작업의 JSON 결과를 읽을 수 없습니다」, 「이 신고 유형에서 성공한 이전 단계 작업이 필요합니다」, 「이전 작업의 작성 스냅샷이 없습니다」, 「작성 내용이 바뀌었습니다. 최신 결과를 다시 확인해 주세요」 입니다. | |
| RESOURCE_ | 작업 상태나 이어 받은 내용이 이 단계와 맞지 않으면 이 오류로 끝납니다. 이 단계에서 이 코드로 끝나는 확인의 BE 문장은 「홈택스에서 새 변환 작업을 확인하지 못했습니다. 업로드를 반복하지 말고 진행현황을 확인해 주세요」, 「다른 변환 작업으로 바뀌었습니다. 재전송하지 말고 진행현황을 확인해 주세요」, 「파일 제출 작업 식별자가 없습니다」, 「형식검증 상세는 현재 오류 목록의 단일 행을 선택해야 합니다」, 「선택한 오류 행의 기관 식별자가 없습니다」 이고, 걸린 확인의 문장 하나가 error.message 로 실립니다. | |
| AUTH_ | 저장된 기관 세션이 없습니다. 같은 연동 계정으로 hometax.session.login 을 먼저 실행해 세션을 연 뒤 다시 보냅니다. |
51. 원천세 전자파일 변환신고 제출hometax. tax. withholding. file_ conversion. submit
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 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| source_ | string | Y | 이어서 진행할 이전 단계 작업의 job_id 를 그대로 입력합니다(job_ 으로 시작하는 작업 번호). 미리보기(preview) 결과를 받습니다. 미리보기를 거치지 않았거나 그 뒤 제출 대상이 바뀌었으면 409 로 거절합니다. 같은 조직과 환경, 같은 기관 연결에서 성공한 원천세 파일변환 작업이어야 하고 아니면 진행하지 않고 거절합니다 | |
| expected_ | string | Y | source_job_id 작업 결과의 snapshot_hash 를 그대로 입력합니다(소문자 16진수 64자리). 그 작업의 내용과 맞지 않으면 진행하지 않고 작성 내용이 바뀌었다는 오류(409)로 거절합니다 | |
| confirm_ | boolean | Y | 변환신고서를 실제로 제출한다는 확인값입니다. 미리보기(preview) 결과를 사용자에게 보여 주고 제출 동의를 받았을 때 true 로 입력합니다. true 가 아니면(빠지거나 false) 기관에 아무것도 보내지 않고 신고서 제출 확인이 필요하다는 오류(422)로 거절합니다. 이 값도 확인 토큰이 가리키는 요청 본문에 들어가므로 확인 토큰을 받는 첫 요청부터 함께 입력합니다. 나중에 더하면 본문이 달라져 확인 토큰을 다시 받아야 합니다. 1 이나 yes, on 처럼 true 로 읽히는 값도 true 로 받고, true 나 false 로 읽을 수 없는 값은 입력 오류로 거절합니다 | |
| sbms_ | boolean | Y | 신고 내용에 동의한다는 확인값입니다. 요청 규격에 필수 칸으로 적혀 있으므로 사용자에게 동의를 받아 true 로 입력합니다. 원천세 변환신고는 이 값이 true 가 아니어도 제출을 거절하지 않고, 기관에 보내지 않으며 응답의 submitUserAcknowledgements 에 받은 값을 돌려줍니다. 이 값도 확인 토큰이 가리키는 요청 본문에 들어가므로 확인 토큰을 받는 첫 요청부터 함께 입력합니다. 나중에 더하면 본문이 달라져 확인 토큰을 다시 받아야 합니다. 1 이나 yes, on 처럼 true 로 읽히는 값도 true 로 받고, true 나 false 로 읽을 수 없는 값은 입력 오류로 거절합니다 | |
| confirm_ | boolean | N | 내용검증 경고를 확인했다는 값입니다. 내용검증에서 경고가 나온 변환은 이 값이 true 여야 제출하고, 아니면 기관에 아무것도 보내지 않고 내용검증 경고를 확인해 달라는 오류(409)로 거절합니다. 경고가 없는 변환에는 필요 없습니다. 이 값도 확인 토큰이 가리키는 요청 본문에 들어가므로 확인 토큰을 받는 첫 요청부터 함께 입력합니다. 나중에 더하면 본문이 달라져 확인 토큰을 다시 받아야 합니다. 1 이나 yes, on 처럼 true 로 읽히는 값도 true 로 받고, true 나 false 로 읽을 수 없는 값은 입력 오류로 거절합니다 | |
| confirmation_ | string | N | 1회용 확인 토큰입니다. 처음에는 보내지 않습니다. 토큰 없이 부르면 기관에 아무것도 보내지 않고 작업도 만들지 않은 채 확인이 필요하다는 오류(WRITE_CONFIRMATION_REQUIRED)로 끝나고, 응답의 error.confirmation_token 에 토큰이 옵니다. error.message 의 안내를 사용자에게 보여 주고 동의를 받은 뒤 같은 요청에 이 토큰을 넣어 다시 부릅니다. 토큰은 10분 안에 한 번만 쓸 수 있고 처음 요청과 같은 본문, 같은 호출자, 같은 환경에서만 맞으며, 아니면 확인이 만료됐거나 내용이 달라졌다는 오류로 거절합니다 |
- 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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: submit-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "hometax",
"action": "hometax.tax.withholding.file_conversion.submit",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {
"source_job_id": "<필수>",
"expected_snapshot_hash": "<필수>",
"confirm_submit": "<필수: boolean>",
"sbms_agreement": "<필수: boolean>"
}
}'Response
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| success | boolean | 단계가 끝났는지입니다. 응답으로 돌아왔다면 항상 true 입니다. 실패는 이 모양이 아니라 오류 응답으로 옵니다. | |
| step | string | 응답이 어느 단계의 결과인지입니다. 이 액션은 항상 `submit` 입니다. | |
| state | string | 이 단계가 끝난 뒤 작업이 놓인 상태입니다. `submitted`(제출을 마친 상태) 이거나, 이미 접수된 작업을 다시 제출했을 때 `receipt`(접수번호를 확인한 상태) 입니다. | |
| snapshot | object | 이 단계가 끝난 작업 상태의 사본입니다. 다음 단계가 이어받는 값이라 직접 고치지 않습니다. | |
| snapshot_ | string | snapshot 의 해시(SHA-256, 16진수 64자)입니다. 다음 단계를 부를 때 expected_snapshot_hash 에 그대로 넣고, 이 작업의 job_id 는 source_job_id 에 넣습니다. 그 사이 작업 상태가 바뀌었으면 거절됩니다. | |
| data | object | 제출 결과 묶음입니다. 기관에 제출하고 접수번호를 확인한 결과를 담습니다. 접수번호를 확인하지 못하면 이 모양이 아니라 오류로 끝나며, 이때는 다시 제출하지 말고 접수내역을 먼저 확인해야 합니다. | |
| data. | boolean | 이미 접수가 끝난 작업을 다시 제출했을 때만 있고 항상 true 입니다. 이때는 기관에 다시 제출하지 않고 접수내역만 돌려줍니다. | |
| data. | array | 이미 접수가 끝난 작업을 다시 제출했을 때만 있습니다. 제출 시점에 읽은 제출 대상 목록이고, 행의 칸은 기관이 정합니다. | |
| data. | array | 접수내역 목록입니다. 행마다 접수번호(rcatNo)가 있고, 나머지 칸은 기관이 정합니다. | |
| data. | array | 제출 직후 다시 읽은 제출 대상 목록입니다. 모든 행이 이 작업에 속하고 접수가 끝난 상태(rtnPrgrSttnCd 가 10)이며 접수내역과 행 수가 같을 때만 성공으로 칩니다. | |
| data. | object | 제출 때 받은 고객 확인을 기록한 묶음입니다. 기관에 보내는 값이 아니라 응답에만 싣는 정보입니다. | |
| data. | boolean | 제출 확인(confirm_submit)을 받았는지입니다. 확인이 없으면 제출 전에 거절되므로 응답으로 돌아왔다면 항상 true 입니다. | |
| data. | boolean | 신고 내용 동의(sbms_agreement)를 보냈는지입니다. 이 신고는 동의가 필요하지 않아 보내지 않으면 false 입니다. | |
| data. | boolean | 이 신고에서 신고 내용 동의가 필요한지입니다. 이 신고는 항상 false 입니다. | |
| data. | boolean | 동의 값이 기관에 보내는 제출 본문에 들어가는지입니다. 항상 false 입니다. | |
| data. | boolean | 내용검증 경고를 확인했다는 값(confirm_warnings)을 보냈는지입니다. 경고가 있는 작업을 제출하려면 true 여야 합니다. | |
| data. | string | 기관 쓰기가 확인됐는지를 가르는 판정입니다. 봉투 바깥의 outcome 과 같은 값이고, 응답으로 돌아왔다면 항상 `confirmed` 입니다. | |
| data. | string | 쓰기 액션의 이름입니다. 봉투 바깥의 action 과 같은 값이고, 이 액션은 항상 `hometax.tax.withholding.file_conversion.submit` 입니다. | |
| warnings | array | 경고 문장의 목록입니다. 이 상품은 경고를 싣지 않아 항상 빈 배열입니다. | |
| outcome | string | 기관 쓰기가 확인됐는지를 가르는 판정입니다. 응답으로 돌아왔다면 항상 `confirmed` 입니다. 결과를 확인하지 못한 경우는 이 모양이 아니라 오류로 끝납니다. 작업 결과 판정이 이 자리를 읽습니다. | |
| action | string | 쓰기 액션의 이름입니다. 이 액션은 항상 `hometax.tax.withholding.file_conversion.submit` 입니다. 작업 결과 판정이 이 자리를 읽습니다. |
// result.data - 값 자리에는 각 칸의 형식을 적었습니다 (실제 값이 아닙니다)
{
"success": "<boolean>",
"step": "<string>",
"state": "<string>",
"snapshot": {},
"snapshot_hash": "<string>",
"data": {
"already_processed": "<boolean>",
"targets": [],
"receipt": [],
"post_submit_targets": [],
"submitUserAcknowledgements": {
"confirmSubmit": "<boolean>",
"sbmsAgreement": "<boolean>",
"sbmsAgreementRequired": "<boolean>",
"sbmsAgreementInSubmitBody": "<boolean>",
"confirmWarnings": "<boolean>"
},
"outcome": "<string>",
"action": "<string>"
},
"warnings": [],
"outcome": "<string>",
"action": "<string>"
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| WRITE_ | 요청에 확인 토큰(confirmation_token)이 없으면 홈택스에 아무것도 보내지 않고 작업도 만들지 않은 채 이 오류로 끝납니다. error.message 는 「원천세 전자파일 변환신고서 제출은 되돌릴 수 없어 제출 전 확인이 필요합니다. 아래 내용을 사용자에게 보여주고 동의를 받으세요.」 로 시작하고 error.confirmation_token 에 1회용 토큰이 옵니다. 이 단계의 확인에는 미리보기 내용이 없어 error.preview 는 빈 객체입니다. 이 내용을 고객에게 그대로 보여 주고 확인을 받은 뒤, 같은 요청의 params.confirmation_token 에 응답의 error.confirmation_token 값을 넣어 다시 호출해 주세요. 토큰은 10분 안에 한 번만 쓸 수 있고, 확인한 요청 본문과 같은 본문에만 맞습니다. | |
| WRITE_ | 토큰이 만료됐거나, 이미 썼거나, 다른 호출자나 다른 환경에서 받은 것이거나, 확인한 요청 본문과 달라졌으면 홈택스에 아무것도 보내지 않고 작업도 만들지 않은 채 이 오류로 끝납니다. error.message 는 「확인이 만료됐거나 확인한 내용과 달라졌습니다. 다시 확인해 주세요.」 입니다. 토큰 없이 다시 요청하면 새 토큰을 받습니다. | |
| VALIDATION_ | 요청 칸이 빠졌거나 칸 값이 이 단계의 요청 형식에 맞지 않으면 홈택스에 아무것도 보내지 않고 이 오류로 끝납니다. error.message 는 「파일변환 요청 값이 올바르지 않습니다(확인할 항목: 칸 경로). 준비자료 안내에서 이 단계에 넣을 값을 확인한 뒤 다시 요청해 주세요.」 꼴입니다. 칸 경로 자리에는 걸린 칸의 위치를 점으로 이은 경로가 다섯까지 쉼표로 이어지고 더 있으면 끝에 「외」 가 붙으며, 칸 하나를 짚지 않고 요청 전체를 보는 검사에 걸리면 그 자리에 「요청 본문」 이 들어갑니다. | |
| RESOURCE_ | 이어 받을 이전 작업(source_job_id)이 같은 조직과 환경에서 성공한 이 신고 유형의 작업이 아니거나, 그 결과를 읽을 수 없거나, 결과에 작성 스냅샷이 없거나 스냅샷이 expected_snapshot_hash 와 다르면 홈택스에 보내기 전에 이 오류로 끝납니다. error.message 는 걸린 확인의 문장 하나이고, BE 문장은 「같은 조직·환경에서 성공한 이전 단계의 작업이 필요합니다」, 「이전 작업의 JSON 결과를 읽을 수 없습니다」, 「이 신고 유형에서 성공한 이전 단계 작업이 필요합니다」, 「이전 작업의 작성 스냅샷이 없습니다」, 「작성 내용이 바뀌었습니다. 최신 결과를 다시 확인해 주세요」 입니다. | |
| RESOURCE_ | 작업 상태나 이어 받은 내용이 이 단계와 맞지 않으면 이 오류로 끝납니다. 이 단계에서 이 코드로 끝나는 확인의 BE 문장은 「최신 제출 대상을 먼저 확인해 주세요」, 「홈택스에서 새 변환 작업을 확인하지 못했습니다. 업로드를 반복하지 말고 진행현황을 확인해 주세요」, 「다른 변환 작업으로 바뀌었습니다. 재전송하지 말고 진행현황을 확인해 주세요」, 「기관 제출 가능 상태가 아닙니다」, 「제출 대상이 미리보기 이후 변경됐습니다」, 「기관 제출 대상의 진행상태를 확인하지 못했습니다. 다시 제출하지 마세요」, 「파일 제출 작업 식별자가 없습니다」, 「접수번호를 확인하지 못했습니다. 다시 제출하지 마세요」, 「접수 전체 건수를 확인할 기관 페이지 정보가 필요합니다. 다시 제출하지 마세요」, 「내용검증 경고를 확인해 주세요」 이고, 걸린 확인의 문장 하나가 error.message 로 실립니다. | |
| AUTH_ | 저장된 기관 세션이 없습니다. 같은 연동 계정으로 hometax.session.login 을 먼저 실행해 세션을 연 뒤 다시 보냅니다. | |
| PROVIDER_ | 제출 요청을 보내는 중이거나 보낸 뒤 홈택스의 접수 여부를 확인하지 못한 경우입니다. 자동으로 다시 시도하지 않습니다. error.message 는 「기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.」 입니다. |
52. 원천세 전자파일 변환신고 원본 올리기hometax. tax. withholding. file_ conversion. upload
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 와 함께 쓰지 않습니다. |
- 대괄호 []는 목록의 각 항목을, 점은 객체의 속성을, {key}는 실제 키로 바꿔 넣는 사전 항목을 뜻하며, 선택인 부모를 보낼 때 하위 필수 칸은 조건부로 표시합니다.
| 순번 | 변수명 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| source_ | string | Y | 이어서 진행할 이전 단계 작업의 job_id 를 그대로 입력합니다(job_ 으로 시작하는 작업 번호). 변환 초기화(init) 결과를 받습니다. 접수된 신고를 다시 올리는 재신고(restart_after_receipt_no)에는 그 기존 변환 작업의 결과를 받습니다. 같은 조직과 환경, 같은 기관 연결에서 성공한 원천세 파일변환 작업이어야 하고 아니면 진행하지 않고 거절합니다 | |
| expected_ | string | Y | source_job_id 작업 결과의 snapshot_hash 를 그대로 입력합니다(소문자 16진수 64자리). 그 작업의 내용과 맞지 않으면 진행하지 않고 작성 내용이 바뀌었다는 오류(409)로 거절합니다 | |
| file | object | Y | 올릴 원본 파일의 참조 객체입니다. 원본 등록 요청이 돌려준 file_job_id(job_ 으로 시작하는 작업 번호), sha256(소문자 16진수 64자리), filename(기관에 전달할 파일 이름)을 그대로 입력합니다. filename 은 1자 이상이고 UTF-8 로 100바이트 이하여야 하며 점 하나나 둘, 줄바꿈 같은 제어 문자, 슬래시와 역슬래시와 쌍점을 쓸 수 없습니다. 파일 내용은 요청에 담을 수 없고, 맞지 않으면 원본 참조가 필요하다는 입력 오류로 거절합니다. JSON 문자열이 아니라 객체로 입력하며 문자열이면 입력 오류로 거절합니다 | |
| file. | string | Y | 원본 등록 요청이 돌려준 작업 번호입니다(job_ 으로 시작). 그대로 입력합니다. 문자열 패턴: "^job_[0-9A-HJKMNP-TV-Z]{26}$" | |
| file. | string | Y | 원본 등록 요청이 돌려준 파일 확인값입니다(소문자 16진수 64자리). 그대로 입력합니다. 문자열 패턴: "^[0-9a-f]{64}$" | |
| file. | string | Y | 기관에 전달할 원본 파일 이름입니다. 1자 이상이고 UTF-8 로 100바이트 이하여야 하며, 점 하나나 둘, 줄바꿈 같은 제어 문자, 슬래시와 역슬래시와 쌍점을 쓸 수 없습니다. 맞지 않으면 입력 오류로 거절합니다. 최소 길이: 1. 최대 길이: 255 | |
| password | string | N | 원본 파일에 걸린 암호입니다. 1자 이상 200자 이하이며 암호가 없는 파일에는 입력하지 않습니다. 기관이 암호를 요구하면 이 단계의 결과 상태가 password_required 로 남고, 그때 형식검증(format_validate)에서 암호를 입력해 다시 요청합니다. 암호는 작업 결과에 저장하지 않습니다. 이 값은 params 에 입력하지 않고 encrypted_fields.password 에 공개키로 암호화해 입력합니다. params 에 입력하면 작업을 만들지 않고 400 VALIDATION_INVALID_FIELD 로 거절합니다 | |
| restart_ | string | N | 이미 접수된 정기신고(regular)를 새 파일로 다시 신고할 때 다시 신고할 기존 접수번호입니다. 숫자 10자리 이상 30자리 이하입니다. source_job_id 는 그 기존 변환 작업의 결과여야 하고, 변환이 끝난 상태이며 이 접수번호가 현재 기관의 변환 작업과 일치해야 합니다. 정기신고가 아니거나 상태나 접수번호가 맞지 않으면 409 로 거절합니다. 입력하지 않으면 기관에 진행 중인 변환 작업이 없을 때만 올릴 수 있고, 있으면 중복 업로드로 409 거절합니다 | |
| confirmation_ | string | N | 1회용 확인 토큰입니다. 처음에는 보내지 않습니다. 토큰 없이 부르면 기관에 아무것도 보내지 않고 작업도 만들지 않은 채 확인이 필요하다는 오류(WRITE_CONFIRMATION_REQUIRED)로 끝나고, 응답의 error.confirmation_token 에 토큰이 옵니다. error.message 의 안내를 사용자에게 보여 주고 동의를 받은 뒤 같은 요청에 이 토큰을 넣어 다시 부릅니다. 토큰은 10분 안에 한 번만 쓸 수 있고 처음 요청과 같은 본문, 같은 호출자, 같은 환경에서만 맞으며, 아니면 확인이 만료됐거나 내용이 달라졌다는 오류로 거절합니다 |
- 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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: upload-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "hometax",
"action": "hometax.tax.withholding.file_conversion.upload",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {
"source_job_id": "<필수>",
"expected_snapshot_hash": "<필수>",
"file": {
"file_job_id": "<필수>",
"sha256": "<필수>",
"filename": "<필수>"
}
}
}'Response
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| success | boolean | 단계가 끝났는지입니다. 응답으로 돌아왔다면 항상 true 입니다. 실패는 이 모양이 아니라 오류 응답으로 옵니다. | |
| step | string | 응답이 어느 단계의 결과인지입니다. 이 액션은 항상 `upload` 입니다. | |
| state | string | 이 단계가 끝난 뒤 작업이 놓인 상태입니다. 기관의 변환 진행 상태 코드 `00`(진행 중인 검증이 없는 처음 상태), `10`(형식검증 진행 중), `11`(형식검증이 끝났고 오류만 있어 내용검증할 자료가 없음), `12`(형식검증이 끝났고 내용검증을 시작할 수 있음), `20`(내용검증 진행 중), `21`(내용검증이 끝났고 오류만 있어 제출할 자료가 없음), `22`(내용검증이 끝났고 제출 대상이 있음), `23`(내용검증 대상 건수가 한도를 넘어 내용검증이 취소됨) 중 하나이거나, 파일에 비밀번호가 필요하면 `password_required`(파일에 비밀번호가 필요해 멈춘 상태, 비밀번호를 넣어 형식검증 단계를 다시 부름) 입니다. | |
| snapshot | object | 이 단계가 끝난 작업 상태의 사본입니다. 다음 단계가 이어받는 값이라 직접 고치지 않습니다. | |
| snapshot_ | string | snapshot 의 해시(SHA-256, 16진수 64자)입니다. 다음 단계를 부를 때 expected_snapshot_hash 에 그대로 넣고, 이 작업의 job_id 는 source_job_id 에 넣습니다. 그 사이 작업 상태가 바뀌었으면 거절됩니다. | |
| data | object | 원본 올리기 결과 묶음입니다. 올린 원본의 기관 저장 정보와, 이어서 한 형식검증 요청의 결과를 담습니다. 기관이 형식검증 요청을 받지 않으면 이 모양이 아니라 오류로 끝나며, 이때는 원본을 다시 올리지 말고 진행현황을 먼저 확인해야 합니다. | |
| data. | object | 기관이 원본을 저장한 뒤 돌려준 파일 정보 객체입니다. 저장 파일 목록(storedFileList), 파일 크기(fileSizeList), 원본 파일명(orcFleNm)이 들어 있고, 크기가 올린 원본의 바이트 수와 같을 때만 성공으로 칩니다. | |
| data. | string | 기관이 형식검증에 붙인 결과 코드입니다. 기관이 파일의 비밀번호를 요구해 멈췄을 때(상태가 `password_required`)만 있습니다. | |
| data. | string | 위 결과 코드에 기관이 붙인 안내 문장입니다. provider_code 와 함께 있고, 기관이 문장을 주지 않았으면 빈 문자열입니다. | |
| data. | string | 파일 암호를 넣어 이어 가는 방법을 적은 서버의 안내 문장입니다. 상태가 `password_required` 일 때만 있습니다. 원본은 다시 올리지 않고, 같은 형식검증 요청에 encrypted_fields.password 로 암호를 넣습니다. | |
| data. | object | 기관이 형식검증 요청에 답한 묶음 그대로입니다. 안쪽 칸은 기관이 정하고, 비밀번호 칸은 서버가 지우고 돌려줍니다. 비밀번호 요구로 멈춘 경우에는 이 칸 대신 provider_code, provider_message, how_to_ko 가 옵니다. | |
| data. | string | 기관 쓰기가 확인됐는지를 가르는 판정입니다. 봉투 바깥의 outcome 과 같은 값이고, 응답으로 돌아왔다면 항상 `confirmed` 입니다. | |
| data. | string | 쓰기 액션의 이름입니다. 봉투 바깥의 action 과 같은 값이고, 이 액션은 항상 `hometax.tax.withholding.file_conversion.upload` 입니다. | |
| warnings | array | 경고 문장의 목록입니다. 이 상품은 경고를 싣지 않아 항상 빈 배열입니다. | |
| outcome | string | 기관 쓰기가 확인됐는지를 가르는 판정입니다. 응답으로 돌아왔다면 항상 `confirmed` 입니다. 결과를 확인하지 못한 경우는 이 모양이 아니라 오류로 끝납니다. 작업 결과 판정이 이 자리를 읽습니다. | |
| action | string | 쓰기 액션의 이름입니다. 이 액션은 항상 `hometax.tax.withholding.file_conversion.upload` 입니다. 작업 결과 판정이 이 자리를 읽습니다. |
// result.data - 값 자리에는 각 칸의 형식을 적었습니다 (실제 값이 아닙니다)
{
"success": "<boolean>",
"step": "<string>",
"state": "<string>",
"snapshot": {},
"snapshot_hash": "<string>",
"data": {
"upload": {},
"provider_code": "<string>",
"provider_message": "<string>",
"how_to_ko": "<string>",
"response": {},
"outcome": "<string>",
"action": "<string>"
},
"warnings": [],
"outcome": "<string>",
"action": "<string>"
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| WRITE_ | 요청에 확인 토큰(confirmation_token)이 없으면 홈택스에 아무것도 보내지 않고 작업도 만들지 않은 채 이 오류로 끝납니다. error.message 는 「원천세 전자파일을 기관 변환 시스템에 올리면 되돌릴 수 없어 올리기 전 확인이 필요합니다. 아래 내용을 사용자에게 보여주고 동의를 받으세요.」 로 시작하고 error.confirmation_token 에 1회용 토큰이 옵니다. 이 단계의 확인에는 미리보기 내용이 없어 error.preview 는 빈 객체입니다. 이 내용을 고객에게 그대로 보여 주고 확인을 받은 뒤, 같은 요청의 params.confirmation_token 에 응답의 error.confirmation_token 값을 넣어 다시 호출해 주세요. 토큰은 10분 안에 한 번만 쓸 수 있고, 확인한 요청 본문과 같은 본문에만 맞습니다. | |
| WRITE_ | 토큰이 만료됐거나, 이미 썼거나, 다른 호출자나 다른 환경에서 받은 것이거나, 확인한 요청 본문과 달라졌으면 홈택스에 아무것도 보내지 않고 작업도 만들지 않은 채 이 오류로 끝납니다. error.message 는 「확인이 만료됐거나 확인한 내용과 달라졌습니다. 다시 확인해 주세요.」 입니다. 토큰 없이 다시 요청하면 새 토큰을 받습니다. | |
| VALIDATION_ | 요청 칸이 빠졌거나 칸 값이 원본 올리기의 요청 형식에 맞지 않으면 작업을 만들지 않고 홈택스에도 아무것도 보내지 않은 채 이 오류로 끝납니다. error.message 는 어느 칸인지와 상관없이 「변환 초기화 결과와 저장된 원본의 작업 번호, 파일명, SHA-256을 입력해 주세요. 파일 내용은 이 요청에 넣을 수 없습니다.」 입니다. | |
| RESOURCE_ | 이어 받을 이전 작업(source_job_id)이 같은 조직과 환경에서 성공한 이 신고 유형의 작업이 아니거나, 그 결과를 읽을 수 없거나, 결과에 작성 스냅샷이 없거나 스냅샷이 expected_snapshot_hash 와 다르면 홈택스에 보내기 전에 이 오류로 끝납니다. error.message 는 걸린 확인의 문장 하나이고, BE 문장은 「같은 조직·환경에서 성공한 이전 단계의 작업이 필요합니다」, 「이전 작업의 JSON 결과를 읽을 수 없습니다」, 「이 신고 유형에서 성공한 이전 단계 작업이 필요합니다」, 「이전 작업의 작성 스냅샷이 없습니다」, 「작성 내용이 바뀌었습니다. 최신 결과를 다시 확인해 주세요」 입니다. | |
| RESOURCE_ | 작업 상태나 이어 받은 내용이 이 단계와 맞지 않으면 이 오류로 끝납니다. 이 단계에서 이 코드로 끝나는 확인의 BE 문장은 「일반 파일변환 신고의 기존 접수 작업을 지정해 주세요」, 「홈택스에서 새 변환 작업을 확인하지 못했습니다. 업로드를 반복하지 말고 진행현황을 확인해 주세요」, 「다른 변환 작업으로 바뀌었습니다. 재전송하지 말고 진행현황을 확인해 주세요」, 「기존 변환 작업이 완료 상태가 아닙니다」, 「파일 제출 작업 식별자가 없습니다」, 「접수번호를 확인하지 못했습니다. 다시 제출하지 마세요」, 「접수 전체 건수를 확인할 기관 페이지 정보가 필요합니다. 다시 제출하지 마세요」, 「재신고할 기존 접수번호와 현재 홈택스 변환 작업이 일치하지 않습니다」, 「진행 중인 변환 작업에 중복 업로드할 수 없습니다」, 「기관에 진행 중인 변환 작업이 있습니다」, 「성공한 같은 조직·환경의 파일 작업이 필요합니다」, 「원본을 등록한 초기화 결과로 업로드해 주세요」, 「등록한 원본을 찾지 못했거나 파일명·해시가 다릅니다」, 「파일명·원본 해시가 저장된 파일과 다릅니다」, 「홈택스 파일 기능은 오전 7시부터 이용할 수 있으니 그 뒤에 새 요청으로 다시 보내 주세요」, 「확보된 기관 파일 메타데이터가 없습니다」, 「기관이 요구하는 암호화 파일이 필요합니다」 이고, 걸린 확인의 문장 하나가 error.message 로 실립니다. | |
| AUTH_ | 저장된 기관 세션이 없습니다. 같은 연동 계정으로 hometax.session.login 을 먼저 실행해 세션을 연 뒤 다시 보냅니다. |
53. 원천세 기한후신고 부표 저장hometax. tax. withholding. late_ report. annex_ save
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 와 함께 쓰지 않습니다. |
- 대괄호 []는 목록의 각 항목을, 점은 객체의 속성을, {key}는 실제 키로 바꿔 넣는 사전 항목을 뜻하며, 선택인 부모를 보낼 때 하위 필수 칸은 조건부로 표시합니다.
| 순번 | 변수명 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| source_ | string | Y | 이어서 진행할 이전 단계 작업의 job_id 를 그대로 입력합니다(job_ 으로 시작하는 작업 번호). 명세 저장(detail_save)이나 부표 저장(annex_save) 결과, 또는 그 상태에서 실행한 조회(lookup) 결과를 받습니다. 부표 종류가 승계명세(refund_succession)이면 기본정보 저장(basic_save) 결과도 받습니다. 같은 조직과 환경, 같은 기관 연결에서 이 신고 유형으로 성공한 작업이어야 하고 아니면 진행하지 않고 거절하며, 받지 않는 작성 상태의 결과이면 409 로 거절합니다 | |
| expected_ | string | Y | source_job_id 작업 결과의 snapshot_hash 를 그대로 입력합니다(소문자 16진수 64자리). 그 작업의 내용과 맞지 않으면 진행하지 않고 작성 내용이 바뀌었다는 오류(409)로 거절합니다 | |
| annex_ | object | Y | 저장할 부표를 담는 객체입니다. kind 에 부표 종류를 입력하고, 값을 바꿀 때는 datasets 에, 행을 추가하거나 수정하거나 삭제할 때는 row_operations 에 담습니다. 같은 목록을 두 곳에 함께 입력하면 입력 오류로 거절합니다. 행을 수정하거나 삭제할 때는 query.kind 가 annex_rows 이고 query.annex_kind 에 같은 부표 종류를 입력한 조회(lookup) 결과의 row_targets 에서 받은 row_index 와 expected_row_hash 를 함께 입력하며, 기관의 지금 행과 다르면 409 로 거절합니다. 행을 추가할 때는 그 둘을 입력하지 않고, 삭제할 때는 values 를 입력하지 않습니다. 환급신청 부표(refund)는 이 신고 유형에서 받지 않고 거절합니다. 승계명세(refund_succession)는 바뀐 행이 없으면 거절하고, 저장한 뒤에는 명세 저장(detail_save)을 다시 해야 합니다. 안쪽 칸은 요구사항 조회(requirements) 결과의 actions 아래 annex_save 항목 schema 에 있습니다. JSON 문자열이 아니라 객체로 입력하며 문자열이면 입력 오류로 거절합니다 | |
| annex_ | string | Y | refund_succession은 승계명세 저장 후 본표 detail_save가 필요합니다. refund는 환급신청을 선택한 대화형에서만 지원합니다. 허용값: ["income_persons", "annex", "refund", "previous_refund", "paid_tax", "refund_succession"] | |
| annex_ | object | N | 부표의 값을 바꿀 때 쓰는 객체입니다. 키는 그 부표에서 바꿀 수 있는 기관 데이터 이름이고, 값은 바꿀 칸만 담은 객체나 행 객체 목록입니다. 행 목록은 기관 행과 개수가 같아야 하며, 행 수를 바꾸려면 row_operations 를 씁니다. 바꿀 수 없는 데이터 이름은 입력 오류로 거절합니다 | |
| annex_ | object | N | 명세 조회 결과의 행을 추가, 수정, 삭제합니다. 한 묶음의 행 번호는 변경 전 조회 기준입니다 | |
| annex_ | string | 조건부 | 행 작업의 종류입니다. 새 행은 add, 기존 행 수정은 update, 기존 행 삭제는 delete 로 입력합니다. 허용값: ["add", "update", "delete"] | |
| annex_ | number | N | 수정하거나 삭제할 행의 위치입니다. 부표 행 조회(lookup 의 query.kind 가 annex_rows) 결과의 row_targets 에서 받은 값을 그대로 입력하며 add 에는 입력하지 않습니다. 조회 결과의 범위를 벗어나거나 기관의 지금 행과 다르면 거절합니다. 최솟값: 0. 생략 시 기본값: null | |
| annex_ | string | N | 수정하거나 삭제할 행의 확인값입니다(소문자 16진수 64자리). row_index 와 같은 row_targets 항목에서 받은 값을 그대로 입력하며 add 에는 입력하지 않습니다. 기관의 지금 행과 다르면 409 로 거절합니다. 문자열 패턴: "^[0-9a-f]{64}$". 생략 시 기본값: null | |
| annex_ | object | 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: annex_save-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "hometax",
"action": "hometax.tax.withholding.late_report.annex_save",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {
"source_job_id": "<필수>",
"expected_snapshot_hash": "<필수>",
"annex_document": {
"kind": "<필수>"
}
}
}'Response
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| success | boolean | 단계가 끝났는지입니다. 응답으로 돌아왔다면 항상 true 입니다. 실패는 이 모양이 아니라 오류 응답으로 옵니다. | |
| step | string | 응답이 어느 단계의 결과인지입니다. 이 액션은 항상 `annex_save` 입니다. | |
| state | string | 이 단계가 끝난 뒤 작업이 놓인 상태입니다. `basic_saved` 또는 `annex_saved` 중 하나입니다. 앞의 상태는 승계명세를 저장해 상위 신고의 소득 명세 저장을 다시 불러야 하는 경우이고 뒤의 상태는 그 밖의 부표를 저장한 경우입니다. | |
| snapshot | object | 이 단계가 끝난 작업 상태의 사본입니다. 다음 단계가 이어받는 값이라 직접 고치지 않습니다. | |
| snapshot_ | string | snapshot 의 해시(SHA-256, 16진수 64자)입니다. 다음 단계를 부를 때 expected_snapshot_hash 에 그대로 넣고, 이 작업의 job_id 는 source_job_id 에 넣습니다. 그 사이 작업 상태가 바뀌었으면 거절됩니다. | |
| data | object | 기관이 부표 저장 요청에 돌려준 응답 본문입니다. 저장한 행이 기관 재조회 결과와 같음을 확인한 뒤에만 이 응답이 돌아오고, 다르면 오류로 끝납니다. | |
| data. | object | 승계명세(부표 종류 `refund_succession`)를 저장했을 때만 응답 본문에 더해지는 묶음입니다. 그 밖의 부표에는 이 칸이 없습니다. | |
| data. | string | 저장한 승계명세의 환급액 합계(원)입니다. 숫자를 문자열로 담고, 상위 신고의 소득 명세 저장이 이 값을 이어받습니다. | |
| data. | boolean | 상위 신고의 소득 명세 저장을 다시 불러야 하는지입니다. 승계명세를 저장하면 상위 신고에 합계가 반영되므로 항상 true 입니다. | |
| warnings | array | 경고 문장의 목록입니다. 이 상품은 경고를 싣지 않아 항상 빈 배열입니다. | |
| outcome | string | 기관 쓰기가 확인됐는지를 가르는 판정입니다. 응답으로 돌아왔다면 항상 `confirmed` 입니다. 결과를 확인하지 못한 경우는 이 모양이 아니라 오류로 끝납니다. 작업 결과 판정이 이 자리를 읽습니다. | |
| action | string | 쓰기 액션의 이름입니다. 이 액션은 항상 `hometax.tax.withholding.late_report.annex_save` 입니다. 작업 결과 판정이 이 자리를 읽습니다. |
// result.data - 값 자리에는 각 칸의 형식을 적었습니다 (실제 값이 아닙니다)
{
"success": "<boolean>",
"step": "<string>",
"state": "<string>",
"snapshot": {},
"snapshot_hash": "<string>",
"data": {
"refund_succession": {
"amount": "<string>",
"parent_detail_save_required": "<boolean>"
}
},
"warnings": [],
"outcome": "<string>",
"action": "<string>"
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| VALIDATION_ | 요청 칸이 빠졌거나 칸 값이 이 단계의 요청 형식에 맞지 않으면 홈택스에 아무것도 보내지 않고 이 오류로 끝납니다. 빠진 칸이 있으면 error.message 는 「요청에 필요한 값이 빠졌습니다. 빠진 값: 칸 이름. 그 값을 넣어 다시 요청해 주세요.」 꼴이고, 그 밖의 검사에 걸린 칸이 있으면 「요청 값이 올바르지 않습니다. 확인할 값: 칸 이름. 값을 고쳐 다시 요청해 주세요.」 꼴이며, 둘 다 있으면 두 문장이 차례로 이어집니다. 칸 이름 자리에는 걸린 칸이 다섯까지 쉼표로 이어지고 더 있으면 「외 N개」 가 붙으며, 목록이나 객체 안의 칸은 「바깥 칸.0.안쪽 칸」 처럼 위치를 점으로 이은 경로로 적습니다. 걸린 검사가 모두 칸 하나를 짚지 않고 요청 전체를 보는 것이면 「요청 값이 올바르지 않습니다.」 만 옵니다. | |
| RESOURCE_ | 이어 받을 이전 작업(source_job_id)이 같은 조직과 환경에서 성공한 이 신고 유형의 작업이 아니거나, 그 결과를 읽을 수 없거나, 결과에 작성 스냅샷이 없거나 스냅샷이 expected_snapshot_hash 와 다르면 홈택스에 보내기 전에 이 오류로 끝납니다. error.message 는 걸린 확인의 문장 하나이고, BE 문장은 「이 신고 유형에서 성공한 이전 단계 작업이 필요합니다」, 「이전 작업의 작성 스냅샷이 없습니다」, 「작성 내용이 바뀌었습니다. 최신 결과를 다시 확인해 주세요」, 「같은 조직·환경에서 성공한 이전 단계의 작업이 필요합니다」, 「이전 작업의 JSON 결과를 읽을 수 없습니다」 입니다. | |
| RESOURCE_ | 작업 상태나 이어 받은 내용, 또는 홈택스에 있는 신고서의 상태가 이 단계와 맞지 않으면 이 오류로 끝납니다. 이 단계에서 이 코드로 끝나는 확인의 BE 문장은 「현재 작성 상태에서는 이 단계를 실행할 수 없습니다. 최신 결과를 확인해 주세요」, 「기관이 현재 신고서의 불러오기를 허용하지 않았습니다」, 「기관이 다른 작성 건을 반환했습니다」, 「불러온 신고서의 식별자가 다릅니다」, 「불러온 신고서의 기간·유형이 다릅니다」, 「불러온 신고서의 사업자가 다릅니다」, 「기관의 신고서가 다른 작성 건으로 바뀌었습니다」, 「승인한 뒤 기관 작성 내용이 변경됐습니다. 최신 내용을 다시 확인해 주세요」, 「명세 조회 결과의 신고서 식별자가 다릅니다」, 「명세의 행 번호·해시가 현재 기관 자료와 다릅니다」, 「대상 행이 조회 후 변경됐습니다」, 「다른 신고서의 행은 수정할 수 없습니다」, 「다른 신고서의 신규 행은 추가할 수 없습니다」, 「저장 후 명세 재조회가 다른 신고서를 가리킵니다」, 「저장한 명세의 거래·금액이 기관 재조회와 일치하지 않습니다. 재저장하지 말고 처리 결과를 확인해 주세요」, 「승계 환급액 합계가 저장 후 재조회와 다릅니다」 이고, 걸린 확인의 문장 하나가 error.message 로 실립니다. | |
| AUTH_ | 저장된 기관 세션이 없습니다. 같은 연동 계정으로 hometax.session.login 을 먼저 실행해 세션을 연 뒤 다시 보냅니다. |
54. 원천세 기한후신고 기본정보 저장hometax. tax. withholding. late_ report. basic_ save
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 와 함께 쓰지 않습니다. |
- 대괄호 []는 목록의 각 항목을, 점은 객체의 속성을, {key}는 실제 키로 바꿔 넣는 사전 항목을 뜻하며, 선택인 부모를 보낼 때 하위 필수 칸은 조건부로 표시합니다.
| 순번 | 변수명 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| source_ | string | Y | 이어서 진행할 이전 단계 작업의 job_id 를 그대로 입력합니다(job_ 으로 시작하는 작업 번호). 작성 준비(init)나 기본정보 저장(basic_save) 결과, 또는 그 상태에서 실행한 조회(lookup) 결과를 받습니다. 같은 조직과 환경, 같은 기관 연결에서 이 신고 유형으로 성공한 작업이어야 하고 아니면 진행하지 않고 거절하며, 받지 않는 작성 상태의 결과이면 409 로 거절합니다 | |
| expected_ | string | Y | source_job_id 작업 결과의 snapshot_hash 를 그대로 입력합니다(소문자 16진수 64자리). 그 작업의 내용과 맞지 않으면 진행하지 않고 작성 내용이 바뀌었다는 오류(409)로 거절합니다 | |
| basic_ | object | N | 기관에서 불러온 기본정보 중 바꿀 값만 입력합니다. 생략한 값은 유지합니다 | |
| basic_ | object | N | 원천징수의무자 정보(사업자등록번호, 상호, 대표자 성명) 가운데 바꿀 값만 담는 객체입니다. 생략한 값은 기관 값을 그대로 쓰고, null 로 입력하면 입력 오류로 거절합니다 | |
| basic_ | string | N | 원천징수의무자의 사업자등록번호입니다. 하이픈 없이 숫자 10자리로 입력합니다. 별칭 businessNo 로도 보낼 수 있습니다. 문자열 패턴: "^\\d{10}$". 생략 시 기본값: null | |
| basic_ | string | N | 원천징수의무자의 상호입니다. 1자 이상으로 입력합니다. 별칭 companyName 로도 보낼 수 있습니다. 최소 길이: 1. 생략 시 기본값: null | |
| basic_ | string | N | 대표자 성명입니다. 1자 이상으로 입력합니다. 최소 길이: 1. 생략 시 기본값: null | |
| basic_ | object | N | 신고 선택 사항(신고 주기, 연말정산, 소득처분, 환급 신청, 일괄 납부, 사업자단위 과세) 가운데 바꿀 값만 담는 객체입니다. 생략한 값은 기관 값을 그대로 쓰고, null 로 입력하면 입력 오류로 거절합니다 | |
| basic_ | string | N | 신고 주기입니다. 매월 신고는 monthly, 반기 신고는 semiannual 로 입력합니다. 별칭 periodType 로도 보낼 수 있습니다. 허용값: ["monthly", "semiannual"]. 생략 시 기본값: null | |
| basic_ | string | N | 연말정산 포함 여부(Y/N). 기한후 신고에서 Y 이면 귀속월이 2월, 3월, 4월 가운데 하나여야 합니다. 별칭 yearEnd 로도 보낼 수 있습니다. 허용값: ["Y", "N"]. 생략 시 기본값: null | |
| basic_ | string | N | 소득처분 신고 여부입니다. Y 또는 N 으로 입력합니다. 수정신고는 Y 를 받지 않고 입력 오류로 거절합니다. 허용값: ["Y", "N"]. 생략 시 기본값: null | |
| basic_ | string | N | 환급 신청 여부입니다. Y 또는 N 으로 입력합니다. 기한후 신고와 수정신고는 Y 를 받지 않고 입력 오류로 거절합니다. 별칭 refundApply 로도 보낼 수 있습니다. 허용값: ["Y", "N"]. 생략 시 기본값: null | |
| basic_ | string | N | 일괄 납부 여부입니다. Y 또는 N 으로 입력합니다. 별칭 bulkPayment 로도 보낼 수 있습니다. 허용값: ["Y", "N"]. 생략 시 기본값: null | |
| basic_ | string | N | 사업자단위 과세 여부입니다. Y 또는 N 으로 입력합니다. 별칭 businessUnit 로도 보낼 수 있습니다. 허용값: ["Y", "N"]. 생략 시 기본값: null | |
| basic_ | array | N | 신고할 소득 종류의 목록입니다. 기관 소득구분 코드 F01 부터 F11 가운데 하나 이상을 중복 없이 입력하며, employment(근로소득, F01), retirement(퇴직소득, F02), business(사업소득, F03), other(기타소득, F04) 이름도 받습니다. 목록에 없는 코드나 중복은 입력 오류로 거절하고, 생략하면 기관 값을 그대로 씁니다. 별칭 selectedIncomeTypes 로도 보낼 수 있습니다. 최소 항목 수: 1. 생략 시 기본값: null |
- 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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: basic_save-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "hometax",
"action": "hometax.tax.withholding.late_report.basic_save",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {
"source_job_id": "<필수>",
"expected_snapshot_hash": "<필수>"
}
}'Response
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| success | boolean | 단계가 끝났는지입니다. 응답으로 돌아왔다면 항상 true 입니다. 실패는 이 모양이 아니라 오류 응답으로 옵니다. | |
| step | string | 응답이 어느 단계의 결과인지입니다. 이 액션은 항상 `basic_save` 입니다. | |
| state | string | 이 단계가 끝난 뒤 작업이 놓인 상태입니다. `basic_saved` 입니다. | |
| snapshot | object | 이 단계가 끝난 작업 상태의 사본입니다. 다음 단계가 이어받는 값이라 직접 고치지 않습니다. | |
| snapshot_ | string | snapshot 의 해시(SHA-256, 16진수 64자)입니다. 다음 단계를 부를 때 expected_snapshot_hash 에 그대로 넣고, 이 작업의 job_id 는 source_job_id 에 넣습니다. 그 사이 작업 상태가 바뀌었으면 거절됩니다. | |
| data | object | 기관이 기본정보 저장 요청에 돌려준 응답 본문입니다. 저장한 신고 옵션이 기관 재조회 결과와 같음을 확인한 뒤에만 이 응답이 돌아오고, 다르면 오류로 끝납니다. | |
| warnings | array | 경고 문장의 목록입니다. 이 상품은 경고를 싣지 않아 항상 빈 배열입니다. | |
| outcome | string | 기관 쓰기가 확인됐는지를 가르는 판정입니다. 응답으로 돌아왔다면 항상 `confirmed` 입니다. 결과를 확인하지 못한 경우는 이 모양이 아니라 오류로 끝납니다. 작업 결과 판정이 이 자리를 읽습니다. | |
| action | string | 쓰기 액션의 이름입니다. 이 액션은 항상 `hometax.tax.withholding.late_report.basic_save` 입니다. 작업 결과 판정이 이 자리를 읽습니다. |
// result.data - 값 자리에는 각 칸의 형식을 적었습니다 (실제 값이 아닙니다)
{
"success": "<boolean>",
"step": "<string>",
"state": "<string>",
"snapshot": {},
"snapshot_hash": "<string>",
"data": {},
"warnings": [],
"outcome": "<string>",
"action": "<string>"
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| VALIDATION_ | 요청 칸이 빠졌거나 칸 값이 이 단계의 요청 형식에 맞지 않으면 홈택스에 아무것도 보내지 않고 이 오류로 끝납니다. 빠진 칸이 있으면 error.message 는 「요청에 필요한 값이 빠졌습니다. 빠진 값: 칸 이름. 그 값을 넣어 다시 요청해 주세요.」 꼴이고, 그 밖의 검사에 걸린 칸이 있으면 「요청 값이 올바르지 않습니다. 확인할 값: 칸 이름. 값을 고쳐 다시 요청해 주세요.」 꼴이며, 둘 다 있으면 두 문장이 차례로 이어집니다. 칸 이름 자리에는 걸린 칸이 다섯까지 쉼표로 이어지고 더 있으면 「외 N개」 가 붙으며, 목록이나 객체 안의 칸은 「바깥 칸.0.안쪽 칸」 처럼 위치를 점으로 이은 경로로 적습니다. 걸린 검사가 모두 칸 하나를 짚지 않고 요청 전체를 보는 것이면 「요청 값이 올바르지 않습니다.」 만 옵니다. | |
| RESOURCE_ | 이어 받을 이전 작업(source_job_id)이 같은 조직과 환경에서 성공한 이 신고 유형의 작업이 아니거나, 그 결과를 읽을 수 없거나, 결과에 작성 스냅샷이 없거나 스냅샷이 expected_snapshot_hash 와 다르면 홈택스에 보내기 전에 이 오류로 끝납니다. error.message 는 걸린 확인의 문장 하나이고, BE 문장은 「이 신고 유형에서 성공한 이전 단계 작업이 필요합니다」, 「이전 작업의 작성 스냅샷이 없습니다」, 「작성 내용이 바뀌었습니다. 최신 결과를 다시 확인해 주세요」, 「같은 조직·환경에서 성공한 이전 단계의 작업이 필요합니다」, 「이전 작업의 JSON 결과를 읽을 수 없습니다」 입니다. | |
| RESOURCE_ | 작업 상태나 이어 받은 내용, 또는 홈택스에 있는 신고서의 상태가 이 단계와 맞지 않으면 이 오류로 끝납니다. 이 단계에서 이 코드로 끝나는 확인의 BE 문장은 「현재 작성 상태에서는 이 단계를 실행할 수 없습니다. 최신 결과를 확인해 주세요」, 「기관이 현재 신고 기간·유형으로 작성을 허용하지 않았습니다 (판정 코드)」, 「작성 중인 신고가 있습니다. 이어서 작성하거나 작성 취소 후 새로 시작해 주세요」, 「이어서 작성할 신고서가 없습니다. 새로 시작해 주세요.」, 「지금 상태에서는 진행할 수 없습니다. 신고서 상태를 확인한 뒤 다시 시도해 주세요.」, 「기관에서 다른 신고 식별자를 반환했습니다」, 「기관 조회 회사와 작성 중인 회사의 사업자등록번호가 다릅니다」, 「신규 작성 상태가 변경됐습니다. 작성 중 신고서를 확인해 주세요」, 「기관이 현재 신고서의 불러오기를 허용하지 않았습니다」, 「작성 식별자가 바뀌었습니다」, 「불러온 신고서의 식별자가 다릅니다」, 「불러온 신고서의 기간·유형이 다릅니다」, 「불러온 신고서의 사업자가 다릅니다」, 「신규 신고서 준비 상태가 아닙니다」, 「작성 중인 회사와 기본정보의 회사가 다릅니다」, 「기관이 다른 작성 건을 반환했습니다」, 「기관의 신고서가 다른 작성 건으로 바뀌었습니다」, 「저장한 신고 옵션이 기관 재조회 결과와 다릅니다. 재저장하지 말고 작성 내용을 확인해 주세요」 이고, 걸린 확인의 문장 하나가 error.message 로 실립니다. 문장의 판정 코드 자리에는 홈택스가 신고서 상태 확인에서 돌려준 판정 코드가 들어갑니다. | |
| AUTH_ | 저장된 기관 세션이 없습니다. 같은 연동 계정으로 hometax.session.login 을 먼저 실행해 세션을 연 뒤 다시 보냅니다. |
55. 원천세 기한후신고 작성 취소hometax. tax. withholding. late_ report. cancel_ draft
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 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| source_ | string | Y | 이어서 진행할 이전 단계 작업의 job_id 를 그대로 입력합니다(job_ 으로 시작하는 작업 번호). 작성 준비(init)부터 미리보기(preview)까지 작성 중인 상태의 결과, 또는 그 상태에서 실행한 조회(lookup) 결과를 받습니다. 제출(submit)이 끝난 신고서는 작성 취소할 수 없어 409 로 거절합니다. 같은 조직과 환경, 같은 기관 연결에서 이 신고 유형으로 성공한 작업이어야 하고 아니면 진행하지 않고 거절하며, 받지 않는 작성 상태의 결과이면 409 로 거절합니다 | |
| expected_ | string | Y | source_job_id 작업 결과의 snapshot_hash 를 그대로 입력합니다(소문자 16진수 64자리). 그 작업의 내용과 맞지 않으면 진행하지 않고 작성 내용이 바뀌었다는 오류(409)로 거절합니다 | |
| confirmation_ | string | N | 1회용 확인 토큰입니다. 처음에는 보내지 않습니다. 토큰 없이 부르면 기관에 아무것도 보내지 않고 작업도 만들지 않은 채 확인이 필요하다는 오류(WRITE_CONFIRMATION_REQUIRED)로 끝나고, 응답의 error.confirmation_token 에 토큰이 옵니다. error.message 의 안내를 사용자에게 보여 주고 동의를 받은 뒤 같은 요청에 이 토큰을 넣어 다시 부릅니다. 토큰은 10분 안에 한 번만 쓸 수 있고 처음 요청과 같은 본문, 같은 호출자, 같은 환경에서만 맞으며, 아니면 확인이 만료됐거나 내용이 달라졌다는 오류로 거절합니다 |
- 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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: cancel_draft-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "hometax",
"action": "hometax.tax.withholding.late_report.cancel_draft",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {
"source_job_id": "<필수>",
"expected_snapshot_hash": "<필수>"
}
}'Response
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| success | boolean | 단계가 끝났는지입니다. 응답으로 돌아왔다면 항상 true 입니다. 실패는 이 모양이 아니라 오류 응답으로 옵니다. | |
| step | string | 응답이 어느 단계의 결과인지입니다. 이 액션은 항상 `cancel_draft` 입니다. | |
| state | string | 이 단계가 끝난 뒤 작업이 놓인 상태입니다. `cancelled` 입니다. | |
| snapshot | object | 이 단계가 끝난 작업 상태의 사본입니다. 다음 단계가 이어받는 값이라 직접 고치지 않습니다. | |
| snapshot_ | string | snapshot 의 해시(SHA-256, 16진수 64자)입니다. 다음 단계를 부를 때 expected_snapshot_hash 에 그대로 넣고, 이 작업의 job_id 는 source_job_id 에 넣습니다. 그 사이 작업 상태가 바뀌었으면 거절됩니다. | |
| data | object | 기관이 작성 취소 요청에 돌려준 응답 본문입니다. 기관이 취소 완료를 확인하고 응답이 다른 작성 신고서를 가리키지 않을 때만 이 응답이 돌아오고, 아니면 오류로 끝납니다. | |
| warnings | array | 경고 문장의 목록입니다. 이 상품은 경고를 싣지 않아 항상 빈 배열입니다. | |
| outcome | string | 기관 쓰기가 확인됐는지를 가르는 판정입니다. 응답으로 돌아왔다면 항상 `confirmed` 입니다. 결과를 확인하지 못한 경우는 이 모양이 아니라 오류로 끝납니다. 작업 결과 판정이 이 자리를 읽습니다. | |
| action | string | 쓰기 액션의 이름입니다. 이 액션은 항상 `hometax.tax.withholding.late_report.cancel_draft` 입니다. 작업 결과 판정이 이 자리를 읽습니다. |
// result.data - 값 자리에는 각 칸의 형식을 적었습니다 (실제 값이 아닙니다)
{
"success": "<boolean>",
"step": "<string>",
"state": "<string>",
"snapshot": {},
"snapshot_hash": "<string>",
"data": {},
"warnings": [],
"outcome": "<string>",
"action": "<string>"
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| WRITE_ | 요청에 확인 토큰(confirmation_token)이 없으면 홈택스에 아무것도 보내지 않고 작업도 만들지 않은 채 이 오류로 끝납니다. error.message 는 「작성 중인 원천세 기한후신고서를 기관에서 작성 취소하면 되돌릴 수 없어 취소 전 확인이 필요합니다. 아래 내용을 사용자에게 보여주고 동의를 받으세요.」 로 시작하고 error.confirmation_token 에 1회용 토큰이 옵니다. 이 단계의 확인에는 미리보기 내용이 없어 error.preview 는 빈 객체입니다. 이 내용을 고객에게 그대로 보여 주고 확인을 받은 뒤, 같은 요청의 params.confirmation_token 에 응답의 error.confirmation_token 값을 넣어 다시 호출해 주세요. 토큰은 10분 안에 한 번만 쓸 수 있고, 확인한 요청 본문과 같은 본문에만 맞습니다. | |
| WRITE_ | 토큰이 만료됐거나, 이미 썼거나, 다른 호출자나 다른 환경에서 받은 것이거나, 확인한 요청 본문과 달라졌으면 홈택스에 아무것도 보내지 않고 작업도 만들지 않은 채 이 오류로 끝납니다. error.message 는 「확인이 만료됐거나 확인한 내용과 달라졌습니다. 다시 확인해 주세요.」 입니다. 토큰 없이 다시 요청하면 새 토큰을 받습니다. | |
| VALIDATION_ | 요청 칸이 빠졌거나 칸 값이 이 단계의 요청 형식에 맞지 않으면 홈택스에 아무것도 보내지 않고 이 오류로 끝납니다. 빠진 칸이 있으면 error.message 는 「요청에 필요한 값이 빠졌습니다. 빠진 값: 칸 이름. 그 값을 넣어 다시 요청해 주세요.」 꼴이고, 그 밖의 검사에 걸린 칸이 있으면 「요청 값이 올바르지 않습니다. 확인할 값: 칸 이름. 값을 고쳐 다시 요청해 주세요.」 꼴이며, 둘 다 있으면 두 문장이 차례로 이어집니다. 칸 이름 자리에는 걸린 칸이 다섯까지 쉼표로 이어지고 더 있으면 「외 N개」 가 붙으며, 목록이나 객체 안의 칸은 「바깥 칸.0.안쪽 칸」 처럼 위치를 점으로 이은 경로로 적습니다. 걸린 검사가 모두 칸 하나를 짚지 않고 요청 전체를 보는 것이면 「요청 값이 올바르지 않습니다.」 만 옵니다. | |
| RESOURCE_ | 이어 받을 이전 작업(source_job_id)이 같은 조직과 환경에서 성공한 이 신고 유형의 작업이 아니거나, 그 결과를 읽을 수 없거나, 결과에 작성 스냅샷이 없거나 스냅샷이 expected_snapshot_hash 와 다르면 홈택스에 보내기 전에 이 오류로 끝납니다. error.message 는 걸린 확인의 문장 하나이고, BE 문장은 「이 신고 유형에서 성공한 이전 단계 작업이 필요합니다」, 「이전 작업의 작성 스냅샷이 없습니다」, 「작성 내용이 바뀌었습니다. 최신 결과를 다시 확인해 주세요」, 「같은 조직·환경에서 성공한 이전 단계의 작업이 필요합니다」, 「이전 작업의 JSON 결과를 읽을 수 없습니다」 입니다. | |
| RESOURCE_ | 작업 상태나 이어 받은 내용, 또는 홈택스에 있는 신고서의 상태가 이 단계와 맞지 않으면 이 오류로 끝납니다. 이 단계에서 이 코드로 끝나는 확인의 BE 문장은 「현재 작성 상태에서는 이 단계를 실행할 수 없습니다. 최신 결과를 확인해 주세요」, 「기관이 현재 신고서의 불러오기를 허용하지 않았습니다」, 「기관이 다른 작성 건을 반환했습니다」, 「불러온 신고서의 식별자가 다릅니다」, 「불러온 신고서의 기간·유형이 다릅니다」, 「불러온 신고서의 사업자가 다릅니다」, 「기관의 신고서가 다른 작성 건으로 바뀌었습니다」, 「승인한 뒤 기관 작성 내용이 변경됐습니다. 최신 내용을 다시 확인해 주세요」, 「기관에서 작성 취소 완료가 확인되지 않았습니다」, 「취소 응답이 다른 작성 신고서를 가리킵니다」 이고, 걸린 확인의 문장 하나가 error.message 로 실립니다. | |
| AUTH_ | 저장된 기관 세션이 없습니다. 같은 연동 계정으로 hometax.session.login 을 먼저 실행해 세션을 연 뒤 다시 보냅니다. |
56. 원천세 기한후신고 소득별 상세 저장hometax. tax. withholding. late_ report. detail_ save
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 와 함께 쓰지 않습니다. |
- 대괄호 []는 목록의 각 항목을, 점은 객체의 속성을, {key}는 실제 키로 바꿔 넣는 사전 항목을 뜻하며, 선택인 부모를 보낼 때 하위 필수 칸은 조건부로 표시합니다.
| 순번 | 변수명 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| source_ | string | Y | 이어서 진행할 이전 단계 작업의 job_id 를 그대로 입력합니다(job_ 으로 시작하는 작업 번호). 기본정보 저장(basic_save), 명세 저장(detail_save), 부표 저장(annex_save) 결과, 또는 그 상태에서 실행한 조회(lookup) 결과를 받습니다. 같은 조직과 환경, 같은 기관 연결에서 이 신고 유형으로 성공한 작업이어야 하고 아니면 진행하지 않고 거절하며, 받지 않는 작성 상태의 결과이면 409 로 거절합니다 | |
| expected_ | string | Y | source_job_id 작업 결과의 snapshot_hash 를 그대로 입력합니다(소문자 16진수 64자리). 그 작업의 내용과 맞지 않으면 진행하지 않고 작성 내용이 바뀌었다는 오류(409)로 거절합니다 | |
| detail_ | object | Y | 저장할 소득 명세를 담는 객체입니다. 안쪽 칸과 필수 여부는 요구사항 조회(requirements) 결과의 actions 아래 detail_save 항목 schema 에 있습니다. JSON 문자열이 아니라 객체로 입력하며 문자열이면 입력 오류로 거절합니다 | |
| detail_ | object | Y | 소득 명세 구분별로 바꿀 소득행을 담는 객체입니다. 키는 employment, retirement, business, other 같은 소득 이름이나 기관 명세 구분 번호이고, 값은 그 구분의 소득행 목록입니다. 하나 이상 입력하며 기관 화면에 없는 구분은 입력 오류로 거절합니다. 소득행에는 code 와 바꿀 칸만 넣고, 생략한 칸은 기관 값을 그대로 씁니다. 합계 행과 납부세액은 서버가 다시 계산합니다. JSON 문자열이 아니라 객체로 입력하며 문자열이면 입력 오류로 거절합니다. 별칭 incomeSections 로도 보낼 수 있습니다 | |
| detail_ | string | Y | 바꿀 소득행의 원천징수소득코드입니다. A 나 C 로 시작하는 세 자리(예 A01)이고, 기관 명세에 이미 있는 행이어야 하며 같은 구분에서 같은 코드를 두 번 입력하면 입력 오류로 거절합니다. 문자열 패턴: "^[AC]\\d{2}$" | |
| detail_ | number | N | 소득 지급 인원수입니다. 0 이상의 정수로 입력하며, 지급 총액이나 징수세액이 있는 행은 인원이 있어야 합니다. 별칭 incPymnNfpCnt 로도 보낼 수 있습니다. 최솟값: 0. 생략 시 기본값: null | |
| detail_ | number | N | 소득 지급 총액(원)입니다. 정수로 입력하며, 인원이 있는 행은 0 보다 커야 합니다. 별칭 incPymnTotaPymnAmt 로도 보낼 수 있습니다. 생략 시 기본값: null | |
| detail_ | number | N | 징수 소득세액(원)입니다. 정수로 입력합니다. 별칭 inctxLvyTxamt 로도 보낼 수 있습니다. 생략 시 기본값: null | |
| detail_ | number | N | 징수 농어촌특별세액(원)입니다. 정수로 입력합니다. 별칭 fnftxLvyTxamt 로도 보낼 수 있습니다. 생략 시 기본값: null | |
| detail_ | number | N | 징수 가산세액(원)입니다. 0 이상의 정수로 입력합니다. 별칭 adttxLvyTxamt 로도 보낼 수 있습니다. 최솟값: 0. 생략 시 기본값: null | |
| detail_ | number | N | 당월 조정 환급세액(원)입니다. 정수로 입력합니다. 별칭 tmnMetnRfndTxamt 로도 보낼 수 있습니다. 생략 시 기본값: null | |
| detail_ | number | N | 납부 소득세액(원)입니다. 서버가 행의 값으로 다시 계산하므로 생략하고, 입력하면 계산값과 같아야 하며 다르면 입력 오류로 거절합니다. 별칭 inctxPmtTxamt 로도 보낼 수 있습니다. 생략 시 기본값: null | |
| detail_ | number | N | 납부 농어촌특별세액(원)입니다. 서버가 행의 값으로 다시 계산하므로 생략하고, 입력하면 계산값과 같아야 하며 다르면 입력 오류로 거절합니다. 별칭 fnftxPmtTxamt 로도 보낼 수 있습니다. 생략 시 기본값: null | |
| detail_ | object | N | 기관에서 불러온 환급 입력값 중 바꿀 항목만 보냅니다. 합계와 차감잔액은 자동 계산합니다. 별칭 refundAdjustment 로도 보낼 수 있습니다 | |
| detail_ | number | N | 전월 미환급세액(원)입니다. 0 이상의 정수로 입력합니다. 별칭 pvmnNrfnTxamt 로도 보낼 수 있습니다. 최솟값: 0. 생략 시 기본값: null | |
| detail_ | number | N | 기환급 신청세액(원)입니다. 0 이상의 정수이고 전월 미환급세액보다 크면 입력 오류로 거절합니다. 별칭 pvmnArefAplnTxamt 로도 보낼 수 있습니다. 최솟값: 0. 생략 시 기본값: null | |
| detail_ | number | N | 신탁재산(금융회사 등) 환급세액(원)입니다. 0 이상의 정수로 입력합니다. 별칭 trstPrpFnnOrgnTxamt 로도 보낼 수 있습니다. 최솟값: 0. 생략 시 기본값: null | |
| detail_ | number | N | 그 밖의 환급세액(금융회사 등, 원)입니다. 0 이상의 정수로 입력합니다. 별칭 fnnEtcRfndTxamt 로도 보낼 수 있습니다. 최솟값: 0. 생략 시 기본값: null | |
| detail_ | number | N | 환급 신청액(원)입니다. 0 이상의 정수이고 차월 이월 환급세액보다 크면 입력 오류로 거절합니다. 수정신고가 아닌 신고서에서 기본정보의 환급 신청이 Y 이면 환급 신청액과 차월 이월 환급세액이 모두 0 보다 커야 합니다. 별칭 rfndAplnAmt 로도 보낼 수 있습니다. 최솟값: 0. 생략 시 기본값: null |
- 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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: detail_save-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "hometax",
"action": "hometax.tax.withholding.late_report.detail_save",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {
"source_job_id": "<필수>",
"expected_snapshot_hash": "<필수>",
"detail_document": {
"income_sections": {
"{key}": [
{
"code": "<필수>"
}
]
}
}
}
}'Response
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| success | boolean | 단계가 끝났는지입니다. 응답으로 돌아왔다면 항상 true 입니다. 실패는 이 모양이 아니라 오류 응답으로 옵니다. | |
| step | string | 응답이 어느 단계의 결과인지입니다. 이 액션은 항상 `detail_save` 입니다. | |
| state | string | 이 단계가 끝난 뒤 작업이 놓인 상태입니다. `detail_saved` 입니다. | |
| snapshot | object | 이 단계가 끝난 작업 상태의 사본입니다. 다음 단계가 이어받는 값이라 직접 고치지 않습니다. | |
| snapshot_ | string | snapshot 의 해시(SHA-256, 16진수 64자)입니다. 다음 단계를 부를 때 expected_snapshot_hash 에 그대로 넣고, 이 작업의 job_id 는 source_job_id 에 넣습니다. 그 사이 작업 상태가 바뀌었으면 거절됩니다. | |
| data | object | 기관이 소득 명세 저장 요청에 돌려준 응답 본문입니다. 저장한 금액과 환급 계산값이 기관 재조회 결과와 같음을 확인한 뒤에만 이 응답이 돌아오고, 다르면 오류로 끝납니다. | |
| warnings | array | 경고 문장의 목록입니다. 이 상품은 경고를 싣지 않아 항상 빈 배열입니다. | |
| outcome | string | 기관 쓰기가 확인됐는지를 가르는 판정입니다. 응답으로 돌아왔다면 항상 `confirmed` 입니다. 결과를 확인하지 못한 경우는 이 모양이 아니라 오류로 끝납니다. 작업 결과 판정이 이 자리를 읽습니다. | |
| action | string | 쓰기 액션의 이름입니다. 이 액션은 항상 `hometax.tax.withholding.late_report.detail_save` 입니다. 작업 결과 판정이 이 자리를 읽습니다. | |
| notices | array | 저장은 됐지만 고객에게 알려야 하는 안내의 목록입니다. 안내가 있을 때만 이 칸이 있고, 없으면 칸 자체가 없습니다. 안내 코드는 `LATE_PENALTY_NOTICE`, `REFUND_SELECTION_NOTICE` 중 하나입니다. | |
| notices[]. | string | 안내의 코드입니다. | |
| notices[]. | string | 안내를 알리는 한국어 문장입니다. |
// result.data - 값 자리에는 각 칸의 형식을 적었습니다 (실제 값이 아닙니다)
{
"success": "<boolean>",
"step": "<string>",
"state": "<string>",
"snapshot": {},
"snapshot_hash": "<string>",
"data": {},
"warnings": [],
"outcome": "<string>",
"action": "<string>",
"notices": [
{
"code": "<string>",
"message": "<string>"
}
]
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| VALIDATION_ | 요청 칸이 빠졌거나 칸 값이 이 단계의 요청 형식에 맞지 않으면 홈택스에 아무것도 보내지 않고 이 오류로 끝납니다. 빠진 칸이 있으면 error.message 는 「요청에 필요한 값이 빠졌습니다. 빠진 값: 칸 이름. 그 값을 넣어 다시 요청해 주세요.」 꼴이고, 그 밖의 검사에 걸린 칸이 있으면 「요청 값이 올바르지 않습니다. 확인할 값: 칸 이름. 값을 고쳐 다시 요청해 주세요.」 꼴이며, 둘 다 있으면 두 문장이 차례로 이어집니다. 칸 이름 자리에는 걸린 칸이 다섯까지 쉼표로 이어지고 더 있으면 「외 N개」 가 붙으며, 목록이나 객체 안의 칸은 「바깥 칸.0.안쪽 칸」 처럼 위치를 점으로 이은 경로로 적습니다. 걸린 검사가 모두 칸 하나를 짚지 않고 요청 전체를 보는 것이면 「요청 값이 올바르지 않습니다.」 만 옵니다. | |
| RESOURCE_ | 이어 받을 이전 작업(source_job_id)이 같은 조직과 환경에서 성공한 이 신고 유형의 작업이 아니거나, 그 결과를 읽을 수 없거나, 결과에 작성 스냅샷이 없거나 스냅샷이 expected_snapshot_hash 와 다르면 홈택스에 보내기 전에 이 오류로 끝납니다. error.message 는 걸린 확인의 문장 하나이고, BE 문장은 「이 신고 유형에서 성공한 이전 단계 작업이 필요합니다」, 「이전 작업의 작성 스냅샷이 없습니다」, 「작성 내용이 바뀌었습니다. 최신 결과를 다시 확인해 주세요」, 「같은 조직·환경에서 성공한 이전 단계의 작업이 필요합니다」, 「이전 작업의 JSON 결과를 읽을 수 없습니다」 입니다. | |
| RESOURCE_ | 작업 상태나 이어 받은 내용, 또는 홈택스에 있는 신고서의 상태가 이 단계와 맞지 않으면 이 오류로 끝납니다. 이 단계에서 이 코드로 끝나는 확인의 BE 문장은 「현재 작성 상태에서는 이 단계를 실행할 수 없습니다. 최신 결과를 확인해 주세요」, 「기관이 현재 신고서의 불러오기를 허용하지 않았습니다」, 「기관이 다른 작성 건을 반환했습니다」, 「불러온 신고서의 식별자가 다릅니다」, 「불러온 신고서의 기간·유형이 다릅니다」, 「불러온 신고서의 사업자가 다릅니다」, 「기관의 신고서가 다른 작성 건으로 바뀌었습니다」, 「승인한 뒤 기관 작성 내용이 변경됐습니다. 최신 내용을 다시 확인해 주세요」, 「저장한 금액이 기관 재조회 결과와 다릅니다. 재저장하지 말고 작성 내용을 확인해 주세요」, 「저장한 환급 계산값이 기관 재조회 결과와 다릅니다. 재저장하지 말고 작성 내용을 확인해 주세요」 이고, 걸린 확인의 문장 하나가 error.message 로 실립니다. | |
| AUTH_ | 저장된 기관 세션이 없습니다. 같은 연동 계정으로 hometax.session.login 을 먼저 실행해 세션을 연 뒤 다시 보냅니다. |
57. 원천세 기한후신고 신고 내역 조회hometax. tax. withholding. late_ report. history
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 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 길이 | 필수 | 설명 |
|---|---|---|---|---|---|
| business_ | string | - | Y | 신고 내역을 조회할 사업자의 사업자등록번호입니다. 하이픈 없이 숫자 10자리로 입력합니다 | |
| start_ | string | 8 | Y | 조회 기간의 시작일입니다. 여덟 자리의 실제 날짜로 입력하며 end_date 보다 늦으면 입력 오류로 거절합니다 | |
| end_ | string | - | Y | 조회 기간의 종료일입니다. 형식은 start_date 와 같고 start_date 보다 빠를 수 없습니다 | |
| page_ | number | - | N | 받을 쪽 번호입니다. 1부터 세는 정수이고 입력하지 않으면 1 입니다 | |
| page_ | number | - | N | 한 쪽에 받을 신고 수입니다. 1 이상 100 이하의 정수이고 입력하지 않으면 10 입니다 |
- 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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: history-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "hometax",
"action": "hometax.tax.withholding.late_report.history",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {
"business_no": "<필수>",
"start_date": "<필수>",
"end_date": "<필수>"
}
}'Response
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| success | boolean | 단계가 끝났는지입니다. 응답으로 돌아왔다면 항상 true 입니다. 실패는 이 모양이 아니라 오류 응답으로 옵니다. | |
| step | string | 응답이 어느 단계의 결과인지입니다. 이 액션은 항상 `history` 입니다. | |
| data | object | 조회 결과 객체입니다. rows 는 요청한 기간의 원천세 신고 목록입니다. 부른 단계의 신고 종류와 관계없이 정기신고, 수정신고, 기한후신고를 가리지 않고 모두 오므로 필요한 신고는 세부 구분 코드(detail_code)로 골라 씁니다. 신고마다 담는 값은 접수번호(receipt_no), 신고 건 식별번호(filing_reference), 귀속연월(attribution_ym), 지급연월(payment_ym), 신고 종류 코드(return_kind_code), 신고 종류 이름(return_kind_name), 세부 구분 코드(detail_code), 세부 구분 이름(detail_name), 사업자등록번호(business_no), 접수일(receipt_date), 신고일(filing_date), 제출연월(submit_ym), 최종 신고 여부(is_final_filing), 차감 납부세액(payable_tax_amount), 납부 상태(payment_status), 첨부서류 접수 건수 표기(attachment_receipt_text), 삭제신청 가능 여부 안내(deletion_eligibility_reason), 상호(business_name) 입니다. 연월은 여섯 자리, 접수일과 신고일은 연월일 여덟 자리이며 값은 기관이 준 그대로이고 없는 값은 null 입니다. 최종 신고 여부만 true 또는 false 로 옮기며 기관 값이 없으면 null 입니다. page 는 페이지 번호(page_num), 페이지 크기(page_size), 전체 건수(total_count)이고 기관이 페이지 정보를 주지 않으면 세 값 모두 null 입니다. |
// result.data - 값 자리에는 각 칸의 형식을 적었습니다 (실제 값이 아닙니다)
{
"success": "<boolean>",
"step": "<string>",
"data": {}
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| VALIDATION_ | 요청 칸이 빠졌거나 칸 값이 이 단계의 요청 형식에 맞지 않으면 홈택스에 아무것도 보내지 않고 이 오류로 끝납니다. 빠진 칸이 있으면 error.message 는 「요청에 필요한 값이 빠졌습니다. 빠진 값: 칸 이름. 그 값을 넣어 다시 요청해 주세요.」 꼴이고, 그 밖의 검사에 걸린 칸이 있으면 「요청 값이 올바르지 않습니다. 확인할 값: 칸 이름. 값을 고쳐 다시 요청해 주세요.」 꼴이며, 둘 다 있으면 두 문장이 차례로 이어집니다. 칸 이름 자리에는 걸린 칸이 다섯까지 쉼표로 이어지고 더 있으면 「외 N개」 가 붙으며, 목록이나 객체 안의 칸은 「바깥 칸.0.안쪽 칸」 처럼 위치를 점으로 이은 경로로 적습니다. 걸린 검사가 모두 칸 하나를 짚지 않고 요청 전체를 보는 것이면 「요청 값이 올바르지 않습니다.」 만 옵니다. | |
| AUTH_ | 저장된 기관 세션이 없습니다. 같은 연동 계정으로 hometax.session.login 을 먼저 실행해 세션을 연 뒤 다시 보냅니다. |
58. 원천세 기한후신고 초안 초기화hometax. tax. withholding. late_ report. init
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 와 함께 쓰지 않습니다. |
- 대괄호 []는 목록의 각 항목을, 점은 객체의 속성을, {key}는 실제 키로 바꿔 넣는 사전 항목을 뜻하며, 선택인 부모를 보낼 때 하위 필수 칸은 조건부로 표시합니다.
| 순번 | 변수명 | 타입 | 길이 | 필수 | 설명 |
|---|---|---|---|---|---|
| business_ | string | - | Y | 신고할 사업자등록번호 10자리 | |
| periods | object | - | Y | 신고 기간 세 값을 담은 객체입니다. submitYm(제출연월), attrYm(귀속연월), pymnYm(지급연월)을 각각 YYYYMM 여섯 자리로 입력하고, 귀속연월이 지급연월보다 늦거나 지급연월이 제출연월보다 늦으면 입력 오류로 거절합니다. JSON 문자열이 아니라 객체로 입력하며 문자열이면 입력 오류로 거절합니다 | |
| periods. | string | 6 | Y | 제출연월입니다. 신고서를 제출하는 연월을 여섯 자리로 입력합니다. 별칭 submitYm 로도 보낼 수 있습니다. 문자열 패턴: "^\\d{4}(0[1-9]|1[0-2])$" | |
| periods. | string | 6 | Y | 귀속연월입니다. 소득이 귀속되는 연월을 여섯 자리로 입력합니다. 작성 준비(init)에서는 지급연월보다 늦으면 입력 오류로 거절합니다. 별칭 attrYm 로도 보낼 수 있습니다. 문자열 패턴: "^\\d{4}(0[1-9]|1[0-2])$" | |
| periods. | string | 6 | Y | 지급연월입니다. 소득을 지급한 연월을 여섯 자리로 입력합니다. 작성 준비(init)에서는 제출연월보다 늦으면 입력 오류로 거절합니다. 별칭 pymnYm 로도 보낼 수 있습니다. 문자열 패턴: "^\\d{4}(0[1-9]|1[0-2])$" | |
| draft_ | string | - | N | 작성 방식입니다. new(기본값)는 새 신고서를 작성하고 resume 은 기관에 저장해 둔 작성 중 신고서를 이어서 씁니다. new 인데 기관에 작성 중인 신고가 이미 있으면 그것을 지우지 않고 409 로 거절하므로, 이어 쓰려면 resume 으로 다시 부릅니다. 다른 값은 입력 오류로 거절합니다 |
- 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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: init-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "hometax",
"action": "hometax.tax.withholding.late_report.init",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {
"business_no": "<필수>",
"periods": {
"submit_ym": "<필수>",
"attr_ym": "<필수>",
"pymn_ym": "<필수>"
}
}
}'Response
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| success | boolean | 단계가 끝났는지입니다. 응답으로 돌아왔다면 항상 true 입니다. 실패는 이 모양이 아니라 오류 응답으로 옵니다. | |
| step | string | 응답이 어느 단계의 결과인지입니다. 이 액션은 항상 `init` 입니다. | |
| state | string | 이 단계가 끝난 뒤 작업이 놓인 상태입니다. `initialized` 입니다. | |
| snapshot | object | 이 단계가 끝난 작업 상태의 사본입니다. 다음 단계가 이어받는 값이라 직접 고치지 않습니다. | |
| snapshot_ | string | snapshot 의 해시(SHA-256, 16진수 64자)입니다. 다음 단계를 부를 때 expected_snapshot_hash 에 그대로 넣고, 이 작업의 job_id 는 source_job_id 에 넣습니다. 그 사이 작업 상태가 바뀌었으면 거절됩니다. | |
| data | object | 작성 시작 결과 묶음입니다. 기관에서 작성 건을 준비하고 그 식별자와 읽어 온 값을 담습니다. 기관이 작성을 확인하지 않으면 이 모양이 아니라 오류로 끝납니다. | |
| data. | string | 기관이 이 작성 건에 붙인 신고서 식별자입니다. 새로 작성하는 건은 기관이 첫 기본정보 저장 때 식별자를 주므로 그전에는 빈 문자열입니다. | |
| data. | object | 기관에서 읽어 채운 기본정보와 소득 명세 초안입니다. 조회의 `prefill` 종류와 같은 칸을 가집니다. | |
| data. | object | 기관에서 읽은 신고 기본사항입니다. 사업자 정보(taxpayer), 선택한 소득종류(selectedIncomeTypes), 신고 구분(report)을 담고, 기관 응답에 없는 값은 비어 있습니다. 기본정보를 저장할 때 그대로 쓸 수 있습니다. | |
| data. | object | 기관에서 읽은 소득 명세 초안입니다. incomeSections 아래에 소득종류별로 행(code 와 금액 칸)을 담습니다. | |
| data. | array | 더 받아야 하는 칸의 경로 목록입니다. 비어 있는 기본정보 항목의 경로와, 금액을 숫자로 읽지 못한 항목의 경로가 함께 들어 있습니다. 모두 갖췄으면 빈 배열입니다. | |
| data. | array | 고객에게 물어볼 질문의 목록입니다. 작성 시작과 자동채움 조회에서는 missing_fields 마다 한 문장씩입니다. 저장 신고서 조회가 입력이 모자라거나 선택을 요청하는 응답에서는 문장이 아니라 `key`, `label_ko`, `required` 칸을 가진 객체의 목록입니다. | |
| data. | object | 읽은 값이 어디서 왔는지의 표입니다. 칸 경로가 키이고 출처 경로가 값입니다. 기관 데이터셋에서 읽었으면 `datasets.` 로, 요청으로 정했으면 `request.` 로 시작하고, 작업 정보에서 온 값은 `snapshot.` 으로 시작합니다. | |
| data. | object | 금액을 숫자로 읽지 못한 값의 표입니다. 칸 경로가 키이고 기관이 준 원래 값이 값입니다. 없으면 빈 객체입니다. | |
| data. | array | 아직 기관에서 읽지 못한 소득종류의 이름 목록입니다. 선택한 소득종류의 명세가 현재 작성 건에 아직 없을 때 들어갑니다. | |
| data. | boolean | 소득 명세를 모두 읽었는지입니다. unread_sections 가 비어 있으면 true 입니다. | |
| warnings | array | 경고 문장의 목록입니다. 이 상품은 경고를 싣지 않아 항상 빈 배열입니다. | |
| outcome | string | 기관 쓰기가 확인됐는지를 가르는 판정입니다. 응답으로 돌아왔다면 항상 `confirmed` 입니다. 결과를 확인하지 못한 경우는 이 모양이 아니라 오류로 끝납니다. 작업 결과 판정이 이 자리를 읽습니다. | |
| action | string | 쓰기 액션의 이름입니다. 이 액션은 항상 `hometax.tax.withholding.late_report.init` 입니다. 작업 결과 판정이 이 자리를 읽습니다. |
// result.data - 값 자리에는 각 칸의 형식을 적었습니다 (실제 값이 아닙니다)
{
"success": "<boolean>",
"step": "<string>",
"state": "<string>",
"snapshot": {},
"snapshot_hash": "<string>",
"data": {
"rtnCvaId": "<string>",
"prefill": {
"basic_document": {},
"detail_document": {},
"missing_fields": [],
"inputs": [],
"field_sources": {},
"unresolved_values": {},
"unread_sections": [],
"detail_loaded": "<boolean>"
}
},
"warnings": [],
"outcome": "<string>",
"action": "<string>"
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| VALIDATION_ | 요청 칸이 빠졌거나 칸 값이 이 단계의 요청 형식에 맞지 않으면 홈택스에 아무것도 보내지 않고 이 오류로 끝납니다. 빠진 칸이 있으면 error.message 는 「요청에 필요한 값이 빠졌습니다. 빠진 값: 칸 이름. 그 값을 넣어 다시 요청해 주세요.」 꼴이고, 그 밖의 검사에 걸린 칸이 있으면 「요청 값이 올바르지 않습니다. 확인할 값: 칸 이름. 값을 고쳐 다시 요청해 주세요.」 꼴이며, 둘 다 있으면 두 문장이 차례로 이어집니다. 칸 이름 자리에는 걸린 칸이 다섯까지 쉼표로 이어지고 더 있으면 「외 N개」 가 붙으며, 목록이나 객체 안의 칸은 「바깥 칸.0.안쪽 칸」 처럼 위치를 점으로 이은 경로로 적습니다. 걸린 검사가 모두 칸 하나를 짚지 않고 요청 전체를 보는 것이면 「요청 값이 올바르지 않습니다.」 만 옵니다. | |
| RESOURCE_ | 작업 상태나 이어 받은 내용, 또는 홈택스에 있는 신고서의 상태가 이 단계와 맞지 않으면 이 오류로 끝납니다. 이 단계에서 이 코드로 끝나는 확인의 BE 문장은 「기관이 현재 신고 기간·유형으로 작성을 허용하지 않았습니다 (판정 코드)」, 「작성 중인 신고가 있습니다. 이어서 작성하거나 작성 취소 후 새로 시작해 주세요」, 「이어서 작성할 신고서가 없습니다. 새로 시작해 주세요.」, 「지금 상태에서는 진행할 수 없습니다. 신고서 상태를 확인한 뒤 다시 시도해 주세요.」, 「기관에서 다른 신고 식별자를 반환했습니다」, 「기관 조회 회사와 작성 중인 회사의 사업자등록번호가 다릅니다」 이고, 걸린 확인의 문장 하나가 error.message 로 실립니다. 문장의 판정 코드 자리에는 홈택스가 신고서 상태 확인에서 돌려준 판정 코드가 들어갑니다. | |
| AUTH_ | 저장된 기관 세션이 없습니다. 같은 연동 계정으로 hometax.session.login 을 먼저 실행해 세션을 연 뒤 다시 보냅니다. |
59. 원천세 기한후신고 작성 참고자료 조회hometax. tax. withholding. late_ report. lookup
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 와 함께 쓰지 않습니다. |
- 대괄호 []는 목록의 각 항목을, 점은 객체의 속성을, {key}는 실제 키로 바꿔 넣는 사전 항목을 뜻하며, 선택인 부모를 보낼 때 하위 필수 칸은 조건부로 표시합니다.
| 순번 | 변수명 | 타입 | 길이 | 필수 | 설명 |
|---|---|---|---|---|---|
| source_ | string | - | N | 현재 신고서의 이전 단계 작업 job_id 입니다(job_ 으로 시작하는 작업 번호). query.kind 가 saved_returns 이면 생략할 수 있고 다른 조회에는 필요하며, 입력할 때는 expected_snapshot_hash 와 함께 입력해야 하고 하나만 입력하면 입력 오류로 거절합니다. 같은 조직과 환경, 같은 기관 연결에서 이 신고 유형으로 성공한 작업이어야 하고 아니면 진행하지 않고 거절하며, 받지 않는 작성 상태의 결과이면 409 로 거절합니다 | |
| expected_ | string | - | N | source_job_id 와 함께 입력하는 값입니다. source_job_id 작업 결과의 snapshot_hash 를 그대로 입력합니다(소문자 16진수 64자리). 그 작업의 내용과 맞지 않으면 진행하지 않고 작성 내용이 바뀌었다는 오류(409)로 거절합니다 | |
| query | object | - | Y | 조회 종류와 조건을 담은 객체입니다. kind 로 종류를 고르며, saved_returns 는 기관에 저장해 둔 작성 중 신고서를 찾거나 불러오고, prefill 은 현재 신고서를 기관에서 다시 읽어 자동 채움 값을 돌려주고, paid_tax 는 기납부 명세를, surcharge 는 미납세액의 가산세를 조회하고, annex_rows 는 현재 신고서의 부표 행을 읽습니다. 어느 종류도 기관에 저장하거나 제출하지 않습니다. 종류마다 받는 칸은 요구사항 조회(requirements) 결과의 actions 아래 lookup 항목 schema 에 있고, 모르는 kind 는 입력 오류로 거절합니다. JSON 문자열이 아니라 객체로 입력하며 문자열이면 입력 오류로 거절합니다 | |
| query. | string | - | Y | 조회 종류입니다. paid_tax 로 입력하면 기납부 명세를 조회합니다. 고정값: "paid_tax" | |
| query. | string | 6 | Y | 조회할 귀속연월입니다. 여섯 자리로 입력하며, 현재 신고서 제출연도의 5년 전 1월보다 이르면 입력 오류로 거절합니다. 별칭 txnrmYm 로도 보낼 수 있습니다. 문자열 패턴: "^\\d{4}(0[1-9]|1[0-2])$" | |
| query. | string | 6 | Y | 조회할 지급연월입니다. 여섯 자리로 입력하며, 귀속연월보다 이르면 입력 오류로 거절합니다. 별칭 pymnYm 로도 보낼 수 있습니다. 문자열 패턴: "^\\d{4}(0[1-9]|1[0-2])$" | |
| query. | string | - | Y | 조회할 소득구분 코드입니다. 현재 신고서의 기관 코드 목록에 있는 값이어야 하고 없으면 입력 오류로 거절합니다. 별칭 whtxIncClCd 로도 보낼 수 있습니다. 최소 길이: 1 | |
| query. | string | - | Y | 조회할 원천징수소득코드입니다. 고른 소득구분에 속한 기관 코드여야 하고 A05, A06, A27, A28 은 받지 않으며, 아니면 입력 오류로 거절합니다. 별칭 whtxIncCd 로도 보낼 수 있습니다. 최소 길이: 1 | |
| query. | string | - | Y | 조회 종류입니다. surcharge 로 입력하면 미납세액의 가산세를 조회합니다. 고정값: "surcharge" | |
| query. | number | - | Y | 가산세를 계산할 미납세액(원)입니다. 0 보다 큰 10원 단위 정수로 입력하며, 10원 단위가 아니면 값을 바꾸지 않고 입력 오류로 거절합니다. 별칭 npmtTxamt 로도 보낼 수 있습니다 | |
| query. | string | 8 | Y | 미납세액의 원래 납부기한입니다. 여덟 자리의 실제 날짜로 입력하며, 오늘보다 이전이고 최근 10년 이내이며 납부일보다 이전이어야 합니다. 아니면 입력 오류로 거절합니다. 별칭 pmtDdt 로도 보낼 수 있습니다. 문자열 패턴: "^\\d{8}$" | |
| query. | string | 8 | Y | 실제로 납부할 날짜입니다. 여덟 자리의 실제 날짜로 입력하며, 오늘이거나 그 뒤여야 하고 아니면 입력 오류로 거절합니다. 별칭 pmtDt 로도 보낼 수 있습니다. 문자열 패턴: "^\\d{8}$" | |
| query. | string | - | Y | 조회 종류입니다. prefill 로 입력하면 현재 신고서를 기관에서 다시 읽어 자동 채움 값을 돌려주며, 다른 칸은 받지 않습니다. 고정값: "prefill" | |
| query. | string | - | Y | 조회 종류입니다. saved_returns 로 입력하면 기관에 저장해 둔 작성 중 신고서를 찾고, load 를 true 로 주거나 returnId 를 주면 불러옵니다. 고정값: "saved_returns" | |
| query. | string | - | N | 이전 작업에 있으면 생략합니다. 문자열 패턴: "^\\d{10}$". 생략 시 기본값: null | |
| query. | object | - | N | 찾을 신고서의 제출연월, 귀속연월, 지급연월입니다. 이전 작업에 있으면 생략하고, 함께 입력하면 이전 작업의 기간과 같아야 하며 다르면 409 로 거절합니다. 생략 시 기본값: null | |
| query. | string | 6 | 조건부 | 제출연월입니다. 신고서를 제출하는 연월을 여섯 자리로 입력합니다. 별칭 submitYm 로도 보낼 수 있습니다. 문자열 패턴: "^\\d{4}(0[1-9]|1[0-2])$" | |
| query. | string | 6 | 조건부 | 귀속연월입니다. 소득이 귀속되는 연월을 여섯 자리로 입력합니다. 작성 준비(init)에서는 지급연월보다 늦으면 입력 오류로 거절합니다. 별칭 attrYm 로도 보낼 수 있습니다. 문자열 패턴: "^\\d{4}(0[1-9]|1[0-2])$" | |
| query. | string | 6 | 조건부 | 지급연월입니다. 소득을 지급한 연월을 여섯 자리로 입력합니다. 작성 준비(init)에서는 제출연월보다 늦으면 입력 오류로 거절합니다. 별칭 pymnYm 로도 보낼 수 있습니다. 문자열 패턴: "^\\d{4}(0[1-9]|1[0-2])$" | |
| query. | string | - | N | 신고서 작성월 검색 시작. 생략하면 홈택스처럼 현재 월을 조회합니다. 문자열 패턴: "^\\d{4}(0[1-9]|1[0-2])$". 생략 시 기본값: null | |
| query. | string | - | N | 신고서 작성월 검색 종료. 귀속연월, 지급연월과 별개입니다. 문자열 패턴: "^\\d{4}(0[1-9]|1[0-2])$". 생략 시 기본값: null | |
| query. | string | - | N | 불러올 작성 중 신고서의 식별값입니다. load 없이 먼저 조회한 결과 choices 의 rtnCvaId 를 그대로 입력하면 그 신고서를 불러오고, 같은 사업자와 기간, 신고 유형의 목록에 없으면 409 로 거절합니다. 별칭 returnId 로도 보낼 수 있습니다. 최소 길이: 1. 최대 길이: 100. 생략 시 기본값: null | |
| query. | boolean | - | N | 불러올 신고서가 하나면 자동 선택합니다. 여러 개면 목록에서 선택합니다. 생략 시 기본값: false | |
| query. | string | - | Y | 조회 종류입니다. annex_rows 로 입력하면 현재 신고서의 부표 행을 읽습니다. 고정값: "annex_rows" | |
| query. | string | - | Y | 현재 작성 건의 부표를 읽습니다. 반환한 row_targets의 row_index와 expected_row_hash로 수정하거나 삭제할 대상을 지정합니다. 허용값: ["income_persons", "annex", "refund", "previous_refund", "paid_tax", "refund_succession"] |
- 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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: lookup-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "hometax",
"action": "hometax.tax.withholding.late_report.lookup",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {
"query": {
"kind": "<필수>",
"txnrm_ym": "<필수>",
"pymn_ym": "<필수>",
"whtx_inc_cl_cd": "<필수>",
"whtx_inc_cd": "<필수>",
"npmt_txamt": "<필수: number>",
"pmt_ddt": "<필수>",
"pmt_dt": "<필수>",
"annex_kind": "<필수>"
}
}
}'Response
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| success | boolean | 단계가 끝났는지입니다. 응답으로 돌아왔다면 항상 true 입니다. 실패는 이 모양이 아니라 오류 응답으로 옵니다. | |
| step | string | 응답이 어느 단계의 결과인지입니다. 이 액션은 항상 `lookup` 입니다. | |
| state | string | 조회가 끝난 뒤 작업이 놓인 상태입니다. 입력이 모자라 기관에 가지 않았으면 `needs_input`, 후보 신고서 목록을 돌려주면 `selection_required`, 그 밖에는 이어받은 작업의 현재 상태입니다. | |
| snapshot | object | 조회가 끝난 작업 상태의 사본입니다. 다음 단계가 이어받는 값이라 직접 고치지 않습니다. 입력이 모자라 기관에 가지 않은 응답(state 가 `needs_input`)에는 이 칸이 없습니다. | |
| snapshot_ | string | snapshot 의 해시(SHA-256, 16진수 64자)입니다. 다음 단계를 부를 때 expected_snapshot_hash 에 그대로 넣고, 이 작업의 job_id 는 source_job_id 에 넣습니다. 입력이 모자라 기관에 가지 않은 응답(state 가 `needs_input`)에는 이 칸이 없습니다. | |
| data | object | 조회 결과 묶음입니다. 칸은 조회 종류(kind)마다 다릅니다. 아래 칸마다 어느 종류에서 오는지 적었습니다. | |
| data. | string | 조회 종류입니다. `saved_returns`, `prefill`, `paid_tax`, `annex_rows`, `surcharge` 중 하나이고, 요청한 query.kind 와 같습니다. | |
| data. | object | 기관의 응답 본문입니다. 기납부세액 조회(`paid_tax`), 가산세 계산(`surcharge`), 부표 행 조회(`annex_rows`)에만 있습니다. | |
| data. | number | 계산한 가산세 합계(원)입니다. 가산세 계산(`surcharge`)에만 있습니다. 기관이 준 계산 행의 가산세액을 더해 10원 미만을 버린 값이고, 기관이 한도를 적용했으면 한도액에서 10원 미만을 버린 값입니다. | |
| data. | string | 읽은 부표의 종류입니다. `income_persons`, `annex`, `refund`, `previous_refund`, `paid_tax`, `refund_succession` 중 하나이고 요청한 값과 같습니다. 부표 행 조회(`annex_rows`)에만 있습니다. | |
| data. | object | 읽은 부표의 기관 데이터셋입니다. 데이터셋 이름이 키인 객체입니다. 부표 행 조회(`annex_rows`)에만 있습니다. | |
| data. | object | 수정하거나 지울 수 있는 부표 행의 표입니다. 데이터셋 이름이 키이고 행의 목록이 값이며, 행마다 `row_index`, `expected_row_hash`, `values` 를 가집니다. 부표를 저장할 때 row_index 와 expected_row_hash 로 대상 행을 지정합니다. 부표 행 조회(`annex_rows`)에만 있습니다. | |
| data. | object | 기관에서 읽은 신고 기본사항입니다. 사업자 정보(taxpayer), 선택한 소득종류(selectedIncomeTypes), 신고 구분(report)을 담고, 기관 응답에 없는 값은 비어 있습니다. 기본정보를 저장할 때 그대로 쓸 수 있습니다. | |
| data. | object | 기관에서 읽은 소득 명세 초안입니다. incomeSections 아래에 소득종류별로 행(code 와 금액 칸)을 담습니다. | |
| data. | array | 더 받아야 하는 칸의 경로 목록입니다. 비어 있는 기본정보 항목의 경로와, 금액을 숫자로 읽지 못한 항목의 경로가 함께 들어 있습니다. 모두 갖췄으면 빈 배열입니다. | |
| data. | array | 고객에게 물어볼 질문의 목록입니다. 작성 시작과 자동채움 조회에서는 missing_fields 마다 한 문장씩입니다. 저장 신고서 조회가 입력이 모자라거나 선택을 요청하는 응답에서는 문장이 아니라 `key`, `label_ko`, `required` 칸을 가진 객체의 목록입니다. | |
| data. | object | 읽은 값이 어디서 왔는지의 표입니다. 칸 경로가 키이고 출처 경로가 값입니다. 기관 데이터셋에서 읽었으면 `datasets.` 로, 요청으로 정했으면 `request.` 로 시작하고, 작업 정보에서 온 값은 `snapshot.` 으로 시작합니다. | |
| data. | object | 금액을 숫자로 읽지 못한 값의 표입니다. 칸 경로가 키이고 기관이 준 원래 값이 값입니다. 없으면 빈 객체입니다. | |
| data. | array | 아직 기관에서 읽지 못한 소득종류의 이름 목록입니다. 선택한 소득종류의 명세가 현재 작성 건에 아직 없을 때 들어갑니다. | |
| data. | boolean | 소득 명세를 모두 읽었는지입니다. unread_sections 가 비어 있으면 true 입니다. | |
| data. | boolean | 기관에 저장을 실행했는지입니다. 조회는 저장하지 않아 항상 false 입니다. 자동채움 조회(`prefill`)와 저장 신고서 조회(`saved_returns`)에만 있습니다. | |
| data. | boolean | 기관에 제출을 실행했는지입니다. 조회는 제출하지 않아 항상 false 입니다. 자동채움 조회(`prefill`)와, 신고서를 불러온 저장 신고서 조회(`saved_returns`)에만 있습니다. | |
| data. | string | 읽어 온 작성 건의 신고서 식별자입니다. 자동채움 조회(`prefill`)와, 신고서를 불러온 저장 신고서 조회(`saved_returns`)에만 있습니다. | |
| data. | array | 저장 신고서 조회에서 조건에 맞는 작성 중 신고서의 목록입니다. 기관이 준 행을 그대로 담습니다. 후보 목록을 돌려주는 응답(state 가 `selection_required`)에만 있습니다. | |
| data. | boolean | 고객이 신고서 하나를 골라야 하는지입니다. choices 가 둘 이상이면 true 입니다. 후보 목록을 돌려주는 응답(state 가 `selection_required`)에만 있습니다. | |
| data. | boolean | 기관을 불렀는지입니다. 입력이 모자라 기관에 가지 않은 응답(state 가 `needs_input`)에만 있고 항상 false 입니다. | |
| data. | boolean | 이미 있던 저장 신고서를 불러왔는지입니다. 신고서를 불러온 저장 신고서 조회(`saved_returns`)에만 있고 항상 true 입니다. | |
| warnings | array | 경고 문장의 목록입니다. 이 조회는 경고를 싣지 않아 항상 빈 배열입니다. 입력이 모자라 기관에 가지 않은 응답(state 가 `needs_input`)에는 이 칸이 없습니다. |
// result.data - 값 자리에는 각 칸의 형식을 적었습니다 (실제 값이 아닙니다)
{
"success": "<boolean>",
"step": "<string>",
"state": "<string>",
"snapshot": {},
"snapshot_hash": "<string>",
"data": {
"kind": "<string>",
"provider": {},
"calculated_surcharge": "<number>",
"annex_kind": "<string>",
"datasets": {},
"row_targets": {},
"basic_document": {},
"detail_document": {},
"missing_fields": [],
"inputs": [],
"field_sources": {},
"unresolved_values": {},
"unread_sections": [],
"detail_loaded": "<boolean>",
"save_executed": "<boolean>",
"submit_executed": "<boolean>",
"loaded_return_id": "<string>",
"choices": [],
"selection_required": "<boolean>",
"institution_called": "<boolean>",
"reused_existing_return": "<boolean>"
},
"warnings": []
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| VALIDATION_ | 요청 칸이 빠졌거나 칸 값이 이 단계의 요청 형식에 맞지 않으면 홈택스에 아무것도 보내지 않고 이 오류로 끝납니다. 빠진 칸이 있으면 error.message 는 「요청에 필요한 값이 빠졌습니다. 빠진 값: 칸 이름. 그 값을 넣어 다시 요청해 주세요.」 꼴이고, 그 밖의 검사에 걸린 칸이 있으면 「요청 값이 올바르지 않습니다. 확인할 값: 칸 이름. 값을 고쳐 다시 요청해 주세요.」 꼴이며, 둘 다 있으면 두 문장이 차례로 이어집니다. 칸 이름 자리에는 걸린 칸이 다섯까지 쉼표로 이어지고 더 있으면 「외 N개」 가 붙으며, 목록이나 객체 안의 칸은 「바깥 칸.0.안쪽 칸」 처럼 위치를 점으로 이은 경로로 적습니다. 걸린 검사가 모두 칸 하나를 짚지 않고 요청 전체를 보는 것이면 「요청 값이 올바르지 않습니다.」 만 옵니다. | |
| RESOURCE_ | 이어 받을 이전 작업(source_job_id)이 같은 조직과 환경에서 성공한 이 신고 유형의 작업이 아니거나, 그 결과를 읽을 수 없거나, 결과에 작성 스냅샷이 없거나 스냅샷이 expected_snapshot_hash 와 다르면 홈택스에 보내기 전에 이 오류로 끝납니다. error.message 는 걸린 확인의 문장 하나이고, BE 문장은 「이 신고 유형에서 성공한 이전 단계 작업이 필요합니다」, 「이전 작업의 작성 스냅샷이 없습니다」, 「작성 내용이 바뀌었습니다. 최신 결과를 다시 확인해 주세요」, 「같은 조직·환경에서 성공한 이전 단계의 작업이 필요합니다」, 「이전 작업의 JSON 결과를 읽을 수 없습니다」 입니다. | |
| RESOURCE_ | 작업 상태나 이어 받은 내용, 또는 홈택스에 있는 신고서의 상태가 이 단계와 맞지 않으면 이 오류로 끝납니다. 이 단계에서 이 코드로 끝나는 확인의 BE 문장은 「이전 작업과 사업자가 다릅니다」, 「이전 작업과 신고기간이 다릅니다」, 「조회 중 기관의 전체 건수가 변경됐습니다」, 「현재 회사·기간·유형의 작성 중 신고서를 찾지 못했습니다」, 「기관이 해당 저장 신고서의 불러오기를 허용하지 않았습니다」, 「기관이 다른 신고서를 반환했습니다」, 「현재 작성 상태에서는 이 단계를 실행할 수 없습니다. 최신 결과를 확인해 주세요」, 「기관이 현재 신고서의 불러오기를 허용하지 않았습니다」, 「기관이 다른 작성 건을 반환했습니다」, 「불러온 신고서의 식별자가 다릅니다」, 「불러온 신고서의 기간·유형이 다릅니다」, 「불러온 신고서의 사업자가 다릅니다」, 「기관의 신고서가 다른 작성 건으로 바뀌었습니다」, 「승인한 뒤 기관 작성 내용이 변경됐습니다. 최신 내용을 다시 확인해 주세요」, 「기관 조회 회사와 작성 중인 회사의 사업자등록번호가 다릅니다」, 「목록과 불러온 신고서의 납세자가 다릅니다」, 「명세 조회 결과의 신고서 식별자가 다릅니다」, 「기납부 명세의 신고서가 현재 작성 건과 다릅니다」 이고, 걸린 확인의 문장 하나가 error.message 로 실립니다. | |
| AUTH_ | 저장된 기관 세션이 없습니다. 같은 연동 계정으로 hometax.session.login 을 먼저 실행해 세션을 연 뒤 다시 보냅니다. |
60. 원천세 기한후신고 제출 전 미리보기hometax. tax. withholding. late_ report. preview
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 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| source_ | string | Y | 이어서 진행할 이전 단계 작업의 job_id 를 그대로 입력합니다(job_ 으로 시작하는 작업 번호). 검토(review) 결과를 받고, 다시 볼 때는 미리보기(preview) 결과도 받습니다. 같은 조직과 환경, 같은 기관 연결에서 이 신고 유형으로 성공한 작업이어야 하고 아니면 진행하지 않고 거절하며, 받지 않는 작성 상태의 결과이면 409 로 거절합니다 | |
| expected_ | string | Y | source_job_id 작업 결과의 snapshot_hash 를 그대로 입력합니다(소문자 16진수 64자리). 그 작업의 내용과 맞지 않으면 진행하지 않고 작성 내용이 바뀌었다는 오류(409)로 거절합니다 |
- 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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: preview-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "hometax",
"action": "hometax.tax.withholding.late_report.preview",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {
"source_job_id": "<필수>",
"expected_snapshot_hash": "<필수>"
}
}'Response
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| success | boolean | 단계가 끝났는지입니다. 응답으로 돌아왔다면 항상 true 입니다. 실패는 이 모양이 아니라 오류 응답으로 옵니다. | |
| step | string | 응답이 어느 단계의 결과인지입니다. 이 액션은 항상 `preview` 입니다. | |
| state | string | 이 단계가 끝난 뒤 작업이 놓인 상태입니다. `previewed` 입니다. | |
| snapshot | object | 이 단계가 끝난 작업 상태의 사본입니다. 다음 단계가 이어받는 값이라 직접 고치지 않습니다. | |
| snapshot_ | string | snapshot 의 해시(SHA-256, 16진수 64자)입니다. 다음 단계를 부를 때 expected_snapshot_hash 에 그대로 넣고, 이 작업의 job_id 는 source_job_id 에 넣습니다. 그 사이 작업 상태가 바뀌었으면 거절됩니다. | |
| data | object | 미리보기 결과 묶음입니다. | |
| data. | object | 기관의 신고 금액 요약 응답 본문입니다. 제출 전에 고객에게 보여 줍니다. | |
| data. | boolean | 제출 전에 고객 확인이 필요한지입니다. 항상 true 입니다. | |
| warnings | array | 경고 문장의 목록입니다. 이 상품은 경고를 싣지 않아 항상 빈 배열입니다. |
// result.data - 값 자리에는 각 칸의 형식을 적었습니다 (실제 값이 아닙니다)
{
"success": "<boolean>",
"step": "<string>",
"state": "<string>",
"snapshot": {},
"snapshot_hash": "<string>",
"data": {
"summary": {},
"requires_confirmation": "<boolean>"
},
"warnings": []
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| VALIDATION_ | 요청 칸이 빠졌거나 칸 값이 이 단계의 요청 형식에 맞지 않으면 홈택스에 아무것도 보내지 않고 이 오류로 끝납니다. 빠진 칸이 있으면 error.message 는 「요청에 필요한 값이 빠졌습니다. 빠진 값: 칸 이름. 그 값을 넣어 다시 요청해 주세요.」 꼴이고, 그 밖의 검사에 걸린 칸이 있으면 「요청 값이 올바르지 않습니다. 확인할 값: 칸 이름. 값을 고쳐 다시 요청해 주세요.」 꼴이며, 둘 다 있으면 두 문장이 차례로 이어집니다. 칸 이름 자리에는 걸린 칸이 다섯까지 쉼표로 이어지고 더 있으면 「외 N개」 가 붙으며, 목록이나 객체 안의 칸은 「바깥 칸.0.안쪽 칸」 처럼 위치를 점으로 이은 경로로 적습니다. 걸린 검사가 모두 칸 하나를 짚지 않고 요청 전체를 보는 것이면 「요청 값이 올바르지 않습니다.」 만 옵니다. | |
| RESOURCE_ | 이어 받을 이전 작업(source_job_id)이 같은 조직과 환경에서 성공한 이 신고 유형의 작업이 아니거나, 그 결과를 읽을 수 없거나, 결과에 작성 스냅샷이 없거나 스냅샷이 expected_snapshot_hash 와 다르면 홈택스에 보내기 전에 이 오류로 끝납니다. error.message 는 걸린 확인의 문장 하나이고, BE 문장은 「이 신고 유형에서 성공한 이전 단계 작업이 필요합니다」, 「이전 작업의 작성 스냅샷이 없습니다」, 「작성 내용이 바뀌었습니다. 최신 결과를 다시 확인해 주세요」, 「같은 조직·환경에서 성공한 이전 단계의 작업이 필요합니다」, 「이전 작업의 JSON 결과를 읽을 수 없습니다」 입니다. | |
| RESOURCE_ | 작업 상태나 이어 받은 내용, 또는 홈택스에 있는 신고서의 상태가 이 단계와 맞지 않으면 이 오류로 끝납니다. 이 단계에서 이 코드로 끝나는 확인의 BE 문장은 「현재 작성 상태에서는 이 단계를 실행할 수 없습니다. 최신 결과를 확인해 주세요」, 「기관이 현재 신고서의 불러오기를 허용하지 않았습니다」, 「기관이 다른 작성 건을 반환했습니다」, 「불러온 신고서의 식별자가 다릅니다」, 「불러온 신고서의 기간·유형이 다릅니다」, 「불러온 신고서의 사업자가 다릅니다」, 「기관의 신고서가 다른 작성 건으로 바뀌었습니다」, 「승인한 뒤 기관 작성 내용이 변경됐습니다. 최신 내용을 다시 확인해 주세요」 이고, 걸린 확인의 문장 하나가 error.message 로 실립니다. | |
| AUTH_ | 저장된 기관 세션이 없습니다. 같은 연동 계정으로 hometax.session.login 을 먼저 실행해 세션을 연 뒤 다시 보냅니다. |
61. 원천세 기한후신고 접수증 조회hometax. tax. withholding. late_ report. receipt
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 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| source_ | string | Y | 이어서 진행할 이전 단계 작업의 job_id 를 그대로 입력합니다(job_ 으로 시작하는 작업 번호). 접수 결과를 찾을 신고서의 작업이면 작성 상태는 묻지 않으므로 제출(submit) 결과나, 제출 결과를 확인하지 못했을 때는 미리보기(preview) 결과를 입력합니다. 같은 조직과 환경, 같은 기관 연결에서 이 신고 유형으로 성공한 작업이어야 하고 아니면 진행하지 않고 거절합니다 | |
| expected_ | string | Y | source_job_id 작업 결과의 snapshot_hash 를 그대로 입력합니다(소문자 16진수 64자리). 그 작업의 내용과 맞지 않으면 진행하지 않고 작성 내용이 바뀌었다는 오류(409)로 거절합니다 |
- 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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: receipt-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "hometax",
"action": "hometax.tax.withholding.late_report.receipt",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {
"source_job_id": "<필수>",
"expected_snapshot_hash": "<필수>"
}
}'Response
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| success | boolean | 단계가 끝났는지입니다. 응답으로 돌아왔다면 항상 true 입니다. 실패는 이 모양이 아니라 오류 응답으로 옵니다. | |
| step | string | 응답이 어느 단계의 결과인지입니다. 이 액션은 항상 `receipt` 입니다. | |
| state | string | 이 단계가 끝난 뒤 작업이 놓인 상태입니다. `submitted` 입니다. | |
| snapshot | object | 이 단계가 끝난 작업 상태의 사본입니다. 다음 단계가 이어받는 값이라 직접 고치지 않습니다. | |
| snapshot_ | string | snapshot 의 해시(SHA-256, 16진수 64자)입니다. 다음 단계를 부를 때 expected_snapshot_hash 에 그대로 넣고, 이 작업의 job_id 는 source_job_id 에 넣습니다. 그 사이 작업 상태가 바뀌었으면 거절됩니다. | |
| data | object | 접수증 조회 결과 묶음입니다. 같은 사업자의 해당 월 접수 목록에서 이 신고서의 접수번호를 확인한 뒤에만 돌아옵니다. | |
| data. | object | 기관 접수증 본문입니다. 해당 신고서의 접수번호와 접수일이 확인된 경우에만 돌아옵니다. 확인하지 못하면 오류로 끝납니다. | |
| warnings | array | 경고 문장의 목록입니다. 이 상품은 경고를 싣지 않아 항상 빈 배열입니다. |
// result.data - 값 자리에는 각 칸의 형식을 적었습니다 (실제 값이 아닙니다)
{
"success": "<boolean>",
"step": "<string>",
"state": "<string>",
"snapshot": {},
"snapshot_hash": "<string>",
"data": {
"receipt": {}
},
"warnings": []
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| VALIDATION_ | 요청 칸이 빠졌거나 칸 값이 이 단계의 요청 형식에 맞지 않으면 홈택스에 아무것도 보내지 않고 이 오류로 끝납니다. 빠진 칸이 있으면 error.message 는 「요청에 필요한 값이 빠졌습니다. 빠진 값: 칸 이름. 그 값을 넣어 다시 요청해 주세요.」 꼴이고, 그 밖의 검사에 걸린 칸이 있으면 「요청 값이 올바르지 않습니다. 확인할 값: 칸 이름. 값을 고쳐 다시 요청해 주세요.」 꼴이며, 둘 다 있으면 두 문장이 차례로 이어집니다. 칸 이름 자리에는 걸린 칸이 다섯까지 쉼표로 이어지고 더 있으면 「외 N개」 가 붙으며, 목록이나 객체 안의 칸은 「바깥 칸.0.안쪽 칸」 처럼 위치를 점으로 이은 경로로 적습니다. 걸린 검사가 모두 칸 하나를 짚지 않고 요청 전체를 보는 것이면 「요청 값이 올바르지 않습니다.」 만 옵니다. | |
| RESOURCE_ | 이어 받을 이전 작업(source_job_id)이 같은 조직과 환경에서 성공한 이 신고 유형의 작업이 아니거나, 그 결과를 읽을 수 없거나, 결과에 작성 스냅샷이 없거나 스냅샷이 expected_snapshot_hash 와 다르면 홈택스에 보내기 전에 이 오류로 끝납니다. error.message 는 걸린 확인의 문장 하나이고, BE 문장은 「이 신고 유형에서 성공한 이전 단계 작업이 필요합니다」, 「이전 작업의 작성 스냅샷이 없습니다」, 「작성 내용이 바뀌었습니다. 최신 결과를 다시 확인해 주세요」, 「같은 조직·환경에서 성공한 이전 단계의 작업이 필요합니다」, 「이전 작업의 JSON 결과를 읽을 수 없습니다」 입니다. | |
| RESOURCE_ | 작업 상태나 이어 받은 내용, 또는 홈택스에 있는 신고서의 상태가 이 단계와 맞지 않으면 이 오류로 끝납니다. 이 단계에서 이 코드로 끝나는 확인의 BE 문장은 「조회 중 접수 목록이 변경됐습니다」, 「동일 회사·기간의 접수 내역을 확인하지 못했습니다」, 「해당 신고의 접수번호·접수일을 확인하지 못했습니다. 재제출하지 말고 접수 목록을 확인해 주세요」 이고, 걸린 확인의 문장 하나가 error.message 로 실립니다. | |
| AUTH_ | 저장된 기관 세션이 없습니다. 같은 연동 계정으로 hometax.session.login 을 먼저 실행해 세션을 연 뒤 다시 보냅니다. |
62. 원천세 기한후신고 준비자료 안내hometax. tax. withholding. late_ report. requirements
MCP 도구 이름 hometax__
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
원천세 기한후신고에 필요한 입력과 준비자료를 단계별로 알려 드립니다. 기관에 접속하지 않습니다.
- 이 API 는 기관 연동과 기관 로그인이 필요 없습니다. 기관 자격증명을 등록하지 않아도 호출할 수 있고, 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 | 호출할 작업입니다.
| |
| 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: requirements-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "hometax",
"action": "hometax.tax.withholding.late_report.requirements",
"params": {}
}'Response
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| success | boolean | 단계가 끝났는지입니다. 응답으로 돌아왔다면 항상 true 입니다. 실패는 이 모양이 아니라 오류 응답으로 옵니다. | |
| step | string | 응답이 어느 단계의 결과인지입니다. 이 액션은 항상 `requirements` 입니다. | |
| data | object | 필요입력 안내 묶음입니다. 기관에 가지 않고 이 신고의 요청 계약에서 바로 만들며, 저장이나 제출은 일어나지 않습니다. | |
| data. | array | 단계마다 받아야 하는 입력의 목록입니다. 이 신고의 모든 단계(액션)의 요청 계약에서 입력 칸마다 한 줄씩 만듭니다. 안쪽 칸을 가진 객체 입력은 안쪽 칸마다 한 줄이고, 그 key 는 점으로 이은 경로입니다. | |
| data. | string | 이 입력을 받는 단계의 이름입니다. 단계 이름은 actions 의 키와 같습니다. | |
| data. | string | 입력 칸의 이름입니다. 요청 본문에 이 이름으로 보냅니다. 안쪽 칸이면 `상위.하위` 꼴입니다. | |
| data. | string | 입력 칸의 한국어 이름입니다. | |
| data. | string | 입력을 누가 채우는지 구분입니다. `institution` 또는 `customer` 중 하나입니다. 앞의 값은 사업자 정보처럼 기관 조회로 확인하는 칸이고 뒤의 값은 고객이 정하는 칸입니다. | |
| data. | boolean | 꼭 보내야 하는 입력인지입니다. 안쪽 칸은 바깥 객체와 안쪽 칸이 모두 필수일 때만 true 입니다. | |
| data. | string | 입력 값의 종류입니다. `string` 또는 `choice` 또는 `number` 또는 `date` 또는 `array` 또는 `object` 또는 `file` 중 하나입니다. `choice` 는 true 나 false 같은 정해진 선택지 중 하나를 뜻합니다. | |
| data. | null | 이미 채워 둔 값입니다. 이 안내는 값을 채우지 않아 항상 null 입니다. | |
| data. | array | 고를 수 있는 값의 목록입니다. 선택지가 정해진 입력에만 있고 아니면 빈 배열입니다. | |
| data. | boolean | 이 입력에 별도 동의가 필요한지입니다. 이 안내는 항상 false 로 돌려줍니다. | |
| data. | string | 입력 값의 출처 문구입니다. `기관 조회` 또는 `사용자 입력` 중 하나입니다. 앞의 값은 tier 가 기관 조회로 확인하는 칸일 때 쓰입니다. | |
| data. | string | 이 입력을 어떻게 채우는지 알리는 한국어 안내 문장입니다. | |
| data. | boolean | 이 입력이 없으면 진행이 막히는지입니다. required 와 같은 값입니다. | |
| data. | boolean | 채워야 하는데 비어 있는 입력이 있는지입니다. blocking_reasons 가 하나라도 있으면 true 입니다. 이 안내는 값을 채우지 않아 필수 입력이 있으면 항상 true 입니다. | |
| data. | array | 진행을 막는 입력마다 한 줄씩 담은 목록입니다. 필수이면서 채워 둔 값이 없는 입력이 대상입니다. | |
| data. | string | 막힌 입력을 받는 단계의 이름입니다. | |
| data. | string | 막힌 입력의 이름입니다. inputs 의 key 와 같습니다. | |
| data. | string | 막힌 까닭을 알리는 한국어 문장입니다. 입력 이름 뒤에 「입력이 필요합니다.」 가 붙는 꼴입니다. | |
| data. | object | 이 안내가 아무것도 실행하지 않았다는 표시 묶음입니다. | |
| data. | boolean | 이 안내가 입력 설명만 한다는 표시입니다. 항상 true 입니다. | |
| data. | boolean | 기관에 저장을 실행했는지입니다. 이 안내는 저장하지 않아 항상 false 입니다. | |
| data. | boolean | 기관에 제출을 실행했는지입니다. 이 안내는 제출하지 않아 항상 false 입니다. | |
| data. | string | 신고 가족 이름입니다. 이 액션은 항상 `late_report` 입니다. | |
| data. | string | 신고 상세 구분 코드입니다. 이 액션은 항상 `03` 입니다. | |
| data. | object | 단계(액션)마다 요청 계약을 담은 객체입니다. 단계 이름이 키이고, 값은 필수 입력 이름의 목록(required)과 요청 본문의 JSON 스키마(schema)입니다. | |
| data. | array | 제출할 때 고객에게 받아야 하는 확인 입력의 이름 목록입니다. `confirmSubmit`, `sbmsAgreement` 가 들어 있습니다. | |
| data. | array | 기관에서 아직 동작을 확인하지 못해 쓰지 못하는 쓰기 액션의 전체 이름 목록입니다. 쓰기 액션에서 열려 있는 것을 뺀 나머지를 이름순으로 담습니다. | |
| data. | boolean | 기관에 쓰는 단계가 기본으로 열려 있는지를 알리는 표시입니다. 이 안내는 항상 false 로 돌려줍니다. |
// result.data - 값 자리에는 각 칸의 형식을 적었습니다 (실제 값이 아닙니다)
{
"success": "<boolean>",
"step": "<string>",
"data": {
"inputs": [
{
"action": "<string>",
"key": "<string>",
"label_ko": "<string>",
"tier": "<string>",
"required": "<boolean>",
"value_type": "<string>",
"provided_value": null,
"options": [],
"consent_required": "<boolean>",
"source": "<string>",
"how_to_ko": "<string>",
"blocks_progress": "<boolean>"
}
],
"blocked": "<boolean>",
"blocking_reasons": [
{
"action": "<string>",
"key": "<string>",
"reason_ko": "<string>"
}
],
"safety": {
"input_only": "<boolean>",
"save_executed": "<boolean>",
"submit_executed": "<boolean>"
},
"family": "<string>",
"detail_code": "<string>",
"actions": {},
"confirmation_fields": [],
"unmeasured_actions": [],
"institution_writes_enabled_by_default": "<boolean>"
}
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| VALIDATION_ | 요청 칸이 빠졌거나 칸 값이 이 단계의 요청 형식에 맞지 않으면 홈택스에 아무것도 보내지 않고 이 오류로 끝납니다. 빠진 칸이 있으면 error.message 는 「요청에 필요한 값이 빠졌습니다. 빠진 값: 칸 이름. 그 값을 넣어 다시 요청해 주세요.」 꼴이고, 그 밖의 검사에 걸린 칸이 있으면 「요청 값이 올바르지 않습니다. 확인할 값: 칸 이름. 값을 고쳐 다시 요청해 주세요.」 꼴이며, 둘 다 있으면 두 문장이 차례로 이어집니다. 칸 이름 자리에는 걸린 칸이 다섯까지 쉼표로 이어지고 더 있으면 「외 N개」 가 붙으며, 목록이나 객체 안의 칸은 「바깥 칸.0.안쪽 칸」 처럼 위치를 점으로 이은 경로로 적습니다. 걸린 검사가 모두 칸 하나를 짚지 않고 요청 전체를 보는 것이면 「요청 값이 올바르지 않습니다.」 만 옵니다. |
63. 원천세 기한후신고 저장 내용 검토hometax. tax. withholding. late_ report. review
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 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| source_ | string | Y | 이어서 진행할 이전 단계 작업의 job_id 를 그대로 입력합니다(job_ 으로 시작하는 작업 번호). 기본정보 저장(basic_save), 명세 저장(detail_save), 부표 저장(annex_save) 결과를 받고, 다시 검토할 때는 검토(review) 결과도 받습니다. 같은 조직과 환경, 같은 기관 연결에서 이 신고 유형으로 성공한 작업이어야 하고 아니면 진행하지 않고 거절하며, 받지 않는 작성 상태의 결과이면 409 로 거절합니다 | |
| expected_ | string | Y | source_job_id 작업 결과의 snapshot_hash 를 그대로 입력합니다(소문자 16진수 64자리). 그 작업의 내용과 맞지 않으면 진행하지 않고 작성 내용이 바뀌었다는 오류(409)로 거절합니다 | |
| refund_ | string | N | 환급받을 은행의 코드입니다. 숫자 세 자리로 입력합니다. 기본정보의 환급신청 여부가 Y 인 신고서를 검토할 때만 쓰며, 그때 은행 코드와 계좌번호가 모두 있어야 하고 없으면 거절합니다 | |
| refund_ | string | N | 환급받을 계좌번호입니다. 하이픈 없이 숫자만 1자리에서 20자리까지 입력합니다. 기본정보의 환급신청 여부가 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: review-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "hometax",
"action": "hometax.tax.withholding.late_report.review",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {
"source_job_id": "<필수>",
"expected_snapshot_hash": "<필수>"
}
}'Response
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| success | boolean | 단계가 끝났는지입니다. 응답으로 돌아왔다면 항상 true 입니다. 실패는 이 모양이 아니라 오류 응답으로 옵니다. | |
| step | string | 응답이 어느 단계의 결과인지입니다. 이 액션은 항상 `review` 입니다. | |
| state | string | 이 단계가 끝난 뒤 작업이 놓인 상태입니다. `reviewed` 입니다. | |
| snapshot | object | 이 단계가 끝난 작업 상태의 사본입니다. 다음 단계가 이어받는 값이라 직접 고치지 않습니다. | |
| snapshot_ | string | snapshot 의 해시(SHA-256, 16진수 64자)입니다. 다음 단계를 부를 때 expected_snapshot_hash 에 그대로 넣고, 이 작업의 job_id 는 source_job_id 에 넣습니다. 그 사이 작업 상태가 바뀌었으면 거절됩니다. | |
| data | object | 검증 결과 묶음입니다. 기관의 내용검증이 끝났을 때만 돌아오고, 끝나지 않았으면 오류로 끝납니다. | |
| data. | object | 기관의 신고서 요약 응답 본문입니다. | |
| data. | object | 기관의 내용검증 응답 본문입니다. 검증 결과 코드가 `10` 이거나 `30` 일 때만 돌아옵니다. | |
| data. | object | 다음 단계로 가도 되는지를 알리는 묶음입니다. | |
| data. | boolean | 경고 없이 제출 단계로 갈 수 있는지입니다. 검증 결과 코드가 `10` 이면 true 입니다. | |
| data. | boolean | 기관의 검증 경고를 고객이 확인해야 하는지입니다. 검증 결과 코드가 `30` 이면 true 이고, 이때 제출 단계에 confirmWarnings 를 true 로 보내야 합니다. | |
| warnings | array | 경고 문장의 목록입니다. 이 상품은 경고를 싣지 않아 항상 빈 배열입니다. | |
| outcome | string | 기관 쓰기가 확인됐는지를 가르는 판정입니다. 응답으로 돌아왔다면 항상 `confirmed` 입니다. 결과를 확인하지 못한 경우는 이 모양이 아니라 오류로 끝납니다. 작업 결과 판정이 이 자리를 읽습니다. | |
| action | string | 쓰기 액션의 이름입니다. 이 액션은 항상 `hometax.tax.withholding.late_report.review` 입니다. 작업 결과 판정이 이 자리를 읽습니다. |
// result.data - 값 자리에는 각 칸의 형식을 적었습니다 (실제 값이 아닙니다)
{
"success": "<boolean>",
"step": "<string>",
"state": "<string>",
"snapshot": {},
"snapshot_hash": "<string>",
"data": {
"summary": {},
"validation": {},
"workflow_gate": {
"can_submit": "<boolean>",
"warnings_confirmation_required": "<boolean>"
}
},
"warnings": [],
"outcome": "<string>",
"action": "<string>"
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| VALIDATION_ | 요청 칸이 빠졌거나 칸 값이 이 단계의 요청 형식에 맞지 않으면 홈택스에 아무것도 보내지 않고 이 오류로 끝납니다. 빠진 칸이 있으면 error.message 는 「요청에 필요한 값이 빠졌습니다. 빠진 값: 칸 이름. 그 값을 넣어 다시 요청해 주세요.」 꼴이고, 그 밖의 검사에 걸린 칸이 있으면 「요청 값이 올바르지 않습니다. 확인할 값: 칸 이름. 값을 고쳐 다시 요청해 주세요.」 꼴이며, 둘 다 있으면 두 문장이 차례로 이어집니다. 칸 이름 자리에는 걸린 칸이 다섯까지 쉼표로 이어지고 더 있으면 「외 N개」 가 붙으며, 목록이나 객체 안의 칸은 「바깥 칸.0.안쪽 칸」 처럼 위치를 점으로 이은 경로로 적습니다. 걸린 검사가 모두 칸 하나를 짚지 않고 요청 전체를 보는 것이면 「요청 값이 올바르지 않습니다.」 만 옵니다. | |
| RESOURCE_ | 이어 받을 이전 작업(source_job_id)이 같은 조직과 환경에서 성공한 이 신고 유형의 작업이 아니거나, 그 결과를 읽을 수 없거나, 결과에 작성 스냅샷이 없거나 스냅샷이 expected_snapshot_hash 와 다르면 홈택스에 보내기 전에 이 오류로 끝납니다. error.message 는 걸린 확인의 문장 하나이고, BE 문장은 「이 신고 유형에서 성공한 이전 단계 작업이 필요합니다」, 「이전 작업의 작성 스냅샷이 없습니다」, 「작성 내용이 바뀌었습니다. 최신 결과를 다시 확인해 주세요」, 「같은 조직·환경에서 성공한 이전 단계의 작업이 필요합니다」, 「이전 작업의 JSON 결과를 읽을 수 없습니다」 입니다. | |
| RESOURCE_ | 작업 상태나 이어 받은 내용, 또는 홈택스에 있는 신고서의 상태가 이 단계와 맞지 않으면 이 오류로 끝납니다. 이 단계에서 이 코드로 끝나는 확인의 BE 문장은 「현재 작성 상태에서는 이 단계를 실행할 수 없습니다. 최신 결과를 확인해 주세요」, 「기관이 현재 신고서의 불러오기를 허용하지 않았습니다」, 「기관이 다른 작성 건을 반환했습니다」, 「불러온 신고서의 식별자가 다릅니다」, 「불러온 신고서의 기간·유형이 다릅니다」, 「불러온 신고서의 사업자가 다릅니다」, 「기관의 신고서가 다른 작성 건으로 바뀌었습니다」, 「승인한 뒤 기관 작성 내용이 변경됐습니다. 최신 내용을 다시 확인해 주세요」, 「명세 조회 결과의 신고서 식별자가 다릅니다」, 「기관 내용검증이 완료되지 않았습니다. 검증 오류를 확인해 주세요」 이고, 걸린 확인의 문장 하나가 error.message 로 실립니다. | |
| AUTH_ | 저장된 기관 세션이 없습니다. 같은 연동 계정으로 hometax.session.login 을 먼저 실행해 세션을 연 뒤 다시 보냅니다. |
64. 원천세 기한후신고 제출hometax. tax. withholding. late_ report. submit
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 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| source_ | string | Y | 이어서 진행할 이전 단계 작업의 job_id 를 그대로 입력합니다(job_ 으로 시작하는 작업 번호). 미리보기(preview) 결과를 받습니다. 같은 조직과 환경, 같은 기관 연결에서 이 신고 유형으로 성공한 작업이어야 하고 아니면 진행하지 않고 거절하며, 받지 않는 작성 상태의 결과이면 409 로 거절합니다 | |
| expected_ | string | Y | source_job_id 작업 결과의 snapshot_hash 를 그대로 입력합니다(소문자 16진수 64자리). 그 작업의 내용과 맞지 않으면 진행하지 않고 작성 내용이 바뀌었다는 오류(409)로 거절합니다 | |
| confirmSubmit | boolean | Y | 신고서를 실제로 제출한다는 확인값입니다. 미리보기(preview) 결과를 사용자에게 보여 주고 제출 동의를 받았을 때 true 로 입력합니다. true 가 아니면(빠지거나 false) 기관에 아무것도 보내지 않고 신고서 제출 확인이 필요하다는 오류(400)로 거절합니다. 이 값도 확인 토큰이 가리키는 요청 본문에 들어가므로 확인 토큰을 받는 첫 요청부터 함께 입력합니다. 나중에 더하면 본문이 달라져 확인 토큰을 다시 받아야 합니다. 1 이나 yes, on 처럼 true 로 읽히는 값도 true 로 받고, true 나 false 로 읽을 수 없는 값은 입력 오류로 거절합니다 | |
| sbmsAgreement | boolean | Y | 신고 내용에 동의한다는 확인값입니다. 사용자에게 신고 내용 동의를 받았을 때 true 로 입력하며, true 가 아니면(빠지거나 false) 기관에 아무것도 보내지 않고 신고서 제출 동의가 필요하다는 오류(400)로 거절합니다. 이 값은 기관에 보내지 않고 제출 전 확인에만 씁니다. 이 값도 확인 토큰이 가리키는 요청 본문에 들어가므로 확인 토큰을 받는 첫 요청부터 함께 입력합니다. 나중에 더하면 본문이 달라져 확인 토큰을 다시 받아야 합니다. 1 이나 yes, on 처럼 true 로 읽히는 값도 true 로 받고, true 나 false 로 읽을 수 없는 값은 입력 오류로 거절합니다 | |
| confirmWarnings | boolean | N | 기관 검증 경고를 확인했다는 값입니다. 검토(review) 결과의 workflow_gate.warnings_confirmation_required 가 true 였던 신고서는 이 값이 true 여야 제출하고, 아니면 기관에 아무것도 보내지 않고 검증 경고를 확인해 달라는 오류(422)로 거절합니다. 경고 없이 검토를 통과한 신고서(workflow_gate.can_submit 이 true)에는 필요 없습니다. 이 값도 확인 토큰이 가리키는 요청 본문에 들어가므로 확인 토큰을 받는 첫 요청부터 함께 입력합니다. 나중에 더하면 본문이 달라져 확인 토큰을 다시 받아야 합니다. 1 이나 yes, on 처럼 true 로 읽히는 값도 true 로 받고, true 나 false 로 읽을 수 없는 값은 입력 오류로 거절합니다 | |
| confirmation_ | string | N | 1회용 확인 토큰입니다. 처음에는 보내지 않습니다. 토큰 없이 부르면 기관에 아무것도 보내지 않고 작업도 만들지 않은 채 확인이 필요하다는 오류(WRITE_CONFIRMATION_REQUIRED)로 끝나고, 응답의 error.confirmation_token 에 토큰이 옵니다. error.message 의 안내를 사용자에게 보여 주고 동의를 받은 뒤 같은 요청에 이 토큰을 넣어 다시 부릅니다. 토큰은 10분 안에 한 번만 쓸 수 있고 처음 요청과 같은 본문, 같은 호출자, 같은 환경에서만 맞으며, 아니면 확인이 만료됐거나 내용이 달라졌다는 오류로 거절합니다 |
- 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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: submit-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "hometax",
"action": "hometax.tax.withholding.late_report.submit",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {
"source_job_id": "<필수>",
"expected_snapshot_hash": "<필수>",
"confirmSubmit": "<필수: boolean>",
"sbmsAgreement": "<필수: boolean>"
}
}'Response
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| success | boolean | 단계가 끝났는지입니다. 응답으로 돌아왔다면 항상 true 입니다. 실패는 이 모양이 아니라 오류 응답으로 옵니다. | |
| step | string | 응답이 어느 단계의 결과인지입니다. 이 액션은 항상 `submit` 입니다. | |
| state | string | 이 단계가 끝난 뒤 작업이 놓인 상태입니다. `submitted` 입니다. | |
| snapshot | object | 이 단계가 끝난 작업 상태의 사본입니다. 다음 단계가 이어받는 값이라 직접 고치지 않습니다. | |
| snapshot_ | string | snapshot 의 해시(SHA-256, 16진수 64자)입니다. 다음 단계를 부를 때 expected_snapshot_hash 에 그대로 넣고, 이 작업의 job_id 는 source_job_id 에 넣습니다. 그 사이 작업 상태가 바뀌었으면 거절됩니다. | |
| data | object | 제출 결과 묶음입니다. 기관에서 접수번호를 확인한 뒤에만 돌아옵니다. | |
| data. | object | 기관 접수증 본문입니다. 해당 신고서의 접수번호와 접수일이 확인된 경우에만 돌아옵니다. 확인하지 못하면 오류로 끝납니다. | |
| data. | object | 제출 때 받은 고객 확인의 기록 묶음입니다. | |
| data. | boolean | 제출 확인을 받았는지입니다. 응답으로 돌아왔다면 항상 true 입니다. | |
| data. | boolean | 신고 내용 동의를 받았는지입니다. 응답으로 돌아왔다면 항상 true 입니다. | |
| data. | boolean | 신고 내용 동의를 기관 제출 본문에 실었는지입니다. 동의는 서버에서 확인하고 기관 제출 본문에는 싣지 않아 항상 false 입니다. | |
| data. | boolean | 고객이 기관의 검증 경고를 확인했는지입니다. 요청의 confirmWarnings 를 그대로 옮긴 값입니다. | |
| warnings | array | 경고 문장의 목록입니다. 이 상품은 경고를 싣지 않아 항상 빈 배열입니다. | |
| outcome | string | 기관 쓰기가 확인됐는지를 가르는 판정입니다. 응답으로 돌아왔다면 항상 `confirmed` 입니다. 결과를 확인하지 못한 경우는 이 모양이 아니라 오류로 끝납니다. 작업 결과 판정이 이 자리를 읽습니다. | |
| action | string | 쓰기 액션의 이름입니다. 이 액션은 항상 `hometax.tax.withholding.late_report.submit` 입니다. 작업 결과 판정이 이 자리를 읽습니다. |
// result.data - 값 자리에는 각 칸의 형식을 적었습니다 (실제 값이 아닙니다)
{
"success": "<boolean>",
"step": "<string>",
"state": "<string>",
"snapshot": {},
"snapshot_hash": "<string>",
"data": {
"receipt": {},
"submitUserAcknowledgements": {
"confirmSubmit": "<boolean>",
"sbmsAgreement": "<boolean>",
"sbmsAgreementInSubmitBody": "<boolean>",
"confirmWarnings": "<boolean>"
}
},
"warnings": [],
"outcome": "<string>",
"action": "<string>"
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| WRITE_ | 요청에 확인 토큰(confirmation_token)이 없으면 홈택스에 아무것도 보내지 않고 작업도 만들지 않은 채 이 오류로 끝납니다. error.message 는 「원천세 기한후신고서 제출은 되돌릴 수 없어 제출 전 확인이 필요합니다. 아래 내용을 사용자에게 보여주고 동의를 받으세요.」 로 시작하고 error.confirmation_token 에 1회용 토큰이 옵니다. 이 단계의 확인에는 미리보기 내용이 없어 error.preview 는 빈 객체입니다. 이 내용을 고객에게 그대로 보여 주고 확인을 받은 뒤, 같은 요청의 params.confirmation_token 에 응답의 error.confirmation_token 값을 넣어 다시 호출해 주세요. 토큰은 10분 안에 한 번만 쓸 수 있고, 확인한 요청 본문과 같은 본문에만 맞습니다. | |
| WRITE_ | 토큰이 만료됐거나, 이미 썼거나, 다른 호출자나 다른 환경에서 받은 것이거나, 확인한 요청 본문과 달라졌으면 홈택스에 아무것도 보내지 않고 작업도 만들지 않은 채 이 오류로 끝납니다. error.message 는 「확인이 만료됐거나 확인한 내용과 달라졌습니다. 다시 확인해 주세요.」 입니다. 토큰 없이 다시 요청하면 새 토큰을 받습니다. | |
| VALIDATION_ | 요청 칸이 빠졌거나 칸 값이 이 단계의 요청 형식에 맞지 않으면 홈택스에 아무것도 보내지 않고 이 오류로 끝납니다. 빠진 칸이 있으면 error.message 는 「요청에 필요한 값이 빠졌습니다. 빠진 값: 칸 이름. 그 값을 넣어 다시 요청해 주세요.」 꼴이고, 그 밖의 검사에 걸린 칸이 있으면 「요청 값이 올바르지 않습니다. 확인할 값: 칸 이름. 값을 고쳐 다시 요청해 주세요.」 꼴이며, 둘 다 있으면 두 문장이 차례로 이어집니다. 칸 이름 자리에는 걸린 칸이 다섯까지 쉼표로 이어지고 더 있으면 「외 N개」 가 붙으며, 목록이나 객체 안의 칸은 「바깥 칸.0.안쪽 칸」 처럼 위치를 점으로 이은 경로로 적습니다. 걸린 검사가 모두 칸 하나를 짚지 않고 요청 전체를 보는 것이면 「요청 값이 올바르지 않습니다.」 만 옵니다. | |
| RESOURCE_ | 이어 받을 이전 작업(source_job_id)이 같은 조직과 환경에서 성공한 이 신고 유형의 작업이 아니거나, 그 결과를 읽을 수 없거나, 결과에 작성 스냅샷이 없거나 스냅샷이 expected_snapshot_hash 와 다르면 홈택스에 보내기 전에 이 오류로 끝납니다. error.message 는 걸린 확인의 문장 하나이고, BE 문장은 「이 신고 유형에서 성공한 이전 단계 작업이 필요합니다」, 「이전 작업의 작성 스냅샷이 없습니다」, 「작성 내용이 바뀌었습니다. 최신 결과를 다시 확인해 주세요」, 「같은 조직·환경에서 성공한 이전 단계의 작업이 필요합니다」, 「이전 작업의 JSON 결과를 읽을 수 없습니다」 입니다. | |
| RESOURCE_ | 작업 상태나 이어 받은 내용, 또는 홈택스에 있는 신고서의 상태가 이 단계와 맞지 않으면 이 오류로 끝납니다. 이 단계에서 이 코드로 끝나는 확인의 BE 문장은 「현재 작성 상태에서는 이 단계를 실행할 수 없습니다. 최신 결과를 확인해 주세요」, 「기관이 현재 신고서의 불러오기를 허용하지 않았습니다」, 「기관이 다른 작성 건을 반환했습니다」, 「불러온 신고서의 식별자가 다릅니다」, 「불러온 신고서의 기간·유형이 다릅니다」, 「불러온 신고서의 사업자가 다릅니다」, 「기관의 신고서가 다른 작성 건으로 바뀌었습니다」, 「승인한 뒤 기관 작성 내용이 변경됐습니다. 최신 내용을 다시 확인해 주세요」, 「미리 본 금액과 현재 신고 내용이 다릅니다」, 「이미 접수번호가 있는 신고입니다. 다시 제출하지 말고 접수 결과를 조회해 주세요」 이고, 걸린 확인의 문장 하나가 error.message 로 실립니다. | |
| AUTH_ | 저장된 기관 세션이 없습니다. 같은 연동 계정으로 hometax.session.login 을 먼저 실행해 세션을 연 뒤 다시 보냅니다. | |
| PROVIDER_ | 제출 요청을 보내는 중이거나 보낸 뒤 홈택스의 접수 여부를 확인하지 못한 경우입니다. 자동으로 다시 시도하지 않습니다. error.message 는 「기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.」 입니다. |