개발자 문서
API 레퍼런스

증명서 - 홈택스

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

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

MCP 도구 이름 hometax__certificate__list

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

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

접수한 증명서 발급 신청의 목록을 조회합니다.

  • 홈택스 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [홈택스 로그인(세션 생성)]
  • 신청일 기준 조회 기간(보내지 않으면 오늘로부터 3일 전까지) 안에 신청이 없으면 items 가 빈 배열로 돌아오며, 실패가 아닙니다.

Request

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

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

[참고] 인증

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

[참고] 환경

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

[참고] 재시도

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

예시 : hometax

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

예시 : hometax.certificate.list

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

형식 : UUID v4

[참고] 자격증명 등록

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

[참고] 암호화

순번변수명타입길이필수설명
strt_dtstring8-10N증명서 신청일을 기준으로 찾는 기간의 시작일입니다. end_dt 와 함께 보내야 하며, 보내지 않으면 오늘로부터 3일 전부터 봅니다. end_dt 보다 뒤일 수 없습니다

형식 : YYYY-MM-DD 또는 YYYYMMDD

end_dtstring8-10N그 기간의 종료일입니다. strt_dt 와 함께 보내야 하며, 보내지 않으면 오늘까지 봅니다. 기간은 한 번에 최대 1개월이고, 넘기면 거절합니다

형식 : YYYY-MM-DD 또는 YYYYMMDD

page_numnumber-N페이지 번호입니다. 1부터 세며 보내지 않으면 1 입니다

예시 : 1

page_sizenumber-N페이지당 조회 건수입니다. 보내지 않으면 10 입니다

예시 : 10

bash
curl --request POST \
  --url 'https://api.xdata.kr/v1/jobs' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: real_test' \
  --header "Idempotency-Key: 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(페이지 정보)를 확인합니다.
순번변수명타입설명
itemsarray증명서 행 배열입니다. 행마다 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 입니다
pageobject페이지 객체 (page_size, page_num, total_count)
json
// 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_INVALID_FIELD기간 오류 — strt_dt 와 end_dt 를 한쪽만 보냈거나, 날짜 형식이 맞지 않거나, strt_dt 가 end_dt 보다 뒤이거나, 기간이 한 번에 최대 1개월을 넘으면 홈택스에 요청을 보내지 않고 거절합니다. error.message 가 어느 경우인지 알려 주니 값을 고쳐 다시 보냅니다.
VALIDATION_INVALID_FIELD숫자 값 오류 — page_num, page_size 에 1 이상의 정수가 아닌 값(0, 음수, 소수부가 있는 수, 숫자가 아닌 글자)을 보내면 홈택스에 요청하지 않고 이 코드로 끝나며, 자동 재시도 대상이 아닙니다. error.message 가 확인할 값의 이름을 알려 주니 그 값을 고쳐 다시 요청합니다. 숫자로 된 문자열도 받고, null 로 보내면 보내지 않은 것으로 보아 기본값을 씁니다.
AUTH_REQUIRED세션 없음 — 홈택스 세션이 없습니다. 홈택스 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다.
PROVIDER_BUSINESS_ERROR업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다.
PROVIDER_VALIDATION_ERROR업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다.
PROVIDER_UNAVAILABLE업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다.
PROVIDER_UPSTREAM_ERROR업스트림 오류 — 홈택스가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 잠시 후 다시 호출합니다.
PROVIDER_SESSION_EXPIRED세션 만료 — 조회하는 도중 홈택스 로그인 세션이 끝난 것을 알게 되면 이 코드로 끝나며, error.message 안내대로 로그인 액션을 다시 실행해 세션을 연 뒤 같은 요청을 다시 보냅니다.

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

MCP 도구 이름 hometax__certificate__apply__national_tax_payment

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

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

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

  • 홈택스 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [홈택스 로그인(세션 생성)]
  • 요청 거절(HTTP 400, 작업은 만들어지지 않음).
  • 요청 거절(HTTP 409, 작업은 만들어지지 않음).
  • params 는 빈 객체로 보내도 호출됩니다. 사용할 인증서는 account_link_id 로 지정합니다.

Request

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

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

[참고] 인증

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

[참고] 환경

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

[참고] 재시도

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

예시 : hometax

actionstring-Y호출할 작업입니다.
  • hometax.certificate.apply.national_tax_payment이 API 고정값 (기본값)

예시 : hometax.certificate.apply.national_tax_payment

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

형식 : UUID v4

[참고] 자격증명 등록

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

[참고] 암호화

순번변수명타입필수설명
tinstring조건부보내도 신청 대상은 바뀌지 않습니다. 신청서의 식별번호는 늘 로그인한 계정의 값입니다
txpr_nmstring조건부미입력 시 세션 상호 사용
confirmation_tokenstringN1회용 확인 토큰입니다. 처음에는 보내지 않습니다. 토큰 없이 부르면 기관에 아무것도 보내지 않고 작업도 만들지 않은 채 확인이 필요하다는 오류(WRITE_CONFIRMATION_REQUIRED)로 끝나고, 응답의 error.confirmation_token 에 토큰이 옵니다. error.message 의 안내를 사용자에게 보여 주고 동의를 받은 뒤 같은 요청에 이 토큰을 넣어 다시 부릅니다. 토큰은 10분 안에 한 번만 쓸 수 있고 처음 요청과 같은 본문, 같은 호출자, 같은 환경에서만 맞으며, 아니면 확인이 만료됐거나 내용이 달라졌다는 오류로 거절합니다
cerpIsnRqsQtystringN신청할 발급 매수입니다. 보내지 않으면 서식에 정해진 값으로 신청합니다
cvaDcumSbmsOrgnClCdstringN증명서 제출처 구분코드입니다. 보내지 않으면 서식에 정해진 값으로 신청합니다
cvaDcumGranMthdCdstringN증명서 교부방법 코드입니다. 보내지 않으면 서식에 정해진 값으로 신청합니다
adrOpYnstringN증명서에 주소를 표시할지 정하는 값으로 Y 나 N 을 보냅니다. 보내지 않으면 서식에 정해진 값으로 신청합니다
resnoOpYnstringN증명서에 주민등록번호를 표시할지 정하는 값으로 Y 나 N 을 보냅니다. 법인(사업자) 계정은 이 값과 관계없이 항상 N 으로 신청하고, 개인 계정이 보내지 않으면 서식에 정해진 값을 씁니다
amtOpYnstringN증명서에 금액을 표시할지 정하는 값으로 Y 나 N 을 보냅니다. 금액 항목이 있는 서식에서만 반영하고 그 밖의 서식에서는 쓰이지 않습니다. 보내지 않으면 서식에 정해진 값으로 신청합니다
bash
curl --request POST \
  --url 'https://api.xdata.kr/v1/jobs' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: real_test' \
  --header "Idempotency-Key: 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 타입이 함께 표시된 칸은 서버가 세부 타입을 고정하지 않는 기관 원문 또는 동적 값입니다.
순번변수명타입설명
outcomestring기관 처리 판정. 성공 응답에서는 항상 confirmed 입니다
actionstring요청한 액션 이름. outcome · action 외의 키는 홈택스 응답 본문에서 옵니다(기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다)
cvaIdstring | number | boolean | object | array | null기관이 발번한 증명서 아이디. 홈택스가 내려주는 키 이름 그대로이며 비어 올 수 있습니다 기관 응답에 존재할 때만 반환됩니다. data 또는 cerpBscInfrDVO 내부에 있을 수 있으므로 최상위 존재를 전제로 접근하지 마세요.
json
// result.data — outcome · action 외의 키는 홈택스 응답 본문에서 옵니다(기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다).
{
  "outcome": "confirmed",
  "action": "hometax.certificate.apply.national_tax_payment",
  "cvaId": "..."
}
순번오류 코드발생 조건
PROVIDER_OUTCOME_UNCONFIRMED처리 확인 불가 — 요청은 홈택스로 전송됐지만 처리됐는지 확인하지 못했습니다. 이미 처리됐을 수 있으므로 다시 요청하지 않고, 오류 메시지가 안내하는 홈택스 화면에서 먼저 확인합니다.
AUTH_REQUIRED세션 없음 — 홈택스 세션이 없습니다. 홈택스 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다.
PROVIDER_BUSINESS_ERROR업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다.
PROVIDER_VALIDATION_ERROR홈택스 통신 오류 — 홈택스가 오류로 답하거나 연결이 끊겨 요청이 처리됐는지 알 수 없을 수 있으니, 다시 요청하기 전에 홈택스 화면에서 먼저 확인합니다. 홈택스가 오류 응답을 보내거나 연결이 끊긴 경우 error.message 는 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')입니다.
PROVIDER_UPSTREAM_ERROR홈택스 통신 오류 — 홈택스가 오류로 답하거나 연결이 끊겨 요청이 처리됐는지 알 수 없을 수 있으니, 다시 요청하기 전에 홈택스 화면에서 먼저 확인합니다. 홈택스가 오류 응답을 보내거나 연결이 끊긴 경우 error.message 는 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')입니다.
PROVIDER_UNAVAILABLE홈택스 통신 오류 — 홈택스가 오류로 답하거나 연결이 끊겨 요청이 처리됐는지 알 수 없을 수 있으니, 다시 요청하기 전에 홈택스 화면에서 먼저 확인합니다. 홈택스가 오류 응답을 보내거나 연결이 끊긴 경우 error.message 는 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')입니다.

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

MCP 도구 이름 hometax__certificate__apply__tax_payment_record

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

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

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

  • 홈택스 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [홈택스 로그인(세션 생성)]
  • 요청 거절(HTTP 400, 작업은 만들어지지 않음).
  • 요청 거절(HTTP 409, 작업은 만들어지지 않음).
  • params 는 빈 객체로 보내도 호출됩니다. 사용할 인증서는 account_link_id 로 지정합니다.

Request

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

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

[참고] 인증

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

[참고] 환경

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

[참고] 재시도

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

예시 : hometax

actionstring-Y호출할 작업입니다.
  • hometax.certificate.apply.tax_payment_record이 API 고정값 (기본값)

예시 : hometax.certificate.apply.tax_payment_record

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

형식 : UUID v4

[참고] 자격증명 등록

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

[참고] 암호화

순번변수명타입길이필수설명
tinstring-조건부보내도 신청 대상은 바뀌지 않습니다. 신청서의 식별번호는 늘 로그인한 계정의 값입니다
txpr_nmstring-조건부미입력 시 세션 상호 사용
confirmation_tokenstring-N1회용 확인 토큰입니다. 처음에는 보내지 않습니다. 토큰 없이 부르면 기관에 아무것도 보내지 않고 작업도 만들지 않은 채 확인이 필요하다는 오류(WRITE_CONFIRMATION_REQUIRED)로 끝나고, 응답의 error.confirmation_token 에 토큰이 옵니다. error.message 의 안내를 사용자에게 보여 주고 동의를 받은 뒤 같은 요청에 이 토큰을 넣어 다시 부릅니다. 토큰은 10분 안에 한 번만 쓸 수 있고 처음 요청과 같은 본문, 같은 호출자, 같은 환경에서만 맞으며, 아니면 확인이 만료됐거나 내용이 달라졌다는 오류로 거절합니다
cerStrtYrstring4N수납기간 시작 연도입니다. 수납기간을 보내지 않으면 올해 1월부터 이번 달까지로 신청됩니다

형식 : YYYY

strtMmstring-N수납기간 시작 월(MM)입니다. 수납기간을 보내지 않으면 올해 1월부터 이번 달까지로 신청됩니다
cerEndYrstring4N수납기간 종료 연도입니다. 수납기간을 보내지 않으면 올해 1월부터 이번 달까지로 신청됩니다

형식 : YYYY

endMmstring-N수납기간 종료 월(MM)입니다. 수납기간을 보내지 않으면 올해 1월부터 이번 달까지로 신청됩니다
cerpIsnRqsQtystring-N신청할 발급 매수입니다. 보내지 않으면 서식에 정해진 값으로 신청합니다
cvaDcumSbmsOrgnClCdstring-N증명서 제출처 구분코드입니다. 보내지 않으면 서식에 정해진 값으로 신청합니다
cvaDcumGranMthdCdstring-N증명서 교부방법 코드입니다. 보내지 않으면 서식에 정해진 값으로 신청합니다
adrOpYnstring-N증명서에 주소를 표시할지 정하는 값으로 Y 나 N 을 보냅니다. 보내지 않으면 서식에 정해진 값으로 신청합니다
resnoOpYnstring-N증명서에 주민등록번호를 표시할지 정하는 값으로 Y 나 N 을 보냅니다. 법인(사업자) 계정은 이 값과 관계없이 항상 N 으로 신청하고, 개인 계정이 보내지 않으면 서식에 정해진 값을 씁니다
amtOpYnstring-N증명서에 금액을 표시할지 정하는 값으로 Y 나 N 을 보냅니다. 금액 항목이 있는 서식에서만 반영하고 그 밖의 서식에서는 쓰이지 않습니다. 보내지 않으면 서식에 정해진 값으로 신청합니다
bash
curl --request POST \
  --url 'https://api.xdata.kr/v1/jobs' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: real_test' \
  --header "Idempotency-Key: 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 타입이 함께 표시된 칸은 서버가 세부 타입을 고정하지 않는 기관 원문 또는 동적 값입니다.
