증명서

납세·사업자 관련 증명서를 신청하고 발급 목록을 조회합니다.

1. 증명서 목록 조회hometax.certificate.list

MCP 도구 이름 hometax__certificate__list

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

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

발급 증명서 목록을 조회합니다.

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

Request

변수명	필수	설명
Authorization	Y	API 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다. 형식 : Basic base64("{client_id}:{client_secret}") [참고] 인증
X-Env-Scope	Y	호출 환경입니다. `sandbox`샌드박스 — 모의 응답 `real_test`데모 — 하루 100 사용 토큰 `production`정식 — 유료 플랜 전용 [참고] 환경
Idempotency-Key	Y	재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다. [참고] 재시도
Content-Type	Y	요청 본문 형식입니다. `application/json`고정값 (기본값)
X-Trace-Id	N	추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.

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

순번	변수명	타입	필수	설명
	page_num	number	N	페이지 번호 예시 : 1
	page_size	number	N	페이지 크기 예시 : 10

bash

curl --request POST \
  --url 'https://api.xdata.kr/v1/jobs' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: sandbox' \
  --header 'Idempotency-Key: demo-list-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "hometax",
  "action": "hometax.certificate.list",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "page_num": 1,
    "page_size": 10
  }
}'

Response

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

순번	변수명	설명
	items	증명서 행 배열 (cva_id, rcat_no, cva_knd_nm, state_nm, issue_stat_nm, rpt_pkg_pth, cerp_isn_qty)
	page	페이지 객체 (page_size, page_num, total_count)

json

// result.data
{
  "items": [
    {
      "cva_id": "...",
      "rcat_no": "...",
      "cva_knd_nm": "국세완납증명",
      "state_nm": "...",
      "issue_stat_nm": "..."
    }
  ],
  "page": { "page_size": 10, "page_num": 1, "total_count": 1 }
}

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

2. 국세납세증명 신청hometax.certificate.apply.national_tax_payment

MCP 도구 이름 hometax__certificate__apply__national_tax_payment

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

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

국세납세증명 신청을 신청합니다.

홈택스 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [홈택스 로그인(세션 생성)]
sandbox 환경에서는 실제 홈택스에 접속하지 않습니다. result.data 에는 mock: true 와 보낸 params 를 그대로 담은 params_echo 가 오고, 업무 응답 필드는 오지 않습니다.

Request

변수명	필수	설명
Authorization	Y	API 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다. 형식 : Basic base64("{client_id}:{client_secret}") [참고] 인증
X-Env-Scope	Y	호출 환경입니다. `sandbox`샌드박스 — 모의 응답 `real_test`데모 — 하루 100 사용 토큰 `production`정식 — 유료 플랜 전용 [참고] 환경
Idempotency-Key	Y	재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다. [참고] 재시도
Content-Type	Y	요청 본문 형식입니다. `application/json`고정값 (기본값)
X-Trace-Id	N	추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.

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

변수명	타입	필수	설명
tin	string	조건부	미입력 시 세션 사업자번호 사용
txpr_nm	string	조건부	미입력 시 세션 상호 사용
confirm	boolean	Y	실행 확인. 사용자에게 미리보기를 보여주고 동의를 받았을 때만 true 로 보낸다. 자동으로 채우지 않는다

bash

curl --request POST \
  --url 'https://api.xdata.kr/v1/jobs' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: sandbox' \
  --header 'Idempotency-Key: demo-national_tax_payment-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "hometax",
  "action": "hometax.certificate.apply.national_tax_payment",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "confirm": "<필수: boolean>"
  }
}'

Response

기관이 신청을 받았음을 확인한 경우에만 성공합니다. result.data.outcome 은 CONFIRMED 이고, 증명서 아이디(cvaId)와 접수번호(rcatNo)를 확인합니다.

순번	변수명	설명
	outcome	기관 처리 판정. 성공 응답에서는 항상 CONFIRMED 입니다
	action	요청한 액션 이름. outcome · action 외의 키는 홈택스 응답 본문에서 옵니다(기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다)
	cvaId	기관이 발번한 증명서 아이디. 홈택스가 내려주는 키 이름 그대로입니다
	rcatNo	기관이 발번한 접수번호. 홈택스가 내려주는 키 이름 그대로입니다

