증명서 발급 - 정부24

이 쪽의 모든 작업에 해당

이 작업은 샌드박스를 지원하지 않습니다. 샌드박스로 보내면 거절되므로 데모나 정식 환경으로 호출합니다.

1. 정부24 사업자등록증명(법인) 발급gov24.business_registration_certificate.issue

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

데모입니다. 실제 기관에 접속하며 가입한 날부터 30일 동안 사용자 기준 하루 10 사용 토큰까지 호출할 수 있습니다(KST 0시 초기화).

법인의 사업자등록증명 발급을 신청하고 발급된 증명서를 다운로드 링크로 받습니다.

Request

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

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

변수명	타입	필수	설명
confirm	boolean	Y	실제로 신청한다는 확인값입니다. 빠지거나 false 처럼 참이 아닌 값이면 정부24에 아무것도 보내지 않고 무엇을 신청할지 보여 주는 미리보기와 함께 확인이 필요하다고 답하므로, 사용자 동의를 받은 뒤 같은 요청에 true 를 넣어 다시 호출합니다. 1 이나 yes, on 처럼 true 로 읽히는 값도 바로 신청되므로 동의를 받기 전에는 이 칸을 보내지 않습니다. 신청을 취소하는 기능은 없습니다
member_type	string	N	신청하는 회원 유형입니다. 법인 회원인 corporate 만 받으며, 보내지 않으면 로그인한 법인 회원 명의로 신청합니다 예시 : corporate
certificate_purpose	string	Y	증명서 사용용도 코드입니다. 앞뒤 공백 없는 두 글자 코드여야 하고, 신청할 때 정부24 신청 화면이 내놓는 사용용도 목록에 있는 코드만 받으며 없으면 입력 오류로 거절합니다
receive_method	string	Y	수령 방법 코드입니다. 0524 - 온라인발급(본인출력) 하나만 받습니다
privacy_disclosure	string	N	신청서 납세자 항목의 개인정보 공개 여부입니다. Y 또는 N 이며 보내지 않으면 N 으로 신청합니다 예시 : N
pre_consent	boolean	Y	신청 전 동의 확인값입니다. 불리언 true 여야 하며 그 밖의 값은 거절합니다

bash

curl --request POST \
  --url 'https://api.xdata.kr/v1/jobs' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: real_test' \
  --header 'Idempotency-Key: demo-issue-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "gov24",
  "action": "gov24.business_registration_certificate.issue",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "confirm": "<필수: boolean>",
    "member_type": "corporate",
    "certificate_purpose": "<필수>",
    "receive_method": "<필수>",
    "privacy_disclosure": "N",
    "pre_consent": "<필수: boolean>"
  }
}'

Response

아래 표의 칸은 작업이 SUCCEEDED 가 된 뒤 GET /v1/jobs/{job_id}/result 의 result.data 에 오고, 응답 예시는 작업을 제출했을 때(POST /v1/jobs)의 응답입니다.
발급한 증명서 PDF 는 result.data 가 아니라 result.artifacts 로 옵니다. result.data 에는 아래 두 칸만 있습니다.

순번	변수명	타입	설명
	outcome	string	발급이 확인됐다는 판정입니다. 성공 응답에서는 항상 confirmed 입니다. 기관에 요청은 갔지만 결과를 확인하지 못한 경우는 이 응답이 아니라 실패(PROVIDER_OUTCOME_UNCONFIRMED)로 옵니다.
	action	string	실행한 액션의 ID 입니다.

json

{
    "job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
    "status": "QUEUED",
    "env_scope": "real_test",
    "provider": "gov24",
    "action": "gov24.business_registration_certificate.issue",
    "submitted_at": "2026-05-27T12:34:56+09:00"
}