순번변수명타입설명
outcomestring기관 처리 판정. 성공 응답에서는 항상 confirmed 입니다
actionstring요청한 액션 이름. outcome · action 외의 키는 홈택스 응답 본문에서 옵니다(기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다)
cvaIdstring | number | boolean | object | array | null기관이 발번한 증명서 아이디. 홈택스가 내려주는 키 이름 그대로이며 비어 올 수 있습니다 기관 응답에 존재할 때만 반환됩니다. data 또는 cerpBscInfrDVO 내부에 있을 수 있으므로 최상위 존재를 전제로 접근하지 마세요.
json
// result.data — outcome · action 외의 키는 홈택스 응답 본문에서 옵니다(기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다).
{
  "outcome": "confirmed",
  "action": "hometax.certificate.apply.tax_payment_record",
  "cvaId": "..."
}
순번오류 코드발생 조건
PROVIDER_OUTCOME_UNCONFIRMED처리 확인 불가 — 요청은 홈택스로 전송됐지만 처리됐는지 확인하지 못했습니다. 이미 처리됐을 수 있으므로 다시 요청하지 않고, 오류 메시지가 안내하는 홈택스 화면에서 먼저 확인합니다.
AUTH_REQUIRED세션 없음 — 홈택스 세션이 없습니다. 홈택스 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다.
PROVIDER_BUSINESS_ERROR업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다.
PROVIDER_VALIDATION_ERROR홈택스 통신 오류 — 홈택스가 오류로 답하거나 연결이 끊겨 요청이 처리됐는지 알 수 없을 수 있으니, 다시 요청하기 전에 홈택스 화면에서 먼저 확인합니다. 홈택스가 오류 응답을 보내거나 연결이 끊긴 경우 error.message 는 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')입니다.
PROVIDER_UPSTREAM_ERROR홈택스 통신 오류 — 홈택스가 오류로 답하거나 연결이 끊겨 요청이 처리됐는지 알 수 없을 수 있으니, 다시 요청하기 전에 홈택스 화면에서 먼저 확인합니다. 홈택스가 오류 응답을 보내거나 연결이 끊긴 경우 error.message 는 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')입니다.
PROVIDER_UNAVAILABLE홈택스 통신 오류 — 홈택스가 오류로 답하거나 연결이 끊겨 요청이 처리됐는지 알 수 없을 수 있으니, 다시 요청하기 전에 홈택스 화면에서 먼저 확인합니다. 홈택스가 오류 응답을 보내거나 연결이 끊긴 경우 error.message 는 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')입니다.

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

MCP 도구 이름 hometax__certificate__apply__vat_standard

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

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

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

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

Request

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

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

[참고] 인증

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

[참고] 환경

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

[참고] 재시도

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

예시 : hometax

actionstring-Y호출할 작업입니다.
  • hometax.certificate.apply.vat_standard이 API 고정값 (기본값)

예시 : hometax.certificate.apply.vat_standard

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

형식 : UUID v4

[참고] 자격증명 등록

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

[참고] 암호화

순번변수명타입길이필수설명
tinstring-조건부보내도 신청 대상은 바뀌지 않습니다. 신청서의 식별번호는 늘 로그인한 계정의 값입니다
txpr_nmstring-조건부미입력 시 세션 상호 사용
strtYmstring6Y조회 시작 연월

형식 : YYYYMM

endYmstring6Y조회 종료 연월

형식 : YYYYMM

confirmation_tokenstring-N1회용 확인 토큰입니다. 처음에는 보내지 않습니다. 토큰 없이 부르면 기관에 아무것도 보내지 않고 작업도 만들지 않은 채 확인이 필요하다는 오류(WRITE_CONFIRMATION_REQUIRED)로 끝나고, 응답의 error.confirmation_token 에 토큰이 옵니다. error.message 의 안내를 사용자에게 보여 주고 동의를 받은 뒤 같은 요청에 이 토큰을 넣어 다시 부릅니다. 토큰은 10분 안에 한 번만 쓸 수 있고 처음 요청과 같은 본문, 같은 호출자, 같은 환경에서만 맞으며, 아니면 확인이 만료됐거나 내용이 달라졌다는 오류로 거절합니다
cerpIsnRqsQtystring-N신청할 발급 매수입니다. 보내지 않으면 서식에 정해진 값으로 신청합니다
cvaDcumSbmsOrgnClCdstring-N증명서 제출처 구분코드입니다. 보내지 않으면 서식에 정해진 값으로 신청합니다
cvaDcumGranMthdCdstring-N증명서 교부방법 코드입니다. 보내지 않으면 서식에 정해진 값으로 신청합니다
adrOpYnstring-N증명서에 주소를 표시할지 정하는 값으로 Y 나 N 을 보냅니다. 보내지 않으면 서식에 정해진 값으로 신청합니다
resnoOpYnstring-N증명서에 주민등록번호를 표시할지 정하는 값으로 Y 나 N 을 보냅니다. 법인(사업자) 계정은 이 값과 관계없이 항상 N 으로 신청하고, 개인 계정이 보내지 않으면 서식에 정해진 값을 씁니다
  • 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
bash
curl --request POST \
  --url 'https://api.xdata.kr/v1/jobs' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: real_test' \
  --header "Idempotency-Key: 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 타입이 함께 표시된 칸은 서버가 세부 타입을 고정하지 않는 기관 원문 또는 동적 값입니다.
순번변수명타입설명
outcomestring기관 처리 판정. 성공 응답에서는 항상 confirmed 입니다
actionstring요청한 액션 이름. outcome · action 외의 키는 홈택스 응답 본문에서 옵니다(기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다)
cvaIdstring | number | boolean | object | array | null기관이 발번한 증명서 아이디. 홈택스가 내려주는 키 이름 그대로입니다. 이 서식은 비어 올 수 있고, 그때 증명서 ID 는 증명서 신청 목록 조회의 같은 신청 행에서 cva_id 로 받습니다 기관 응답에 존재할 때만 반환됩니다. data 또는 cerpBscInfrDVO 내부에 있을 수 있으므로 최상위 존재를 전제로 접근하지 마세요.
json
// result.data — outcome · action 외의 키는 홈택스 응답 본문에서 옵니다(기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다).
{
  "outcome": "confirmed",
  "action": "hometax.certificate.apply.vat_standard",
  "cvaId": "..."
}
순번오류 코드발생 조건
PROVIDER_OUTCOME_UNCONFIRMED처리 확인 불가 — 요청은 홈택스로 전송됐지만 처리됐는지 확인하지 못했습니다. 이미 처리됐을 수 있으므로 다시 요청하지 않고, 오류 메시지가 안내하는 홈택스 화면에서 먼저 확인합니다.
VALIDATION_INVALID_FIELD개인 계정 — 연결된 홈택스 계정이 개인 계정이면 신청하기 전에 멈추는 경우이며, 신청은 접수되지 않았고 자동 재시도 대상이 아닙니다. error.message 는 「부가가치세 과세표준증명 발급은 사업자 계정으로만 신청할 수 있습니다. 사업자로 연결된 계정을 선택한 뒤 다시 시도해 주세요.」 입니다.
AUTH_REQUIRED세션 없음 — 홈택스 세션이 없습니다. 홈택스 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다.
PROVIDER_BUSINESS_ERROR업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다.
PROVIDER_VALIDATION_ERROR홈택스 통신 오류 — 홈택스가 오류로 답하거나 연결이 끊겨 요청이 처리됐는지 알 수 없을 수 있으니, 다시 요청하기 전에 홈택스 화면에서 먼저 확인합니다. 홈택스가 오류 응답을 보내거나 연결이 끊긴 경우 error.message 는 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')입니다.
PROVIDER_UPSTREAM_ERROR홈택스 통신 오류 — 홈택스가 오류로 답하거나 연결이 끊겨 요청이 처리됐는지 알 수 없을 수 있으니, 다시 요청하기 전에 홈택스 화면에서 먼저 확인합니다. 홈택스가 오류 응답을 보내거나 연결이 끊긴 경우 error.message 는 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')입니다.
PROVIDER_UNAVAILABLE홈택스 통신 오류 — 홈택스가 오류로 답하거나 연결이 끊겨 요청이 처리됐는지 알 수 없을 수 있으니, 다시 요청하기 전에 홈택스 화면에서 먼저 확인합니다. 홈택스가 오류 응답을 보내거나 연결이 끊긴 경우 error.message 는 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')입니다.

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

MCP 도구 이름 hometax__certificate__apply__business_registration

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

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

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

  • 홈택스 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [홈택스 로그인(세션 생성)]
  • 요청 거절(HTTP 400, 작업은 만들어지지 않음).
  • 요청 거절(HTTP 409, 작업은 만들어지지 않음).
  • params 는 빈 객체로 보내도 호출됩니다. 사용할 인증서는 account_link_id 로 지정합니다.

Request

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

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

[참고] 인증

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

[참고] 환경

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

[참고] 재시도

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

예시 : hometax

actionstring-Y호출할 작업입니다.
  • hometax.certificate.apply.business_registration이 API 고정값 (기본값)

예시 : hometax.certificate.apply.business_registration

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

형식 : UUID v4

[참고] 자격증명 등록

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

[참고] 암호화

순번변수명타입필수설명
tinstring조건부보내도 신청 대상은 바뀌지 않습니다. 신청서의 식별번호는 늘 로그인한 계정의 값입니다
txpr_nmstring조건부미입력 시 세션 상호 사용
confirmation_tokenstringN1회용 확인 토큰입니다. 처음에는 보내지 않습니다. 토큰 없이 부르면 기관에 아무것도 보내지 않고 작업도 만들지 않은 채 확인이 필요하다는 오류(WRITE_CONFIRMATION_REQUIRED)로 끝나고, 응답의 error.confirmation_token 에 토큰이 옵니다. error.message 의 안내를 사용자에게 보여 주고 동의를 받은 뒤 같은 요청에 이 토큰을 넣어 다시 부릅니다. 토큰은 10분 안에 한 번만 쓸 수 있고 처음 요청과 같은 본문, 같은 호출자, 같은 환경에서만 맞으며, 아니면 확인이 만료됐거나 내용이 달라졌다는 오류로 거절합니다
cerpIsnRqsQtystringN신청할 발급 매수입니다. 보내지 않으면 서식에 정해진 값으로 신청합니다
cvaDcumSbmsOrgnClCdstringN증명서 제출처 구분코드입니다. 보내지 않으면 서식에 정해진 값으로 신청합니다
cvaDcumGranMthdCdstringN증명서 교부방법 코드입니다. 보내지 않으면 서식에 정해진 값으로 신청합니다
adrOpYnstringN증명서에 주소를 표시할지 정하는 값으로 Y 나 N 을 보냅니다. 보내지 않으면 서식에 정해진 값으로 신청합니다
resnoOpYnstringN증명서에 주민등록번호를 표시할지 정하는 값으로 Y 나 N 을 보냅니다. 법인(사업자) 계정은 이 값과 관계없이 항상 N 으로 신청하고, 개인 계정이 보내지 않으면 서식에 정해진 값을 씁니다
amtOpYnstringN증명서에 금액을 표시할지 정하는 값으로 Y 나 N 을 보냅니다. 금액 항목이 있는 서식에서만 반영하고 그 밖의 서식에서는 쓰이지 않습니다. 보내지 않으면 서식에 정해진 값으로 신청합니다
bash
curl --request POST \
  --url 'https://api.xdata.kr/v1/jobs' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: real_test' \
  --header "Idempotency-Key: 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 타입이 함께 표시된 칸은 서버가 세부 타입을 고정하지 않는 기관 원문 또는 동적 값입니다.
순번변수명타입설명
outcomestring기관 처리 판정. 성공 응답에서는 항상 confirmed 입니다
actionstring요청한 액션 이름. outcome · action 외의 키는 홈택스 응답 본문에서 옵니다(기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다)
cvaIdstring | number | boolean | object | array | null기관이 발번한 증명서 아이디. 홈택스가 내려주는 키 이름 그대로이며 비어 올 수 있습니다 기관 응답에 존재할 때만 반환됩니다. data 또는 cerpBscInfrDVO 내부에 있을 수 있으므로 최상위 존재를 전제로 접근하지 마세요.
json
// result.data — outcome · action 외의 키는 홈택스 응답 본문에서 옵니다(기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다).
{
  "outcome": "confirmed",
  "action": "hometax.certificate.apply.business_registration",
  "cvaId": "..."
}
순번오류 코드발생 조건
PROVIDER_OUTCOME_UNCONFIRMED처리 확인 불가 — 요청은 홈택스로 전송됐지만 처리됐는지 확인하지 못했습니다. 이미 처리됐을 수 있으므로 다시 요청하지 않고, 오류 메시지가 안내하는 홈택스 화면에서 먼저 확인합니다.
AUTH_REQUIRED세션 없음 — 홈택스 세션이 없습니다. 홈택스 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다.
PROVIDER_BUSINESS_ERROR업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다.
PROVIDER_VALIDATION_ERROR홈택스 통신 오류 — 홈택스가 오류로 답하거나 연결이 끊겨 요청이 처리됐는지 알 수 없을 수 있으니, 다시 요청하기 전에 홈택스 화면에서 먼저 확인합니다. 홈택스가 오류 응답을 보내거나 연결이 끊긴 경우 error.message 는 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')입니다.
PROVIDER_UPSTREAM_ERROR홈택스 통신 오류 — 홈택스가 오류로 답하거나 연결이 끊겨 요청이 처리됐는지 알 수 없을 수 있으니, 다시 요청하기 전에 홈택스 화면에서 먼저 확인합니다. 홈택스가 오류 응답을 보내거나 연결이 끊긴 경우 error.message 는 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')입니다.
PROVIDER_UNAVAILABLE홈택스 통신 오류 — 홈택스가 오류로 답하거나 연결이 끊겨 요청이 처리됐는지 알 수 없을 수 있으니, 다시 요청하기 전에 홈택스 화면에서 먼저 확인합니다. 홈택스가 오류 응답을 보내거나 연결이 끊긴 경우 error.message 는 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')입니다.

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

MCP 도구 이름 hometax__certificate__apply__business_suspension

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

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

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

  • 홈택스 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [홈택스 로그인(세션 생성)]
  • 요청 거절(HTTP 400, 작업은 만들어지지 않음).
  • 요청 거절(HTTP 409, 작업은 만들어지지 않음).
  • params 는 빈 객체로 보내도 호출됩니다. 사용할 인증서는 account_link_id 로 지정합니다.

Request

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

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

[참고] 인증

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

[참고] 환경

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

[참고] 재시도

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

예시 : hometax

actionstring-Y호출할 작업입니다.
  • hometax.certificate.apply.business_suspension이 API 고정값 (기본값)

예시 : hometax.certificate.apply.business_suspension

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

형식 : UUID v4

[참고] 자격증명 등록

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

[참고] 암호화