json

// result.data — outcome · action 외의 키는 홈택스 응답 본문에서 옵니다(기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다).
{
  "outcome": "CONFIRMED",
  "action": "hometax.certificate.apply.national_tax_payment",
  "cvaId": "...",
  "rcatNo": "..."
}

순번	오류 코드	발생 조건
	PROVIDER_OUTCOME_UNCONFIRMED	처리 확인 불가 — 요청은 홈택스로 전송됐지만 처리됐는지 확인하지 못했습니다. 이미 처리됐을 수 있으므로 다시 요청하지 않고, 오류 메시지가 안내하는 홈택스 화면에서 먼저 확인합니다.
	AUTH_REQUIRED	세션 없음 — 홈택스 세션이 없습니다. 홈택스 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다.
	PROVIDER_BUSINESS_ERROR	업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다.
	PROVIDER_VALIDATION_ERROR	업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다.
	PROVIDER_UNAVAILABLE	업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다.
	PROVIDER_UPSTREAM_ERROR	업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다.

3. 납세사실증명 신청hometax.certificate.apply.tax_payment_record

MCP 도구 이름 hometax__certificate__apply__tax_payment_record

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

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

납세사실증명 신청을 신청합니다.

홈택스 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [홈택스 로그인(세션 생성)]
sandbox 환경에서는 실제 홈택스에 접속하지 않습니다. result.data 에는 mock: true 와 보낸 params 를 그대로 담은 params_echo 가 오고, 업무 응답 필드는 오지 않습니다.

Request

변수명	필수	설명
Authorization	Y	API 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다. 형식 : Basic base64("{client_id}:{client_secret}") [참고] 인증
X-Env-Scope	Y	호출 환경입니다. `sandbox`샌드박스 — 모의 응답 `real_test`데모 — 하루 100 사용 토큰 `production`정식 — 유료 플랜 전용 [참고] 환경
Idempotency-Key	Y	재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다. [참고] 재시도
Content-Type	Y	요청 본문 형식입니다. `application/json`고정값 (기본값)
X-Trace-Id	N	추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.

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

변수명	타입	필수	설명
tin	string	조건부	미입력 시 세션 사업자번호 사용
txpr_nm	string	조건부	미입력 시 세션 상호 사용
confirm	boolean	Y	실행 확인. 사용자에게 미리보기를 보여주고 동의를 받았을 때만 true 로 보낸다. 자동으로 채우지 않는다

bash

curl --request POST \
  --url 'https://api.xdata.kr/v1/jobs' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: sandbox' \
  --header 'Idempotency-Key: demo-tax_payment_record-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "hometax",
  "action": "hometax.certificate.apply.tax_payment_record",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "confirm": "<필수: boolean>"
  }
}'

Response

기관이 신청을 받았음을 확인한 경우에만 성공합니다. result.data.outcome 은 CONFIRMED 이고, 증명서 아이디(cvaId)와 접수번호(rcatNo)를 확인합니다.

순번	변수명	설명
	outcome	기관 처리 판정. 성공 응답에서는 항상 CONFIRMED 입니다
	action	요청한 액션 이름. outcome · action 외의 키는 홈택스 응답 본문에서 옵니다(기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다)
	cvaId	기관이 발번한 증명서 아이디. 홈택스가 내려주는 키 이름 그대로입니다
	rcatNo	기관이 발번한 접수번호. 홈택스가 내려주는 키 이름 그대로입니다

json

// result.data — outcome · action 외의 키는 홈택스 응답 본문에서 옵니다(기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다).
{
  "outcome": "CONFIRMED",
  "action": "hometax.certificate.apply.tax_payment_record",
  "cvaId": "...",
  "rcatNo": "..."
}

순번	오류 코드	발생 조건
	PROVIDER_OUTCOME_UNCONFIRMED	처리 확인 불가 — 요청은 홈택스로 전송됐지만 처리됐는지 확인하지 못했습니다. 이미 처리됐을 수 있으므로 다시 요청하지 않고, 오류 메시지가 안내하는 홈택스 화면에서 먼저 확인합니다.
	AUTH_REQUIRED	세션 없음 — 홈택스 세션이 없습니다. 홈택스 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다.
	PROVIDER_BUSINESS_ERROR	업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다.
	PROVIDER_VALIDATION_ERROR	업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다.
	PROVIDER_UNAVAILABLE	업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다.
	PROVIDER_UPSTREAM_ERROR	업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다.