순번	오류 코드	발생 조건
	VALIDATION_MISSING_FIELD	확인값(confirm)이 빠지거나 참이 아니면 기관에 아무것도 보내지 않고 이 오류로 끝납니다. 사업자등록증명 발급 신청은 취소할 수 없어 신청 전 확인이 필요합니다. 같은 요청에 confirm=true 만 추가해 다시 호출하면 신청합니다. 사용자 동의 없이 자동으로 채우지 마세요. error.message 에 신청 내용의 미리보기와 되돌릴 수 없다는 안내가 함께 옵니다.
	PROVIDER_OUTCOME_UNCONFIRMED	요청은 기관에 전송됐지만 처리 결과를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다. 사업자등록증명 신청이 접수됐을 수 있습니다. 다시 실행하지 말고 정부24 서비스 신청 내역에서 신청과 발급 문서를 확인해 주세요.
	PROVIDER_BUSINESS_ERROR	기관이 신청을 거절했습니다. error.message 에 기관이 알려 준 거절 사유가 옵니다.
	AUTH_REQUIRED	저장된 기관 세션이 없습니다. 같은 연동 계정으로 gov24.session.login 을 먼저 실행해 세션을 연 뒤 다시 보냅니다.
	VALIDATION_INVALID_FIELD	사업자등록증명 발급 요청 항목을 확인해 주세요. 법인 본인출력만 지원합니다.

2. 정부24 지방세 납세증명서(법인) 발급gov24.local_tax_certificate.issue

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

데모입니다. 실제 기관에 접속하며 가입한 날부터 30일 동안 사용자 기준 하루 10 사용 토큰까지 호출할 수 있습니다(KST 0시 초기화).

법인의 지방세 납세증명서 발급을 신청하고 발급된 증명서를 다운로드 링크로 받습니다.

Request

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

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

변수명	타입	필수	설명
confirm	boolean	Y	실제로 신청한다는 확인값입니다. 빠지거나 false 처럼 참이 아닌 값이면 정부24에 아무것도 보내지 않고 무엇을 신청할지 보여 주는 미리보기와 함께 확인이 필요하다고 답하므로, 사용자 동의를 받은 뒤 같은 요청에 true 를 넣어 다시 호출합니다. 1 이나 yes, on 처럼 true 로 읽히는 값도 바로 신청되므로 동의를 받기 전에는 이 칸을 보내지 않습니다. 신청을 취소하는 기능은 없고, 다시 실행하면 민원이 한 번 더 신청됩니다
member_type	string	N	신청하는 회원 유형입니다. 법인 회원인 corporate 만 받으며, 보내지 않으면 로그인한 법인 회원 명의로 신청합니다 예시 : corporate
phone	object	Y	신청서에 적을 연락처 전화번호를 세 칸으로 나눈 객체이며 세 칸 모두 문자열로 보냅니다. area_code(필수)는 010, 011, 016, 017, 018, 019, 02 이거나 0 다음에 3에서 9 사이 숫자가 오는 세 자리 번호(예: 031, 070)이고, exchange(필수)는 숫자 3자리나 4자리, subscriber(필수)는 숫자 4자리이며 이 세 칸 밖의 칸은 받지 않습니다
business_address	object	Y	신청서에 적을 영업소 주소로, 정부24 주소 찾기 결과에서 한 곳을 고르는 객체입니다. search(필수)는 keyword(필수, 검색어)와 page_no(선택, 결과를 10건씩 나눈 쪽 번호, 1 이상, 기본 1)이고, selection_hint(필수)는 주소 행의 roadNmForm(도로명주소), lawAreaCd(법정동코드), pubAreaCd, zipcd(우편번호) 중 적어도 하나와 처리 기관 행을 고르는 deptIncCd, fullNmForm(선택)이며, detail_line(필수)은 상세주소입니다. 보낸 값과 글자 그대로 같은 행이 정확히 하나여야 하고(처리 기관 값이 없으면 처리 기관이 하나뿐일 때만) 없거나 둘 이상이면 신청을 보내지 않으며, 글자 값은 공백만이거나 제어 문자가 있으면 거절합니다
certificate_purpose	string	Y	증명서 사용목적 코드입니다. 01 - 대금수령, 02 - 해외이주, 99 - 기타 중 하나이며, 01 이면 payment_recipient 를, 99 이면 other_purpose_text 를 함께 보내야 합니다
payment_recipient	string	N	대금 지급자입니다. certificate_purpose 가 01 일 때만 필수로 받고 다른 목적에서 보내면 거절하며, 공백만이거나 제어 문자가 든 값과 null 은 받지 않습니다
other_purpose_text	string	N	기타 사용목적 내용입니다. certificate_purpose 가 99 일 때만 필수로 받고 다른 목적에서 보내면 거절하며, 공백만이거나 제어 문자가 든 값과 null 은 받지 않습니다
receive_method	string	Y	수령 방법 코드입니다. 0533 - 온라인발급(본인출력) 하나만 받습니다
pre_consent	boolean	Y	신청 전 동의 확인값입니다. 불리언 true 여야 하며 그 밖의 값은 거절하고, true 로 보내면 신청서의 동의 항목을 모두 체크해 신청합니다

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: demo-issue-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "gov24",
  "action": "gov24.local_tax_certificate.issue",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "confirm": "<필수: boolean>",
    "member_type": "corporate",
    "phone": "<필수: object>",
    "business_address": "<필수: object>",
    "certificate_purpose": "<필수>",
    "receive_method": "<필수>",
    "pre_consent": "<필수: boolean>"
  }
}'