순번변수명타입길이필수설명
tinstring-조건부보내도 신청 대상은 바뀌지 않습니다. 신청서의 식별번호는 늘 로그인한 계정의 값입니다
txpr_nmstring-조건부미입력 시 세션 상호 사용
confirmation_tokenstring-N1회용 확인 토큰입니다. 처음에는 보내지 않습니다. 토큰 없이 부르면 기관에 아무것도 보내지 않고 작업도 만들지 않은 채 확인이 필요하다는 오류(WRITE_CONFIRMATION_REQUIRED)로 끝나고, 응답의 error.confirmation_token 에 토큰이 옵니다. error.message 의 안내를 사용자에게 보여 주고 동의를 받은 뒤 같은 요청에 이 토큰을 넣어 다시 부릅니다. 토큰은 10분 안에 한 번만 쓸 수 있고 처음 요청과 같은 본문, 같은 호출자, 같은 환경에서만 맞으며, 아니면 확인이 만료됐거나 내용이 달라졌다는 오류로 거절합니다
sfbTermStrtDtstring8N신청할 휴업 기간의 시작일(휴업 기간이 여럿일 때)입니다

형식 : YYYYMMDD

sfbTermEndDtstring8N신청할 휴업 기간의 종료일(시작일이 같은 기간이 여럿일 때)입니다

형식 : YYYYMMDD

cerpIsnRqsQtystring-N신청할 발급 매수입니다. 보내지 않으면 서식에 정해진 값으로 신청합니다
cvaDcumSbmsOrgnClCdstring-N증명서 제출처 구분코드입니다. 보내지 않으면 서식에 정해진 값으로 신청합니다
cvaDcumGranMthdCdstring-N증명서 교부방법 코드입니다. 보내지 않으면 서식에 정해진 값으로 신청합니다
adrOpYnstring-N증명서에 주소를 표시할지 정하는 값으로 Y 나 N 을 보냅니다. 보내지 않으면 서식에 정해진 값으로 신청합니다
resnoOpYnstring-N증명서에 주민등록번호를 표시할지 정하는 값으로 Y 나 N 을 보냅니다. 법인(사업자) 계정은 이 값과 관계없이 항상 N 으로 신청하고, 개인 계정이 보내지 않으면 서식에 정해진 값을 씁니다
amtOpYnstring-N증명서에 금액을 표시할지 정하는 값으로 Y 나 N 을 보냅니다. 금액 항목이 있는 서식에서만 반영하고 그 밖의 서식에서는 쓰이지 않습니다. 보내지 않으면 서식에 정해진 값으로 신청합니다
bash
curl --request POST \
  --url 'https://api.xdata.kr/v1/jobs' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: real_test' \
  --header "Idempotency-Key: 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 타입이 함께 표시된 칸은 서버가 세부 타입을 고정하지 않는 기관 원문 또는 동적 값입니다.
순번변수명타입설명
outcomestring기관 처리 판정. 성공 응답에서는 항상 confirmed 입니다
actionstring요청한 액션 이름. outcome · action 외의 키는 홈택스 응답 본문에서 옵니다(기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다)
cvaIdstring | number | boolean | object | array | null기관이 발번한 증명서 아이디. 홈택스가 내려주는 키 이름 그대로이며 비어 올 수 있습니다 기관 응답에 존재할 때만 반환됩니다. data 또는 cerpBscInfrDVO 내부에 있을 수 있으므로 최상위 존재를 전제로 접근하지 마세요.
json
// result.data — outcome · action 외의 키는 홈택스 응답 본문에서 옵니다(기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다).
{
  "outcome": "confirmed",
  "action": "hometax.certificate.apply.business_suspension",
  "cvaId": "..."
}
순번오류 코드발생 조건
PROVIDER_OUTCOME_UNCONFIRMED처리 확인 불가 — 요청은 홈택스로 전송됐지만 처리됐는지 확인하지 못했습니다. 이미 처리됐을 수 있으므로 다시 요청하지 않고, 오류 메시지가 안내하는 홈택스 화면에서 먼저 확인합니다.
VALIDATION_INVALID_FIELD사업자 계정 아님 — 연결된 홈택스 계정이 사업자 계정이 아니면 신청하기 전에 멈추는 경우이며, 신청은 접수되지 않았고 자동 재시도 대상이 아닙니다. error.message 는 「휴업사실증명 발급은 사업자 계정으로만 신청할 수 있습니다. 사업자로 연결된 계정을 선택한 뒤 다시 시도해 주세요.」 입니다.
VALIDATION_INVALID_FIELD다른 사업자 지정 — params 에 bsno 를 보내 연결된 계정의 사업자등록번호와 다른 번호를 지정한 경우이며, 신청은 접수되지 않았고 자동 재시도 대상이 아닙니다. error.message 는 「휴업사실증명 발급은 연결된 사업자 본인 것만 신청할 수 있습니다. bsno 를 비우고 다시 요청하거나, 그 사업자로 연결된 계정을 선택해 주세요.」 입니다. 이 증명서는 연결된 사업자 본인 것만 신청하므로 bsno 는 보내지 않아도 됩니다.
PROVIDER_BUSINESS_ERROR휴업 이력 없음 — 신청 전에 조회한 연결 사업자의 이력에 휴업 기간이 없는 경우이며, 신청은 접수되지 않았고 자동 재시도 대상이 아닙니다. error.message 는 「연결된 사업자에는 휴업 기간이 없어 휴업사실증명을 신청할 수 없습니다. 신청은 접수하지 않았습니다. 휴업 신고가 처리된 뒤 다시 시도해 주세요.」 입니다.
VALIDATION_INVALID_FIELD휴업 기간 선택 — 연결 사업자의 휴업 기간이 여럿인데 신청할 기간을 정하지 못했거나, 보낸 sfbTermStrtDt 또는 sfbTermEndDt 와 맞는 기간이 없는 경우이며, 신청은 접수되지 않았고 자동 재시도 대상이 아닙니다. error.message 가 신청할 수 있는 휴업 기간을 나열합니다. 휴업 기간이 하나면 params 를 빈 객체로 보내도 그 기간으로 신청합니다. 여럿이면 sfbTermStrtDt 에 신청할 기간의 시작일(YYYYMMDD)을 넣고, 시작일이 같은 기간이 여럿이면 sfbTermEndDt 도 넣어 다시 요청합니다. 본문이 달라지므로 confirmation_token 없이 보내 새 확인부터 받습니다.
AUTH_REQUIRED세션 없음 — 홈택스 세션이 없습니다. 홈택스 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다.
PROVIDER_BUSINESS_ERROR업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다.
PROVIDER_VALIDATION_ERROR홈택스 통신 오류 — 홈택스가 오류로 답하거나 연결이 끊겨 요청이 처리됐는지 알 수 없을 수 있으니, 다시 요청하기 전에 홈택스 화면에서 먼저 확인합니다. 홈택스가 오류 응답을 보내거나 연결이 끊긴 경우 error.message 는 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')입니다.
PROVIDER_UPSTREAM_ERROR홈택스 통신 오류 — 홈택스가 오류로 답하거나 연결이 끊겨 요청이 처리됐는지 알 수 없을 수 있으니, 다시 요청하기 전에 홈택스 화면에서 먼저 확인합니다. 홈택스가 오류 응답을 보내거나 연결이 끊긴 경우 error.message 는 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')입니다.
PROVIDER_UNAVAILABLE홈택스 통신 오류 — 홈택스가 오류로 답하거나 연결이 끊겨 요청이 처리됐는지 알 수 없을 수 있으니, 다시 요청하기 전에 홈택스 화면에서 먼저 확인합니다. 홈택스가 오류 응답을 보내거나 연결이 끊긴 경우 error.message 는 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')입니다.

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

MCP 도구 이름 hometax__certificate__apply__financial_statement

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

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

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

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

Request

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

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

[참고] 인증

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

[참고] 환경

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

[참고] 재시도

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

예시 : hometax

actionstring-Y호출할 작업입니다.
  • hometax.certificate.apply.financial_statement이 API 고정값 (기본값)

예시 : hometax.certificate.apply.financial_statement

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

형식 : UUID v4

[참고] 자격증명 등록

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

[참고] 암호화

순번변수명타입길이필수설명
tinstring-조건부보내도 신청 대상은 바뀌지 않습니다. 신청서의 식별번호는 늘 로그인한 계정의 값입니다
txpr_nmstring-조건부미입력 시 세션 상호 사용
bsnostring-Y대상 사업자등록번호(숫자 10자리)
qrtTrtstring-Y개인/법인 구분 코드(02 개인, 03 법인)
txyrstring4조건부과세년도(개인)

형식 : YYYY

incClCdstring-조건부소득구분(개인)
bsyrEndYmstring6조건부사업연도 종료연월(법인)

형식 : YYYYMM

confirmation_tokenstring-N1회용 확인 토큰입니다. 처음에는 보내지 않습니다. 토큰 없이 부르면 기관에 아무것도 보내지 않고 작업도 만들지 않은 채 확인이 필요하다는 오류(WRITE_CONFIRMATION_REQUIRED)로 끝나고, 응답의 error.confirmation_token 에 토큰이 옵니다. error.message 의 안내를 사용자에게 보여 주고 동의를 받은 뒤 같은 요청에 이 토큰을 넣어 다시 부릅니다. 토큰은 10분 안에 한 번만 쓸 수 있고 처음 요청과 같은 본문, 같은 호출자, 같은 환경에서만 맞으며, 아니면 확인이 만료됐거나 내용이 달라졌다는 오류로 거절합니다
cerpIsnRqsQtystring-N신청할 발급 매수입니다. 보내지 않으면 서식에 정해진 값으로 신청합니다
cvaDcumSbmsOrgnClCdstring-N증명서 제출처 구분코드입니다. 보내지 않으면 서식에 정해진 값으로 신청합니다
cvaDcumGranMthdCdstring-N증명서 교부방법 코드입니다. 보내지 않으면 서식에 정해진 값으로 신청합니다
adrOpYnstring-N증명서에 주소를 표시할지 정하는 값으로 Y 나 N 을 보냅니다. 보내지 않으면 서식에 정해진 값으로 신청합니다
resnoOpYnstring-N증명서에 주민등록번호를 표시할지 정하는 값으로 Y 나 N 을 보냅니다. 법인(사업자) 계정은 이 값과 관계없이 항상 N 으로 신청하고, 개인 계정이 보내지 않으면 서식에 정해진 값을 씁니다
amtOpYnstring-N증명서에 금액을 표시할지 정하는 값으로 Y 나 N 을 보냅니다. 금액 항목이 있는 서식에서만 반영하고 그 밖의 서식에서는 쓰이지 않습니다. 보내지 않으면 서식에 정해진 값으로 신청합니다
  • 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
bash
curl --request POST \
  --url 'https://api.xdata.kr/v1/jobs' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: real_test' \
  --header "Idempotency-Key: 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 타입이 함께 표시된 칸은 서버가 세부 타입을 고정하지 않는 기관 원문 또는 동적 값입니다.
순번변수명타입설명
outcomestring기관 처리 판정. 성공 응답에서는 항상 confirmed 입니다
actionstring요청한 액션 이름. outcome · action 외의 키는 홈택스 응답 본문에서 옵니다(기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다)
cvaIdstring | number | boolean | object | array | null기관이 발번한 증명서 아이디. 홈택스가 내려주는 키 이름 그대로입니다. 이 서식은 비어 올 수 있고, 그때 증명서 ID 는 증명서 신청 목록 조회의 같은 신청 행에서 cva_id 로 받습니다 기관 응답에 존재할 때만 반환됩니다. data 또는 cerpBscInfrDVO 내부에 있을 수 있으므로 최상위 존재를 전제로 접근하지 마세요.
rtnCvaIdstring | number | boolean | object | array | null홈택스 신고 내역 조회 결과의 rtnCvaId 와 같은 종류의 값이며 증명서 ID 가 아닙니다. 홈택스가 내려주는 키 이름 그대로입니다 기관 응답에 존재할 때만 반환됩니다. data 또는 cerpBscInfrDVO 내부에 있을 수 있으므로 최상위 존재를 전제로 접근하지 마세요.
json
// result.data — outcome · action 외의 키는 홈택스 응답 본문에서 옵니다(기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다).
{
  "outcome": "confirmed",
  "action": "hometax.certificate.apply.financial_statement",
  "cvaId": "...",
  "rtnCvaId": "..."
}
순번오류 코드발생 조건
PROVIDER_OUTCOME_UNCONFIRMED처리 확인 불가 — 요청은 홈택스로 전송됐지만 처리됐는지 확인하지 못했습니다. 이미 처리됐을 수 있으므로 다시 요청하지 않고, 오류 메시지가 안내하는 홈택스 화면에서 먼저 확인합니다.
AUTH_REQUIRED세션 없음 — 홈택스 세션이 없습니다. 홈택스 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다.
PROVIDER_BUSINESS_ERROR업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다.
PROVIDER_VALIDATION_ERROR홈택스 통신 오류 — 홈택스가 오류로 답하거나 연결이 끊겨 요청이 처리됐는지 알 수 없을 수 있으니, 다시 요청하기 전에 홈택스 화면에서 먼저 확인합니다. 홈택스가 오류 응답을 보내거나 연결이 끊긴 경우 error.message 는 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')입니다.
PROVIDER_UPSTREAM_ERROR홈택스 통신 오류 — 홈택스가 오류로 답하거나 연결이 끊겨 요청이 처리됐는지 알 수 없을 수 있으니, 다시 요청하기 전에 홈택스 화면에서 먼저 확인합니다. 홈택스가 오류 응답을 보내거나 연결이 끊긴 경우 error.message 는 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')입니다.
PROVIDER_UNAVAILABLE홈택스 통신 오류 — 홈택스가 오류로 답하거나 연결이 끊겨 요청이 처리됐는지 알 수 없을 수 있으니, 다시 요청하기 전에 홈택스 화면에서 먼저 확인합니다. 홈택스가 오류 응답을 보내거나 연결이 끊긴 경우 error.message 는 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')입니다.

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

MCP 도구 이름 hometax__certificate__apply__business_closure

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

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

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

  • 홈택스 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [홈택스 로그인(세션 생성)]
  • 요청 거절(HTTP 400, 작업은 만들어지지 않음).
  • 요청 거절(HTTP 409, 작업은 만들어지지 않음).
  • params 는 빈 객체로 보내도 호출됩니다. 사용할 인증서는 account_link_id 로 지정합니다.

Request

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

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

[참고] 인증

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

[참고] 환경

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

[참고] 재시도

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

예시 : hometax