4. 부가가치세 과세표준증명 신청hometax.certificate.apply.vat_standard

MCP 도구 이름 hometax__certificate__apply__vat_standard

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

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

부가가치세 과세표준증명 신청을 신청합니다.

홈택스 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [홈택스 로그인(세션 생성)]
sandbox 환경에서는 실제 홈택스에 접속하지 않습니다. result.data 에는 mock: true 와 보낸 params 를 그대로 담은 params_echo 가 오고, 업무 응답 필드는 오지 않습니다.

Request

변수명	필수	설명
Authorization	Y	API 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다. 형식 : Basic base64("{client_id}:{client_secret}") [참고] 인증
X-Env-Scope	Y	호출 환경입니다. `sandbox`샌드박스 — 모의 응답 `real_test`데모 — 하루 100 사용 토큰 `production`정식 — 유료 플랜 전용 [참고] 환경
Idempotency-Key	Y	재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다. [참고] 재시도
Content-Type	Y	요청 본문 형식입니다. `application/json`고정값 (기본값)
X-Trace-Id	N	추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.

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

변수명	타입	필수	설명
tin	string	조건부	미입력 시 세션 사업자번호 사용
txpr_nm	string	조건부	미입력 시 세션 상호 사용
confirm	boolean	Y	실행 확인. 사용자에게 미리보기를 보여주고 동의를 받았을 때만 true 로 보낸다. 자동으로 채우지 않는다

bash

curl --request POST \
  --url 'https://api.xdata.kr/v1/jobs' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: sandbox' \
  --header 'Idempotency-Key: demo-vat_standard-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "hometax",
  "action": "hometax.certificate.apply.vat_standard",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "confirm": "<필수: boolean>"
  }
}'

Response

기관이 신청을 받았음을 확인한 경우에만 성공합니다. result.data.outcome 은 CONFIRMED 이고, 증명서 아이디(cvaId)와 접수번호(rcatNo)를 확인합니다.

순번	변수명	설명
	outcome	기관 처리 판정. 성공 응답에서는 항상 CONFIRMED 입니다
	action	요청한 액션 이름. outcome · action 외의 키는 홈택스 응답 본문에서 옵니다(기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다)
	cvaId	기관이 발번한 증명서 아이디. 홈택스가 내려주는 키 이름 그대로입니다
	rcatNo	기관이 발번한 접수번호. 홈택스가 내려주는 키 이름 그대로입니다

json

// result.data — outcome · action 외의 키는 홈택스 응답 본문에서 옵니다(기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다).
{
  "outcome": "CONFIRMED",
  "action": "hometax.certificate.apply.vat_standard",
  "cvaId": "...",
  "rcatNo": "..."
}

순번	오류 코드	발생 조건
	PROVIDER_OUTCOME_UNCONFIRMED	처리 확인 불가 — 요청은 홈택스로 전송됐지만 처리됐는지 확인하지 못했습니다. 이미 처리됐을 수 있으므로 다시 요청하지 않고, 오류 메시지가 안내하는 홈택스 화면에서 먼저 확인합니다.
	AUTH_REQUIRED	세션 없음 — 홈택스 세션이 없습니다. 홈택스 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다.
	PROVIDER_BUSINESS_ERROR	업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다.
	PROVIDER_VALIDATION_ERROR	업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다.
	PROVIDER_UNAVAILABLE	업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다.
	PROVIDER_UPSTREAM_ERROR	업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다.

5. 사업자등록 증명hometax.certificate.apply.business_registration

MCP 도구 이름 hometax__certificate__apply__business_registration

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

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

사업자등록 증명을 신청합니다.

홈택스 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [홈택스 로그인(세션 생성)]
sandbox 환경에서는 실제 홈택스에 접속하지 않습니다. result.data 에는 mock: true 와 보낸 params 를 그대로 담은 params_echo 가 오고, 업무 응답 필드는 오지 않습니다.

