증명서 - 홈택스
납세·사업자 관련 증명서를 신청하고 발급 목록을 조회합니다.
1. 증명서 목록 조회hometax. certificate. list
MCP 도구 이름 hometax__
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
접수한 증명서 발급 신청의 목록을 조회합니다.
- 홈택스 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [홈택스 로그인(세션 생성)]
- 신청일 기준 조회 기간(보내지 않으면 오늘로부터 3일 전까지) 안에 신청이 없으면 items 가 빈 배열로 돌아오며, 실패가 아닙니다.더 오래된 신청은 strt_dt 와 end_dt 로 기간을 넓혀 다시 조회합니다(한 번에 최대 1개월).
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-10 | N | 증명서 신청일을 기준으로 찾는 기간의 시작일입니다. end_dt 와 함께 보내야 하며, 보내지 않으면 오늘로부터 3일 전부터 봅니다. end_dt 보다 뒤일 수 없습니다 | |
| end_ | string | 8-10 | N | 그 기간의 종료일입니다. strt_dt 와 함께 보내야 하며, 보내지 않으면 오늘까지 봅니다. 기간은 한 번에 최대 1개월이고, 넘기면 거절합니다 | |
| page_ | number | - | N | 페이지 번호입니다. 1부터 세며 보내지 않으면 1 입니다 | |
| page_ | number | - | N | 페이지당 조회 건수입니다. 보내지 않으면 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: list-$(date +%s)-$RANDOM" \
--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 의 items(신청 목록)와 page(페이지 정보)를 확인합니다.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| items | array | 증명서 행 배열입니다. 행마다 cva_id, rcat_no, cva_knd_nm, state_nm, issue_stat_nm, rpt_pkg_pth, cerp_isn_qty, cer_cva_isn_no, lnk_cl_cd, mdl_txpr_yn, cerp_isn_rqs_qty, cerp_isn_actl_qty 가 옵니다. 마지막 5칸(cer_cva_isn_no 부터)은 기관 목록이 주지 않으면 null 입니다 | |
| page | object | 페이지 객체 (page_size, page_num, total_count) |
// result.data
{
"items": [
{
"cva_id": "...",
"rcat_no": "...",
"cva_knd_nm": "국세완납증명",
"state_nm": "...",
"issue_stat_nm": "...",
"rpt_pkg_pth": "...",
"cerp_isn_qty": "1",
"cer_cva_isn_no": "...",
"lnk_cl_cd": "...",
"mdl_txpr_yn": "...",
"cerp_isn_rqs_qty": 1,
"cerp_isn_actl_qty": 0
}
],
"page": { "page_size": 10, "page_num": 1, "total_count": 1 }
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| VALIDATION_ | 기간 오류 — strt_dt 와 end_dt 를 한쪽만 보냈거나, 날짜 형식이 맞지 않거나, strt_dt 가 end_dt 보다 뒤이거나, 기간이 한 번에 최대 1개월을 넘으면 홈택스에 요청을 보내지 않고 거절합니다. error.message 가 어느 경우인지 알려 주니 값을 고쳐 다시 보냅니다. | |
| VALIDATION_ | 숫자 값 오류 — page_num, page_size 에 1 이상의 정수가 아닌 값(0, 음수, 소수부가 있는 수, 숫자가 아닌 글자)을 보내면 홈택스에 요청하지 않고 이 코드로 끝나며, 자동 재시도 대상이 아닙니다. error.message 가 확인할 값의 이름을 알려 주니 그 값을 고쳐 다시 요청합니다. 숫자로 된 문자열도 받고, null 로 보내면 보내지 않은 것으로 보아 기본값을 씁니다. | |
| AUTH_ | 세션 없음 — 홈택스 세션이 없습니다. 홈택스 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다. | |
| PROVIDER_ | 업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다. | |
| PROVIDER_ | 업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다. | |
| PROVIDER_ | 업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다. | |
| PROVIDER_ | 업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다. | |
| PROVIDER_ | 세션 만료 — 조회하는 도중 홈택스 로그인 세션이 끝난 것을 알게 되면 이 코드로 끝나며, error.message 안내대로 로그인 액션을 다시 실행해 세션을 연 뒤 같은 요청을 다시 보냅니다. |
2. 국세납세증명 신청hometax. certificate. apply. national_ tax_ payment
MCP 도구 이름 hometax__
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
국세납세증명을 신청합니다.
- 홈택스 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [홈택스 로그인(세션 생성)]
- 요청 거절(HTTP 400, 작업은 만들어지지 않음).error.code=WRITE_CONFIRMATION_REQUIRED — confirmation_token 없이 부르면 홈택스에 아무것도 보내지 않고 이 오류로 끝납니다.error.message 에 확인할 내용이, error.confirmation_token 에 1회용 토큰이, error.preview 에 실행할 내용(what_will_happen_ko), 보낸 값(items), 보내지 않은 칸에 쓰일 값(defaults_ko), 되돌릴 수 없다는 안내(irreversible_ko)가 함께 옵니다.안내를 사용자에게 보여 주고 동의를 받은 뒤 같은 요청의 params.confirmation_token 에 그 토큰을 넣어 다시 보냅니다. 토큰은 10분 안에 한 번만 쓸 수 있고 처음 요청과 같은 본문에만 맞습니다.confirm 칸은 확인으로 쓰이지 않으며, 다시 보낼 때 더하면 본문이 달라져 확인 토큰 불일치로 끝납니다.
- 요청 거절(HTTP 409, 작업은 만들어지지 않음).error.code=WRITE_CONFIRMATION_INVALID — 토큰이 만료됐거나, 이미 썼거나, 다른 호출자나 다른 환경에서 받은 것이거나, 확인한 요청 본문과 달라졌으면 홈택스에 아무것도 보내지 않고 이 오류로 끝나며 어느 쪽인지는 알려 주지 않습니다.error.message 는 「확인이 만료됐거나 확인한 내용과 달라졌습니다. 다시 확인해 주세요.」 입니다. confirmation_token 없이 같은 요청을 다시 보내 새 토큰과 안내를 받은 뒤 사용자에게 다시 확인을 받습니다.
- 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 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| tin | string | 조건부 | 보내도 신청 대상은 바뀌지 않습니다. 신청서의 식별번호는 늘 로그인한 계정의 값입니다 | |
| txpr_ | string | 조건부 | 미입력 시 세션 상호 사용 | |
| confirmation_ | string | N | 1회용 확인 토큰입니다. 처음에는 보내지 않습니다. 토큰 없이 부르면 기관에 아무것도 보내지 않고 작업도 만들지 않은 채 확인이 필요하다는 오류(WRITE_CONFIRMATION_REQUIRED)로 끝나고, 응답의 error.confirmation_token 에 토큰이 옵니다. error.message 의 안내를 사용자에게 보여 주고 동의를 받은 뒤 같은 요청에 이 토큰을 넣어 다시 부릅니다. 토큰은 10분 안에 한 번만 쓸 수 있고 처음 요청과 같은 본문, 같은 호출자, 같은 환경에서만 맞으며, 아니면 확인이 만료됐거나 내용이 달라졌다는 오류로 거절합니다 | |
| cerpIsnRqsQty | string | N | 신청할 발급 매수입니다. 보내지 않으면 서식에 정해진 값으로 신청합니다 | |
| cvaDcumSbmsOrgnClCd | string | N | 증명서 제출처 구분코드입니다. 보내지 않으면 서식에 정해진 값으로 신청합니다 | |
| cvaDcumGranMthdCd | string | N | 증명서 교부방법 코드입니다. 보내지 않으면 서식에 정해진 값으로 신청합니다 | |
| adrOpYn | string | N | 증명서에 주소를 표시할지 정하는 값으로 Y 나 N 을 보냅니다. 보내지 않으면 서식에 정해진 값으로 신청합니다 | |
| resnoOpYn | string | N | 증명서에 주민등록번호를 표시할지 정하는 값으로 Y 나 N 을 보냅니다. 법인(사업자) 계정은 이 값과 관계없이 항상 N 으로 신청하고, 개인 계정이 보내지 않으면 서식에 정해진 값을 씁니다 | |
| amtOpYn | string | N | 증명서에 금액을 표시할지 정하는 값으로 Y 나 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: national_tax_payment-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "hometax",
"action": "hometax.certificate.apply.national_tax_payment",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {}
}'Response
- 기관이 신청을 받았음을 확인한 경우에만 성공합니다. result.data.outcome 은 confirmed 입니다.
- 접수번호(rcat_no)는 이 응답에 실리지 않을 수 있습니다. 내려받기에 쓸 접수번호는 증명서 신청 목록 조회의 행에서 읽습니다.
- 여러 JSON 타입이 함께 표시된 칸은 서버가 세부 타입을 고정하지 않는 기관 원문 또는 동적 값입니다.예시 값의 타입으로 단정하지 말고 실제 값의 타입을 확인해 주세요. null은 값이 비어 있다는 뜻이며, 필드 자체의 생략 여부는 필수 여부와 설명을 확인해 주세요.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| outcome | string | 기관 처리 판정. 성공 응답에서는 항상 confirmed 입니다 | |
| action | string | 요청한 액션 이름. outcome · action 외의 키는 홈택스 응답 본문에서 옵니다(기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다) | |
| cvaId | string | number | boolean | object | array | null | 기관이 발번한 증명서 아이디. 홈택스가 내려주는 키 이름 그대로이며 비어 올 수 있습니다 기관 응답에 존재할 때만 반환됩니다. data 또는 cerpBscInfrDVO 내부에 있을 수 있으므로 최상위 존재를 전제로 접근하지 마세요. |
// result.data — outcome · action 외의 키는 홈택스 응답 본문에서 옵니다(기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다).
{
"outcome": "confirmed",
"action": "hometax.certificate.apply.national_tax_payment",
"cvaId": "..."
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| PROVIDER_ | 처리 확인 불가 — 요청은 홈택스로 전송됐지만 처리됐는지 확인하지 못했습니다. 이미 처리됐을 수 있으므로 다시 요청하지 않고, 오류 메시지가 안내하는 홈택스 화면에서 먼저 확인합니다. | |
| AUTH_ | 세션 없음 — 홈택스 세션이 없습니다. 홈택스 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다. | |
| PROVIDER_ | 업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다. | |
| PROVIDER_ | 홈택스 통신 오류 — 홈택스가 오류로 답하거나 연결이 끊겨 요청이 처리됐는지 알 수 없을 수 있으니, 다시 요청하기 전에 홈택스 화면에서 먼저 확인합니다. 홈택스가 오류 응답을 보내거나 연결이 끊긴 경우 error.message 는 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')입니다. | |
| PROVIDER_ | 홈택스 통신 오류 — 홈택스가 오류로 답하거나 연결이 끊겨 요청이 처리됐는지 알 수 없을 수 있으니, 다시 요청하기 전에 홈택스 화면에서 먼저 확인합니다. 홈택스가 오류 응답을 보내거나 연결이 끊긴 경우 error.message 는 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')입니다. | |
| PROVIDER_ | 홈택스 통신 오류 — 홈택스가 오류로 답하거나 연결이 끊겨 요청이 처리됐는지 알 수 없을 수 있으니, 다시 요청하기 전에 홈택스 화면에서 먼저 확인합니다. 홈택스가 오류 응답을 보내거나 연결이 끊긴 경우 error.message 는 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')입니다. |
3. 납세사실증명 신청hometax. certificate. apply. tax_ payment_ record
MCP 도구 이름 hometax__
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
납세사실증명을 신청합니다.
- 홈택스 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [홈택스 로그인(세션 생성)]
- 요청 거절(HTTP 400, 작업은 만들어지지 않음).error.code=WRITE_CONFIRMATION_REQUIRED — confirmation_token 없이 부르면 홈택스에 아무것도 보내지 않고 이 오류로 끝납니다.error.message 에 확인할 내용이, error.confirmation_token 에 1회용 토큰이, error.preview 에 실행할 내용(what_will_happen_ko), 보낸 값(items), 보내지 않은 칸에 쓰일 값(defaults_ko), 되돌릴 수 없다는 안내(irreversible_ko)가 함께 옵니다.안내를 사용자에게 보여 주고 동의를 받은 뒤 같은 요청의 params.confirmation_token 에 그 토큰을 넣어 다시 보냅니다. 토큰은 10분 안에 한 번만 쓸 수 있고 처음 요청과 같은 본문에만 맞습니다.confirm 칸은 확인으로 쓰이지 않으며, 다시 보낼 때 더하면 본문이 달라져 확인 토큰 불일치로 끝납니다.
- 요청 거절(HTTP 409, 작업은 만들어지지 않음).error.code=WRITE_CONFIRMATION_INVALID — 토큰이 만료됐거나, 이미 썼거나, 다른 호출자나 다른 환경에서 받은 것이거나, 확인한 요청 본문과 달라졌으면 홈택스에 아무것도 보내지 않고 이 오류로 끝나며 어느 쪽인지는 알려 주지 않습니다.error.message 는 「확인이 만료됐거나 확인한 내용과 달라졌습니다. 다시 확인해 주세요.」 입니다. confirmation_token 없이 같은 요청을 다시 보내 새 토큰과 안내를 받은 뒤 사용자에게 다시 확인을 받습니다.
- 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 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 길이 | 필수 | 설명 |
|---|---|---|---|---|---|
| tin | string | - | 조건부 | 보내도 신청 대상은 바뀌지 않습니다. 신청서의 식별번호는 늘 로그인한 계정의 값입니다 | |
| txpr_ | string | - | 조건부 | 미입력 시 세션 상호 사용 | |
| confirmation_ | string | - | N | 1회용 확인 토큰입니다. 처음에는 보내지 않습니다. 토큰 없이 부르면 기관에 아무것도 보내지 않고 작업도 만들지 않은 채 확인이 필요하다는 오류(WRITE_CONFIRMATION_REQUIRED)로 끝나고, 응답의 error.confirmation_token 에 토큰이 옵니다. error.message 의 안내를 사용자에게 보여 주고 동의를 받은 뒤 같은 요청에 이 토큰을 넣어 다시 부릅니다. 토큰은 10분 안에 한 번만 쓸 수 있고 처음 요청과 같은 본문, 같은 호출자, 같은 환경에서만 맞으며, 아니면 확인이 만료됐거나 내용이 달라졌다는 오류로 거절합니다 | |
| cerStrtYr | string | 4 | N | 수납기간 시작 연도입니다. 수납기간을 보내지 않으면 올해 1월부터 이번 달까지로 신청됩니다 | |
| strtMm | string | - | N | 수납기간 시작 월(MM)입니다. 수납기간을 보내지 않으면 올해 1월부터 이번 달까지로 신청됩니다 | |
| cerEndYr | string | 4 | N | 수납기간 종료 연도입니다. 수납기간을 보내지 않으면 올해 1월부터 이번 달까지로 신청됩니다 | |
| endMm | string | - | N | 수납기간 종료 월(MM)입니다. 수납기간을 보내지 않으면 올해 1월부터 이번 달까지로 신청됩니다 | |
| cerpIsnRqsQty | string | - | N | 신청할 발급 매수입니다. 보내지 않으면 서식에 정해진 값으로 신청합니다 | |
| cvaDcumSbmsOrgnClCd | string | - | N | 증명서 제출처 구분코드입니다. 보내지 않으면 서식에 정해진 값으로 신청합니다 | |
| cvaDcumGranMthdCd | string | - | N | 증명서 교부방법 코드입니다. 보내지 않으면 서식에 정해진 값으로 신청합니다 | |
| adrOpYn | string | - | N | 증명서에 주소를 표시할지 정하는 값으로 Y 나 N 을 보냅니다. 보내지 않으면 서식에 정해진 값으로 신청합니다 | |
| resnoOpYn | string | - | N | 증명서에 주민등록번호를 표시할지 정하는 값으로 Y 나 N 을 보냅니다. 법인(사업자) 계정은 이 값과 관계없이 항상 N 으로 신청하고, 개인 계정이 보내지 않으면 서식에 정해진 값을 씁니다 | |
| amtOpYn | string | - | N | 증명서에 금액을 표시할지 정하는 값으로 Y 나 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: tax_payment_record-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "hometax",
"action": "hometax.certificate.apply.tax_payment_record",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {}
}'Response
- 기관이 신청을 받았음을 확인한 경우에만 성공합니다. result.data.outcome 은 confirmed 입니다.
- 접수번호(rcat_no)는 이 응답에 실리지 않을 수 있습니다. 내려받기에 쓸 접수번호는 증명서 신청 목록 조회의 행에서 읽습니다.
- 여러 JSON 타입이 함께 표시된 칸은 서버가 세부 타입을 고정하지 않는 기관 원문 또는 동적 값입니다.예시 값의 타입으로 단정하지 말고 실제 값의 타입을 확인해 주세요. null은 값이 비어 있다는 뜻이며, 필드 자체의 생략 여부는 필수 여부와 설명을 확인해 주세요.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| outcome | string | 기관 처리 판정. 성공 응답에서는 항상 confirmed 입니다 | |
| action | string | 요청한 액션 이름. outcome · action 외의 키는 홈택스 응답 본문에서 옵니다(기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다) | |
| cvaId | string | number | boolean | object | array | null | 기관이 발번한 증명서 아이디. 홈택스가 내려주는 키 이름 그대로이며 비어 올 수 있습니다 기관 응답에 존재할 때만 반환됩니다. data 또는 cerpBscInfrDVO 내부에 있을 수 있으므로 최상위 존재를 전제로 접근하지 마세요. |
// result.data — outcome · action 외의 키는 홈택스 응답 본문에서 옵니다(기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다).
{
"outcome": "confirmed",
"action": "hometax.certificate.apply.tax_payment_record",
"cvaId": "..."
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| PROVIDER_ | 처리 확인 불가 — 요청은 홈택스로 전송됐지만 처리됐는지 확인하지 못했습니다. 이미 처리됐을 수 있으므로 다시 요청하지 않고, 오류 메시지가 안내하는 홈택스 화면에서 먼저 확인합니다. | |
| AUTH_ | 세션 없음 — 홈택스 세션이 없습니다. 홈택스 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다. | |
| PROVIDER_ | 업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다. | |
| PROVIDER_ | 홈택스 통신 오류 — 홈택스가 오류로 답하거나 연결이 끊겨 요청이 처리됐는지 알 수 없을 수 있으니, 다시 요청하기 전에 홈택스 화면에서 먼저 확인합니다. 홈택스가 오류 응답을 보내거나 연결이 끊긴 경우 error.message 는 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')입니다. | |
| PROVIDER_ | 홈택스 통신 오류 — 홈택스가 오류로 답하거나 연결이 끊겨 요청이 처리됐는지 알 수 없을 수 있으니, 다시 요청하기 전에 홈택스 화면에서 먼저 확인합니다. 홈택스가 오류 응답을 보내거나 연결이 끊긴 경우 error.message 는 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')입니다. | |
| PROVIDER_ | 홈택스 통신 오류 — 홈택스가 오류로 답하거나 연결이 끊겨 요청이 처리됐는지 알 수 없을 수 있으니, 다시 요청하기 전에 홈택스 화면에서 먼저 확인합니다. 홈택스가 오류 응답을 보내거나 연결이 끊긴 경우 error.message 는 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')입니다. |
4. 부가가치세 과세표준증명 신청hometax. certificate. apply. vat_ standard
MCP 도구 이름 hometax__
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
부가가치세 과세표준증명을 신청합니다.
- 홈택스 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [홈택스 로그인(세션 생성)]
- 요청 거절(HTTP 400, 작업은 만들어지지 않음).error.code=WRITE_CONFIRMATION_REQUIRED — confirmation_token 없이 부르면 홈택스에 아무것도 보내지 않고 이 오류로 끝납니다.error.message 에 확인할 내용이, error.confirmation_token 에 1회용 토큰이, error.preview 에 실행할 내용(what_will_happen_ko), 보낸 값(items), 보내지 않은 칸에 쓰일 값(defaults_ko), 되돌릴 수 없다는 안내(irreversible_ko)가 함께 옵니다.안내를 사용자에게 보여 주고 동의를 받은 뒤 같은 요청의 params.confirmation_token 에 그 토큰을 넣어 다시 보냅니다. 토큰은 10분 안에 한 번만 쓸 수 있고 처음 요청과 같은 본문에만 맞습니다.confirm 칸은 확인으로 쓰이지 않으며, 다시 보낼 때 더하면 본문이 달라져 확인 토큰 불일치로 끝납니다.
- 요청 거절(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 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 길이 | 필수 | 설명 |
|---|---|---|---|---|---|
| tin | string | - | 조건부 | 보내도 신청 대상은 바뀌지 않습니다. 신청서의 식별번호는 늘 로그인한 계정의 값입니다 | |
| txpr_ | string | - | 조건부 | 미입력 시 세션 상호 사용 | |
| strtYm | string | 6 | Y | 조회 시작 연월 | |
| endYm | string | 6 | Y | 조회 종료 연월 | |
| confirmation_ | string | - | N | 1회용 확인 토큰입니다. 처음에는 보내지 않습니다. 토큰 없이 부르면 기관에 아무것도 보내지 않고 작업도 만들지 않은 채 확인이 필요하다는 오류(WRITE_CONFIRMATION_REQUIRED)로 끝나고, 응답의 error.confirmation_token 에 토큰이 옵니다. error.message 의 안내를 사용자에게 보여 주고 동의를 받은 뒤 같은 요청에 이 토큰을 넣어 다시 부릅니다. 토큰은 10분 안에 한 번만 쓸 수 있고 처음 요청과 같은 본문, 같은 호출자, 같은 환경에서만 맞으며, 아니면 확인이 만료됐거나 내용이 달라졌다는 오류로 거절합니다 | |
| cerpIsnRqsQty | string | - | N | 신청할 발급 매수입니다. 보내지 않으면 서식에 정해진 값으로 신청합니다 | |
| cvaDcumSbmsOrgnClCd | string | - | N | 증명서 제출처 구분코드입니다. 보내지 않으면 서식에 정해진 값으로 신청합니다 | |
| cvaDcumGranMthdCd | string | - | N | 증명서 교부방법 코드입니다. 보내지 않으면 서식에 정해진 값으로 신청합니다 | |
| adrOpYn | string | - | N | 증명서에 주소를 표시할지 정하는 값으로 Y 나 N 을 보냅니다. 보내지 않으면 서식에 정해진 값으로 신청합니다 | |
| resnoOpYn | string | - | N | 증명서에 주민등록번호를 표시할지 정하는 값으로 Y 나 N 을 보냅니다. 법인(사업자) 계정은 이 값과 관계없이 항상 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: vat_standard-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "hometax",
"action": "hometax.certificate.apply.vat_standard",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {
"strtYm": "<필수>",
"endYm": "<필수>"
}
}'Response
- 기관이 신청을 받았음을 확인한 경우에만 성공합니다. result.data.outcome 은 confirmed 입니다.
- 접수번호(rcat_no)는 이 응답에 실리지 않을 수 있습니다. 내려받기에 쓸 접수번호는 증명서 신청 목록 조회의 행에서 읽습니다.
- 여러 JSON 타입이 함께 표시된 칸은 서버가 세부 타입을 고정하지 않는 기관 원문 또는 동적 값입니다.예시 값의 타입으로 단정하지 말고 실제 값의 타입을 확인해 주세요. null은 값이 비어 있다는 뜻이며, 필드 자체의 생략 여부는 필수 여부와 설명을 확인해 주세요.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| outcome | string | 기관 처리 판정. 성공 응답에서는 항상 confirmed 입니다 | |
| action | string | 요청한 액션 이름. outcome · action 외의 키는 홈택스 응답 본문에서 옵니다(기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다) | |
| cvaId | string | number | boolean | object | array | null | 기관이 발번한 증명서 아이디. 홈택스가 내려주는 키 이름 그대로입니다. 이 서식은 비어 올 수 있고, 그때 증명서 ID 는 증명서 신청 목록 조회의 같은 신청 행에서 cva_id 로 받습니다 기관 응답에 존재할 때만 반환됩니다. data 또는 cerpBscInfrDVO 내부에 있을 수 있으므로 최상위 존재를 전제로 접근하지 마세요. |
// result.data — outcome · action 외의 키는 홈택스 응답 본문에서 옵니다(기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다).
{
"outcome": "confirmed",
"action": "hometax.certificate.apply.vat_standard",
"cvaId": "..."
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| PROVIDER_ | 처리 확인 불가 — 요청은 홈택스로 전송됐지만 처리됐는지 확인하지 못했습니다. 이미 처리됐을 수 있으므로 다시 요청하지 않고, 오류 메시지가 안내하는 홈택스 화면에서 먼저 확인합니다. | |
| VALIDATION_ | 개인 계정 — 연결된 홈택스 계정이 개인 계정이면 신청하기 전에 멈추는 경우이며, 신청은 접수되지 않았고 자동 재시도 대상이 아닙니다. error.message 는 「부가가치세 과세표준증명 발급은 사업자 계정으로만 신청할 수 있습니다. 사업자로 연결된 계정을 선택한 뒤 다시 시도해 주세요.」 입니다. | |
| AUTH_ | 세션 없음 — 홈택스 세션이 없습니다. 홈택스 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다. | |
| PROVIDER_ | 업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다. | |
| PROVIDER_ | 홈택스 통신 오류 — 홈택스가 오류로 답하거나 연결이 끊겨 요청이 처리됐는지 알 수 없을 수 있으니, 다시 요청하기 전에 홈택스 화면에서 먼저 확인합니다. 홈택스가 오류 응답을 보내거나 연결이 끊긴 경우 error.message 는 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')입니다. | |
| PROVIDER_ | 홈택스 통신 오류 — 홈택스가 오류로 답하거나 연결이 끊겨 요청이 처리됐는지 알 수 없을 수 있으니, 다시 요청하기 전에 홈택스 화면에서 먼저 확인합니다. 홈택스가 오류 응답을 보내거나 연결이 끊긴 경우 error.message 는 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')입니다. | |
| PROVIDER_ | 홈택스 통신 오류 — 홈택스가 오류로 답하거나 연결이 끊겨 요청이 처리됐는지 알 수 없을 수 있으니, 다시 요청하기 전에 홈택스 화면에서 먼저 확인합니다. 홈택스가 오류 응답을 보내거나 연결이 끊긴 경우 error.message 는 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')입니다. |
5. 사업자등록 증명hometax. certificate. apply. business_ registration
MCP 도구 이름 hometax__
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
사업자등록 증명을 신청합니다.
- 홈택스 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [홈택스 로그인(세션 생성)]
- 요청 거절(HTTP 400, 작업은 만들어지지 않음).error.code=WRITE_CONFIRMATION_REQUIRED — confirmation_token 없이 부르면 홈택스에 아무것도 보내지 않고 이 오류로 끝납니다.error.message 에 확인할 내용이, error.confirmation_token 에 1회용 토큰이, error.preview 에 실행할 내용(what_will_happen_ko), 보낸 값(items), 보내지 않은 칸에 쓰일 값(defaults_ko), 되돌릴 수 없다는 안내(irreversible_ko)가 함께 옵니다.안내를 사용자에게 보여 주고 동의를 받은 뒤 같은 요청의 params.confirmation_token 에 그 토큰을 넣어 다시 보냅니다. 토큰은 10분 안에 한 번만 쓸 수 있고 처음 요청과 같은 본문에만 맞습니다.confirm 칸은 확인으로 쓰이지 않으며, 다시 보낼 때 더하면 본문이 달라져 확인 토큰 불일치로 끝납니다.
- 요청 거절(HTTP 409, 작업은 만들어지지 않음).error.code=WRITE_CONFIRMATION_INVALID — 토큰이 만료됐거나, 이미 썼거나, 다른 호출자나 다른 환경에서 받은 것이거나, 확인한 요청 본문과 달라졌으면 홈택스에 아무것도 보내지 않고 이 오류로 끝나며 어느 쪽인지는 알려 주지 않습니다.error.message 는 「확인이 만료됐거나 확인한 내용과 달라졌습니다. 다시 확인해 주세요.」 입니다. confirmation_token 없이 같은 요청을 다시 보내 새 토큰과 안내를 받은 뒤 사용자에게 다시 확인을 받습니다.
- 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 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| tin | string | 조건부 | 보내도 신청 대상은 바뀌지 않습니다. 신청서의 식별번호는 늘 로그인한 계정의 값입니다 | |
| txpr_ | string | 조건부 | 미입력 시 세션 상호 사용 | |
| confirmation_ | string | N | 1회용 확인 토큰입니다. 처음에는 보내지 않습니다. 토큰 없이 부르면 기관에 아무것도 보내지 않고 작업도 만들지 않은 채 확인이 필요하다는 오류(WRITE_CONFIRMATION_REQUIRED)로 끝나고, 응답의 error.confirmation_token 에 토큰이 옵니다. error.message 의 안내를 사용자에게 보여 주고 동의를 받은 뒤 같은 요청에 이 토큰을 넣어 다시 부릅니다. 토큰은 10분 안에 한 번만 쓸 수 있고 처음 요청과 같은 본문, 같은 호출자, 같은 환경에서만 맞으며, 아니면 확인이 만료됐거나 내용이 달라졌다는 오류로 거절합니다 | |
| cerpIsnRqsQty | string | N | 신청할 발급 매수입니다. 보내지 않으면 서식에 정해진 값으로 신청합니다 | |
| cvaDcumSbmsOrgnClCd | string | N | 증명서 제출처 구분코드입니다. 보내지 않으면 서식에 정해진 값으로 신청합니다 | |
| cvaDcumGranMthdCd | string | N | 증명서 교부방법 코드입니다. 보내지 않으면 서식에 정해진 값으로 신청합니다 | |
| adrOpYn | string | N | 증명서에 주소를 표시할지 정하는 값으로 Y 나 N 을 보냅니다. 보내지 않으면 서식에 정해진 값으로 신청합니다 | |
| resnoOpYn | string | N | 증명서에 주민등록번호를 표시할지 정하는 값으로 Y 나 N 을 보냅니다. 법인(사업자) 계정은 이 값과 관계없이 항상 N 으로 신청하고, 개인 계정이 보내지 않으면 서식에 정해진 값을 씁니다 | |
| amtOpYn | string | N | 증명서에 금액을 표시할지 정하는 값으로 Y 나 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: business_registration-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "hometax",
"action": "hometax.certificate.apply.business_registration",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {}
}'Response
- 기관이 신청을 받았음을 확인한 경우에만 성공합니다. result.data.outcome 은 confirmed 입니다.
- 접수번호(rcat_no)는 이 응답에 실리지 않을 수 있습니다. 내려받기에 쓸 접수번호는 증명서 신청 목록 조회의 행에서 읽습니다.
- 여러 JSON 타입이 함께 표시된 칸은 서버가 세부 타입을 고정하지 않는 기관 원문 또는 동적 값입니다.예시 값의 타입으로 단정하지 말고 실제 값의 타입을 확인해 주세요. null은 값이 비어 있다는 뜻이며, 필드 자체의 생략 여부는 필수 여부와 설명을 확인해 주세요.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| outcome | string | 기관 처리 판정. 성공 응답에서는 항상 confirmed 입니다 | |
| action | string | 요청한 액션 이름. outcome · action 외의 키는 홈택스 응답 본문에서 옵니다(기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다) | |
| cvaId | string | number | boolean | object | array | null | 기관이 발번한 증명서 아이디. 홈택스가 내려주는 키 이름 그대로이며 비어 올 수 있습니다 기관 응답에 존재할 때만 반환됩니다. data 또는 cerpBscInfrDVO 내부에 있을 수 있으므로 최상위 존재를 전제로 접근하지 마세요. |
// result.data — outcome · action 외의 키는 홈택스 응답 본문에서 옵니다(기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다).
{
"outcome": "confirmed",
"action": "hometax.certificate.apply.business_registration",
"cvaId": "..."
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| PROVIDER_ | 처리 확인 불가 — 요청은 홈택스로 전송됐지만 처리됐는지 확인하지 못했습니다. 이미 처리됐을 수 있으므로 다시 요청하지 않고, 오류 메시지가 안내하는 홈택스 화면에서 먼저 확인합니다. | |
| AUTH_ | 세션 없음 — 홈택스 세션이 없습니다. 홈택스 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다. | |
| PROVIDER_ | 업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다. | |
| PROVIDER_ | 홈택스 통신 오류 — 홈택스가 오류로 답하거나 연결이 끊겨 요청이 처리됐는지 알 수 없을 수 있으니, 다시 요청하기 전에 홈택스 화면에서 먼저 확인합니다. 홈택스가 오류 응답을 보내거나 연결이 끊긴 경우 error.message 는 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')입니다. | |
| PROVIDER_ | 홈택스 통신 오류 — 홈택스가 오류로 답하거나 연결이 끊겨 요청이 처리됐는지 알 수 없을 수 있으니, 다시 요청하기 전에 홈택스 화면에서 먼저 확인합니다. 홈택스가 오류 응답을 보내거나 연결이 끊긴 경우 error.message 는 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')입니다. | |
| PROVIDER_ | 홈택스 통신 오류 — 홈택스가 오류로 답하거나 연결이 끊겨 요청이 처리됐는지 알 수 없을 수 있으니, 다시 요청하기 전에 홈택스 화면에서 먼저 확인합니다. 홈택스가 오류 응답을 보내거나 연결이 끊긴 경우 error.message 는 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')입니다. |
6. 휴업사실증명hometax. certificate. apply. business_ suspension
MCP 도구 이름 hometax__
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
휴업사실증명을 신청합니다.
- 홈택스 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [홈택스 로그인(세션 생성)]
- 요청 거절(HTTP 400, 작업은 만들어지지 않음).error.code=WRITE_CONFIRMATION_REQUIRED — confirmation_token 없이 부르면 홈택스에 아무것도 보내지 않고 이 오류로 끝납니다.error.message 에 확인할 내용이, error.confirmation_token 에 1회용 토큰이, error.preview 에 실행할 내용(what_will_happen_ko), 보낸 값(items), 보내지 않은 칸에 쓰일 값(defaults_ko), 되돌릴 수 없다는 안내(irreversible_ko)가 함께 옵니다.안내를 사용자에게 보여 주고 동의를 받은 뒤 같은 요청의 params.confirmation_token 에 그 토큰을 넣어 다시 보냅니다. 토큰은 10분 안에 한 번만 쓸 수 있고 처음 요청과 같은 본문에만 맞습니다.confirm 칸은 확인으로 쓰이지 않으며, 다시 보낼 때 더하면 본문이 달라져 확인 토큰 불일치로 끝납니다.
- 요청 거절(HTTP 409, 작업은 만들어지지 않음).error.code=WRITE_CONFIRMATION_INVALID — 토큰이 만료됐거나, 이미 썼거나, 다른 호출자나 다른 환경에서 받은 것이거나, 확인한 요청 본문과 달라졌으면 홈택스에 아무것도 보내지 않고 이 오류로 끝나며 어느 쪽인지는 알려 주지 않습니다.error.message 는 「확인이 만료됐거나 확인한 내용과 달라졌습니다. 다시 확인해 주세요.」 입니다. confirmation_token 없이 같은 요청을 다시 보내 새 토큰과 안내를 받은 뒤 사용자에게 다시 확인을 받습니다.
- 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 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 길이 | 필수 | 설명 |
|---|---|---|---|---|---|
| tin | string | - | 조건부 | 보내도 신청 대상은 바뀌지 않습니다. 신청서의 식별번호는 늘 로그인한 계정의 값입니다 | |
| txpr_ | string | - | 조건부 | 미입력 시 세션 상호 사용 | |
| confirmation_ | string | - | N | 1회용 확인 토큰입니다. 처음에는 보내지 않습니다. 토큰 없이 부르면 기관에 아무것도 보내지 않고 작업도 만들지 않은 채 확인이 필요하다는 오류(WRITE_CONFIRMATION_REQUIRED)로 끝나고, 응답의 error.confirmation_token 에 토큰이 옵니다. error.message 의 안내를 사용자에게 보여 주고 동의를 받은 뒤 같은 요청에 이 토큰을 넣어 다시 부릅니다. 토큰은 10분 안에 한 번만 쓸 수 있고 처음 요청과 같은 본문, 같은 호출자, 같은 환경에서만 맞으며, 아니면 확인이 만료됐거나 내용이 달라졌다는 오류로 거절합니다 | |
| sfbTermStrtDt | string | 8 | N | 신청할 휴업 기간의 시작일(휴업 기간이 여럿일 때)입니다 | |
| sfbTermEndDt | string | 8 | N | 신청할 휴업 기간의 종료일(시작일이 같은 기간이 여럿일 때)입니다 | |
| cerpIsnRqsQty | string | - | N | 신청할 발급 매수입니다. 보내지 않으면 서식에 정해진 값으로 신청합니다 | |
| cvaDcumSbmsOrgnClCd | string | - | N | 증명서 제출처 구분코드입니다. 보내지 않으면 서식에 정해진 값으로 신청합니다 | |
| cvaDcumGranMthdCd | string | - | N | 증명서 교부방법 코드입니다. 보내지 않으면 서식에 정해진 값으로 신청합니다 | |
| adrOpYn | string | - | N | 증명서에 주소를 표시할지 정하는 값으로 Y 나 N 을 보냅니다. 보내지 않으면 서식에 정해진 값으로 신청합니다 | |
| resnoOpYn | string | - | N | 증명서에 주민등록번호를 표시할지 정하는 값으로 Y 나 N 을 보냅니다. 법인(사업자) 계정은 이 값과 관계없이 항상 N 으로 신청하고, 개인 계정이 보내지 않으면 서식에 정해진 값을 씁니다 | |
| amtOpYn | string | - | N | 증명서에 금액을 표시할지 정하는 값으로 Y 나 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: business_suspension-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "hometax",
"action": "hometax.certificate.apply.business_suspension",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {}
}'Response
- 기관이 신청을 받았음을 확인한 경우에만 성공합니다. result.data.outcome 은 confirmed 입니다.
- 접수번호(rcat_no)는 이 응답에 실리지 않을 수 있습니다. 내려받기에 쓸 접수번호는 증명서 신청 목록 조회의 행에서 읽습니다.
- 여러 JSON 타입이 함께 표시된 칸은 서버가 세부 타입을 고정하지 않는 기관 원문 또는 동적 값입니다.예시 값의 타입으로 단정하지 말고 실제 값의 타입을 확인해 주세요. null은 값이 비어 있다는 뜻이며, 필드 자체의 생략 여부는 필수 여부와 설명을 확인해 주세요.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| outcome | string | 기관 처리 판정. 성공 응답에서는 항상 confirmed 입니다 | |
| action | string | 요청한 액션 이름. outcome · action 외의 키는 홈택스 응답 본문에서 옵니다(기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다) | |
| cvaId | string | number | boolean | object | array | null | 기관이 발번한 증명서 아이디. 홈택스가 내려주는 키 이름 그대로이며 비어 올 수 있습니다 기관 응답에 존재할 때만 반환됩니다. data 또는 cerpBscInfrDVO 내부에 있을 수 있으므로 최상위 존재를 전제로 접근하지 마세요. |
// result.data — outcome · action 외의 키는 홈택스 응답 본문에서 옵니다(기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다).
{
"outcome": "confirmed",
"action": "hometax.certificate.apply.business_suspension",
"cvaId": "..."
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| PROVIDER_ | 처리 확인 불가 — 요청은 홈택스로 전송됐지만 처리됐는지 확인하지 못했습니다. 이미 처리됐을 수 있으므로 다시 요청하지 않고, 오류 메시지가 안내하는 홈택스 화면에서 먼저 확인합니다. | |
| VALIDATION_ | 사업자 계정 아님 — 연결된 홈택스 계정이 사업자 계정이 아니면 신청하기 전에 멈추는 경우이며, 신청은 접수되지 않았고 자동 재시도 대상이 아닙니다. error.message 는 「휴업사실증명 발급은 사업자 계정으로만 신청할 수 있습니다. 사업자로 연결된 계정을 선택한 뒤 다시 시도해 주세요.」 입니다. | |
| VALIDATION_ | 다른 사업자 지정 — params 에 bsno 를 보내 연결된 계정의 사업자등록번호와 다른 번호를 지정한 경우이며, 신청은 접수되지 않았고 자동 재시도 대상이 아닙니다. error.message 는 「휴업사실증명 발급은 연결된 사업자 본인 것만 신청할 수 있습니다. bsno 를 비우고 다시 요청하거나, 그 사업자로 연결된 계정을 선택해 주세요.」 입니다. 이 증명서는 연결된 사업자 본인 것만 신청하므로 bsno 는 보내지 않아도 됩니다. | |
| PROVIDER_ | 휴업 이력 없음 — 신청 전에 조회한 연결 사업자의 이력에 휴업 기간이 없는 경우이며, 신청은 접수되지 않았고 자동 재시도 대상이 아닙니다. error.message 는 「연결된 사업자에는 휴업 기간이 없어 휴업사실증명을 신청할 수 없습니다. 신청은 접수하지 않았습니다. 휴업 신고가 처리된 뒤 다시 시도해 주세요.」 입니다. | |
| VALIDATION_ | 휴업 기간 선택 — 연결 사업자의 휴업 기간이 여럿인데 신청할 기간을 정하지 못했거나, 보낸 sfbTermStrtDt 또는 sfbTermEndDt 와 맞는 기간이 없는 경우이며, 신청은 접수되지 않았고 자동 재시도 대상이 아닙니다. error.message 가 신청할 수 있는 휴업 기간을 나열합니다. 휴업 기간이 하나면 params 를 빈 객체로 보내도 그 기간으로 신청합니다. 여럿이면 sfbTermStrtDt 에 신청할 기간의 시작일(YYYYMMDD)을 넣고, 시작일이 같은 기간이 여럿이면 sfbTermEndDt 도 넣어 다시 요청합니다. 본문이 달라지므로 confirmation_token 없이 보내 새 확인부터 받습니다. | |
| AUTH_ | 세션 없음 — 홈택스 세션이 없습니다. 홈택스 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다. | |
| PROVIDER_ | 업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다. | |
| PROVIDER_ | 홈택스 통신 오류 — 홈택스가 오류로 답하거나 연결이 끊겨 요청이 처리됐는지 알 수 없을 수 있으니, 다시 요청하기 전에 홈택스 화면에서 먼저 확인합니다. 홈택스가 오류 응답을 보내거나 연결이 끊긴 경우 error.message 는 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')입니다. | |
| PROVIDER_ | 홈택스 통신 오류 — 홈택스가 오류로 답하거나 연결이 끊겨 요청이 처리됐는지 알 수 없을 수 있으니, 다시 요청하기 전에 홈택스 화면에서 먼저 확인합니다. 홈택스가 오류 응답을 보내거나 연결이 끊긴 경우 error.message 는 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')입니다. | |
| PROVIDER_ | 홈택스 통신 오류 — 홈택스가 오류로 답하거나 연결이 끊겨 요청이 처리됐는지 알 수 없을 수 있으니, 다시 요청하기 전에 홈택스 화면에서 먼저 확인합니다. 홈택스가 오류 응답을 보내거나 연결이 끊긴 경우 error.message 는 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')입니다. |
7. 표준재무제표증명 신청hometax. certificate. apply. financial_ statement
MCP 도구 이름 hometax__
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
표준재무제표증명을 신청합니다.
- 홈택스 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [홈택스 로그인(세션 생성)]
- 요청 거절(HTTP 400, 작업은 만들어지지 않음).error.code=WRITE_CONFIRMATION_REQUIRED — confirmation_token 없이 부르면 홈택스에 아무것도 보내지 않고 이 오류로 끝납니다.error.message 에 확인할 내용이, error.confirmation_token 에 1회용 토큰이, error.preview 에 실행할 내용(what_will_happen_ko), 보낸 값(items), 보내지 않은 칸에 쓰일 값(defaults_ko), 되돌릴 수 없다는 안내(irreversible_ko)가 함께 옵니다.안내를 사용자에게 보여 주고 동의를 받은 뒤 같은 요청의 params.confirmation_token 에 그 토큰을 넣어 다시 보냅니다. 토큰은 10분 안에 한 번만 쓸 수 있고 처음 요청과 같은 본문에만 맞습니다.confirm 칸은 확인으로 쓰이지 않으며, 다시 보낼 때 더하면 본문이 달라져 확인 토큰 불일치로 끝납니다.
- 요청 거절(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 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 길이 | 필수 | 설명 |
|---|---|---|---|---|---|
| tin | string | - | 조건부 | 보내도 신청 대상은 바뀌지 않습니다. 신청서의 식별번호는 늘 로그인한 계정의 값입니다 | |
| txpr_ | string | - | 조건부 | 미입력 시 세션 상호 사용 | |
| bsno | string | - | Y | 대상 사업자등록번호(숫자 10자리) | |
| qrtTrt | string | - | Y | 개인/법인 구분 코드(02 개인, 03 법인) | |
| txyr | string | 4 | 조건부 | 과세년도(개인) | |
| incClCd | string | - | 조건부 | 소득구분(개인) | |
| bsyrEndYm | string | 6 | 조건부 | 사업연도 종료연월(법인) | |
| confirmation_ | string | - | N | 1회용 확인 토큰입니다. 처음에는 보내지 않습니다. 토큰 없이 부르면 기관에 아무것도 보내지 않고 작업도 만들지 않은 채 확인이 필요하다는 오류(WRITE_CONFIRMATION_REQUIRED)로 끝나고, 응답의 error.confirmation_token 에 토큰이 옵니다. error.message 의 안내를 사용자에게 보여 주고 동의를 받은 뒤 같은 요청에 이 토큰을 넣어 다시 부릅니다. 토큰은 10분 안에 한 번만 쓸 수 있고 처음 요청과 같은 본문, 같은 호출자, 같은 환경에서만 맞으며, 아니면 확인이 만료됐거나 내용이 달라졌다는 오류로 거절합니다 | |
| cerpIsnRqsQty | string | - | N | 신청할 발급 매수입니다. 보내지 않으면 서식에 정해진 값으로 신청합니다 | |
| cvaDcumSbmsOrgnClCd | string | - | N | 증명서 제출처 구분코드입니다. 보내지 않으면 서식에 정해진 값으로 신청합니다 | |
| cvaDcumGranMthdCd | string | - | N | 증명서 교부방법 코드입니다. 보내지 않으면 서식에 정해진 값으로 신청합니다 | |
| adrOpYn | string | - | N | 증명서에 주소를 표시할지 정하는 값으로 Y 나 N 을 보냅니다. 보내지 않으면 서식에 정해진 값으로 신청합니다 | |
| resnoOpYn | string | - | N | 증명서에 주민등록번호를 표시할지 정하는 값으로 Y 나 N 을 보냅니다. 법인(사업자) 계정은 이 값과 관계없이 항상 N 으로 신청하고, 개인 계정이 보내지 않으면 서식에 정해진 값을 씁니다 | |
| amtOpYn | string | - | N | 증명서에 금액을 표시할지 정하는 값으로 Y 나 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: financial_statement-$(date +%s)-$RANDOM" \
--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": "<필수>"
}
}'Response
- 기관이 신청을 받았음을 확인한 경우에만 성공합니다. result.data.outcome 은 confirmed 입니다.
- 접수번호(rcat_no)는 이 응답에 실리지 않을 수 있습니다. 내려받기에 쓸 접수번호는 증명서 신청 목록 조회의 행에서 읽습니다.
- 여러 JSON 타입이 함께 표시된 칸은 서버가 세부 타입을 고정하지 않는 기관 원문 또는 동적 값입니다.예시 값의 타입으로 단정하지 말고 실제 값의 타입을 확인해 주세요. null은 값이 비어 있다는 뜻이며, 필드 자체의 생략 여부는 필수 여부와 설명을 확인해 주세요.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| outcome | string | 기관 처리 판정. 성공 응답에서는 항상 confirmed 입니다 | |
| action | string | 요청한 액션 이름. outcome · action 외의 키는 홈택스 응답 본문에서 옵니다(기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다) | |
| cvaId | string | number | boolean | object | array | null | 기관이 발번한 증명서 아이디. 홈택스가 내려주는 키 이름 그대로입니다. 이 서식은 비어 올 수 있고, 그때 증명서 ID 는 증명서 신청 목록 조회의 같은 신청 행에서 cva_id 로 받습니다 기관 응답에 존재할 때만 반환됩니다. data 또는 cerpBscInfrDVO 내부에 있을 수 있으므로 최상위 존재를 전제로 접근하지 마세요. | |
| rtnCvaId | string | number | boolean | object | array | null | 홈택스 신고 내역 조회 결과의 rtnCvaId 와 같은 종류의 값이며 증명서 ID 가 아닙니다. 홈택스가 내려주는 키 이름 그대로입니다 기관 응답에 존재할 때만 반환됩니다. data 또는 cerpBscInfrDVO 내부에 있을 수 있으므로 최상위 존재를 전제로 접근하지 마세요. |
// result.data — outcome · action 외의 키는 홈택스 응답 본문에서 옵니다(기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다).
{
"outcome": "confirmed",
"action": "hometax.certificate.apply.financial_statement",
"cvaId": "...",
"rtnCvaId": "..."
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| PROVIDER_ | 처리 확인 불가 — 요청은 홈택스로 전송됐지만 처리됐는지 확인하지 못했습니다. 이미 처리됐을 수 있으므로 다시 요청하지 않고, 오류 메시지가 안내하는 홈택스 화면에서 먼저 확인합니다. | |
| AUTH_ | 세션 없음 — 홈택스 세션이 없습니다. 홈택스 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다. | |
| PROVIDER_ | 업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다. | |
| PROVIDER_ | 홈택스 통신 오류 — 홈택스가 오류로 답하거나 연결이 끊겨 요청이 처리됐는지 알 수 없을 수 있으니, 다시 요청하기 전에 홈택스 화면에서 먼저 확인합니다. 홈택스가 오류 응답을 보내거나 연결이 끊긴 경우 error.message 는 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')입니다. | |
| PROVIDER_ | 홈택스 통신 오류 — 홈택스가 오류로 답하거나 연결이 끊겨 요청이 처리됐는지 알 수 없을 수 있으니, 다시 요청하기 전에 홈택스 화면에서 먼저 확인합니다. 홈택스가 오류 응답을 보내거나 연결이 끊긴 경우 error.message 는 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')입니다. | |
| PROVIDER_ | 홈택스 통신 오류 — 홈택스가 오류로 답하거나 연결이 끊겨 요청이 처리됐는지 알 수 없을 수 있으니, 다시 요청하기 전에 홈택스 화면에서 먼저 확인합니다. 홈택스가 오류 응답을 보내거나 연결이 끊긴 경우 error.message 는 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')입니다. |
8. 폐업사실증명hometax. certificate. apply. business_ closure
MCP 도구 이름 hometax__
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
폐업사실증명을 신청합니다.
- 홈택스 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [홈택스 로그인(세션 생성)]
- 요청 거절(HTTP 400, 작업은 만들어지지 않음).error.code=WRITE_CONFIRMATION_REQUIRED — confirmation_token 없이 부르면 홈택스에 아무것도 보내지 않고 이 오류로 끝납니다.error.message 에 확인할 내용이, error.confirmation_token 에 1회용 토큰이, error.preview 에 실행할 내용(what_will_happen_ko), 보낸 값(items), 보내지 않은 칸에 쓰일 값(defaults_ko), 되돌릴 수 없다는 안내(irreversible_ko)가 함께 옵니다.안내를 사용자에게 보여 주고 동의를 받은 뒤 같은 요청의 params.confirmation_token 에 그 토큰을 넣어 다시 보냅니다. 토큰은 10분 안에 한 번만 쓸 수 있고 처음 요청과 같은 본문에만 맞습니다.confirm 칸은 확인으로 쓰이지 않으며, 다시 보낼 때 더하면 본문이 달라져 확인 토큰 불일치로 끝납니다.
- 요청 거절(HTTP 409, 작업은 만들어지지 않음).error.code=WRITE_CONFIRMATION_INVALID — 토큰이 만료됐거나, 이미 썼거나, 다른 호출자나 다른 환경에서 받은 것이거나, 확인한 요청 본문과 달라졌으면 홈택스에 아무것도 보내지 않고 이 오류로 끝나며 어느 쪽인지는 알려 주지 않습니다.error.message 는 「확인이 만료됐거나 확인한 내용과 달라졌습니다. 다시 확인해 주세요.」 입니다. confirmation_token 없이 같은 요청을 다시 보내 새 토큰과 안내를 받은 뒤 사용자에게 다시 확인을 받습니다.
- 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 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| tin | string | 조건부 | 보내도 신청 대상은 바뀌지 않습니다. 신청서의 식별번호는 늘 로그인한 계정의 값입니다 | |
| txpr_ | string | 조건부 | 미입력 시 세션 상호 사용 | |
| confirmation_ | string | N | 1회용 확인 토큰입니다. 처음에는 보내지 않습니다. 토큰 없이 부르면 기관에 아무것도 보내지 않고 작업도 만들지 않은 채 확인이 필요하다는 오류(WRITE_CONFIRMATION_REQUIRED)로 끝나고, 응답의 error.confirmation_token 에 토큰이 옵니다. error.message 의 안내를 사용자에게 보여 주고 동의를 받은 뒤 같은 요청에 이 토큰을 넣어 다시 부릅니다. 토큰은 10분 안에 한 번만 쓸 수 있고 처음 요청과 같은 본문, 같은 호출자, 같은 환경에서만 맞으며, 아니면 확인이 만료됐거나 내용이 달라졌다는 오류로 거절합니다 | |
| cerpIsnRqsQty | string | N | 신청할 발급 매수입니다. 보내지 않으면 서식에 정해진 값으로 신청합니다 | |
| cvaDcumSbmsOrgnClCd | string | N | 증명서 제출처 구분코드입니다. 보내지 않으면 서식에 정해진 값으로 신청합니다 | |
| cvaDcumGranMthdCd | string | N | 증명서 교부방법 코드입니다. 보내지 않으면 서식에 정해진 값으로 신청합니다 | |
| adrOpYn | string | N | 증명서에 주소를 표시할지 정하는 값으로 Y 나 N 을 보냅니다. 보내지 않으면 서식에 정해진 값으로 신청합니다 | |
| resnoOpYn | string | N | 증명서에 주민등록번호를 표시할지 정하는 값으로 Y 나 N 을 보냅니다. 법인(사업자) 계정은 이 값과 관계없이 항상 N 으로 신청하고, 개인 계정이 보내지 않으면 서식에 정해진 값을 씁니다 | |
| amtOpYn | string | N | 증명서에 금액을 표시할지 정하는 값으로 Y 나 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: business_closure-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "hometax",
"action": "hometax.certificate.apply.business_closure",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {}
}'Response
- 기관이 신청을 받았음을 확인한 경우에만 성공합니다. result.data.outcome 은 confirmed 입니다.
- 접수번호(rcat_no)는 이 응답에 실리지 않을 수 있습니다. 내려받기에 쓸 접수번호는 증명서 신청 목록 조회의 행에서 읽습니다.
- 여러 JSON 타입이 함께 표시된 칸은 서버가 세부 타입을 고정하지 않는 기관 원문 또는 동적 값입니다.예시 값의 타입으로 단정하지 말고 실제 값의 타입을 확인해 주세요. null은 값이 비어 있다는 뜻이며, 필드 자체의 생략 여부는 필수 여부와 설명을 확인해 주세요.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| outcome | string | 기관 처리 판정. 성공 응답에서는 항상 confirmed 입니다 | |
| action | string | 요청한 액션 이름. outcome · action 외의 키는 홈택스 응답 본문에서 옵니다(기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다) | |
| cvaId | string | number | boolean | object | array | null | 기관이 발번한 증명서 아이디. 홈택스가 내려주는 키 이름 그대로이며 비어 올 수 있습니다 기관 응답에 존재할 때만 반환됩니다. data 또는 cerpBscInfrDVO 내부에 있을 수 있으므로 최상위 존재를 전제로 접근하지 마세요. |
// result.data — outcome · action 외의 키는 홈택스 응답 본문에서 옵니다(기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다).
{
"outcome": "confirmed",
"action": "hometax.certificate.apply.business_closure",
"cvaId": "..."
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| PROVIDER_ | 처리 확인 불가 — 요청은 홈택스로 전송됐지만 처리됐는지 확인하지 못했습니다. 이미 처리됐을 수 있으므로 다시 요청하지 않고, 오류 메시지가 안내하는 홈택스 화면에서 먼저 확인합니다. | |
| VALIDATION_ | 사업자 계정 아님 — 연결된 홈택스 계정이 사업자 계정이 아니면 신청하기 전에 멈추는 경우이며, 신청은 접수되지 않았고 자동 재시도 대상이 아닙니다. error.message 는 「폐업사실증명 발급은 사업자 계정으로만 신청할 수 있습니다. 사업자로 연결된 계정을 선택한 뒤 다시 시도해 주세요.」 입니다. | |
| VALIDATION_ | 다른 사업자 지정 — params 에 bsno 를 보내 연결된 계정의 사업자등록번호와 다른 번호를 지정한 경우이며, 신청은 접수되지 않았고 자동 재시도 대상이 아닙니다. error.message 는 「폐업사실증명 발급은 연결된 사업자 본인 것만 신청할 수 있습니다. bsno 를 비우고 다시 요청하거나, 그 사업자로 연결된 계정을 선택해 주세요.」 입니다. 이 증명서는 연결된 사업자 본인 것만 신청하므로 bsno 는 보내지 않아도 됩니다. | |
| PROVIDER_ | 폐업 이력 없음 — 신청 전에 조회한 연결 사업자의 이력에 폐업일이 없는 경우이며, 신청은 접수되지 않았고 자동 재시도 대상이 아닙니다. error.message 는 「연결된 사업자에는 폐업 사실이 없어 폐업사실증명을 신청할 수 없습니다. 신청은 접수하지 않았습니다. 폐업 신고가 처리된 사업자 계정으로 다시 시도해 주세요.」 입니다. | |
| AUTH_ | 세션 없음 — 홈택스 세션이 없습니다. 홈택스 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다. | |
| PROVIDER_ | 업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다. | |
| PROVIDER_ | 홈택스 통신 오류 — 홈택스가 오류로 답하거나 연결이 끊겨 요청이 처리됐는지 알 수 없을 수 있으니, 다시 요청하기 전에 홈택스 화면에서 먼저 확인합니다. 홈택스가 오류 응답을 보내거나 연결이 끊긴 경우 error.message 는 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')입니다. | |
| PROVIDER_ | 홈택스 통신 오류 — 홈택스가 오류로 답하거나 연결이 끊겨 요청이 처리됐는지 알 수 없을 수 있으니, 다시 요청하기 전에 홈택스 화면에서 먼저 확인합니다. 홈택스가 오류 응답을 보내거나 연결이 끊긴 경우 error.message 는 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')입니다. | |
| PROVIDER_ | 홈택스 통신 오류 — 홈택스가 오류로 답하거나 연결이 끊겨 요청이 처리됐는지 알 수 없을 수 있으니, 다시 요청하기 전에 홈택스 화면에서 먼저 확인합니다. 홈택스가 오류 응답을 보내거나 연결이 끊긴 경우 error.message 는 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')입니다. |
9. 사업자등록증 재발급hometax. certificate. apply. business_ registration_ reissue
MCP 도구 이름 hometax__
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
사업자등록증 재발급을 신청합니다.
- 홈택스 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [홈택스 로그인(세션 생성)]
- 요청 거절(HTTP 400, 작업은 만들어지지 않음).error.code=WRITE_CONFIRMATION_REQUIRED — confirmation_token 없이 부르면 홈택스에 아무것도 보내지 않고 이 오류로 끝납니다.error.message 에 확인할 내용이, error.confirmation_token 에 1회용 토큰이, error.preview 에 실행할 내용(what_will_happen_ko), 보낸 값(items), 보내지 않은 칸에 쓰일 값(defaults_ko), 되돌릴 수 없다는 안내(irreversible_ko)가 함께 옵니다.안내를 사용자에게 보여 주고 동의를 받은 뒤 같은 요청의 params.confirmation_token 에 그 토큰을 넣어 다시 보냅니다. 토큰은 10분 안에 한 번만 쓸 수 있고 처음 요청과 같은 본문에만 맞습니다.confirm 칸은 확인으로 쓰이지 않으며, 다시 보낼 때 더하면 본문이 달라져 확인 토큰 불일치로 끝납니다.
- 요청 거절(HTTP 409, 작업은 만들어지지 않음).error.code=WRITE_CONFIRMATION_INVALID — 토큰이 만료됐거나, 이미 썼거나, 다른 호출자나 다른 환경에서 받은 것이거나, 확인한 요청 본문과 달라졌으면 홈택스에 아무것도 보내지 않고 이 오류로 끝나며 어느 쪽인지는 알려 주지 않습니다.error.message 는 「확인이 만료됐거나 확인한 내용과 달라졌습니다. 다시 확인해 주세요.」 입니다. confirmation_token 없이 같은 요청을 다시 보내 새 토큰과 안내를 받은 뒤 사용자에게 다시 확인을 받습니다.
- 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 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| tin | string | 조건부 | 보내도 신청 대상은 바뀌지 않습니다. 신청서의 식별번호는 늘 로그인한 계정의 값입니다 | |
| txpr_ | string | 조건부 | 미입력 시 세션 상호 사용 | |
| confirmation_ | string | N | 1회용 확인 토큰입니다. 처음에는 보내지 않습니다. 토큰 없이 부르면 기관에 아무것도 보내지 않고 작업도 만들지 않은 채 확인이 필요하다는 오류(WRITE_CONFIRMATION_REQUIRED)로 끝나고, 응답의 error.confirmation_token 에 토큰이 옵니다. error.message 의 안내를 사용자에게 보여 주고 동의를 받은 뒤 같은 요청에 이 토큰을 넣어 다시 부릅니다. 토큰은 10분 안에 한 번만 쓸 수 있고 처음 요청과 같은 본문, 같은 호출자, 같은 환경에서만 맞으며, 아니면 확인이 만료됐거나 내용이 달라졌다는 오류로 거절합니다 | |
| cerpIsnRqsQty | string | N | 신청할 발급 매수입니다. 보내지 않으면 서식에 정해진 값으로 신청합니다 | |
| cvaDcumGranMthdCd | string | N | 증명서 교부방법 코드입니다. 보내지 않으면 서식에 정해진 값으로 신청합니다 | |
| adrOpYn | string | N | 증명서에 주소를 표시할지 정하는 값으로 Y 나 N 을 보냅니다. 보내지 않으면 서식에 정해진 값으로 신청합니다 | |
| resnoOpYn | string | N | 증명서에 주민등록번호를 표시할지 정하는 값으로 Y 나 N 을 보냅니다. 법인(사업자) 계정은 이 값과 관계없이 항상 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: business_registration_reissue-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "hometax",
"action": "hometax.certificate.apply.business_registration_reissue",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {}
}'Response
- 기관이 신청을 받았음을 확인한 경우에만 성공합니다. result.data.outcome 은 confirmed 입니다.
- 접수번호(rcat_no)는 이 응답에 실리지 않을 수 있습니다. 내려받기에 쓸 접수번호는 증명서 신청 목록 조회의 행에서 읽습니다.
- 여러 JSON 타입이 함께 표시된 칸은 서버가 세부 타입을 고정하지 않는 기관 원문 또는 동적 값입니다.예시 값의 타입으로 단정하지 말고 실제 값의 타입을 확인해 주세요. null은 값이 비어 있다는 뜻이며, 필드 자체의 생략 여부는 필수 여부와 설명을 확인해 주세요.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| outcome | string | 기관 처리 판정. 성공 응답에서는 항상 confirmed 입니다 | |
| action | string | 요청한 액션 이름. outcome · action 외의 키는 홈택스 응답 본문에서 옵니다(기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다) | |
| cvaId | string | number | boolean | object | array | null | 기관이 발번한 증명서 아이디. 홈택스가 내려주는 키 이름 그대로이며 비어 올 수 있습니다 기관 응답에 존재할 때만 반환됩니다. data 또는 cerpBscInfrDVO 내부에 있을 수 있으므로 최상위 존재를 전제로 접근하지 마세요. |
// result.data — outcome · action 외의 키는 홈택스 응답 본문에서 옵니다(기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다).
{
"outcome": "confirmed",
"action": "hometax.certificate.apply.business_registration_reissue",
"cvaId": "..."
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| PROVIDER_ | 처리 확인 불가 — 요청은 홈택스로 전송됐지만 처리됐는지 확인하지 못했습니다. 이미 처리됐을 수 있으므로 다시 요청하지 않고, 오류 메시지가 안내하는 홈택스 화면에서 먼저 확인합니다. | |
| AUTH_ | 세션 없음 — 홈택스 세션이 없습니다. 홈택스 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다. | |
| PROVIDER_ | 업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다. | |
| PROVIDER_ | 홈택스 통신 오류 — 홈택스가 오류로 답하거나 연결이 끊겨 요청이 처리됐는지 알 수 없을 수 있으니, 다시 요청하기 전에 홈택스 화면에서 먼저 확인합니다. 홈택스가 오류 응답을 보내거나 연결이 끊긴 경우 error.message 는 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')입니다. | |
| PROVIDER_ | 홈택스 통신 오류 — 홈택스가 오류로 답하거나 연결이 끊겨 요청이 처리됐는지 알 수 없을 수 있으니, 다시 요청하기 전에 홈택스 화면에서 먼저 확인합니다. 홈택스가 오류 응답을 보내거나 연결이 끊긴 경우 error.message 는 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')입니다. | |
| PROVIDER_ | 홈택스 통신 오류 — 홈택스가 오류로 답하거나 연결이 끊겨 요청이 처리됐는지 알 수 없을 수 있으니, 다시 요청하기 전에 홈택스 화면에서 먼저 확인합니다. 홈택스가 오류 응답을 보내거나 연결이 끊긴 경우 error.message 는 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')입니다. |
10. 증명발급 소득금액증명원hometax. certificate. apply. income_ statement
MCP 도구 이름 hometax__
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
증명발급 소득금액증명원을 신청합니다.
- 홈택스 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [홈택스 로그인(세션 생성)]
- 요청 거절(HTTP 400, 작업은 만들어지지 않음).error.code=WRITE_CONFIRMATION_REQUIRED — confirmation_token 없이 부르면 홈택스에 아무것도 보내지 않고 이 오류로 끝납니다.error.message 에 확인할 내용이, error.confirmation_token 에 1회용 토큰이, error.preview 에 실행할 내용(what_will_happen_ko), 보낸 값(items), 보내지 않은 칸에 쓰일 값(defaults_ko), 되돌릴 수 없다는 안내(irreversible_ko)가 함께 옵니다.안내를 사용자에게 보여 주고 동의를 받은 뒤 같은 요청의 params.confirmation_token 에 그 토큰을 넣어 다시 보냅니다. 토큰은 10분 안에 한 번만 쓸 수 있고 처음 요청과 같은 본문에만 맞습니다.confirm 칸은 확인으로 쓰이지 않으며, 다시 보낼 때 더하면 본문이 달라져 확인 토큰 불일치로 끝납니다.
- 요청 거절(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 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 길이 | 필수 | 설명 |
|---|---|---|---|---|---|
| tin | string | - | 조건부 | 보내도 신청 대상은 바뀌지 않습니다. 신청서의 식별번호는 늘 로그인한 계정의 값입니다 | |
| txpr_ | string | - | 조건부 | 미입력 시 세션 상호 사용 | |
| txnrmStrtYm | string | 6 | Y | 과세기간 시작년월(귀속연도 전체 예: 202401) | |
| txnrmEndYm | string | 6 | Y | 과세기간 종료년월(예: 202412) | |
| confirmation_ | string | - | N | 1회용 확인 토큰입니다. 처음에는 보내지 않습니다. 토큰 없이 부르면 기관에 아무것도 보내지 않고 작업도 만들지 않은 채 확인이 필요하다는 오류(WRITE_CONFIRMATION_REQUIRED)로 끝나고, 응답의 error.confirmation_token 에 토큰이 옵니다. error.message 의 안내를 사용자에게 보여 주고 동의를 받은 뒤 같은 요청에 이 토큰을 넣어 다시 부릅니다. 토큰은 10분 안에 한 번만 쓸 수 있고 처음 요청과 같은 본문, 같은 호출자, 같은 환경에서만 맞으며, 아니면 확인이 만료됐거나 내용이 달라졌다는 오류로 거절합니다 | |
| cerpIsnRqsQty | string | - | N | 신청할 발급 매수입니다. 보내지 않으면 서식에 정해진 값으로 신청합니다 | |
| cvaDcumSbmsOrgnClCd | string | - | N | 증명서 제출처 구분코드입니다. 보내지 않으면 서식에 정해진 값으로 신청합니다 | |
| cvaDcumGranMthdCd | string | - | N | 증명서 교부방법 코드입니다. 보내지 않으면 서식에 정해진 값으로 신청합니다 | |
| adrOpYn | string | - | N | 증명서에 주소를 표시할지 정하는 값으로 Y 나 N 을 보냅니다. 보내지 않으면 서식에 정해진 값으로 신청합니다 | |
| resnoOpYn | string | - | N | 증명서에 주민등록번호를 표시할지 정하는 값으로 Y 나 N 을 보냅니다. 법인(사업자) 계정은 이 값과 관계없이 항상 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: income_statement-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "hometax",
"action": "hometax.certificate.apply.income_statement",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {
"txnrmStrtYm": "<필수>",
"txnrmEndYm": "<필수>"
}
}'Response
- 기관이 신청을 받았음을 확인한 경우에만 성공합니다. result.data.outcome 은 confirmed 입니다.
- 접수번호(rcat_no)는 이 응답에 실리지 않을 수 있습니다. 내려받기에 쓸 접수번호는 증명서 신청 목록 조회의 행에서 읽습니다.
- 여러 JSON 타입이 함께 표시된 칸은 서버가 세부 타입을 고정하지 않는 기관 원문 또는 동적 값입니다.예시 값의 타입으로 단정하지 말고 실제 값의 타입을 확인해 주세요. null은 값이 비어 있다는 뜻이며, 필드 자체의 생략 여부는 필수 여부와 설명을 확인해 주세요.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| outcome | string | 기관 처리 판정. 성공 응답에서는 항상 confirmed 입니다 | |
| action | string | 요청한 액션 이름. outcome · action 외의 키는 홈택스 응답 본문에서 옵니다(기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다) | |
| cvaId | string | number | boolean | object | array | null | 기관이 발번한 증명서 아이디. 홈택스가 내려주는 키 이름 그대로이며 비어 올 수 있습니다 기관 응답에 존재할 때만 반환됩니다. data 또는 cerpBscInfrDVO 내부에 있을 수 있으므로 최상위 존재를 전제로 접근하지 마세요. |
// result.data — outcome · action 외의 키는 홈택스 응답 본문에서 옵니다(기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다).
{
"outcome": "confirmed",
"action": "hometax.certificate.apply.income_statement",
"cvaId": "..."
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| PROVIDER_ | 처리 확인 불가 — 요청은 홈택스로 전송됐지만 처리됐는지 확인하지 못했습니다. 이미 처리됐을 수 있으므로 다시 요청하지 않고, 오류 메시지가 안내하는 홈택스 화면에서 먼저 확인합니다. | |
| AUTH_ | 세션 없음 — 홈택스 세션이 없습니다. 홈택스 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다. | |
| PROVIDER_ | 업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다. | |
| PROVIDER_ | 홈택스 통신 오류 — 홈택스가 오류로 답하거나 연결이 끊겨 요청이 처리됐는지 알 수 없을 수 있으니, 다시 요청하기 전에 홈택스 화면에서 먼저 확인합니다. 홈택스가 오류 응답을 보내거나 연결이 끊긴 경우 error.message 는 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')입니다. | |
| PROVIDER_ | 홈택스 통신 오류 — 홈택스가 오류로 답하거나 연결이 끊겨 요청이 처리됐는지 알 수 없을 수 있으니, 다시 요청하기 전에 홈택스 화면에서 먼저 확인합니다. 홈택스가 오류 응답을 보내거나 연결이 끊긴 경우 error.message 는 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')입니다. | |
| PROVIDER_ | 홈택스 통신 오류 — 홈택스가 오류로 답하거나 연결이 끊겨 요청이 처리됐는지 알 수 없을 수 있으니, 다시 요청하기 전에 홈택스 화면에서 먼저 확인합니다. 홈택스가 오류 응답을 보내거나 연결이 끊긴 경우 error.message 는 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')입니다. |
11. 증명서 자동 신청hometax. certificate. apply_ auto
MCP 도구 이름 hometax__
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
로그인한 사업자의 정보로 신청서를 채워 증명서를 홈택스에 신청하고, 접수번호와 내려받기에 쓸 정보를 함께 받습니다.
Request
| 순번 | 변수명 | 필수 | 설명 |
|---|---|---|---|
| Authorization | Y | API 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다. | |
| X- | Y | 호출 환경입니다.
| |
| Idempotency- | Y | 재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다. | |
| Content- | Y | 요청 본문 형식입니다.
| |
| X- | N | 추적 아이디입니다. 지정하지 않으면 서버가 발급합니다. |
| 순번 | 변수명 | 타입 | 길이 | 필수 | 설명 |
|---|---|---|---|---|---|
| provider | string | - | Y | 호출할 기관입니다.
| |
| action | string | - | Y | 호출할 작업입니다.
| |
| account_ | string | 36 | 조건부 | 등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명이 하나뿐일 때만 그것이 자동으로 선택됩니다. 둘 이상이면 대표로 지정한 것이 있어도 고르지 않으므로 직접 지정해야 합니다. 대표는 묶음 상품이 기관마다 자격증명을 고를 때만 씁니다. 등록한 자격증명이 없거나 하나를 고르지 못하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다. | |
| params | object | - | N | 작업 파라미터입니다. 이 API 는 빈 객체로 호출할 수 있습니다. | |
| encrypted_ | object | - | N | 민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 길이 | 필수 | 설명 |
|---|---|---|---|---|---|
| confirmation_ | string | - | N | 1회용 확인 토큰입니다. 처음에는 보내지 않습니다. 토큰 없이 부르면 기관에 아무것도 보내지 않고 작업도 만들지 않은 채 확인이 필요하다는 오류(WRITE_CONFIRMATION_REQUIRED)로 끝나고, 응답의 error.confirmation_token 에 토큰이 옵니다. error.message 의 안내를 사용자에게 보여 주고 동의를 받은 뒤 같은 요청에 이 토큰을 넣어 다시 부릅니다. 토큰은 10분 안에 한 번만 쓸 수 있고 처음 요청과 같은 본문, 같은 호출자, 같은 환경에서만 맞으며, 아니면 확인이 만료됐거나 내용이 달라졌다는 오류로 거절합니다. 신청하면 홈택스에 접수 기록이 남고 취소할 수 없습니다 | |
| cert_ | string | - | N | 증명서 서식 — 다음 9종 중 하나: cert_gukse_wannap 국세완납증명 / cert_napse_sasil 납세사실증명 / cert_bugase_gwase_pyojun 부가가치세과세표준증명 / cert_saeopja_deungrok_jeungmyeong 사업자등록증명 / cert_hyupeop_sasil 휴업사실증명 / cert_pyojun_jaemu_jepyo 표준재무제표증명 / cert_pyepeop_sasil 폐업사실증명 / cert_saeopja_jaebalgup 사업자등록증 재발급 / cert_sodeuk_geumaeg_jeungmyeong 소득금액증명. 보내지 않으면 cert_gukse_wannap(국세완납증명)로 신청되며, 표에 없는 값은 홈택스에 닿기 전에 거절됩니다 | |
| use_ | boolean | - | N | 신청서에 적을 납세자 이름을 고릅니다. true 이면 로그인한 계정의 사업자(법인) 이름을, false 이면 대표자 이름(없으면 사업자 이름)을 씁니다. 신청서의 식별번호는 이 값과 상관없이 로그인한 계정의 값입니다. 보내지 않거나 null 이면 true 입니다. 참/거짓 값 말고 글자로도 받습니다(대소문자 무관, 참은 1, on, true, y, yes, 거짓은 0, false, n, no, off). 수는 0 이면 false, 그 밖의 수는 true 입니다. 그 밖의 값은 신청하지 않고 거절합니다 | |
| strtYm | string | 6 | N | 조회 시작 연월입니다. 부가가치세과세표준증명 서식을 고를 때 필요하고, 그 밖의 서식에서는 보내지 않습니다 | |
| endYm | string | 6 | N | 조회 종료 연월입니다. 부가가치세과세표준증명 서식을 고를 때 필요하고, 그 밖의 서식에서는 보내지 않습니다 | |
| bsno | string | - | N | 대상 사업자등록번호(숫자 10자리)입니다. 표준재무제표증명 서식을 고를 때 필요하고, 그 밖의 서식에서는 보내지 않습니다 | |
| qrtTrt | string | - | N | 개인인지 법인인지 나누는 구분 코드입니다(02 개인, 03 법인). 표준재무제표증명 서식을 고를 때 필요하고, 이 값에 따라 아래의 txyr 나 bsyrEndYm 중 하나를 함께 보냅니다 | |
| txyr | string | 4 | N | 과세년도입니다. 표준재무제표증명 서식에서 개인(qrtTrt 가 02)일 때 필요합니다 | |
| incClCd | string | - | N | 소득구분 코드입니다. 표준재무제표증명 서식에서 개인(qrtTrt 가 02)일 때 필요합니다 | |
| bsyrEndYm | string | 6 | N | 사업연도 종료연월입니다. 표준재무제표증명 서식에서 법인(qrtTrt 가 03)일 때 필요합니다 | |
| txnrmStrtYm | string | 6 | N | 과세기간 시작년월입니다. 소득금액증명 서식을 고를 때 필요하고, 귀속연도 전체를 보려면 그 해의 1월(예: 202401)을 보냅니다 | |
| txnrmEndYm | string | 6 | N | 과세기간 종료년월입니다. 소득금액증명 서식을 고를 때 필요하고, 귀속연도 전체를 보려면 그 해의 12월(예: 202412)을 보냅니다 | |
| cerpIsnRqsQty | string | - | N | 신청할 발급 매수입니다. 보내지 않으면 서식에 정해진 값으로 신청합니다 | |
| cvaDcumSbmsOrgnClCd | string | - | N | 증명서 제출처 구분코드입니다. 보내지 않으면 서식에 정해진 값으로 신청합니다 | |
| cvaDcumGranMthdCd | string | - | N | 증명서 교부방법 코드입니다. 보내지 않으면 서식에 정해진 값으로 신청합니다 | |
| adrOpYn | string | - | N | 증명서에 주소를 표시할지 정하는 값으로 Y 나 N 을 보냅니다. 보내지 않으면 서식에 정해진 값으로 신청합니다 | |
| resnoOpYn | string | - | N | 증명서에 주민등록번호를 표시할지 정하는 값으로 Y 나 N 을 보냅니다. 법인(사업자) 계정은 이 값과 관계없이 항상 N 으로 신청하고, 개인 계정이 보내지 않으면 서식에 정해진 값을 씁니다 | |
| amtOpYn | string | - | N | 증명서에 금액을 표시할지 정하는 값으로 Y 나 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: apply_auto-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "hometax",
"action": "hometax.certificate.apply_auto",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {}
}'Response
- result.data 에는 홈택스가 신청 응답으로 내려 준 본문에 outcome 과 action 이 더해져 담깁니다.아래 칸 밖의 칸은 이름과 값을 홈택스가 정하므로 이 문서가 보장하지 않습니다(기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다).
- 내려받기에 쓸 접수번호(rcat_no)와 보고서 경로(rpt_pkg_pth)는 list_info 안에 옵니다. list_info 가 없으면 증명서 신청 목록 조회의 행에서 읽습니다.
- 서식이 cert_bugase_gwase_pyojun 또는 cert_pyojun_jaemu_jepyo 이면 cvaId 가 비어 올 수 있고, 그때 증명서 ID 는 증명서 신청 목록 조회의 같은 신청 행에서 cva_id 로 받습니다.
- 서식이 cert_pyojun_jaemu_jepyo 이면 응답에 오는 rtnCvaId 는 증명서 ID 가 아닙니다.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| outcome | string | 기관이 신청을 받았다는 판정입니다. 성공 응답에서는 항상 confirmed 입니다. 기관에 요청은 갔지만 접수됐는지 확인하지 못한 경우는 이 응답이 아니라 실패(PROVIDER_OUTCOME_UNCONFIRMED)로 옵니다. | |
| action | string | 실행한 액션의 ID 입니다. | |
| cvaId | string | null | 기관이 발번한 증명서 ID 입니다. 홈택스가 내려 주는 키 이름 그대로이고, 내려받기의 cva_id 로 보내며 서식에 따라 비어 올 수 있습니다. | |
| list_ | object | 방금 신청한 증명서의 신청 목록 행입니다. 신청이 접수된 직후 신청 목록의 첫 쪽(10건)에서 그 증명서를 찾았을 때만 오고, 목록 조회가 실패하거나 거기서 찾지 못하면 이 칸 없이 신청 결과만 옵니다. | |
| list_ | string | null | 신청 목록 행의 보고서 경로입니다. 내려받기의 rpt_pkg_pth 로 보냅니다. 값이 없으면 null 입니다. | |
| list_ | string | 신청 목록 행의 접수번호입니다. 내려받기의 rcat_no 로 보냅니다. | |
| list_ | string | 신청 목록 행의 증명서 종류 이름입니다. | |
| list_ | string | 신청 목록 행의 처리 상태 이름입니다. | |
| list_ | string | 신청 목록 행의 발급 상태 이름입니다. | |
| list_ | string | null | 신청 목록 행의 발급 수량 칸입니다. 값이 없으면 null 입니다. |
// result.data - 값 자리에는 각 칸의 형식을 적었습니다 (실제 값이 아닙니다)
{
"outcome": "<string>",
"action": "<string>",
"cvaId": "<string | null>",
"list_info": {
"rpt_pkg_pth": "<string | null>",
"rcat_no": "<string>",
"cva_knd_nm": "<string>",
"state_nm": "<string>",
"issue_stat_nm": "<string>",
"cerp_isn_qty": "<string | null>"
}
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| WRITE_ | 요청에 확인 토큰(confirmation_token)이 없으면 홈택스에 아무것도 보내지 않고 작업도 만들지 않은 채 이 오류로 끝납니다. error.message 는 cert_template 로 정한 서식의 확인 문구로 시작해 실행할 내용의 미리보기가 이어지고, error.confirmation_token 에 1회용 토큰이, error.preview 에 미리보기 객체가 함께 옵니다. 이 내용을 고객에게 그대로 보여 주고 확인을 받은 뒤, 같은 요청의 params.confirmation_token 에 응답의 error.confirmation_token 값을 넣어 다시 호출해 주세요. 토큰은 10분 안에 한 번만 쓸 수 있고, 확인한 요청 본문과 같은 본문에만 맞습니다. 확인값(confirm)은 보지 않으니 입력하지 않아도 됩니다. | |
| WRITE_ | 토큰이 만료됐거나, 이미 썼거나, 다른 호출자나 다른 환경에서 받은 것이거나, 확인한 요청 본문과 달라졌으면 홈택스에 아무것도 보내지 않고 작업도 만들지 않은 채 이 오류로 끝납니다. error.message 는 「확인이 만료됐거나 확인한 내용과 달라졌습니다. 다시 확인해 주세요.」 입니다. 토큰 없이 다시 요청하면 새 토큰과 미리보기를 받습니다. | |
| VALIDATION_ | cert_template 이 신청할 수 있는 서식 9가지에 없으면 홈택스에 보내지 않고 이 오류로 끝납니다. error.message 는 「지원하지 않는 증명서 서식입니다: '보낸 값'」 으로 시작하고 고를 수 있는 서식 목록이 이어집니다. | |
| AUTH_ | 저장된 기관 세션이 없습니다. 같은 연동 계정으로 hometax.session.login 을 먼저 실행해 세션을 연 뒤 다시 보냅니다. | |
| PROVIDER_ | 기관 세션이 만료됐습니다. 같은 연동 계정으로 hometax.session.login 을 다시 실행해 세션을 연 뒤 다시 보냅니다. | |
| PROVIDER_ | 신청 전에 홈택스에서 납세자 주소를 조회하는 서식은, 홈택스가 그 조회를 거절하면(응답 봉투의 resultMsg.result 가 비어 있지도 S 도 아닌 값) 신청을 보내지 않고 이 오류로 끝납니다. error.message 는 홈택스가 알려 준 사유이고, 사유를 주지 않으면 「기관이 요청을 처리하지 않았습니다. 사유는 알려 주지 않았습니다. 입력값을 그대로 두고 잠시 후 다시 시도해 주세요.」 입니다. | |
| PROVIDER_ | 홈택스가 서비스 중지 시간이라고 답한 경우입니다. 값이 틀린 것이 아니라 시간의 문제이고 요청은 처리되지 않았습니다. error.message 는 중지 시간을 읽었으면 그 시간을 함께 알리고, 읽지 못했으면 「지금은 홈택스 서비스 중지 시간이라 요청이 처리되지 않았습니다. 중지 시간이 지난 뒤 다시 요청해 주세요.」 입니다. | |
| VALIDATION_ | 서식(cert_template)이 cert_bugase_gwase_pyojun 이고 연결된 홈택스 계정이 개인 계정이면 신청하기 전에 이 오류로 끝나며, 신청은 접수되지 않았고 자동으로 다시 시도하지 않습니다. error.message 는 「부가가치세 과세표준증명 발급은 사업자 계정으로만 신청할 수 있습니다. 사업자로 연결된 계정을 선택한 뒤 다시 시도해 주세요.」 입니다. | |
| VALIDATION_ | 서식(cert_template)이 cert_hyupeop_sasil 이고 연결된 홈택스 계정이 사업자 계정이 아니면 신청하기 전에 이 오류로 끝나며, 신청은 접수되지 않았고 자동으로 다시 시도하지 않습니다. error.message 는 「휴업사실증명 발급은 사업자 계정으로만 신청할 수 있습니다. 사업자로 연결된 계정을 선택한 뒤 다시 시도해 주세요.」 입니다. | |
| VALIDATION_ | 서식(cert_template)이 cert_hyupeop_sasil 이고 bsno 를 보내 연결된 계정의 사업자등록번호와 다른 번호를 지정하면 신청하기 전에 이 오류로 끝나며, 신청은 접수되지 않았고 자동으로 다시 시도하지 않습니다. error.message 는 「휴업사실증명 발급은 연결된 사업자 본인 것만 신청할 수 있습니다. bsno 를 비우고 다시 요청하거나, 그 사업자로 연결된 계정을 선택해 주세요.」 입니다. 이 서식은 연결된 사업자 본인 것만 신청하므로 bsno 는 보내지 않아도 됩니다. | |
| VALIDATION_ | 서식(cert_template)이 cert_pyepeop_sasil 이고 연결된 홈택스 계정이 사업자 계정이 아니면 신청하기 전에 이 오류로 끝나며, 신청은 접수되지 않았고 자동으로 다시 시도하지 않습니다. error.message 는 「폐업사실증명 발급은 사업자 계정으로만 신청할 수 있습니다. 사업자로 연결된 계정을 선택한 뒤 다시 시도해 주세요.」 입니다. | |
| VALIDATION_ | 서식(cert_template)이 cert_pyepeop_sasil 이고 bsno 를 보내 연결된 계정의 사업자등록번호와 다른 번호를 지정하면 신청하기 전에 이 오류로 끝나며, 신청은 접수되지 않았고 자동으로 다시 시도하지 않습니다. error.message 는 「폐업사실증명 발급은 연결된 사업자 본인 것만 신청할 수 있습니다. bsno 를 비우고 다시 요청하거나, 그 사업자로 연결된 계정을 선택해 주세요.」 입니다. 이 서식은 연결된 사업자 본인 것만 신청하므로 bsno 는 보내지 않아도 됩니다. | |
| PROVIDER_ | 기관이 신청을 거절한 경우입니다(접수 전). error.message 는 「기관이 민원증명 신청을 거절했습니다.」 로 시작하고 기관이 알려 준 사유가 이어집니다. 신청이 접수되지 않았으므로 사유를 고쳐 다시 신청할 수 있습니다. 서식(cert_template)이 cert_sodeuk_geumaeg_jeungmyeong 이면 error.message 는 「기관이 민원증명 신청을 거절했습니다. 소득금액증명은 개인과 개인사업자만 신청할 수 있습니다. 법인 계정으로는 신청되지 않습니다.」 로 시작합니다. | |
| PROVIDER_ | 신청 요청은 기관에 갔지만 접수됐는지 확인하지 못한 경우입니다(응답에 접수 판정 resultMsg.result 도 발번된 증명서 ID 나 접수번호도 없습니다). 이 오류로 끝나며 자동으로 다시 시도하지 않습니다. error.message 는 「기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다. 홈택스 [민원증명 > 민원증명 발급신청 결과 조회]에서 방금 신청한 증명이 접수됐는지 확인해 주세요. 접수되지 않았을 때만 다시 신청하세요.」 입니다. |
12. 증명서 자동 신청 후 내려받기hometax. certificate. apply_ auto_ download
MCP 도구 이름 hometax__
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
국세완납증명 1매를 홈택스에 신청하고, 발급되면 바로 발급용으로 출력해 PDF 파일로 받는 일을 미리보기를 확인한 뒤 다시 요청하는 것으로 끝냅니다.
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 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| confirmation_ | string | N | 1회용 확인 토큰입니다. 처음에는 보내지 않습니다. 토큰 없이 부르면 기관에 아무것도 보내지 않고 작업도 만들지 않은 채 확인이 필요하다는 오류(WRITE_CONFIRMATION_REQUIRED)로 끝나고, 응답의 error.confirmation_token 에 토큰이 옵니다. error.message 의 안내를 사용자에게 보여 주고 동의를 받은 뒤 같은 요청에 이 토큰을 넣어 다시 부릅니다. 토큰은 10분 안에 한 번만 쓸 수 있고 처음 요청과 같은 본문, 같은 호출자, 같은 환경에서만 맞으며, 아니면 확인이 만료됐거나 내용이 달라졌다는 오류로 거절합니다. 국세완납증명 신청이 먼저 접수되고 이어서 발급용으로 출력하므로 접수 기록이 남고 발급 한도 1매가 사용되며 되돌릴 수 없습니다 |
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: apply_auto_download-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "hometax",
"action": "hometax.certificate.apply_auto_download",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {}
}'Response
- 발급한 증명서 PDF 는 result.data 가 아니라 result.artifacts 로 옵니다. result.data 에는 아래 칸만 있습니다.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| outcome | string | 발급이 확인됐다는 판정입니다. 성공 응답에서는 항상 confirmed 입니다. 기관에 요청은 갔지만 결과를 확인하지 못한 경우는 이 응답이 아니라 실패(PROVIDER_OUTCOME_UNCONFIRMED)로 옵니다. | |
| action | string | 실행한 액션의 ID 입니다. | |
| verdict_ | object | 기관이 출력을 기록했다고 판정한 근거입니다. 기관의 출력 결과 보고 응답에서 resultMsg.result 의 값이 S 이면 확인으로 읽고, 그 값이 없거나 다르면 기관 신청 목록의 실제 발급 수량이 출력 전보다 늘었는지로 다시 확인합니다. 읽은 위치(verdict_path)와 읽은 값(verdict), 받아들이는 값(accepted_values) 같은 진단 칸이 담기고 칸 구성은 판정 경로에 따라 달라집니다. | |
| cva_ | string | 이 요청이 신청해 기관이 발번한 증명서 ID 입니다. | |
| rcat_ | string | 신청 목록의 그 증명서 행에서 읽은 접수번호입니다. |
// result.data - 값 자리에는 각 칸의 형식을 적었습니다 (실제 값이 아닙니다)
{
"outcome": "<string>",
"action": "<string>",
"verdict_detail": {},
"cva_id": "<string>",
"rcat_no": "<string>"
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| WRITE_ | 요청에 확인 토큰(confirmation_token)이 없으면 홈택스에 아무것도 보내지 않고 작업도 만들지 않은 채 이 오류로 끝납니다. error.message 는 「증명서 발급 신청은 홈택스에 접수 기록을 남기고 취소할 수 없어 신청 전 확인이 필요합니다. 아래 내용을 사용자에게 보여주고 동의를 받으세요.」 로 시작해 실행할 내용의 미리보기가 이어지고, error.confirmation_token 에 1회용 토큰이, error.preview 에 미리보기 객체가 함께 옵니다. 이 내용을 고객에게 그대로 보여 주고 확인을 받은 뒤, 같은 요청의 params.confirmation_token 에 응답의 error.confirmation_token 값을 넣어 다시 호출해 주세요. 토큰은 10분 안에 한 번만 쓸 수 있고, 확인한 요청 본문과 같은 본문에만 맞습니다. 확인값(confirm)은 보지 않으니 입력하지 않아도 됩니다. | |
| WRITE_ | 토큰이 만료됐거나, 이미 썼거나, 다른 호출자나 다른 환경에서 받은 것이거나, 확인한 요청 본문과 달라졌으면 홈택스에 아무것도 보내지 않고 작업도 만들지 않은 채 이 오류로 끝납니다. error.message 는 「확인이 만료됐거나 확인한 내용과 달라졌습니다. 다시 확인해 주세요.」 입니다. 토큰 없이 다시 요청하면 새 토큰과 미리보기를 받습니다. | |
| AUTH_ | 저장된 기관 세션이 없습니다. 같은 연동 계정으로 hometax.session.login 을 먼저 실행해 세션을 연 뒤 다시 보냅니다. | |
| PROVIDER_ | 기관 세션이 만료됐습니다. 같은 연동 계정으로 hometax.session.login 을 다시 실행해 세션을 연 뒤 다시 보냅니다. | |
| PROVIDER_ | 홈택스가 서비스 중지 시간이라고 답한 경우입니다. 값이 틀린 것이 아니라 시간의 문제이고 요청은 처리되지 않았습니다. error.message 는 중지 시간을 읽었으면 그 시간을 함께 알리고, 읽지 못했으면 「지금은 홈택스 서비스 중지 시간이라 요청이 처리되지 않았습니다. 중지 시간이 지난 뒤 다시 요청해 주세요.」 입니다. | |
| PROVIDER_ | 기관이 신청을 거절한 경우입니다(접수 전). error.message 는 「기관이 민원증명 신청을 거절했습니다.」 로 시작하고 기관이 알려 준 사유가 이어집니다. 신청이 접수되지 않았으므로 사유를 고쳐 다시 신청할 수 있습니다. | |
| PROVIDER_ | 기관이 증명서 신청 결과로 접수번호를 주지 않았습니다. 접수됐는지 확인하기 전에는 다시 신청하지 마세요. 홈택스 민원증명 발급내역에서 같은 증명서가 있는지 먼저 확인해 주세요. | |
| PROVIDER_ | 신청은 접수됐지만 발급 대기나 출력 단계에서 멈춘 경우입니다. error.message 는 「증명서 신청은 접수됐습니다(증명서 ID {cva_id}, 접수번호 {rcat_no}). 파일은 내려받지 못했습니다.」 로 시작하고 아래 사유 중 하나가 이어진 뒤 「다시 신청하지 마시고, 잠시 뒤 증명서 내려받기에 이 증명서 ID 와 접수번호로 요청해 주세요.」 로 끝납니다(중괄호 자리에는 그 건의 실제 값이 들어갑니다). 신청은 이미 접수됐으므로 이 작업을 다시 부르면 두 번째 신청이 접수됩니다. | |
| PROVIDER_ | 접수번호를 아직 읽지 못한 채 멈추면 앞 문장은 「증명서 신청은 접수됐습니다(증명서 ID {cva_id}).」 로 증명서 ID 만 싣고 끝 안내는 「다시 신청하지 마시고, 잠시 뒤 증명서 목록에서 이 증명서 ID 의 접수번호를 확인한 다음 증명서 내려받기에 두 값으로 요청해 주세요.」 입니다. 사유가 발급 한도 소진이면 끝 안내가 붙지 않습니다. | |
| PROVIDER_ | 신청이 접수된 뒤의 사유입니다. 「기관이 아직 발급을 끝내지 않았습니다.」 | |
| PROVIDER_ | 신청이 접수된 뒤의 사유입니다. 「증명서 발급번호를 찾지 못했습니다. 증명서가 아직 발급되지 않았거나, 증명서 목록에서 해당 건을 먼저 조회해야 합니다.」 | |
| PROVIDER_ | 신청이 접수된 뒤의 사유입니다. 「이 증명서의 발급 한도를 이미 모두 사용했습니다. 더 필요하면 같은 증명서를 다시 신청한 뒤 내려받아 주세요.」 | |
| PROVIDER_ | 신청이 접수된 뒤의 사유입니다. 「증명서 출력을 시작하지 못했습니다. 기관이 보고서를 만들지 않았습니다. 증명서 목록에서 해당 건이 '처리완료' 이고 발급 가능한지 확인한 뒤 다시 시도해 주세요.」 | |
| PROVIDER_ | 신청이 접수된 뒤의 사유입니다. 「증명서 출력 준비 상태를 확인하지 못했습니다. 증명서 목록을 다시 조회해 남은 발급 수량을 확인한 뒤 내려받아 주세요.」 | |
| PROVIDER_ | 신청이 접수된 뒤의 사유입니다. 「기관이 증명서 보고서를 만들지 못했습니다. 기관 로그인이 만료됐을 수 있으니 다시 로그인한 뒤 시도해 주세요.」 | |
| PROVIDER_ | 신청이 접수된 뒤의 사유입니다. 「기관이 증명서 보고서를 아직 만들지 않았습니다. 증명서 목록을 다시 조회해 남은 발급 수량을 확인한 뒤 내려받아 주세요.」 | |
| PROVIDER_ | 신청이 접수된 뒤의 사유입니다. 「기관이 증명서 파일 대신 PDF 가 아닌 응답을 보냈습니다. 증명서 목록에서 해당 건이 '처리완료' 인지 확인한 뒤 다시 시도해 주세요.」 | |
| PROVIDER_ | 신청이 접수된 뒤 기관이 증명서 출력 결과 기록을 거절한 경우입니다. 사유 문장은 「기관이 증명서 출력 결과 기록을 거절했습니다.」 로 시작하고 기관이 알려 준 사유가 이어집니다. | |
| PROVIDER_ | 신청은 접수됐지만 그 뒤 단계가 전송이 끊기거나 기관의 HTTP 오류, 읽지 못한 응답처럼 이 문서에 따로 적지 않은 이유로 멈춰 결과를 확인하지 못한 경우입니다. 자동으로 다시 시도하지 않습니다. error.message 는 「증명서 신청은 접수됐습니다(증명서 ID {cva_id}, 접수번호 {rcat_no}). 파일은 내려받지 못했습니다. 접수 뒤 단계에서 기관 응답을 확인하지 못했습니다. 다시 신청하지 마시고, 잠시 뒤 증명서 내려받기에 이 증명서 ID 와 접수번호로 요청해 주세요.」 입니다(중괄호 자리에는 그 건의 실제 값이 들어갑니다). | |
| PROVIDER_ | 신청은 접수됐고 출력 기록만 확인하지 못한 경우입니다. 파일은 돌려주지 않고 자동으로 다시 시도하지 않습니다. error.message 는 「기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다. 증명서 신청은 접수됐습니다(증명서 ID {cva_id}, 접수번호 {rcat_no}). 확인하지 못한 것은 증명서 출력 기록입니다. 홈택스 민원증명 발급신청 결과 조회 화면에서 그 증명의 발급 수량을 확인해 주세요. 발급 수량이 신청 수량만큼 찼으면 이미 발급된 것이니 같은 증명서를 다시 신청한 뒤 내려받으세요. 발급 수량이 그대로이면 같은 건으로 다시 내려받으세요.」 입니다(중괄호 자리에는 그 건의 실제 값이 들어갑니다). |
13. 증명서 서식 지정 신청hometax. certificate. apply_ with_ template
MCP 도구 이름 hometax__
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
서식 목록에서 고른 증명서를 발급 매수와 제출처, 공개 여부를 정해 홈택스에 신청하고 증명서 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 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 길이 | 필수 | 설명 |
|---|---|---|---|---|---|
| confirmation_ | string | - | N | 1회용 확인 토큰입니다. 처음에는 보내지 않습니다. 토큰 없이 부르면 기관에 아무것도 보내지 않고 작업도 만들지 않은 채 확인이 필요하다는 오류(WRITE_CONFIRMATION_REQUIRED)로 끝나고, 응답의 error.confirmation_token 에 토큰이 옵니다. error.message 의 안내를 사용자에게 보여 주고 동의를 받은 뒤 같은 요청에 이 토큰을 넣어 다시 부릅니다. 토큰은 10분 안에 한 번만 쓸 수 있고 처음 요청과 같은 본문, 같은 호출자, 같은 환경에서만 맞으며, 아니면 확인이 만료됐거나 내용이 달라졌다는 오류로 거절합니다. 신청하면 홈택스에 접수 기록이 남고 취소할 수 없습니다 | |
| cert_ | string | - | N | 증명서 서식 — 다음 9종 중 하나: cert_gukse_wannap 국세완납증명 / cert_napse_sasil 납세사실증명 / cert_bugase_gwase_pyojun 부가가치세과세표준증명 / cert_saeopja_deungrok_jeungmyeong 사업자등록증명 / cert_hyupeop_sasil 휴업사실증명 / cert_pyojun_jaemu_jepyo 표준재무제표증명 / cert_pyepeop_sasil 폐업사실증명 / cert_saeopja_jaebalgup 사업자등록증 재발급 / cert_sodeuk_geumaeg_jeungmyeong 소득금액증명. 보내지 않으면 cert_gukse_wannap(국세완납증명)로 신청되며, 표에 없는 값은 홈택스에 닿기 전에 거절됩니다 | |
| strtYm | string | 6 | N | 조회 시작 연월입니다. 부가가치세과세표준증명 서식을 고를 때 필요하고, 그 밖의 서식에서는 보내지 않습니다 | |
| endYm | string | 6 | N | 조회 종료 연월입니다. 부가가치세과세표준증명 서식을 고를 때 필요하고, 그 밖의 서식에서는 보내지 않습니다 | |
| bsno | string | - | N | 대상 사업자등록번호(숫자 10자리)입니다. 표준재무제표증명 서식을 고를 때 필요하고, 그 밖의 서식에서는 보내지 않습니다 | |
| qrtTrt | string | - | N | 개인인지 법인인지 나누는 구분 코드입니다(02 개인, 03 법인). 표준재무제표증명 서식을 고를 때 필요하고, 이 값에 따라 아래의 txyr 나 bsyrEndYm 중 하나를 함께 보냅니다 | |
| txyr | string | 4 | N | 과세년도입니다. 표준재무제표증명 서식에서 개인(qrtTrt 가 02)일 때 필요합니다 | |
| incClCd | string | - | N | 소득구분 코드입니다. 표준재무제표증명 서식에서 개인(qrtTrt 가 02)일 때 필요합니다 | |
| bsyrEndYm | string | 6 | N | 사업연도 종료연월입니다. 표준재무제표증명 서식에서 법인(qrtTrt 가 03)일 때 필요합니다 | |
| txnrmStrtYm | string | 6 | N | 과세기간 시작년월입니다. 소득금액증명 서식을 고를 때 필요하고, 귀속연도 전체를 보려면 그 해의 1월(예: 202401)을 보냅니다 | |
| txnrmEndYm | string | 6 | N | 과세기간 종료년월입니다. 소득금액증명 서식을 고를 때 필요하고, 귀속연도 전체를 보려면 그 해의 12월(예: 202412)을 보냅니다 | |
| cerpIsnRqsQty | string | - | N | 신청할 발급 매수입니다. 보내지 않으면 서식에 정해진 값으로 신청합니다 | |
| cvaDcumSbmsOrgnClCd | string | - | N | 증명서 제출처 구분코드입니다. 보내지 않으면 서식에 정해진 값으로 신청합니다 | |
| cvaDcumGranMthdCd | string | - | N | 증명서 교부방법 코드입니다. 보내지 않으면 서식에 정해진 값으로 신청합니다 | |
| adrOpYn | string | - | N | 증명서에 주소를 표시할지 정하는 값으로 Y 나 N 을 보냅니다. 보내지 않으면 서식에 정해진 값으로 신청합니다 | |
| resnoOpYn | string | - | N | 증명서에 주민등록번호를 표시할지 정하는 값으로 Y 나 N 을 보냅니다. 법인(사업자) 계정은 이 값과 관계없이 항상 N 으로 신청하고, 개인 계정이 보내지 않으면 서식에 정해진 값을 씁니다 | |
| amtOpYn | string | - | N | 증명서에 금액을 표시할지 정하는 값으로 Y 나 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: apply_with_template-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "hometax",
"action": "hometax.certificate.apply_with_template",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {}
}'Response
- result.data 에는 홈택스가 신청 응답으로 내려 준 본문에 outcome 과 action 이 더해져 담깁니다.아래 칸 밖의 칸은 이름과 값을 홈택스가 정하므로 이 문서가 보장하지 않습니다(기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다).
- 접수번호(rcat_no)는 이 응답에 실리지 않을 수 있습니다. 내려받기에 쓸 접수번호는 증명서 신청 목록 조회의 행에서 읽습니다.
- 서식이 cert_bugase_gwase_pyojun 또는 cert_pyojun_jaemu_jepyo 이면 cvaId 가 비어 올 수 있고, 그때 증명서 ID 는 증명서 신청 목록 조회의 같은 신청 행에서 cva_id 로 받습니다.
- 서식이 cert_pyojun_jaemu_jepyo 이면 응답에 오는 rtnCvaId 는 증명서 ID 가 아닙니다.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| outcome | string | 기관이 신청을 받았다는 판정입니다. 성공 응답에서는 항상 confirmed 입니다. 기관에 요청은 갔지만 접수됐는지 확인하지 못한 경우는 이 응답이 아니라 실패(PROVIDER_OUTCOME_UNCONFIRMED)로 옵니다. | |
| action | string | 실행한 액션의 ID 입니다. | |
| cvaId | string | null | 기관이 발번한 증명서 ID 입니다. 홈택스가 내려 주는 키 이름 그대로이고, 내려받기의 cva_id 로 보내며 서식에 따라 비어 올 수 있습니다. |
// result.data - 값 자리에는 각 칸의 형식을 적었습니다 (실제 값이 아닙니다)
{
"outcome": "<string>",
"action": "<string>",
"cvaId": "<string | null>"
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| WRITE_ | 요청에 확인 토큰(confirmation_token)이 없으면 홈택스에 아무것도 보내지 않고 작업도 만들지 않은 채 이 오류로 끝납니다. error.message 는 cert_template 로 정한 서식의 확인 문구로 시작해 실행할 내용의 미리보기가 이어지고, error.confirmation_token 에 1회용 토큰이, error.preview 에 미리보기 객체가 함께 옵니다. 이 내용을 고객에게 그대로 보여 주고 확인을 받은 뒤, 같은 요청의 params.confirmation_token 에 응답의 error.confirmation_token 값을 넣어 다시 호출해 주세요. 토큰은 10분 안에 한 번만 쓸 수 있고, 확인한 요청 본문과 같은 본문에만 맞습니다. 확인값(confirm)은 보지 않으니 입력하지 않아도 됩니다. | |
| WRITE_ | 토큰이 만료됐거나, 이미 썼거나, 다른 호출자나 다른 환경에서 받은 것이거나, 확인한 요청 본문과 달라졌으면 홈택스에 아무것도 보내지 않고 작업도 만들지 않은 채 이 오류로 끝납니다. error.message 는 「확인이 만료됐거나 확인한 내용과 달라졌습니다. 다시 확인해 주세요.」 입니다. 토큰 없이 다시 요청하면 새 토큰과 미리보기를 받습니다. | |
| VALIDATION_ | cert_template 이 신청할 수 있는 서식 9가지에 없으면 홈택스에 보내지 않고 이 오류로 끝납니다. error.message 는 「지원하지 않는 증명서 서식입니다: '보낸 값'」 으로 시작하고 고를 수 있는 서식 목록이 이어집니다. | |
| AUTH_ | 저장된 기관 세션이 없습니다. 같은 연동 계정으로 hometax.session.login 을 먼저 실행해 세션을 연 뒤 다시 보냅니다. | |
| PROVIDER_ | 기관 세션이 만료됐습니다. 같은 연동 계정으로 hometax.session.login 을 다시 실행해 세션을 연 뒤 다시 보냅니다. | |
| PROVIDER_ | 신청 전에 홈택스에서 납세자 주소를 조회하는 서식은, 홈택스가 그 조회를 거절하면(응답 봉투의 resultMsg.result 가 비어 있지도 S 도 아닌 값) 신청을 보내지 않고 이 오류로 끝납니다. error.message 는 홈택스가 알려 준 사유이고, 사유를 주지 않으면 「기관이 요청을 처리하지 않았습니다. 사유는 알려 주지 않았습니다. 입력값을 그대로 두고 잠시 후 다시 시도해 주세요.」 입니다. | |
| PROVIDER_ | 홈택스가 서비스 중지 시간이라고 답한 경우입니다. 값이 틀린 것이 아니라 시간의 문제이고 요청은 처리되지 않았습니다. error.message 는 중지 시간을 읽었으면 그 시간을 함께 알리고, 읽지 못했으면 「지금은 홈택스 서비스 중지 시간이라 요청이 처리되지 않았습니다. 중지 시간이 지난 뒤 다시 요청해 주세요.」 입니다. | |
| VALIDATION_ | 서식(cert_template)이 cert_bugase_gwase_pyojun 이고 연결된 홈택스 계정이 개인 계정이면 신청하기 전에 이 오류로 끝나며, 신청은 접수되지 않았고 자동으로 다시 시도하지 않습니다. error.message 는 「부가가치세 과세표준증명 발급은 사업자 계정으로만 신청할 수 있습니다. 사업자로 연결된 계정을 선택한 뒤 다시 시도해 주세요.」 입니다. | |
| VALIDATION_ | 서식(cert_template)이 cert_hyupeop_sasil 이고 연결된 홈택스 계정이 사업자 계정이 아니면 신청하기 전에 이 오류로 끝나며, 신청은 접수되지 않았고 자동으로 다시 시도하지 않습니다. error.message 는 「휴업사실증명 발급은 사업자 계정으로만 신청할 수 있습니다. 사업자로 연결된 계정을 선택한 뒤 다시 시도해 주세요.」 입니다. | |
| VALIDATION_ | 서식(cert_template)이 cert_hyupeop_sasil 이고 bsno 를 보내 연결된 계정의 사업자등록번호와 다른 번호를 지정하면 신청하기 전에 이 오류로 끝나며, 신청은 접수되지 않았고 자동으로 다시 시도하지 않습니다. error.message 는 「휴업사실증명 발급은 연결된 사업자 본인 것만 신청할 수 있습니다. bsno 를 비우고 다시 요청하거나, 그 사업자로 연결된 계정을 선택해 주세요.」 입니다. 이 서식은 연결된 사업자 본인 것만 신청하므로 bsno 는 보내지 않아도 됩니다. | |
| VALIDATION_ | 서식(cert_template)이 cert_pyepeop_sasil 이고 연결된 홈택스 계정이 사업자 계정이 아니면 신청하기 전에 이 오류로 끝나며, 신청은 접수되지 않았고 자동으로 다시 시도하지 않습니다. error.message 는 「폐업사실증명 발급은 사업자 계정으로만 신청할 수 있습니다. 사업자로 연결된 계정을 선택한 뒤 다시 시도해 주세요.」 입니다. | |
| VALIDATION_ | 서식(cert_template)이 cert_pyepeop_sasil 이고 bsno 를 보내 연결된 계정의 사업자등록번호와 다른 번호를 지정하면 신청하기 전에 이 오류로 끝나며, 신청은 접수되지 않았고 자동으로 다시 시도하지 않습니다. error.message 는 「폐업사실증명 발급은 연결된 사업자 본인 것만 신청할 수 있습니다. bsno 를 비우고 다시 요청하거나, 그 사업자로 연결된 계정을 선택해 주세요.」 입니다. 이 서식은 연결된 사업자 본인 것만 신청하므로 bsno 는 보내지 않아도 됩니다. | |
| PROVIDER_ | 기관이 신청을 거절한 경우입니다(접수 전). error.message 는 「기관이 민원증명 신청을 거절했습니다.」 로 시작하고 기관이 알려 준 사유가 이어집니다. 신청이 접수되지 않았으므로 사유를 고쳐 다시 신청할 수 있습니다. 서식(cert_template)이 cert_sodeuk_geumaeg_jeungmyeong 이면 error.message 는 「기관이 민원증명 신청을 거절했습니다. 소득금액증명은 개인과 개인사업자만 신청할 수 있습니다. 법인 계정으로는 신청되지 않습니다.」 로 시작합니다. | |
| PROVIDER_ | 신청 요청은 기관에 갔지만 접수됐는지 확인하지 못한 경우입니다(응답에 접수 판정 resultMsg.result 도 발번된 증명서 ID 나 접수번호도 없습니다). 이 오류로 끝나며 자동으로 다시 시도하지 않습니다. error.message 는 「기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다. 홈택스 [민원증명 > 민원증명 발급신청 결과 조회]에서 방금 신청한 증명이 접수됐는지 확인해 주세요. 접수되지 않았을 때만 다시 신청하세요.」 입니다. |
14. 증명서 내려받기hometax. certificate. download
MCP 도구 이름 hometax__
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
신청해 둔 증명서를 발급용으로 출력해 PDF 파일로 받습니다. 출력할 때마다 신청한 발급 매수가 하나씩 줄어듭니다.
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 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 길이 | 필수 | 설명 |
|---|---|---|---|---|---|
| confirmation_ | string | - | N | 1회용 확인 토큰입니다. 처음에는 보내지 않습니다. 토큰 없이 부르면 기관에 아무것도 보내지 않고 작업도 만들지 않은 채 확인이 필요하다는 오류(WRITE_CONFIRMATION_REQUIRED)로 끝나고, 응답의 error.confirmation_token 에 토큰이 옵니다. error.message 의 안내를 사용자에게 보여 주고 동의를 받은 뒤 같은 요청에 이 토큰을 넣어 다시 부릅니다. 토큰은 10분 안에 한 번만 쓸 수 있고 처음 요청과 같은 본문, 같은 호출자, 같은 환경에서만 맞으며, 아니면 확인이 만료됐거나 내용이 달라졌다는 오류로 거절합니다. 출력하면 그 증명서의 발급 한도 1매가 사용되고 되돌릴 수 없으며, 더 필요하면 다시 신청해야 합니다 | |
| cva_ | string | - | Y | 내려받을 증명서의 ID(cva_id)입니다. 신청 결과의 cvaId 나 증명서 신청 목록 조회의 cva_id 를 그대로 보냅니다 | |
| rcat_ | string | - | Y | 내려받을 증명서의 접수번호(rcat_no)입니다. 자동 신청 결과의 list_info 안 rcat_no 나 증명서 신청 목록 조회의 rcat_no 를 그대로 보냅니다 | |
| rpt_ | string | - | N | 증명서 신청 목록 조회 결과 행의 보고서 경로(rpt_pkg_pth)를 그대로 보냅니다. 이 값과 cer_cva_isn_no, cerp_isn_rqs_qty, cerp_isn_actl_qty 를 모두 보내면 목록을 다시 조회하지 않으므로 조회 기간이 지난 오래된 신청도 내려받을 수 있습니다. 하나라도 빠지면 증명서 신청 목록에서 cva_id 로 이 증명서의 행을 찾아 빠진 값만 채우므로, 기본으로 보는 최근 3일 첫 쪽에 없는 신청이면 strt_dt, end_dt 로 그 신청일이 든 기간을 지정하거나 page_size 를 키웁니다. 목록에서 찾지 못했는데 보고서 경로나 발급번호가 없으면 오류로 거절합니다 | |
| cer_ | string | - | N | 내려받을 증명서의 발급번호입니다. 증명서 신청 목록 조회 결과 행의 cer_cva_isn_no 를 그대로 보내며, 이 번호는 증명서가 발급된 뒤에만 붙습니다. 보내지 않으면 목록에서 cva_id 로 이 증명서의 행을 찾아 채우고, 그래도 없으면 증명서가 아직 발급되지 않았거나 목록에서 먼저 조회해야 한다는 오류로 거절합니다 | |
| lnk_ | string | - | N | 증명서 신청 목록 조회 결과 행의 lnk_cl_cd(연계 구분)를 그대로 보냅니다. 보내지 않으면 목록을 조회할 때 그 행의 값으로 채우고, 목록을 조회하지 않았거나 값이 없으면 N 으로 보냅니다 | |
| mdl_ | string | - | N | 증명서 신청 목록 조회 결과 행의 mdl_txpr_yn(모범납세자 여부)을 그대로 보냅니다. 보내지 않으면 목록을 조회할 때 그 행의 값으로 채우고, 목록을 조회하지 않았거나 값이 없으면 N 으로 보냅니다 | |
| cerp_ | number | - | N | 증명서 신청 목록 조회 결과 행의 cerp_isn_rqs_qty(신청한 발급 매수)를 정수로 그대로 보냅니다. 보내지 않으면 목록에서 이 증명서의 행을 찾아 채웁니다 | |
| cerp_ | number | - | N | 증명서 신청 목록 조회 결과 행의 cerp_isn_actl_qty(이미 발급한 매수)를 정수로 그대로 보냅니다. 보내지 않으면 목록에서 채웁니다. 두 매수를 모두 알면 신청한 매수에서 발급한 매수를 뺀 남은 매수가 0 이하일 때 기관에 보내기 전에 발급 한도를 모두 사용했다는 오류로 거절합니다 | |
| strt_ | string | 8-10 | N | 증명서 신청 목록에서 이 증명서의 행을 찾을 때 보는 기간의 시작일(신청일 기준)입니다. end_dt 와 함께 보내야 하며, 보내지 않으면 오늘로부터 3일 전부터 봅니다 | |
| end_ | string | 8-10 | N | 그 기간의 종료일입니다. strt_dt 와 함께 보내야 하며 strt_dt 보다 앞설 수 없습니다. 기간은 한 번에 최대 1개월이고, 보내지 않으면 오늘까지 봅니다 | |
| page_ | number | - | N | 증명서 신청 목록에서 볼 쪽 번호입니다. 1부터 세는 정수이고 보내지 않으면 1 입니다. 목록을 볼 때 1 이상의 정수가 아니면 홈택스에 묻지 않고 거절합니다 | |
| page_ | number | - | N | 증명서 신청 목록의 한 쪽에서 볼 건수입니다. 보내지 않으면 10 입니다. 조회 기간 안의 신청이 첫 쪽에 다 담기지 않아 이 증명서가 보이지 않을 때 키웁니다. 목록을 볼 때 1 이상의 정수가 아니면 홈택스에 묻지 않고 거절합니다 |
- 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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: download-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "hometax",
"action": "hometax.certificate.download",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {
"cva_id": "<필수>",
"rcat_no": "<필수>"
}
}'Response
- 발급한 증명서 PDF 는 result.data 가 아니라 result.artifacts 로 옵니다. result.data 에는 아래 칸만 있습니다.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| outcome | string | 발급이 확인됐다는 판정입니다. 성공 응답에서는 항상 confirmed 입니다. 기관에 요청은 갔지만 결과를 확인하지 못한 경우는 이 응답이 아니라 실패(PROVIDER_OUTCOME_UNCONFIRMED)로 옵니다. | |
| action | string | 실행한 액션의 ID 입니다. | |
| verdict_ | object | 기관이 출력을 기록했다고 판정한 근거입니다. 기관의 출력 결과 보고 응답에서 resultMsg.result 의 값이 S 이면 확인으로 읽고, 그 값이 없거나 다르면 기관 신청 목록의 실제 발급 수량이 출력 전보다 늘었는지로 다시 확인합니다. 읽은 위치(verdict_path)와 읽은 값(verdict), 받아들이는 값(accepted_values) 같은 진단 칸이 담기고 칸 구성은 판정 경로에 따라 달라집니다. | |
| cva_ | string | 출력한 증명서의 ID 입니다. 요청의 cva_id 와 같습니다. | |
| rcat_ | string | 출력한 증명서의 접수번호입니다. 요청의 rcat_no 와 같습니다. |
// result.data - 값 자리에는 각 칸의 형식을 적었습니다 (실제 값이 아닙니다)
{
"outcome": "<string>",
"action": "<string>",
"verdict_detail": {},
"cva_id": "<string>",
"rcat_no": "<string>"
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| WRITE_ | 요청에 확인 토큰(confirmation_token)이 없으면 홈택스에 아무것도 보내지 않고 작업도 만들지 않은 채 이 오류로 끝납니다. error.message 는 「증명서 출력은 홈택스에서 발급 한도를 소모하며 되돌릴 수 없습니다. 아래 내용을 사용자에게 보여주고 동의를 받으세요.」 로 시작해 실행할 내용의 미리보기가 이어지고, error.confirmation_token 에 1회용 토큰이, error.preview 에 미리보기 객체가 함께 옵니다. 이 내용을 고객에게 그대로 보여 주고 확인을 받은 뒤, 같은 요청의 params.confirmation_token 에 응답의 error.confirmation_token 값을 넣어 다시 호출해 주세요. 토큰은 10분 안에 한 번만 쓸 수 있고, 확인한 요청 본문과 같은 본문에만 맞습니다. 확인값(confirm)은 보지 않으니 입력하지 않아도 됩니다. | |
| WRITE_ | 토큰이 만료됐거나, 이미 썼거나, 다른 호출자나 다른 환경에서 받은 것이거나, 확인한 요청 본문과 달라졌으면 홈택스에 아무것도 보내지 않고 작업도 만들지 않은 채 이 오류로 끝납니다. error.message 는 「확인이 만료됐거나 확인한 내용과 달라졌습니다. 다시 확인해 주세요.」 입니다. 토큰 없이 다시 요청하면 새 토큰과 미리보기를 받습니다. | |
| AUTH_ | 저장된 기관 세션이 없습니다. 같은 연동 계정으로 hometax.session.login 을 먼저 실행해 세션을 연 뒤 다시 보냅니다. | |
| PROVIDER_ | 기관 세션이 만료됐습니다. 같은 연동 계정으로 hometax.session.login 을 다시 실행해 세션을 연 뒤 다시 보냅니다. | |
| VALIDATION_ | rpt_pkg_pth 를 보내지 않았고 증명서 목록에서도 보낸 cva_id 를 찾지 못하면 이 오류로 끝납니다. error.message 는 「cva_id='{cva_id}' 를 증명서 목록에서 찾지 못했습니다. 이 조회는 기본적으로 최근 3일·첫 페이지만 봅니다 — strt_dt/end_dt 로 기간을 넓히거나 page_size 를 키우거나, 이미 알고 있다면 rpt_pkg_pth 를 직접 입력해 주세요.」 입니다(중괄호 자리에는 보낸 cva_id 가 들어갑니다). | |
| PROVIDER_ | 증명서 발급번호를 찾지 못했습니다. 증명서가 아직 발급되지 않았거나, 증명서 목록에서 해당 건을 먼저 조회해야 합니다. | |
| PROVIDER_ | 이 증명서의 발급 한도를 이미 모두 사용했습니다. 더 필요하면 같은 증명서를 다시 신청한 뒤 내려받아 주세요. | |
| PROVIDER_ | 증명서 출력을 시작하지 못했습니다. 기관이 보고서를 만들지 않았습니다. 증명서 목록에서 해당 건이 '처리완료' 이고 발급 가능한지 확인한 뒤 다시 시도해 주세요. | |
| PROVIDER_ | 증명서 출력 준비 상태를 확인하지 못했습니다. 증명서 목록을 다시 조회해 남은 발급 수량을 확인한 뒤 내려받아 주세요. | |
| PROVIDER_ | 기관이 증명서 보고서를 만들지 못했습니다. 기관 로그인이 만료됐을 수 있으니 다시 로그인한 뒤 시도해 주세요. | |
| PROVIDER_ | 기관이 증명서 보고서를 아직 만들지 않았습니다. 증명서 목록을 다시 조회해 남은 발급 수량을 확인한 뒤 내려받아 주세요. | |
| PROVIDER_ | 기관이 증명서 파일 대신 PDF 가 아닌 응답을 보냈습니다. 증명서 목록에서 해당 건이 '처리완료' 인지 확인한 뒤 다시 시도해 주세요. | |
| PROVIDER_ | 기관이 증명서 출력 결과 기록을 거절하면 이 오류로 끝납니다. error.message 는 「기관이 증명서 출력 결과 기록을 거절했습니다.」 로 시작하고 기관이 알려 준 사유가 이어집니다. | |
| PROVIDER_ | 출력 요청은 기관에 갔지만 출력이 기록됐는지 확인하지 못한 경우입니다. 파일은 돌려주지 않고 이 오류로 끝나며 자동으로 다시 시도하지 않습니다. error.message 는 「기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다. 홈택스 민원증명 발급신청 결과 조회 화면에서 그 증명의 발급 수량을 확인해 주세요. 발급 수량이 신청 수량만큼 찼으면 이미 발급된 것이니 같은 증명서를 다시 신청한 뒤 내려받으세요. 발급 수량이 그대로이면 같은 건으로 다시 내려받으세요.」 입니다. |
15. 증명서 서식 목록 조회hometax. certificate. list_ templates
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: list_templates-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "hometax",
"action": "hometax.certificate.list_templates",
"params": {}
}'Response
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| success | boolean | 서식 목록을 돌려줬다는 표지입니다. 항상 true 입니다. | |
| templates | object | 신청할 수 있는 증명서 서식 목록입니다. 키는 hometax.certificate.apply_auto 와 hometax.certificate.apply_with_template 의 cert_template 에 보내는 서식 값이고, 값은 증명서 이름입니다. | |
| templates. | string | 국세완납증명 서식입니다. cert_template 에 cert_gukse_wannap 를 보내면 이 증명서를 신청합니다. | |
| templates. | string | 납세사실증명 서식입니다. cert_template 에 cert_napse_sasil 를 보내면 이 증명서를 신청합니다. | |
| templates. | string | 부가가치세과세표준증명 서식입니다. cert_template 에 cert_bugase_gwase_pyojun 를 보내면 이 증명서를 신청합니다. | |
| templates. | string | 사업자등록증명 서식입니다. cert_template 에 cert_saeopja_deungrok_jeungmyeong 를 보내면 이 증명서를 신청합니다. | |
| templates. | string | 휴업사실증명 서식입니다. cert_template 에 cert_hyupeop_sasil 를 보내면 이 증명서를 신청합니다. | |
| templates. | string | 표준재무제표증명 서식입니다. cert_template 에 cert_pyojun_jaemu_jepyo 를 보내면 이 증명서를 신청합니다. | |
| templates. | string | 폐업사실증명 서식입니다. cert_template 에 cert_pyepeop_sasil 를 보내면 이 증명서를 신청합니다. | |
| templates. | string | 사업자등록증 재발급 서식입니다. cert_template 에 cert_saeopja_jaebalgup 를 보내면 이 증명서를 신청합니다. | |
| templates. | string | 소득금액증명 서식입니다. cert_template 에 cert_sodeuk_geumaeg_jeungmyeong 를 보내면 이 증명서를 신청합니다. | |
| count | number | templates 에 담긴 서식의 수입니다. |
// result.data - 값 자리에는 각 칸의 형식을 적었습니다 (실제 값이 아닙니다)
{
"success": "<boolean>",
"templates": {
"cert_gukse_wannap": "<string>",
"cert_napse_sasil": "<string>",
"cert_bugase_gwase_pyojun": "<string>",
"cert_saeopja_deungrok_jeungmyeong": "<string>",
"cert_hyupeop_sasil": "<string>",
"cert_pyojun_jaemu_jepyo": "<string>",
"cert_pyepeop_sasil": "<string>",
"cert_saeopja_jaebalgup": "<string>",
"cert_sodeuk_geumaeg_jeungmyeong": "<string>"
},
"count": "<number>"
}