actionstring-Y호출할 작업입니다.
  • hometax.certificate.apply.business_closure이 API 고정값 (기본값)

예시 : hometax.certificate.apply.business_closure

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

형식 : UUID v4

[참고] 자격증명 등록

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

[참고] 암호화

순번변수명타입필수설명
tinstring조건부보내도 신청 대상은 바뀌지 않습니다. 신청서의 식별번호는 늘 로그인한 계정의 값입니다
txpr_nmstring조건부미입력 시 세션 상호 사용
confirmation_tokenstringN1회용 확인 토큰입니다. 처음에는 보내지 않습니다. 토큰 없이 부르면 기관에 아무것도 보내지 않고 작업도 만들지 않은 채 확인이 필요하다는 오류(WRITE_CONFIRMATION_REQUIRED)로 끝나고, 응답의 error.confirmation_token 에 토큰이 옵니다. error.message 의 안내를 사용자에게 보여 주고 동의를 받은 뒤 같은 요청에 이 토큰을 넣어 다시 부릅니다. 토큰은 10분 안에 한 번만 쓸 수 있고 처음 요청과 같은 본문, 같은 호출자, 같은 환경에서만 맞으며, 아니면 확인이 만료됐거나 내용이 달라졌다는 오류로 거절합니다
cerpIsnRqsQtystringN신청할 발급 매수입니다. 보내지 않으면 서식에 정해진 값으로 신청합니다
cvaDcumSbmsOrgnClCdstringN증명서 제출처 구분코드입니다. 보내지 않으면 서식에 정해진 값으로 신청합니다
cvaDcumGranMthdCdstringN증명서 교부방법 코드입니다. 보내지 않으면 서식에 정해진 값으로 신청합니다
adrOpYnstringN증명서에 주소를 표시할지 정하는 값으로 Y 나 N 을 보냅니다. 보내지 않으면 서식에 정해진 값으로 신청합니다
resnoOpYnstringN증명서에 주민등록번호를 표시할지 정하는 값으로 Y 나 N 을 보냅니다. 법인(사업자) 계정은 이 값과 관계없이 항상 N 으로 신청하고, 개인 계정이 보내지 않으면 서식에 정해진 값을 씁니다
amtOpYnstringN증명서에 금액을 표시할지 정하는 값으로 Y 나 N 을 보냅니다. 금액 항목이 있는 서식에서만 반영하고 그 밖의 서식에서는 쓰이지 않습니다. 보내지 않으면 서식에 정해진 값으로 신청합니다
bash
curl --request POST \
  --url 'https://api.xdata.kr/v1/jobs' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: real_test' \
  --header "Idempotency-Key: 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 타입이 함께 표시된 칸은 서버가 세부 타입을 고정하지 않는 기관 원문 또는 동적 값입니다.
순번변수명타입설명
outcomestring기관 처리 판정. 성공 응답에서는 항상 confirmed 입니다
actionstring요청한 액션 이름. outcome · action 외의 키는 홈택스 응답 본문에서 옵니다(기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다)
cvaIdstring | number | boolean | object | array | null기관이 발번한 증명서 아이디. 홈택스가 내려주는 키 이름 그대로이며 비어 올 수 있습니다 기관 응답에 존재할 때만 반환됩니다. data 또는 cerpBscInfrDVO 내부에 있을 수 있으므로 최상위 존재를 전제로 접근하지 마세요.
json
// result.data — outcome · action 외의 키는 홈택스 응답 본문에서 옵니다(기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다).
{
  "outcome": "confirmed",
  "action": "hometax.certificate.apply.business_closure",
  "cvaId": "..."
}
순번오류 코드발생 조건
PROVIDER_OUTCOME_UNCONFIRMED처리 확인 불가 — 요청은 홈택스로 전송됐지만 처리됐는지 확인하지 못했습니다. 이미 처리됐을 수 있으므로 다시 요청하지 않고, 오류 메시지가 안내하는 홈택스 화면에서 먼저 확인합니다.
VALIDATION_INVALID_FIELD사업자 계정 아님 — 연결된 홈택스 계정이 사업자 계정이 아니면 신청하기 전에 멈추는 경우이며, 신청은 접수되지 않았고 자동 재시도 대상이 아닙니다. error.message 는 「폐업사실증명 발급은 사업자 계정으로만 신청할 수 있습니다. 사업자로 연결된 계정을 선택한 뒤 다시 시도해 주세요.」 입니다.
VALIDATION_INVALID_FIELD다른 사업자 지정 — params 에 bsno 를 보내 연결된 계정의 사업자등록번호와 다른 번호를 지정한 경우이며, 신청은 접수되지 않았고 자동 재시도 대상이 아닙니다. error.message 는 「폐업사실증명 발급은 연결된 사업자 본인 것만 신청할 수 있습니다. bsno 를 비우고 다시 요청하거나, 그 사업자로 연결된 계정을 선택해 주세요.」 입니다. 이 증명서는 연결된 사업자 본인 것만 신청하므로 bsno 는 보내지 않아도 됩니다.
PROVIDER_BUSINESS_ERROR폐업 이력 없음 — 신청 전에 조회한 연결 사업자의 이력에 폐업일이 없는 경우이며, 신청은 접수되지 않았고 자동 재시도 대상이 아닙니다. error.message 는 「연결된 사업자에는 폐업 사실이 없어 폐업사실증명을 신청할 수 없습니다. 신청은 접수하지 않았습니다. 폐업 신고가 처리된 사업자 계정으로 다시 시도해 주세요.」 입니다.
AUTH_REQUIRED세션 없음 — 홈택스 세션이 없습니다. 홈택스 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다.
PROVIDER_BUSINESS_ERROR업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다.
PROVIDER_VALIDATION_ERROR홈택스 통신 오류 — 홈택스가 오류로 답하거나 연결이 끊겨 요청이 처리됐는지 알 수 없을 수 있으니, 다시 요청하기 전에 홈택스 화면에서 먼저 확인합니다. 홈택스가 오류 응답을 보내거나 연결이 끊긴 경우 error.message 는 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')입니다.
PROVIDER_UPSTREAM_ERROR홈택스 통신 오류 — 홈택스가 오류로 답하거나 연결이 끊겨 요청이 처리됐는지 알 수 없을 수 있으니, 다시 요청하기 전에 홈택스 화면에서 먼저 확인합니다. 홈택스가 오류 응답을 보내거나 연결이 끊긴 경우 error.message 는 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')입니다.
PROVIDER_UNAVAILABLE홈택스 통신 오류 — 홈택스가 오류로 답하거나 연결이 끊겨 요청이 처리됐는지 알 수 없을 수 있으니, 다시 요청하기 전에 홈택스 화면에서 먼저 확인합니다. 홈택스가 오류 응답을 보내거나 연결이 끊긴 경우 error.message 는 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')입니다.

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

MCP 도구 이름 hometax__certificate__apply__business_registration_reissue

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

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

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

  • 홈택스 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [홈택스 로그인(세션 생성)]
  • 요청 거절(HTTP 400, 작업은 만들어지지 않음).
  • 요청 거절(HTTP 409, 작업은 만들어지지 않음).
  • params 는 빈 객체로 보내도 호출됩니다. 사용할 인증서는 account_link_id 로 지정합니다.

Request

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

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

[참고] 인증

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

[참고] 환경

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

[참고] 재시도

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

예시 : hometax

actionstring-Y호출할 작업입니다.
  • hometax.certificate.apply.business_registration_reissue이 API 고정값 (기본값)

예시 : hometax.certificate.apply.business_registration_reissue

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

형식 : UUID v4

[참고] 자격증명 등록

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

[참고] 암호화

순번변수명타입필수설명
tinstring조건부보내도 신청 대상은 바뀌지 않습니다. 신청서의 식별번호는 늘 로그인한 계정의 값입니다
txpr_nmstring조건부미입력 시 세션 상호 사용
confirmation_tokenstringN1회용 확인 토큰입니다. 처음에는 보내지 않습니다. 토큰 없이 부르면 기관에 아무것도 보내지 않고 작업도 만들지 않은 채 확인이 필요하다는 오류(WRITE_CONFIRMATION_REQUIRED)로 끝나고, 응답의 error.confirmation_token 에 토큰이 옵니다. error.message 의 안내를 사용자에게 보여 주고 동의를 받은 뒤 같은 요청에 이 토큰을 넣어 다시 부릅니다. 토큰은 10분 안에 한 번만 쓸 수 있고 처음 요청과 같은 본문, 같은 호출자, 같은 환경에서만 맞으며, 아니면 확인이 만료됐거나 내용이 달라졌다는 오류로 거절합니다
cerpIsnRqsQtystringN신청할 발급 매수입니다. 보내지 않으면 서식에 정해진 값으로 신청합니다
cvaDcumGranMthdCdstringN증명서 교부방법 코드입니다. 보내지 않으면 서식에 정해진 값으로 신청합니다
adrOpYnstringN증명서에 주소를 표시할지 정하는 값으로 Y 나 N 을 보냅니다. 보내지 않으면 서식에 정해진 값으로 신청합니다
resnoOpYnstringN증명서에 주민등록번호를 표시할지 정하는 값으로 Y 나 N 을 보냅니다. 법인(사업자) 계정은 이 값과 관계없이 항상 N 으로 신청하고, 개인 계정이 보내지 않으면 서식에 정해진 값을 씁니다
bash
curl --request POST \
  --url 'https://api.xdata.kr/v1/jobs' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: real_test' \
  --header "Idempotency-Key: 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 타입이 함께 표시된 칸은 서버가 세부 타입을 고정하지 않는 기관 원문 또는 동적 값입니다.
순번변수명타입설명
outcomestring기관 처리 판정. 성공 응답에서는 항상 confirmed 입니다
actionstring요청한 액션 이름. outcome · action 외의 키는 홈택스 응답 본문에서 옵니다(기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다)
cvaIdstring | number | boolean | object | array | null기관이 발번한 증명서 아이디. 홈택스가 내려주는 키 이름 그대로이며 비어 올 수 있습니다 기관 응답에 존재할 때만 반환됩니다. data 또는 cerpBscInfrDVO 내부에 있을 수 있으므로 최상위 존재를 전제로 접근하지 마세요.
json
// result.data — outcome · action 외의 키는 홈택스 응답 본문에서 옵니다(기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다).
{
  "outcome": "confirmed",
  "action": "hometax.certificate.apply.business_registration_reissue",
  "cvaId": "..."
}
순번오류 코드발생 조건
PROVIDER_OUTCOME_UNCONFIRMED처리 확인 불가 — 요청은 홈택스로 전송됐지만 처리됐는지 확인하지 못했습니다. 이미 처리됐을 수 있으므로 다시 요청하지 않고, 오류 메시지가 안내하는 홈택스 화면에서 먼저 확인합니다.
AUTH_REQUIRED세션 없음 — 홈택스 세션이 없습니다. 홈택스 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다.
PROVIDER_BUSINESS_ERROR업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다.
PROVIDER_VALIDATION_ERROR홈택스 통신 오류 — 홈택스가 오류로 답하거나 연결이 끊겨 요청이 처리됐는지 알 수 없을 수 있으니, 다시 요청하기 전에 홈택스 화면에서 먼저 확인합니다. 홈택스가 오류 응답을 보내거나 연결이 끊긴 경우 error.message 는 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')입니다.
PROVIDER_UPSTREAM_ERROR홈택스 통신 오류 — 홈택스가 오류로 답하거나 연결이 끊겨 요청이 처리됐는지 알 수 없을 수 있으니, 다시 요청하기 전에 홈택스 화면에서 먼저 확인합니다. 홈택스가 오류 응답을 보내거나 연결이 끊긴 경우 error.message 는 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')입니다.
PROVIDER_UNAVAILABLE홈택스 통신 오류 — 홈택스가 오류로 답하거나 연결이 끊겨 요청이 처리됐는지 알 수 없을 수 있으니, 다시 요청하기 전에 홈택스 화면에서 먼저 확인합니다. 홈택스가 오류 응답을 보내거나 연결이 끊긴 경우 error.message 는 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')입니다.

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

MCP 도구 이름 hometax__certificate__apply__income_statement

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

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

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

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

Request

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

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

[참고] 인증

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

[참고] 환경

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

[참고] 재시도

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

예시 : hometax

actionstring-Y호출할 작업입니다.
  • hometax.certificate.apply.income_statement이 API 고정값 (기본값)

예시 : hometax.certificate.apply.income_statement

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

형식 : UUID v4

[참고] 자격증명 등록

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

[참고] 암호화

순번변수명타입길이필수설명
tinstring-조건부보내도 신청 대상은 바뀌지 않습니다. 신청서의 식별번호는 늘 로그인한 계정의 값입니다
txpr_nmstring-조건부미입력 시 세션 상호 사용
txnrmStrtYmstring6Y과세기간 시작년월(귀속연도 전체 예: 202401)

형식 : YYYYMM

txnrmEndYmstring6Y과세기간 종료년월(예: 202412)

형식 : YYYYMM

confirmation_tokenstring-N1회용 확인 토큰입니다. 처음에는 보내지 않습니다. 토큰 없이 부르면 기관에 아무것도 보내지 않고 작업도 만들지 않은 채 확인이 필요하다는 오류(WRITE_CONFIRMATION_REQUIRED)로 끝나고, 응답의 error.confirmation_token 에 토큰이 옵니다. error.message 의 안내를 사용자에게 보여 주고 동의를 받은 뒤 같은 요청에 이 토큰을 넣어 다시 부릅니다. 토큰은 10분 안에 한 번만 쓸 수 있고 처음 요청과 같은 본문, 같은 호출자, 같은 환경에서만 맞으며, 아니면 확인이 만료됐거나 내용이 달라졌다는 오류로 거절합니다
cerpIsnRqsQtystring-N신청할 발급 매수입니다. 보내지 않으면 서식에 정해진 값으로 신청합니다
cvaDcumSbmsOrgnClCdstring-N증명서 제출처 구분코드입니다. 보내지 않으면 서식에 정해진 값으로 신청합니다
cvaDcumGranMthdCdstring-N증명서 교부방법 코드입니다. 보내지 않으면 서식에 정해진 값으로 신청합니다
adrOpYnstring-N증명서에 주소를 표시할지 정하는 값으로 Y 나 N 을 보냅니다. 보내지 않으면 서식에 정해진 값으로 신청합니다
resnoOpYnstring-N증명서에 주민등록번호를 표시할지 정하는 값으로 Y 나 N 을 보냅니다. 법인(사업자) 계정은 이 값과 관계없이 항상 N 으로 신청하고, 개인 계정이 보내지 않으면 서식에 정해진 값을 씁니다
  • 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