Request

변수명	필수	설명
Authorization	Y	API 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다. 형식 : Basic base64("{client_id}:{client_secret}") [참고] 인증
X-Env-Scope	Y	호출 환경입니다. `sandbox`샌드박스 — 모의 응답 `real_test`데모 — 하루 100 사용 토큰 `production`정식 — 유료 플랜 전용 [참고] 환경
Idempotency-Key	Y	재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다. [참고] 재시도
Content-Type	Y	요청 본문 형식입니다. `application/json`고정값 (기본값)
X-Trace-Id	N	추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.

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

변수명	타입	필수	설명
tin	string	조건부	미입력 시 세션 사업자번호 사용
txpr_nm	string	조건부	미입력 시 세션 상호 사용
confirm	boolean	Y	실행 확인. 사용자에게 미리보기를 보여주고 동의를 받았을 때만 true 로 보낸다. 자동으로 채우지 않는다

bash

curl --request POST \
  --url 'https://api.xdata.kr/v1/jobs' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: sandbox' \
  --header 'Idempotency-Key: demo-business_registration-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "hometax",
  "action": "hometax.certificate.apply.business_registration",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "confirm": "<필수: boolean>"
  }
}'

Response

기관이 신청을 받았음을 확인한 경우에만 성공합니다. result.data.outcome 은 CONFIRMED 이고, 증명서 아이디(cvaId)와 접수번호(rcatNo)를 확인합니다.

순번	변수명	설명
	outcome	기관 처리 판정. 성공 응답에서는 항상 CONFIRMED 입니다
	action	요청한 액션 이름. outcome · action 외의 키는 홈택스 응답 본문에서 옵니다(기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다)
	cvaId	기관이 발번한 증명서 아이디. 홈택스가 내려주는 키 이름 그대로입니다
	rcatNo	기관이 발번한 접수번호. 홈택스가 내려주는 키 이름 그대로입니다

json

// result.data — outcome · action 외의 키는 홈택스 응답 본문에서 옵니다(기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다).
{
  "outcome": "CONFIRMED",
  "action": "hometax.certificate.apply.business_registration",
  "cvaId": "...",
  "rcatNo": "..."
}

순번	오류 코드	발생 조건
	PROVIDER_OUTCOME_UNCONFIRMED	처리 확인 불가 — 요청은 홈택스로 전송됐지만 처리됐는지 확인하지 못했습니다. 이미 처리됐을 수 있으므로 다시 요청하지 않고, 오류 메시지가 안내하는 홈택스 화면에서 먼저 확인합니다.
	AUTH_REQUIRED	세션 없음 — 홈택스 세션이 없습니다. 홈택스 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다.
	PROVIDER_BUSINESS_ERROR	업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다.
	PROVIDER_VALIDATION_ERROR	업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다.
	PROVIDER_UNAVAILABLE	업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다.
	PROVIDER_UPSTREAM_ERROR	업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다.

6. 휴업사실증명hometax.certificate.apply.business_suspension

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

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

휴업사실증명을 신청합니다.

홈택스 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [홈택스 로그인(세션 생성)]
sandbox 환경에서는 실제 홈택스에 접속하지 않습니다. result.data 에는 mock: true 와 보낸 params 를 그대로 담은 params_echo 가 오고, 업무 응답 필드는 오지 않습니다.

Request

변수명	필수	설명
Authorization	Y	API 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다. 형식 : Basic base64("{client_id}:{client_secret}") [참고] 인증
X-Env-Scope	Y	호출 환경입니다. `sandbox`샌드박스 — 모의 응답 `real_test`데모 — 하루 100 사용 토큰 `production`정식 — 유료 플랜 전용 [참고] 환경
Idempotency-Key	Y	재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다. [참고] 재시도
Content-Type	Y	요청 본문 형식입니다. `application/json`고정값 (기본값)
X-Trace-Id	N	추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.

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