Response

아래 표의 칸은 작업이 SUCCEEDED 가 된 뒤 GET /v1/jobs/{job_id}/result 의 result.data 에 오고, 응답 예시는 작업을 제출했을 때(POST /v1/jobs)의 응답입니다.
발급한 증명서 PDF 는 result.data 가 아니라 result.artifacts 로 옵니다. result.data 에는 아래 두 칸만 있습니다.

순번	변수명	타입	설명
	outcome	string	발급이 확인됐다는 판정입니다. 성공 응답에서는 항상 confirmed 입니다. 기관에 요청은 갔지만 결과를 확인하지 못한 경우는 이 응답이 아니라 실패(PROVIDER_OUTCOME_UNCONFIRMED)로 옵니다.
	action	string	실행한 액션의 ID 입니다.

json

{
    "job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
    "status": "QUEUED",
    "env_scope": "real_test",
    "provider": "gov24",
    "action": "gov24.local_tax_certificate.issue",
    "submitted_at": "2026-05-27T12:34:56+09:00"
}

순번	오류 코드	발생 조건
	VALIDATION_MISSING_FIELD	확인값(confirm)이 빠지거나 참이 아니면 기관에 아무것도 보내지 않고 이 오류로 끝납니다. 지방세 납세증명서 발급 신청은 취소할 수 없어 신청 전 확인이 필요합니다. 아래 내용을 사용자에게 보여주고 동의를 받은 뒤 confirm=true 로 다시 호출해 주세요. 같은 요청에 confirm=true 만 추가해 다시 호출하면 신청합니다. 사용자 동의 없이 자동으로 채우지 마세요. error.message 에 신청 내용의 미리보기와 되돌릴 수 없다는 안내가 함께 옵니다.
	PROVIDER_OUTCOME_UNCONFIRMED	요청은 기관에 전송됐지만 처리 결과를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다. 지방세 납세증명서 신청이 이미 접수됐을 수 있습니다. 바로 다시 실행하지 말고, 정부24 마이페이지의 서비스 신청 내역에서 신청과 발급 문서를 확인해 주세요.
	PROVIDER_BUSINESS_ERROR	기관이 신청을 거절했습니다. error.message 에 기관이 알려 준 거절 사유가 옵니다.
	AUTH_REQUIRED	저장된 기관 세션이 없습니다. 같은 연동 계정으로 gov24.session.login 을 먼저 실행해 세션을 연 뒤 다시 보냅니다.
	VALIDATION_INVALID_FIELD	지방세 납세증명서 발급 요청값이 올바르지 않습니다.