bash
curl --request POST \
  --url 'https://api.xdata.kr/v1/jobs' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: real_test' \
  --header "Idempotency-Key: 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 타입이 함께 표시된 칸은 서버가 세부 타입을 고정하지 않는 기관 원문 또는 동적 값입니다.
순번변수명타입설명
outcomestring기관 처리 판정. 성공 응답에서는 항상 confirmed 입니다
actionstring요청한 액션 이름. outcome · action 외의 키는 홈택스 응답 본문에서 옵니다(기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다)
cvaIdstring | number | boolean | object | array | null기관이 발번한 증명서 아이디. 홈택스가 내려주는 키 이름 그대로이며 비어 올 수 있습니다 기관 응답에 존재할 때만 반환됩니다. data 또는 cerpBscInfrDVO 내부에 있을 수 있으므로 최상위 존재를 전제로 접근하지 마세요.
json
// result.data — outcome · action 외의 키는 홈택스 응답 본문에서 옵니다(기관 세션 정보 resultMsg.sessionMap 은 빼고 전달합니다).
{
  "outcome": "confirmed",
  "action": "hometax.certificate.apply.income_statement",
  "cvaId": "..."
}
순번오류 코드발생 조건
PROVIDER_OUTCOME_UNCONFIRMED처리 확인 불가 — 요청은 홈택스로 전송됐지만 처리됐는지 확인하지 못했습니다. 이미 처리됐을 수 있으므로 다시 요청하지 않고, 오류 메시지가 안내하는 홈택스 화면에서 먼저 확인합니다.
AUTH_REQUIRED세션 없음 — 홈택스 세션이 없습니다. 홈택스 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다.
PROVIDER_BUSINESS_ERROR업무 오류 — 홈택스가 요청을 거절했습니다. 보낸 파라미터 값을 확인합니다.
PROVIDER_VALIDATION_ERROR홈택스 통신 오류 — 홈택스가 오류로 답하거나 연결이 끊겨 요청이 처리됐는지 알 수 없을 수 있으니, 다시 요청하기 전에 홈택스 화면에서 먼저 확인합니다. 홈택스가 오류 응답을 보내거나 연결이 끊긴 경우 error.message 는 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')입니다.
PROVIDER_UPSTREAM_ERROR홈택스 통신 오류 — 홈택스가 오류로 답하거나 연결이 끊겨 요청이 처리됐는지 알 수 없을 수 있으니, 다시 요청하기 전에 홈택스 화면에서 먼저 확인합니다. 홈택스가 오류 응답을 보내거나 연결이 끊긴 경우 error.message 는 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')입니다.
PROVIDER_UNAVAILABLE홈택스 통신 오류 — 홈택스가 오류로 답하거나 연결이 끊겨 요청이 처리됐는지 알 수 없을 수 있으니, 다시 요청하기 전에 홈택스 화면에서 먼저 확인합니다. 홈택스가 오류 응답을 보내거나 연결이 끊긴 경우 error.message 는 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')입니다.

11. 증명서 자동 신청hometax.certificate.apply_auto

MCP 도구 이름 hometax__certificate__apply_auto

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

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

로그인한 사업자의 정보로 신청서를 채워 증명서를 홈택스에 신청하고, 접수번호와 내려받기에 쓸 정보를 함께 받습니다.

Request

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

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

[참고] 인증

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

[참고] 환경

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

[참고] 재시도

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

예시 : hometax

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

예시 : hometax.certificate.apply_auto

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

형식 : UUID v4

[참고] 자격증명 등록

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

[참고] 암호화

순번변수명타입길이필수설명
confirmation_tokenstring-N1회용 확인 토큰입니다. 처음에는 보내지 않습니다. 토큰 없이 부르면 기관에 아무것도 보내지 않고 작업도 만들지 않은 채 확인이 필요하다는 오류(WRITE_CONFIRMATION_REQUIRED)로 끝나고, 응답의 error.confirmation_token 에 토큰이 옵니다. error.message 의 안내를 사용자에게 보여 주고 동의를 받은 뒤 같은 요청에 이 토큰을 넣어 다시 부릅니다. 토큰은 10분 안에 한 번만 쓸 수 있고 처음 요청과 같은 본문, 같은 호출자, 같은 환경에서만 맞으며, 아니면 확인이 만료됐거나 내용이 달라졌다는 오류로 거절합니다. 신청하면 홈택스에 접수 기록이 남고 취소할 수 없습니다
cert_templatestring-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_company_tinboolean-N신청서에 적을 납세자 이름을 고릅니다. true 이면 로그인한 계정의 사업자(법인) 이름을, false 이면 대표자 이름(없으면 사업자 이름)을 씁니다. 신청서의 식별번호는 이 값과 상관없이 로그인한 계정의 값입니다. 보내지 않거나 null 이면 true 입니다. 참/거짓 값 말고 글자로도 받습니다(대소문자 무관, 참은 1, on, true, y, yes, 거짓은 0, false, n, no, off). 수는 0 이면 false, 그 밖의 수는 true 입니다. 그 밖의 값은 신청하지 않고 거절합니다
strtYmstring6N조회 시작 연월입니다. 부가가치세과세표준증명 서식을 고를 때 필요하고, 그 밖의 서식에서는 보내지 않습니다

형식 : YYYYMM

endYmstring6N조회 종료 연월입니다. 부가가치세과세표준증명 서식을 고를 때 필요하고, 그 밖의 서식에서는 보내지 않습니다

형식 : YYYYMM

bsnostring-N대상 사업자등록번호(숫자 10자리)입니다. 표준재무제표증명 서식을 고를 때 필요하고, 그 밖의 서식에서는 보내지 않습니다
qrtTrtstring-N개인인지 법인인지 나누는 구분 코드입니다(02 개인, 03 법인). 표준재무제표증명 서식을 고를 때 필요하고, 이 값에 따라 아래의 txyr 나 bsyrEndYm 중 하나를 함께 보냅니다
txyrstring4N과세년도입니다. 표준재무제표증명 서식에서 개인(qrtTrt 가 02)일 때 필요합니다

형식 : YYYY

incClCdstring-N소득구분 코드입니다. 표준재무제표증명 서식에서 개인(qrtTrt 가 02)일 때 필요합니다
bsyrEndYmstring6N사업연도 종료연월입니다. 표준재무제표증명 서식에서 법인(qrtTrt 가 03)일 때 필요합니다

형식 : YYYYMM

txnrmStrtYmstring6N과세기간 시작년월입니다. 소득금액증명 서식을 고를 때 필요하고, 귀속연도 전체를 보려면 그 해의 1월(예: 202401)을 보냅니다

형식 : YYYYMM

txnrmEndYmstring6N과세기간 종료년월입니다. 소득금액증명 서식을 고를 때 필요하고, 귀속연도 전체를 보려면 그 해의 12월(예: 202412)을 보냅니다

형식 : YYYYMM