변수명	타입	길이	필수	설명
tin	string	-	조건부	미입력 시 세션 사업자번호 사용
txpr_nm	string	-	조건부	미입력 시 세션 상호 사용
bsno	string	-	Y	대상 사업자등록번호(숫자 10자리)
endYm	string	6	Y	조회 종료 연월() 형식 : YYYYMM
strtYm	string	6	Y	조회 시작 연월() 형식 : YYYYMM
confirm	boolean	-	Y	실행 확인. 사용자에게 미리보기를 보여주고 동의를 받았을 때만 true 로 보낸다. 자동으로 채우지 않는다

bash

curl --request POST \
  --url 'https://api.xdata.kr/v1/jobs' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: sandbox' \
  --header 'Idempotency-Key: demo-business_suspension-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "hometax",
  "action": "hometax.certificate.apply.business_suspension",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "bsno": "<필수>",
    "endYm": "<필수>",
    "strtYm": "<필수>",
    "confirm": "<필수: boolean>"
  }
}'

Response

기관이 신청을 받았음을 확인한 경우에만 성공합니다. result.data.outcome 은 CONFIRMED 이고, 증명서 아이디(cvaId)와 접수번호(rcatNo)를 확인합니다.

순번	변수명	설명
	outcome	기관 처리 판정. 성공 응답에서는 항상 CONFIRMED 입니다
	action	요청한 액션 이름. outcome · action 외의 키는 홈택스 응답 본문에서 옵니다(기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다)
	cvaId	기관이 발번한 증명서 아이디. 홈택스가 내려주는 키 이름 그대로입니다
	rcatNo	기관이 발번한 접수번호. 홈택스가 내려주는 키 이름 그대로입니다

json

// result.data — outcome · action 외의 키는 홈택스 응답 본문에서 옵니다(기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다).
{
  "outcome": "CONFIRMED",
  "action": "hometax.certificate.apply.business_suspension",
  "cvaId": "...",
  "rcatNo": "..."
}

순번	오류 코드	발생 조건
	PROVIDER_OUTCOME_UNCONFIRMED	처리 확인 불가 — 요청은 홈택스로 전송됐지만 처리됐는지 확인하지 못했습니다. 이미 처리됐을 수 있으므로 다시 요청하지 않고, 오류 메시지가 안내하는 홈택스 화면에서 먼저 확인합니다.
	AUTH_REQUIRED	세션 없음 — 홈택스 세션이 없습니다. 홈택스 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다.
	PROVIDER_BUSINESS_ERROR	업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다.
	PROVIDER_VALIDATION_ERROR	업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다.
	PROVIDER_UNAVAILABLE	업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다.
	PROVIDER_UPSTREAM_ERROR	업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다.

7. 표준재무제표증명 신청hometax.certificate.apply.financial_statement

MCP 도구 이름 hometax__certificate__apply__financial_statement

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

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

표준재무제표증명 신청을 신청합니다.

홈택스 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [홈택스 로그인(세션 생성)]
sandbox 환경에서는 실제 홈택스에 접속하지 않습니다. result.data 에는 mock: true 와 보낸 params 를 그대로 담은 params_echo 가 오고, 업무 응답 필드는 오지 않습니다.

Request

변수명	필수	설명
Authorization	Y	API 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다. 형식 : Basic base64("{client_id}:{client_secret}") [참고] 인증
X-Env-Scope	Y	호출 환경입니다. `sandbox`샌드박스 — 모의 응답 `real_test`데모 — 하루 100 사용 토큰 `production`정식 — 유료 플랜 전용 [참고] 환경
Idempotency-Key	Y	재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다. [참고] 재시도
Content-Type	Y	요청 본문 형식입니다. `application/json`고정값 (기본값)
X-Trace-Id	N	추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.

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

변수명	타입	길이	필수	설명
tin	string	-	조건부	미입력 시 세션 사업자번호 사용
txpr_nm	string	-	조건부	미입력 시 세션 상호 사용
bsno	string	-	Y	대상 사업자등록번호(숫자 10자리)
qrtTrt	string	-	Y	개인/법인 구분 코드(02 개인, 03 법인)
txyr	string	4	조건부	과세년도(개인,) 형식 : YYYY
incClCd	string	-	조건부	소득구분(개인)
bsyrEndYm	string	6	조건부	사업연도 종료연월(법인,) 형식 : YYYYMM
confirm	boolean	-	Y	실행 확인. 사용자에게 미리보기를 보여주고 동의를 받았을 때만 true 로 보낸다. 자동으로 채우지 않는다

bash

curl --request POST \
  --url 'https://api.xdata.kr/v1/jobs' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: sandbox' \
  --header 'Idempotency-Key: demo-financial_statement-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "hometax",
  "action": "hometax.certificate.apply.financial_statement",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "bsno": "<필수>",
    "qrtTrt": "<필수>",
    "confirm": "<필수: boolean>"
  }
}'

Response

기관이 신청을 받았음을 확인한 경우에만 성공합니다. result.data.outcome 은 CONFIRMED 이고, 증명서 아이디(cvaId)와 접수번호(rcatNo)를 확인합니다.

순번	변수명	설명
	outcome	기관 처리 판정. 성공 응답에서는 항상 CONFIRMED 입니다
	action	요청한 액션 이름. outcome · action 외의 키는 홈택스 응답 본문에서 옵니다(기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다)
	cvaId	기관이 발번한 증명서 아이디. 홈택스가 내려주는 키 이름 그대로입니다
	rcatNo	기관이 발번한 접수번호. 홈택스가 내려주는 키 이름 그대로입니다

json

// result.data — outcome · action 외의 키는 홈택스 응답 본문에서 옵니다(기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다).
{
  "outcome": "CONFIRMED",
  "action": "hometax.certificate.apply.financial_statement",
  "cvaId": "...",
  "rcatNo": "..."
}

순번	오류 코드	발생 조건
	PROVIDER_OUTCOME_UNCONFIRMED	처리 확인 불가 — 요청은 홈택스로 전송됐지만 처리됐는지 확인하지 못했습니다. 이미 처리됐을 수 있으므로 다시 요청하지 않고, 오류 메시지가 안내하는 홈택스 화면에서 먼저 확인합니다.
	AUTH_REQUIRED	세션 없음 — 홈택스 세션이 없습니다. 홈택스 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다.
	PROVIDER_BUSINESS_ERROR	업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다.
	PROVIDER_VALIDATION_ERROR	업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다.
	PROVIDER_UNAVAILABLE	업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다.
	PROVIDER_UPSTREAM_ERROR	업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다.

8. 폐업사실증명hometax.certificate.apply.business_closure

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

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

폐업사실증명을 신청합니다.

홈택스 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [홈택스 로그인(세션 생성)]
sandbox 환경에서는 실제 홈택스에 접속하지 않습니다. result.data 에는 mock: true 와 보낸 params 를 그대로 담은 params_echo 가 오고, 업무 응답 필드는 오지 않습니다.

Request

변수명	필수	설명
Authorization	Y	API 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다. 형식 : Basic base64("{client_id}:{client_secret}") [참고] 인증
X-Env-Scope	Y	호출 환경입니다. `sandbox`샌드박스 — 모의 응답 `real_test`데모 — 하루 100 사용 토큰 `production`정식 — 유료 플랜 전용 [참고] 환경
Idempotency-Key	Y	재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다. [참고] 재시도
Content-Type	Y	요청 본문 형식입니다. `application/json`고정값 (기본값)
X-Trace-Id	N	추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.

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

변수명	타입	길이	필수	설명
tin	string	-	조건부	미입력 시 세션 사업자번호 사용
txpr_nm	string	-	조건부	미입력 시 세션 상호 사용
bsno	string	-	Y	대상 사업자등록번호(숫자 10자리)
ofbDt	string	8	Y	대상 사업자의 개업일자() 형식 : YYYYMMDD
confirm	boolean	-	Y	실행 확인. 사용자에게 미리보기를 보여주고 동의를 받았을 때만 true 로 보낸다. 자동으로 채우지 않는다

bash

curl --request POST \
  --url 'https://api.xdata.kr/v1/jobs' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: sandbox' \
  --header 'Idempotency-Key: demo-business_closure-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "hometax",
  "action": "hometax.certificate.apply.business_closure",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "bsno": "<필수>",
    "ofbDt": "<필수>",
    "confirm": "<필수: boolean>"
  }
}'

Response