cerpIsnRqsQtystring-N신청할 발급 매수입니다. 보내지 않으면 서식에 정해진 값으로 신청합니다
cvaDcumSbmsOrgnClCdstring-N증명서 제출처 구분코드입니다. 보내지 않으면 서식에 정해진 값으로 신청합니다
cvaDcumGranMthdCdstring-N증명서 교부방법 코드입니다. 보내지 않으면 서식에 정해진 값으로 신청합니다
adrOpYnstring-N증명서에 주소를 표시할지 정하는 값으로 Y 나 N 을 보냅니다. 보내지 않으면 서식에 정해진 값으로 신청합니다
resnoOpYnstring-N증명서에 주민등록번호를 표시할지 정하는 값으로 Y 나 N 을 보냅니다. 법인(사업자) 계정은 이 값과 관계없이 항상 N 으로 신청하고, 개인 계정이 보내지 않으면 서식에 정해진 값을 씁니다
amtOpYnstring-N증명서에 금액을 표시할지 정하는 값으로 Y 나 N 을 보냅니다. 금액 항목이 있는 서식에서만 반영하고 그 밖의 서식에서는 쓰이지 않습니다. 보내지 않으면 서식에 정해진 값으로 신청합니다
bash
curl --request POST \
  --url 'https://api.xdata.kr/v1/jobs' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: real_test' \
  --header "Idempotency-Key: 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 이 더해져 담깁니다.
  • 내려받기에 쓸 접수번호(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 가 아닙니다.
순번변수명타입설명
outcomestring기관이 신청을 받았다는 판정입니다. 성공 응답에서는 항상 confirmed 입니다. 기관에 요청은 갔지만 접수됐는지 확인하지 못한 경우는 이 응답이 아니라 실패(PROVIDER_OUTCOME_UNCONFIRMED)로 옵니다.
actionstring실행한 액션의 ID 입니다.
cvaIdstring | null기관이 발번한 증명서 ID 입니다. 홈택스가 내려 주는 키 이름 그대로이고, 내려받기의 cva_id 로 보내며 서식에 따라 비어 올 수 있습니다.
list_infoobject방금 신청한 증명서의 신청 목록 행입니다. 신청이 접수된 직후 신청 목록의 첫 쪽(10건)에서 그 증명서를 찾았을 때만 오고, 목록 조회가 실패하거나 거기서 찾지 못하면 이 칸 없이 신청 결과만 옵니다.
list_info.rpt_pkg_pthstring | null신청 목록 행의 보고서 경로입니다. 내려받기의 rpt_pkg_pth 로 보냅니다. 값이 없으면 null 입니다.
list_info.rcat_nostring신청 목록 행의 접수번호입니다. 내려받기의 rcat_no 로 보냅니다.
list_info.cva_knd_nmstring신청 목록 행의 증명서 종류 이름입니다.
list_info.state_nmstring신청 목록 행의 처리 상태 이름입니다.
list_info.issue_stat_nmstring신청 목록 행의 발급 상태 이름입니다.
list_info.cerp_isn_qtystring | null신청 목록 행의 발급 수량 칸입니다. 값이 없으면 null 입니다.
json
// 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_REQUIRED요청에 확인 토큰(confirmation_token)이 없으면 홈택스에 아무것도 보내지 않고 작업도 만들지 않은 채 이 오류로 끝납니다. error.message 는 cert_template 로 정한 서식의 확인 문구로 시작해 실행할 내용의 미리보기가 이어지고, error.confirmation_token 에 1회용 토큰이, error.preview 에 미리보기 객체가 함께 옵니다. 이 내용을 고객에게 그대로 보여 주고 확인을 받은 뒤, 같은 요청의 params.confirmation_token 에 응답의 error.confirmation_token 값을 넣어 다시 호출해 주세요. 토큰은 10분 안에 한 번만 쓸 수 있고, 확인한 요청 본문과 같은 본문에만 맞습니다. 확인값(confirm)은 보지 않으니 입력하지 않아도 됩니다.
WRITE_CONFIRMATION_INVALID토큰이 만료됐거나, 이미 썼거나, 다른 호출자나 다른 환경에서 받은 것이거나, 확인한 요청 본문과 달라졌으면 홈택스에 아무것도 보내지 않고 작업도 만들지 않은 채 이 오류로 끝납니다. error.message 는 「확인이 만료됐거나 확인한 내용과 달라졌습니다. 다시 확인해 주세요.」 입니다. 토큰 없이 다시 요청하면 새 토큰과 미리보기를 받습니다.
VALIDATION_INVALID_FIELDcert_template 이 신청할 수 있는 서식 9가지에 없으면 홈택스에 보내지 않고 이 오류로 끝납니다. error.message 는 「지원하지 않는 증명서 서식입니다: '보낸 값'」 으로 시작하고 고를 수 있는 서식 목록이 이어집니다.
AUTH_REQUIRED저장된 기관 세션이 없습니다. 같은 연동 계정으로 hometax.session.login 을 먼저 실행해 세션을 연 뒤 다시 보냅니다.
PROVIDER_SESSION_EXPIRED기관 세션이 만료됐습니다. 같은 연동 계정으로 hometax.session.login 을 다시 실행해 세션을 연 뒤 다시 보냅니다.
PROVIDER_BUSINESS_ERROR신청 전에 홈택스에서 납세자 주소를 조회하는 서식은, 홈택스가 그 조회를 거절하면(응답 봉투의 resultMsg.result 가 비어 있지도 S 도 아닌 값) 신청을 보내지 않고 이 오류로 끝납니다. error.message 는 홈택스가 알려 준 사유이고, 사유를 주지 않으면 「기관이 요청을 처리하지 않았습니다. 사유는 알려 주지 않았습니다. 입력값을 그대로 두고 잠시 후 다시 시도해 주세요.」 입니다.
PROVIDER_UNAVAILABLE홈택스가 서비스 중지 시간이라고 답한 경우입니다. 값이 틀린 것이 아니라 시간의 문제이고 요청은 처리되지 않았습니다. error.message 는 중지 시간을 읽었으면 그 시간을 함께 알리고, 읽지 못했으면 「지금은 홈택스 서비스 중지 시간이라 요청이 처리되지 않았습니다. 중지 시간이 지난 뒤 다시 요청해 주세요.」 입니다.
VALIDATION_INVALID_FIELD서식(cert_template)이 cert_bugase_gwase_pyojun 이고 연결된 홈택스 계정이 개인 계정이면 신청하기 전에 이 오류로 끝나며, 신청은 접수되지 않았고 자동으로 다시 시도하지 않습니다. error.message 는 「부가가치세 과세표준증명 발급은 사업자 계정으로만 신청할 수 있습니다. 사업자로 연결된 계정을 선택한 뒤 다시 시도해 주세요.」 입니다.
VALIDATION_INVALID_FIELD서식(cert_template)이 cert_hyupeop_sasil 이고 연결된 홈택스 계정이 사업자 계정이 아니면 신청하기 전에 이 오류로 끝나며, 신청은 접수되지 않았고 자동으로 다시 시도하지 않습니다. error.message 는 「휴업사실증명 발급은 사업자 계정으로만 신청할 수 있습니다. 사업자로 연결된 계정을 선택한 뒤 다시 시도해 주세요.」 입니다.
VALIDATION_INVALID_FIELD서식(cert_template)이 cert_hyupeop_sasil 이고 bsno 를 보내 연결된 계정의 사업자등록번호와 다른 번호를 지정하면 신청하기 전에 이 오류로 끝나며, 신청은 접수되지 않았고 자동으로 다시 시도하지 않습니다. error.message 는 「휴업사실증명 발급은 연결된 사업자 본인 것만 신청할 수 있습니다. bsno 를 비우고 다시 요청하거나, 그 사업자로 연결된 계정을 선택해 주세요.」 입니다. 이 서식은 연결된 사업자 본인 것만 신청하므로 bsno 는 보내지 않아도 됩니다.
VALIDATION_INVALID_FIELD서식(cert_template)이 cert_pyepeop_sasil 이고 연결된 홈택스 계정이 사업자 계정이 아니면 신청하기 전에 이 오류로 끝나며, 신청은 접수되지 않았고 자동으로 다시 시도하지 않습니다. error.message 는 「폐업사실증명 발급은 사업자 계정으로만 신청할 수 있습니다. 사업자로 연결된 계정을 선택한 뒤 다시 시도해 주세요.」 입니다.
VALIDATION_INVALID_FIELD서식(cert_template)이 cert_pyepeop_sasil 이고 bsno 를 보내 연결된 계정의 사업자등록번호와 다른 번호를 지정하면 신청하기 전에 이 오류로 끝나며, 신청은 접수되지 않았고 자동으로 다시 시도하지 않습니다. error.message 는 「폐업사실증명 발급은 연결된 사업자 본인 것만 신청할 수 있습니다. bsno 를 비우고 다시 요청하거나, 그 사업자로 연결된 계정을 선택해 주세요.」 입니다. 이 서식은 연결된 사업자 본인 것만 신청하므로 bsno 는 보내지 않아도 됩니다.
PROVIDER_BUSINESS_ERROR기관이 신청을 거절한 경우입니다(접수 전). error.message 는 「기관이 민원증명 신청을 거절했습니다.」 로 시작하고 기관이 알려 준 사유가 이어집니다. 신청이 접수되지 않았으므로 사유를 고쳐 다시 신청할 수 있습니다. 서식(cert_template)이 cert_sodeuk_geumaeg_jeungmyeong 이면 error.message 는 「기관이 민원증명 신청을 거절했습니다. 소득금액증명은 개인과 개인사업자만 신청할 수 있습니다. 법인 계정으로는 신청되지 않습니다.」 로 시작합니다.
PROVIDER_OUTCOME_UNCONFIRMED신청 요청은 기관에 갔지만 접수됐는지 확인하지 못한 경우입니다(응답에 접수 판정 resultMsg.result 도 발번된 증명서 ID 나 접수번호도 없습니다). 이 오류로 끝나며 자동으로 다시 시도하지 않습니다. error.message 는 「기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다. 홈택스 [민원증명 > 민원증명 발급신청 결과 조회]에서 방금 신청한 증명이 접수됐는지 확인해 주세요. 접수되지 않았을 때만 다시 신청하세요.」 입니다.

12. 증명서 자동 신청 후 내려받기hometax.certificate.apply_auto_download

MCP 도구 이름 hometax__certificate__apply_auto_download

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

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

국세완납증명 1매를 홈택스에 신청하고, 발급되면 바로 발급용으로 출력해 PDF 파일로 받는 일을 미리보기를 확인한 뒤 다시 요청하는 것으로 끝냅니다.

Request

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

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

[참고] 인증

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

[참고] 환경

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

[참고] 재시도

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

예시 : hometax

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

예시 : hometax.certificate.apply_auto_download

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

형식 : UUID v4

[참고] 자격증명 등록

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

[참고] 암호화

순번변수명타입필수설명
confirmation_tokenstringN1회용 확인 토큰입니다. 처음에는 보내지 않습니다. 토큰 없이 부르면 기관에 아무것도 보내지 않고 작업도 만들지 않은 채 확인이 필요하다는 오류(WRITE_CONFIRMATION_REQUIRED)로 끝나고, 응답의 error.confirmation_token 에 토큰이 옵니다. error.message 의 안내를 사용자에게 보여 주고 동의를 받은 뒤 같은 요청에 이 토큰을 넣어 다시 부릅니다. 토큰은 10분 안에 한 번만 쓸 수 있고 처음 요청과 같은 본문, 같은 호출자, 같은 환경에서만 맞으며, 아니면 확인이 만료됐거나 내용이 달라졌다는 오류로 거절합니다. 국세완납증명 신청이 먼저 접수되고 이어서 발급용으로 출력하므로 접수 기록이 남고 발급 한도 1매가 사용되며 되돌릴 수 없습니다
bash
curl --request POST \
  --url 'https://api.xdata.kr/v1/jobs' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: real_test' \
  --header "Idempotency-Key: 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 에는 아래 칸만 있습니다.
순번변수명타입설명
outcomestring발급이 확인됐다는 판정입니다. 성공 응답에서는 항상 confirmed 입니다. 기관에 요청은 갔지만 결과를 확인하지 못한 경우는 이 응답이 아니라 실패(PROVIDER_OUTCOME_UNCONFIRMED)로 옵니다.
actionstring실행한 액션의 ID 입니다.
verdict_detailobject기관이 출력을 기록했다고 판정한 근거입니다. 기관의 출력 결과 보고 응답에서 resultMsg.result 의 값이 S 이면 확인으로 읽고, 그 값이 없거나 다르면 기관 신청 목록의 실제 발급 수량이 출력 전보다 늘었는지로 다시 확인합니다. 읽은 위치(verdict_path)와 읽은 값(verdict), 받아들이는 값(accepted_values) 같은 진단 칸이 담기고 칸 구성은 판정 경로에 따라 달라집니다.
cva_idstring이 요청이 신청해 기관이 발번한 증명서 ID 입니다.
rcat_nostring신청 목록의 그 증명서 행에서 읽은 접수번호입니다.
json
// result.data - 값 자리에는 각 칸의 형식을 적었습니다 (실제 값이 아닙니다)
{
  "outcome": "<string>",
  "action": "<string>",
  "verdict_detail": {},
  "cva_id": "<string>",
  "rcat_no": "<string>"
}
순번오류 코드발생 조건
WRITE_CONFIRMATION_REQUIRED요청에 확인 토큰(confirmation_token)이 없으면 홈택스에 아무것도 보내지 않고 작업도 만들지 않은 채 이 오류로 끝납니다. error.message 는 「증명서 발급 신청은 홈택스에 접수 기록을 남기고 취소할 수 없어 신청 전 확인이 필요합니다. 아래 내용을 사용자에게 보여주고 동의를 받으세요.」 로 시작해 실행할 내용의 미리보기가 이어지고, error.confirmation_token 에 1회용 토큰이, error.preview 에 미리보기 객체가 함께 옵니다. 이 내용을 고객에게 그대로 보여 주고 확인을 받은 뒤, 같은 요청의 params.confirmation_token 에 응답의 error.confirmation_token 값을 넣어 다시 호출해 주세요. 토큰은 10분 안에 한 번만 쓸 수 있고, 확인한 요청 본문과 같은 본문에만 맞습니다. 확인값(confirm)은 보지 않으니 입력하지 않아도 됩니다.
WRITE_CONFIRMATION_INVALID토큰이 만료됐거나, 이미 썼거나, 다른 호출자나 다른 환경에서 받은 것이거나, 확인한 요청 본문과 달라졌으면 홈택스에 아무것도 보내지 않고 작업도 만들지 않은 채 이 오류로 끝납니다. error.message 는 「확인이 만료됐거나 확인한 내용과 달라졌습니다. 다시 확인해 주세요.」 입니다. 토큰 없이 다시 요청하면 새 토큰과 미리보기를 받습니다.
AUTH_REQUIRED저장된 기관 세션이 없습니다. 같은 연동 계정으로 hometax.session.login 을 먼저 실행해 세션을 연 뒤 다시 보냅니다.
PROVIDER_SESSION_EXPIRED기관 세션이 만료됐습니다. 같은 연동 계정으로 hometax.session.login 을 다시 실행해 세션을 연 뒤 다시 보냅니다.
PROVIDER_UNAVAILABLE홈택스가 서비스 중지 시간이라고 답한 경우입니다. 값이 틀린 것이 아니라 시간의 문제이고 요청은 처리되지 않았습니다. error.message 는 중지 시간을 읽었으면 그 시간을 함께 알리고, 읽지 못했으면 「지금은 홈택스 서비스 중지 시간이라 요청이 처리되지 않았습니다. 중지 시간이 지난 뒤 다시 요청해 주세요.」 입니다.
PROVIDER_BUSINESS_ERROR기관이 신청을 거절한 경우입니다(접수 전). error.message 는 「기관이 민원증명 신청을 거절했습니다.」 로 시작하고 기관이 알려 준 사유가 이어집니다. 신청이 접수되지 않았으므로 사유를 고쳐 다시 신청할 수 있습니다.
PROVIDER_BUSINESS_ERROR기관이 증명서 신청 결과로 접수번호를 주지 않았습니다. 접수됐는지 확인하기 전에는 다시 신청하지 마세요. 홈택스 민원증명 발급내역에서 같은 증명서가 있는지 먼저 확인해 주세요.
PROVIDER_BUSINESS_ERROR신청은 접수됐지만 발급 대기나 출력 단계에서 멈춘 경우입니다. error.message 는 「증명서 신청은 접수됐습니다(증명서 ID {cva_id}, 접수번호 {rcat_no}). 파일은 내려받지 못했습니다.」 로 시작하고 아래 사유 중 하나가 이어진 뒤 「다시 신청하지 마시고, 잠시 뒤 증명서 내려받기에 이 증명서 ID 와 접수번호로 요청해 주세요.」 로 끝납니다(중괄호 자리에는 그 건의 실제 값이 들어갑니다). 신청은 이미 접수됐으므로 이 작업을 다시 부르면 두 번째 신청이 접수됩니다.
PROVIDER_BUSINESS_ERROR접수번호를 아직 읽지 못한 채 멈추면 앞 문장은 「증명서 신청은 접수됐습니다(증명서 ID {cva_id}).」 로 증명서 ID 만 싣고 끝 안내는 「다시 신청하지 마시고, 잠시 뒤 증명서 목록에서 이 증명서 ID 의 접수번호를 확인한 다음 증명서 내려받기에 두 값으로 요청해 주세요.」 입니다. 사유가 발급 한도 소진이면 끝 안내가 붙지 않습니다.
PROVIDER_BUSINESS_ERROR신청이 접수된 뒤의 사유입니다. 「기관이 아직 발급을 끝내지 않았습니다.」
PROVIDER_BUSINESS_ERROR신청이 접수된 뒤의 사유입니다. 「증명서 발급번호를 찾지 못했습니다. 증명서가 아직 발급되지 않았거나, 증명서 목록에서 해당 건을 먼저 조회해야 합니다.」
PROVIDER_BUSINESS_ERROR신청이 접수된 뒤의 사유입니다. 「이 증명서의 발급 한도를 이미 모두 사용했습니다. 더 필요하면 같은 증명서를 다시 신청한 뒤 내려받아 주세요.」
PROVIDER_BUSINESS_ERROR신청이 접수된 뒤의 사유입니다. 「증명서 출력을 시작하지 못했습니다. 기관이 보고서를 만들지 않았습니다. 증명서 목록에서 해당 건이 '처리완료' 이고 발급 가능한지 확인한 뒤 다시 시도해 주세요.」
PROVIDER_BUSINESS_ERROR신청이 접수된 뒤의 사유입니다. 「증명서 출력 준비 상태를 확인하지 못했습니다. 증명서 목록을 다시 조회해 남은 발급 수량을 확인한 뒤 내려받아 주세요.」
PROVIDER_BUSINESS_ERROR신청이 접수된 뒤의 사유입니다. 「기관이 증명서 보고서를 만들지 못했습니다. 기관 로그인이 만료됐을 수 있으니 다시 로그인한 뒤 시도해 주세요.」
PROVIDER_BUSINESS_ERROR신청이 접수된 뒤의 사유입니다. 「기관이 증명서 보고서를 아직 만들지 않았습니다. 증명서 목록을 다시 조회해 남은 발급 수량을 확인한 뒤 내려받아 주세요.」
PROVIDER_BUSINESS_ERROR신청이 접수된 뒤의 사유입니다. 「기관이 증명서 파일 대신 PDF 가 아닌 응답을 보냈습니다. 증명서 목록에서 해당 건이 '처리완료' 인지 확인한 뒤 다시 시도해 주세요.」
PROVIDER_BUSINESS_ERROR신청이 접수된 뒤 기관이 증명서 출력 결과 기록을 거절한 경우입니다. 사유 문장은 「기관이 증명서 출력 결과 기록을 거절했습니다.」 로 시작하고 기관이 알려 준 사유가 이어집니다.
PROVIDER_OUTCOME_UNCONFIRMED신청은 접수됐지만 그 뒤 단계가 전송이 끊기거나 기관의 HTTP 오류, 읽지 못한 응답처럼 이 문서에 따로 적지 않은 이유로 멈춰 결과를 확인하지 못한 경우입니다. 자동으로 다시 시도하지 않습니다. error.message 는 「증명서 신청은 접수됐습니다(증명서 ID {cva_id}, 접수번호 {rcat_no}). 파일은 내려받지 못했습니다. 접수 뒤 단계에서 기관 응답을 확인하지 못했습니다. 다시 신청하지 마시고, 잠시 뒤 증명서 내려받기에 이 증명서 ID 와 접수번호로 요청해 주세요.」 입니다(중괄호 자리에는 그 건의 실제 값이 들어갑니다).
PROVIDER_OUTCOME_UNCONFIRMED신청은 접수됐고 출력 기록만 확인하지 못한 경우입니다. 파일은 돌려주지 않고 자동으로 다시 시도하지 않습니다. error.message 는 「기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다. 증명서 신청은 접수됐습니다(증명서 ID {cva_id}, 접수번호 {rcat_no}). 확인하지 못한 것은 증명서 출력 기록입니다. 홈택스 민원증명 발급신청 결과 조회 화면에서 그 증명의 발급 수량을 확인해 주세요. 발급 수량이 신청 수량만큼 찼으면 이미 발급된 것이니 같은 증명서를 다시 신청한 뒤 내려받으세요. 발급 수량이 그대로이면 같은 건으로 다시 내려받으세요.」 입니다(중괄호 자리에는 그 건의 실제 값이 들어갑니다).

13. 증명서 서식 지정 신청hometax.certificate.apply_with_template

MCP 도구 이름 hometax__certificate__apply_with_template

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

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

서식 목록에서 고른 증명서를 발급 매수와 제출처, 공개 여부를 정해 홈택스에 신청하고 증명서 ID를 받습니다.

Request

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

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

[참고] 인증

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

[참고] 환경

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

[참고] 재시도

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

예시 : hometax

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

예시 : hometax.certificate.apply_with_template

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

형식 : UUID v4

[참고] 자격증명 등록

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

[참고] 암호화

순번변수명타입길이필수설명
confirmation_tokenstring-N1회용 확인 토큰입니다. 처음에는 보내지 않습니다. 토큰 없이 부르면 기관에 아무것도 보내지 않고 작업도 만들지 않은 채 확인이 필요하다는 오류(WRITE_CONFIRMATION_REQUIRED)로 끝나고, 응답의 error.confirmation_token 에 토큰이 옵니다. error.message 의 안내를 사용자에게 보여 주고 동의를 받은 뒤 같은 요청에 이 토큰을 넣어 다시 부릅니다. 토큰은 10분 안에 한 번만 쓸 수 있고 처음 요청과 같은 본문, 같은 호출자, 같은 환경에서만 맞으며, 아니면 확인이 만료됐거나 내용이 달라졌다는 오류로 거절합니다. 신청하면 홈택스에 접수 기록이 남고 취소할 수 없습니다
cert_templatestring-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(국세완납증명)로 신청되며, 표에 없는 값은 홈택스에 닿기 전에 거절됩니다
strtYmstring6N조회 시작 연월입니다. 부가가치세과세표준증명 서식을 고를 때 필요하고, 그 밖의 서식에서는 보내지 않습니다

형식 : YYYYMM

endYmstring6N조회 종료 연월입니다. 부가가치세과세표준증명 서식을 고를 때 필요하고, 그 밖의 서식에서는 보내지 않습니다

형식 : YYYYMM

bsnostring-N대상 사업자등록번호(숫자 10자리)입니다. 표준재무제표증명 서식을 고를 때 필요하고, 그 밖의 서식에서는 보내지 않습니다
qrtTrtstring-N개인인지 법인인지 나누는 구분 코드입니다(02 개인, 03 법인). 표준재무제표증명 서식을 고를 때 필요하고, 이 값에 따라 아래의 txyr 나 bsyrEndYm 중 하나를 함께 보냅니다
txyrstring4N과세년도입니다. 표준재무제표증명 서식에서 개인(qrtTrt 가 02)일 때 필요합니다

형식 : YYYY

incClCdstring-N소득구분 코드입니다. 표준재무제표증명 서식에서 개인(qrtTrt 가 02)일 때 필요합니다
bsyrEndYmstring6N사업연도 종료연월입니다. 표준재무제표증명 서식에서 법인(qrtTrt 가 03)일 때 필요합니다

형식 : YYYYMM

txnrmStrtYmstring6N과세기간 시작년월입니다. 소득금액증명 서식을 고를 때 필요하고, 귀속연도 전체를 보려면 그 해의 1월(예: 202401)을 보냅니다

형식 : YYYYMM

txnrmEndYmstring6N과세기간 종료년월입니다. 소득금액증명 서식을 고를 때 필요하고, 귀속연도 전체를 보려면 그 해의 12월(예: 202412)을 보냅니다

형식 : YYYYMM

cerpIsnRqsQtystring-N신청할 발급 매수입니다. 보내지 않으면 서식에 정해진 값으로 신청합니다
cvaDcumSbmsOrgnClCdstring-N증명서 제출처 구분코드입니다. 보내지 않으면 서식에 정해진 값으로 신청합니다
cvaDcumGranMthdCdstring-N증명서 교부방법 코드입니다. 보내지 않으면 서식에 정해진 값으로 신청합니다
adrOpYnstring-N증명서에 주소를 표시할지 정하는 값으로 Y 나 N 을 보냅니다. 보내지 않으면 서식에 정해진 값으로 신청합니다
resnoOpYnstring-N증명서에 주민등록번호를 표시할지 정하는 값으로 Y 나 N 을 보냅니다. 법인(사업자) 계정은 이 값과 관계없이 항상 N 으로 신청하고, 개인 계정이 보내지 않으면 서식에 정해진 값을 씁니다
amtOpYnstring-N증명서에 금액을 표시할지 정하는 값으로 Y 나 N 을 보냅니다. 금액 항목이 있는 서식에서만 반영하고 그 밖의 서식에서는 쓰이지 않습니다. 보내지 않으면 서식에 정해진 값으로 신청합니다
bash
curl --request POST \
  --url 'https://api.xdata.kr/v1/jobs' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: real_test' \
  --header "Idempotency-Key: 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 이 더해져 담깁니다.
  • 접수번호(rcat_no)는 이 응답에 실리지 않을 수 있습니다. 내려받기에 쓸 접수번호는 증명서 신청 목록 조회의 행에서 읽습니다.
  • 서식이 cert_bugase_gwase_pyojun 또는 cert_pyojun_jaemu_jepyo 이면 cvaId 가 비어 올 수 있고, 그때 증명서 ID 는 증명서 신청 목록 조회의 같은 신청 행에서 cva_id 로 받습니다.
  • 서식이 cert_pyojun_jaemu_jepyo 이면 응답에 오는 rtnCvaId 는 증명서 ID 가 아닙니다.
순번변수명타입설명
outcomestring기관이 신청을 받았다는 판정입니다. 성공 응답에서는 항상 confirmed 입니다. 기관에 요청은 갔지만 접수됐는지 확인하지 못한 경우는 이 응답이 아니라 실패(PROVIDER_OUTCOME_UNCONFIRMED)로 옵니다.
actionstring실행한 액션의 ID 입니다.
cvaIdstring | null기관이 발번한 증명서 ID 입니다. 홈택스가 내려 주는 키 이름 그대로이고, 내려받기의 cva_id 로 보내며 서식에 따라 비어 올 수 있습니다.
json
// result.data - 값 자리에는 각 칸의 형식을 적었습니다 (실제 값이 아닙니다)
{
  "outcome": "<string>",
  "action": "<string>",
  "cvaId": "<string | null>"
}
순번오류 코드발생 조건
WRITE_CONFIRMATION_REQUIRED요청에 확인 토큰(confirmation_token)이 없으면 홈택스에 아무것도 보내지 않고 작업도 만들지 않은 채 이 오류로 끝납니다. error.message 는 cert_template 로 정한 서식의 확인 문구로 시작해 실행할 내용의 미리보기가 이어지고, error.confirmation_token 에 1회용 토큰이, error.preview 에 미리보기 객체가 함께 옵니다. 이 내용을 고객에게 그대로 보여 주고 확인을 받은 뒤, 같은 요청의 params.confirmation_token 에 응답의 error.confirmation_token 값을 넣어 다시 호출해 주세요. 토큰은 10분 안에 한 번만 쓸 수 있고, 확인한 요청 본문과 같은 본문에만 맞습니다. 확인값(confirm)은 보지 않으니 입력하지 않아도 됩니다.
WRITE_CONFIRMATION_INVALID토큰이 만료됐거나, 이미 썼거나, 다른 호출자나 다른 환경에서 받은 것이거나, 확인한 요청 본문과 달라졌으면 홈택스에 아무것도 보내지 않고 작업도 만들지 않은 채 이 오류로 끝납니다. error.message 는 「확인이 만료됐거나 확인한 내용과 달라졌습니다. 다시 확인해 주세요.」 입니다. 토큰 없이 다시 요청하면 새 토큰과 미리보기를 받습니다.
VALIDATION_INVALID_FIELDcert_template 이 신청할 수 있는 서식 9가지에 없으면 홈택스에 보내지 않고 이 오류로 끝납니다. error.message 는 「지원하지 않는 증명서 서식입니다: '보낸 값'」 으로 시작하고 고를 수 있는 서식 목록이 이어집니다.
AUTH_REQUIRED저장된 기관 세션이 없습니다. 같은 연동 계정으로 hometax.session.login 을 먼저 실행해 세션을 연 뒤 다시 보냅니다.
PROVIDER_SESSION_EXPIRED기관 세션이 만료됐습니다. 같은 연동 계정으로 hometax.session.login 을 다시 실행해 세션을 연 뒤 다시 보냅니다.
PROVIDER_BUSINESS_ERROR신청 전에 홈택스에서 납세자 주소를 조회하는 서식은, 홈택스가 그 조회를 거절하면(응답 봉투의 resultMsg.result 가 비어 있지도 S 도 아닌 값) 신청을 보내지 않고 이 오류로 끝납니다. error.message 는 홈택스가 알려 준 사유이고, 사유를 주지 않으면 「기관이 요청을 처리하지 않았습니다. 사유는 알려 주지 않았습니다. 입력값을 그대로 두고 잠시 후 다시 시도해 주세요.」 입니다.
PROVIDER_UNAVAILABLE홈택스가 서비스 중지 시간이라고 답한 경우입니다. 값이 틀린 것이 아니라 시간의 문제이고 요청은 처리되지 않았습니다. error.message 는 중지 시간을 읽었으면 그 시간을 함께 알리고, 읽지 못했으면 「지금은 홈택스 서비스 중지 시간이라 요청이 처리되지 않았습니다. 중지 시간이 지난 뒤 다시 요청해 주세요.」 입니다.
VALIDATION_INVALID_FIELD서식(cert_template)이 cert_bugase_gwase_pyojun 이고 연결된 홈택스 계정이 개인 계정이면 신청하기 전에 이 오류로 끝나며, 신청은 접수되지 않았고 자동으로 다시 시도하지 않습니다. error.message 는 「부가가치세 과세표준증명 발급은 사업자 계정으로만 신청할 수 있습니다. 사업자로 연결된 계정을 선택한 뒤 다시 시도해 주세요.」 입니다.
VALIDATION_INVALID_FIELD서식(cert_template)이 cert_hyupeop_sasil 이고 연결된 홈택스 계정이 사업자 계정이 아니면 신청하기 전에 이 오류로 끝나며, 신청은 접수되지 않았고 자동으로 다시 시도하지 않습니다. error.message 는 「휴업사실증명 발급은 사업자 계정으로만 신청할 수 있습니다. 사업자로 연결된 계정을 선택한 뒤 다시 시도해 주세요.」 입니다.
VALIDATION_INVALID_FIELD서식(cert_template)이 cert_hyupeop_sasil 이고 bsno 를 보내 연결된 계정의 사업자등록번호와 다른 번호를 지정하면 신청하기 전에 이 오류로 끝나며, 신청은 접수되지 않았고 자동으로 다시 시도하지 않습니다. error.message 는 「휴업사실증명 발급은 연결된 사업자 본인 것만 신청할 수 있습니다. bsno 를 비우고 다시 요청하거나, 그 사업자로 연결된 계정을 선택해 주세요.」 입니다. 이 서식은 연결된 사업자 본인 것만 신청하므로 bsno 는 보내지 않아도 됩니다.
VALIDATION_INVALID_FIELD서식(cert_template)이 cert_pyepeop_sasil 이고 연결된 홈택스 계정이 사업자 계정이 아니면 신청하기 전에 이 오류로 끝나며, 신청은 접수되지 않았고 자동으로 다시 시도하지 않습니다. error.message 는 「폐업사실증명 발급은 사업자 계정으로만 신청할 수 있습니다. 사업자로 연결된 계정을 선택한 뒤 다시 시도해 주세요.」 입니다.
VALIDATION_INVALID_FIELD서식(cert_template)이 cert_pyepeop_sasil 이고 bsno 를 보내 연결된 계정의 사업자등록번호와 다른 번호를 지정하면 신청하기 전에 이 오류로 끝나며, 신청은 접수되지 않았고 자동으로 다시 시도하지 않습니다. error.message 는 「폐업사실증명 발급은 연결된 사업자 본인 것만 신청할 수 있습니다. bsno 를 비우고 다시 요청하거나, 그 사업자로 연결된 계정을 선택해 주세요.」 입니다. 이 서식은 연결된 사업자 본인 것만 신청하므로 bsno 는 보내지 않아도 됩니다.
PROVIDER_BUSINESS_ERROR기관이 신청을 거절한 경우입니다(접수 전). error.message 는 「기관이 민원증명 신청을 거절했습니다.」 로 시작하고 기관이 알려 준 사유가 이어집니다. 신청이 접수되지 않았으므로 사유를 고쳐 다시 신청할 수 있습니다. 서식(cert_template)이 cert_sodeuk_geumaeg_jeungmyeong 이면 error.message 는 「기관이 민원증명 신청을 거절했습니다. 소득금액증명은 개인과 개인사업자만 신청할 수 있습니다. 법인 계정으로는 신청되지 않습니다.」 로 시작합니다.
PROVIDER_OUTCOME_UNCONFIRMED신청 요청은 기관에 갔지만 접수됐는지 확인하지 못한 경우입니다(응답에 접수 판정 resultMsg.result 도 발번된 증명서 ID 나 접수번호도 없습니다). 이 오류로 끝나며 자동으로 다시 시도하지 않습니다. error.message 는 「기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다. 홈택스 [민원증명 > 민원증명 발급신청 결과 조회]에서 방금 신청한 증명이 접수됐는지 확인해 주세요. 접수되지 않았을 때만 다시 신청하세요.」 입니다.

14. 증명서 내려받기hometax.certificate.download

MCP 도구 이름 hometax__certificate__download

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

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

신청해 둔 증명서를 발급용으로 출력해 PDF 파일로 받습니다. 출력할 때마다 신청한 발급 매수가 하나씩 줄어듭니다.

Request

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

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

[참고] 인증

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

[참고] 환경

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

[참고] 재시도

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

예시 : hometax

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

예시 : hometax.certificate.download

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

형식 : UUID v4

[참고] 자격증명 등록

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

[참고] 암호화

순번변수명타입길이필수설명
confirmation_tokenstring-N1회용 확인 토큰입니다. 처음에는 보내지 않습니다. 토큰 없이 부르면 기관에 아무것도 보내지 않고 작업도 만들지 않은 채 확인이 필요하다는 오류(WRITE_CONFIRMATION_REQUIRED)로 끝나고, 응답의 error.confirmation_token 에 토큰이 옵니다. error.message 의 안내를 사용자에게 보여 주고 동의를 받은 뒤 같은 요청에 이 토큰을 넣어 다시 부릅니다. 토큰은 10분 안에 한 번만 쓸 수 있고 처음 요청과 같은 본문, 같은 호출자, 같은 환경에서만 맞으며, 아니면 확인이 만료됐거나 내용이 달라졌다는 오류로 거절합니다. 출력하면 그 증명서의 발급 한도 1매가 사용되고 되돌릴 수 없으며, 더 필요하면 다시 신청해야 합니다
cva_idstring-Y내려받을 증명서의 ID(cva_id)입니다. 신청 결과의 cvaId 나 증명서 신청 목록 조회의 cva_id 를 그대로 보냅니다
rcat_nostring-Y내려받을 증명서의 접수번호(rcat_no)입니다. 자동 신청 결과의 list_info 안 rcat_no 나 증명서 신청 목록 조회의 rcat_no 를 그대로 보냅니다
rpt_pkg_pthstring-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_cva_isn_nostring-N내려받을 증명서의 발급번호입니다. 증명서 신청 목록 조회 결과 행의 cer_cva_isn_no 를 그대로 보내며, 이 번호는 증명서가 발급된 뒤에만 붙습니다. 보내지 않으면 목록에서 cva_id 로 이 증명서의 행을 찾아 채우고, 그래도 없으면 증명서가 아직 발급되지 않았거나 목록에서 먼저 조회해야 한다는 오류로 거절합니다
lnk_cl_cdstring-N증명서 신청 목록 조회 결과 행의 lnk_cl_cd(연계 구분)를 그대로 보냅니다. 보내지 않으면 목록을 조회할 때 그 행의 값으로 채우고, 목록을 조회하지 않았거나 값이 없으면 N 으로 보냅니다
mdl_txpr_ynstring-N증명서 신청 목록 조회 결과 행의 mdl_txpr_yn(모범납세자 여부)을 그대로 보냅니다. 보내지 않으면 목록을 조회할 때 그 행의 값으로 채우고, 목록을 조회하지 않았거나 값이 없으면 N 으로 보냅니다
cerp_isn_rqs_qtynumber-N증명서 신청 목록 조회 결과 행의 cerp_isn_rqs_qty(신청한 발급 매수)를 정수로 그대로 보냅니다. 보내지 않으면 목록에서 이 증명서의 행을 찾아 채웁니다
cerp_isn_actl_qtynumber-N증명서 신청 목록 조회 결과 행의 cerp_isn_actl_qty(이미 발급한 매수)를 정수로 그대로 보냅니다. 보내지 않으면 목록에서 채웁니다. 두 매수를 모두 알면 신청한 매수에서 발급한 매수를 뺀 남은 매수가 0 이하일 때 기관에 보내기 전에 발급 한도를 모두 사용했다는 오류로 거절합니다
strt_dtstring8-10N증명서 신청 목록에서 이 증명서의 행을 찾을 때 보는 기간의 시작일(신청일 기준)입니다. end_dt 와 함께 보내야 하며, 보내지 않으면 오늘로부터 3일 전부터 봅니다

형식 : YYYY-MM-DD 또는 YYYYMMDD

end_dtstring8-10N그 기간의 종료일입니다. strt_dt 와 함께 보내야 하며 strt_dt 보다 앞설 수 없습니다. 기간은 한 번에 최대 1개월이고, 보내지 않으면 오늘까지 봅니다

형식 : YYYY-MM-DD 또는 YYYYMMDD

page_numnumber-N증명서 신청 목록에서 볼 쪽 번호입니다. 1부터 세는 정수이고 보내지 않으면 1 입니다. 목록을 볼 때 1 이상의 정수가 아니면 홈택스에 묻지 않고 거절합니다
page_sizenumber-N증명서 신청 목록의 한 쪽에서 볼 건수입니다. 보내지 않으면 10 입니다. 조회 기간 안의 신청이 첫 쪽에 다 담기지 않아 이 증명서가 보이지 않을 때 키웁니다. 목록을 볼 때 1 이상의 정수가 아니면 홈택스에 묻지 않고 거절합니다
  • 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
bash
curl --request POST \
  --url 'https://api.xdata.kr/v1/jobs' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: real_test' \
  --header "Idempotency-Key: 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 에는 아래 칸만 있습니다.
순번변수명타입설명
outcomestring발급이 확인됐다는 판정입니다. 성공 응답에서는 항상 confirmed 입니다. 기관에 요청은 갔지만 결과를 확인하지 못한 경우는 이 응답이 아니라 실패(PROVIDER_OUTCOME_UNCONFIRMED)로 옵니다.
actionstring실행한 액션의 ID 입니다.
verdict_detailobject기관이 출력을 기록했다고 판정한 근거입니다. 기관의 출력 결과 보고 응답에서 resultMsg.result 의 값이 S 이면 확인으로 읽고, 그 값이 없거나 다르면 기관 신청 목록의 실제 발급 수량이 출력 전보다 늘었는지로 다시 확인합니다. 읽은 위치(verdict_path)와 읽은 값(verdict), 받아들이는 값(accepted_values) 같은 진단 칸이 담기고 칸 구성은 판정 경로에 따라 달라집니다.
cva_idstring출력한 증명서의 ID 입니다. 요청의 cva_id 와 같습니다.
rcat_nostring출력한 증명서의 접수번호입니다. 요청의 rcat_no 와 같습니다.
json
// result.data - 값 자리에는 각 칸의 형식을 적었습니다 (실제 값이 아닙니다)
{
  "outcome": "<string>",
  "action": "<string>",
  "verdict_detail": {},
  "cva_id": "<string>",
  "rcat_no": "<string>"
}
순번오류 코드발생 조건
WRITE_CONFIRMATION_REQUIRED요청에 확인 토큰(confirmation_token)이 없으면 홈택스에 아무것도 보내지 않고 작업도 만들지 않은 채 이 오류로 끝납니다. error.message 는 「증명서 출력은 홈택스에서 발급 한도를 소모하며 되돌릴 수 없습니다. 아래 내용을 사용자에게 보여주고 동의를 받으세요.」 로 시작해 실행할 내용의 미리보기가 이어지고, error.confirmation_token 에 1회용 토큰이, error.preview 에 미리보기 객체가 함께 옵니다. 이 내용을 고객에게 그대로 보여 주고 확인을 받은 뒤, 같은 요청의 params.confirmation_token 에 응답의 error.confirmation_token 값을 넣어 다시 호출해 주세요. 토큰은 10분 안에 한 번만 쓸 수 있고, 확인한 요청 본문과 같은 본문에만 맞습니다. 확인값(confirm)은 보지 않으니 입력하지 않아도 됩니다.
WRITE_CONFIRMATION_INVALID토큰이 만료됐거나, 이미 썼거나, 다른 호출자나 다른 환경에서 받은 것이거나, 확인한 요청 본문과 달라졌으면 홈택스에 아무것도 보내지 않고 작업도 만들지 않은 채 이 오류로 끝납니다. error.message 는 「확인이 만료됐거나 확인한 내용과 달라졌습니다. 다시 확인해 주세요.」 입니다. 토큰 없이 다시 요청하면 새 토큰과 미리보기를 받습니다.
AUTH_REQUIRED저장된 기관 세션이 없습니다. 같은 연동 계정으로 hometax.session.login 을 먼저 실행해 세션을 연 뒤 다시 보냅니다.
PROVIDER_SESSION_EXPIRED기관 세션이 만료됐습니다. 같은 연동 계정으로 hometax.session.login 을 다시 실행해 세션을 연 뒤 다시 보냅니다.
VALIDATION_INVALID_FIELDrpt_pkg_pth 를 보내지 않았고 증명서 목록에서도 보낸 cva_id 를 찾지 못하면 이 오류로 끝납니다. error.message 는 「cva_id='{cva_id}' 를 증명서 목록에서 찾지 못했습니다. 이 조회는 기본적으로 최근 3일·첫 페이지만 봅니다 — strt_dt/end_dt 로 기간을 넓히거나 page_size 를 키우거나, 이미 알고 있다면 rpt_pkg_pth 를 직접 입력해 주세요.」 입니다(중괄호 자리에는 보낸 cva_id 가 들어갑니다).
PROVIDER_BUSINESS_ERROR증명서 발급번호를 찾지 못했습니다. 증명서가 아직 발급되지 않았거나, 증명서 목록에서 해당 건을 먼저 조회해야 합니다.
PROVIDER_BUSINESS_ERROR이 증명서의 발급 한도를 이미 모두 사용했습니다. 더 필요하면 같은 증명서를 다시 신청한 뒤 내려받아 주세요.
PROVIDER_BUSINESS_ERROR증명서 출력을 시작하지 못했습니다. 기관이 보고서를 만들지 않았습니다. 증명서 목록에서 해당 건이 '처리완료' 이고 발급 가능한지 확인한 뒤 다시 시도해 주세요.
PROVIDER_BUSINESS_ERROR증명서 출력 준비 상태를 확인하지 못했습니다. 증명서 목록을 다시 조회해 남은 발급 수량을 확인한 뒤 내려받아 주세요.
PROVIDER_BUSINESS_ERROR기관이 증명서 보고서를 만들지 못했습니다. 기관 로그인이 만료됐을 수 있으니 다시 로그인한 뒤 시도해 주세요.
PROVIDER_BUSINESS_ERROR기관이 증명서 보고서를 아직 만들지 않았습니다. 증명서 목록을 다시 조회해 남은 발급 수량을 확인한 뒤 내려받아 주세요.
PROVIDER_BUSINESS_ERROR기관이 증명서 파일 대신 PDF 가 아닌 응답을 보냈습니다. 증명서 목록에서 해당 건이 '처리완료' 인지 확인한 뒤 다시 시도해 주세요.
PROVIDER_BUSINESS_ERROR기관이 증명서 출력 결과 기록을 거절하면 이 오류로 끝납니다. error.message 는 「기관이 증명서 출력 결과 기록을 거절했습니다.」 로 시작하고 기관이 알려 준 사유가 이어집니다.
PROVIDER_OUTCOME_UNCONFIRMED출력 요청은 기관에 갔지만 출력이 기록됐는지 확인하지 못한 경우입니다. 파일은 돌려주지 않고 이 오류로 끝나며 자동으로 다시 시도하지 않습니다. error.message 는 「기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다. 홈택스 민원증명 발급신청 결과 조회 화면에서 그 증명의 발급 수량을 확인해 주세요. 발급 수량이 신청 수량만큼 찼으면 이미 발급된 것이니 같은 증명서를 다시 신청한 뒤 내려받으세요. 발급 수량이 그대로이면 같은 건으로 다시 내려받으세요.」 입니다.

15. 증명서 서식 목록 조회hometax.certificate.list_templates

MCP 도구 이름 hometax__certificate__list_templates

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

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

증명서 신청에서 고를 수 있는 서식 아홉 가지의 이름과 서식 값을 돌려받습니다.

  • 이 API 는 기관 연동과 기관 로그인이 필요 없습니다. 기관 자격증명을 등록하지 않아도 호출할 수 있고, account_link_id 는 보내지 않습니다.

Request

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

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

[참고] 인증

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

[참고] 환경

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

[참고] 재시도

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

예시 : hometax

actionstringY호출할 작업입니다.
  • hometax.certificate.list_templates이 API 고정값 (기본값)

예시 : hometax.certificate.list_templates

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

[참고] 암호화

추가 파라미터가 없습니다. params 는 {} 로 보냅니다.

bash
curl --request POST \
  --url 'https://api.xdata.kr/v1/jobs' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: real_test' \
  --header "Idempotency-Key: list_templates-$(date +%s)-$RANDOM" \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "hometax",
  "action": "hometax.certificate.list_templates",
  "params": {}
}'