기관이 신청을 받았음을 확인한 경우에만 성공합니다. result.data.outcome 은 CONFIRMED 이고, 증명서 아이디(cvaId)와 접수번호(rcatNo)를 확인합니다.

순번	변수명	설명
	outcome	기관 처리 판정. 성공 응답에서는 항상 CONFIRMED 입니다
	action	요청한 액션 이름. outcome · action 외의 키는 홈택스 응답 본문에서 옵니다(기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다)
	cvaId	기관이 발번한 증명서 아이디. 홈택스가 내려주는 키 이름 그대로입니다
	rcatNo	기관이 발번한 접수번호. 홈택스가 내려주는 키 이름 그대로입니다

json

// result.data — outcome · action 외의 키는 홈택스 응답 본문에서 옵니다(기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다).
{
  "outcome": "CONFIRMED",
  "action": "hometax.certificate.apply.business_closure",
  "cvaId": "...",
  "rcatNo": "..."
}

순번	오류 코드	발생 조건
	PROVIDER_OUTCOME_UNCONFIRMED	처리 확인 불가 — 요청은 홈택스로 전송됐지만 처리됐는지 확인하지 못했습니다. 이미 처리됐을 수 있으므로 다시 요청하지 않고, 오류 메시지가 안내하는 홈택스 화면에서 먼저 확인합니다.
	AUTH_REQUIRED	세션 없음 — 홈택스 세션이 없습니다. 홈택스 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다.
	PROVIDER_BUSINESS_ERROR	업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다.
	PROVIDER_VALIDATION_ERROR	업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다.
	PROVIDER_UNAVAILABLE	업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다.
	PROVIDER_UPSTREAM_ERROR	업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다.

9. 사업자등록증 재발급hometax.certificate.apply.business_registration_reissue

MCP 도구 이름 hometax__certificate__apply__business_registration_reissue

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

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

사업자등록증 재발급을 신청합니다.

홈택스 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [홈택스 로그인(세션 생성)]
sandbox 환경에서는 실제 홈택스에 접속하지 않습니다. result.data 에는 mock: true 와 보낸 params 를 그대로 담은 params_echo 가 오고, 업무 응답 필드는 오지 않습니다.

Request

변수명	필수	설명
Authorization	Y	API 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다. 형식 : Basic base64("{client_id}:{client_secret}") [참고] 인증
X-Env-Scope	Y	호출 환경입니다. `sandbox`샌드박스 — 모의 응답 `real_test`데모 — 하루 100 사용 토큰 `production`정식 — 유료 플랜 전용 [참고] 환경
Idempotency-Key	Y	재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다. [참고] 재시도
Content-Type	Y	요청 본문 형식입니다. `application/json`고정값 (기본값)
X-Trace-Id	N	추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.

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

변수명	타입	필수	설명
tin	string	조건부	미입력 시 세션 사업자번호 사용
txpr_nm	string	조건부	미입력 시 세션 상호 사용
confirm	boolean	Y	실행 확인. 사용자에게 미리보기를 보여주고 동의를 받았을 때만 true 로 보낸다. 자동으로 채우지 않는다

bash

curl --request POST \
  --url 'https://api.xdata.kr/v1/jobs' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: sandbox' \
  --header 'Idempotency-Key: demo-business_registration_reissue-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "hometax",
  "action": "hometax.certificate.apply.business_registration_reissue",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "confirm": "<필수: boolean>"
  }
}'

Response

기관이 신청을 받았음을 확인한 경우에만 성공합니다. result.data.outcome 은 CONFIRMED 이고, 증명서 아이디(cvaId)와 접수번호(rcatNo)를 확인합니다.

순번	변수명	설명
	outcome	기관 처리 판정. 성공 응답에서는 항상 CONFIRMED 입니다
	action	요청한 액션 이름. outcome · action 외의 키는 홈택스 응답 본문에서 옵니다(기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다)
	cvaId	기관이 발번한 증명서 아이디. 홈택스가 내려주는 키 이름 그대로입니다
	rcatNo	기관이 발번한 접수번호. 홈택스가 내려주는 키 이름 그대로입니다

json

// result.data — outcome · action 외의 키는 홈택스 응답 본문에서 옵니다(기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다).
{
  "outcome": "CONFIRMED",
  "action": "hometax.certificate.apply.business_registration_reissue",
  "cvaId": "...",
  "rcatNo": "..."
}