Response

순번변수명타입설명
successboolean서식 목록을 돌려줬다는 표지입니다. 항상 true 입니다.
templatesobject신청할 수 있는 증명서 서식 목록입니다. 키는 hometax.certificate.apply_auto 와 hometax.certificate.apply_with_template 의 cert_template 에 보내는 서식 값이고, 값은 증명서 이름입니다.
templates.cert_gukse_wannapstring국세완납증명 서식입니다. cert_template 에 cert_gukse_wannap 를 보내면 이 증명서를 신청합니다.
templates.cert_napse_sasilstring납세사실증명 서식입니다. cert_template 에 cert_napse_sasil 를 보내면 이 증명서를 신청합니다.
templates.cert_bugase_gwase_pyojunstring부가가치세과세표준증명 서식입니다. cert_template 에 cert_bugase_gwase_pyojun 를 보내면 이 증명서를 신청합니다.
templates.cert_saeopja_deungrok_jeungmyeongstring사업자등록증명 서식입니다. cert_template 에 cert_saeopja_deungrok_jeungmyeong 를 보내면 이 증명서를 신청합니다.
templates.cert_hyupeop_sasilstring휴업사실증명 서식입니다. cert_template 에 cert_hyupeop_sasil 를 보내면 이 증명서를 신청합니다.
templates.cert_pyojun_jaemu_jepyostring표준재무제표증명 서식입니다. cert_template 에 cert_pyojun_jaemu_jepyo 를 보내면 이 증명서를 신청합니다.
templates.cert_pyepeop_sasilstring폐업사실증명 서식입니다. cert_template 에 cert_pyepeop_sasil 를 보내면 이 증명서를 신청합니다.
templates.cert_saeopja_jaebalgupstring사업자등록증 재발급 서식입니다. cert_template 에 cert_saeopja_jaebalgup 를 보내면 이 증명서를 신청합니다.
templates.cert_sodeuk_geumaeg_jeungmyeongstring소득금액증명 서식입니다. cert_template 에 cert_sodeuk_geumaeg_jeungmyeong 를 보내면 이 증명서를 신청합니다.
countnumbertemplates 에 담긴 서식의 수입니다.
json
// 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>"
}