순번	오류 코드	발생 조건
	PROVIDER_OUTCOME_UNCONFIRMED	처리 확인 불가 — 요청은 홈택스로 전송됐지만 처리됐는지 확인하지 못했습니다. 이미 처리됐을 수 있으므로 다시 요청하지 않고, 오류 메시지가 안내하는 홈택스 화면에서 먼저 확인합니다.
	AUTH_REQUIRED	세션 없음 — 홈택스 세션이 없습니다. 홈택스 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다.
	PROVIDER_BUSINESS_ERROR	업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다.
	PROVIDER_VALIDATION_ERROR	업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다.
	PROVIDER_UNAVAILABLE	업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다.
	PROVIDER_UPSTREAM_ERROR	업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다.

10. 증명발급 소득금액증명원hometax.certificate.apply.income_statement

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

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

증명발급 소득금액증명원을 신청합니다.

홈택스 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [홈택스 로그인(세션 생성)]
sandbox 환경에서는 실제 홈택스에 접속하지 않습니다. result.data 에는 mock: true 와 보낸 params 를 그대로 담은 params_echo 가 오고, 업무 응답 필드는 오지 않습니다.

Request

변수명	필수	설명
Authorization	Y	API 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다. 형식 : Basic base64("{client_id}:{client_secret}") [참고] 인증
X-Env-Scope	Y	호출 환경입니다. `sandbox`샌드박스 — 모의 응답 `real_test`데모 — 하루 100 사용 토큰 `production`정식 — 유료 플랜 전용 [참고] 환경
Idempotency-Key	Y	재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다. [참고] 재시도
Content-Type	Y	요청 본문 형식입니다. `application/json`고정값 (기본값)
X-Trace-Id	N	추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.

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

변수명	타입	필수	설명
tin	string	조건부	미입력 시 세션 사업자번호 사용
txpr_nm	string	조건부	미입력 시 세션 상호 사용
confirm	boolean	Y	실행 확인. 사용자에게 미리보기를 보여주고 동의를 받았을 때만 true 로 보낸다. 자동으로 채우지 않는다

bash

curl --request POST \
  --url 'https://api.xdata.kr/v1/jobs' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: sandbox' \
  --header 'Idempotency-Key: demo-income_statement-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "hometax",
  "action": "hometax.certificate.apply.income_statement",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "confirm": "<필수: boolean>"
  }
}'

Response

기관이 신청을 받았음을 확인한 경우에만 성공합니다. result.data.outcome 은 CONFIRMED 이고, 증명서 아이디(cvaId)와 접수번호(rcatNo)를 확인합니다.

순번	변수명	설명
	outcome	기관 처리 판정. 성공 응답에서는 항상 CONFIRMED 입니다
	action	요청한 액션 이름. outcome · action 외의 키는 홈택스 응답 본문에서 옵니다(기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다)
	cvaId	기관이 발번한 증명서 아이디. 홈택스가 내려주는 키 이름 그대로입니다
	rcatNo	기관이 발번한 접수번호. 홈택스가 내려주는 키 이름 그대로입니다

json

// result.data — outcome · action 외의 키는 홈택스 응답 본문에서 옵니다(기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다).
{
  "outcome": "CONFIRMED",
  "action": "hometax.certificate.apply.income_statement",
  "cvaId": "...",
  "rcatNo": "..."
}

순번	오류 코드	발생 조건
	PROVIDER_OUTCOME_UNCONFIRMED	처리 확인 불가 — 요청은 홈택스로 전송됐지만 처리됐는지 확인하지 못했습니다. 이미 처리됐을 수 있으므로 다시 요청하지 않고, 오류 메시지가 안내하는 홈택스 화면에서 먼저 확인합니다.
	AUTH_REQUIRED	세션 없음 — 홈택스 세션이 없습니다. 홈택스 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다.
	PROVIDER_BUSINESS_ERROR	업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다.
	PROVIDER_VALIDATION_ERROR	업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다.
	PROVIDER_UNAVAILABLE	업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다.
	PROVIDER_UPSTREAM_ERROR	업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다.