증명서 발급 API로 사업자등록증명, 납세증명서, 법인등기 PDF 받기

보안문자 입력 없이 요청부터 PDF 수령까지, 이용 조건과 실패 원인을 함께 정리했습니다
진태양's avatar
Nov 16, 2026
증명서 발급 API로 사업자등록증명, 납세증명서, 법인등기 PDF 받기

증명서 발급 API를 쓰면 사업자등록증명, 납세증명서, 부가가치세 과세표준증명 같은 홈택스 국세 증명 서류와 법인등기사항전부증명서를 요청 한 번으로 받고, 결과 조회 응답의 주소에서 원본 PDF를 내려받습니다. 볼타 서류 발급 API는 POST /v1/documentIssuances로 접수하고 issuanceKey로 상태를 확인하는 비동기 방식입니다. 요금은 홈택스 서류 한 건 500포인트, 법인등기 열람용 2,000포인트, 제출용 3,000포인트이며 발급에 실패한 건은 차감하지 않습니다.

이 글은 2026년 11월 볼타 개발자 문서 기준으로 정리했습니다. 홈택스 화면에서 직접 발급하는 방법은 각 서류 가이드에 따로 있으니, 여기서는 반복 발급을 내부 시스템에 연결하려는 개발자와 운영 담당자를 위해 API 흐름만 다룹니다.

사람이 하던 서류 발급을 API로 옮기는 이유

입찰 서류 제출, 대금 청구, 거래처 심사, 관공서나 은행 제출처럼 증명서가 필요한 순간은 자주 돌아옵니다. 그때마다 담당자는 홈택스에 로그인하고 보안문자를 입력합니다. 받은 PDF는 다시 메일이나 사내 시스템으로 옮겨야 합니다. 한 번이면 몇 분이지만, 요청이 몰리는 달에는 이 반복이 고스란히 사람의 시간으로 쌓입니다.

볼타 서류 발급 API는 이 과정을 요청과 응답으로 바꿉니다. 내 서비스가 서류 종류를 골라 요청하면 볼타가 인증서 처리와 기관 연결을 맡고, 발급이 끝나면 원본 PDF 주소를 돌려줍니다. 보안문자를 기다리는 단계가 없어서 입찰 준비 화면이나 거래처 심사 워크플로에 발급 버튼을 바로 붙일 수 있습니다.

가끔 한두 장만 필요하다면 API보다 홈택스 화면이 빠릅니다. 직접 발급 절차는 국세 납세증명서(완납증명서) 발급 가이드와 부가가치세 과세표준증명원 발급 가이드에서 확인하세요.

증명서 발급 API로 받을 수 있는 서류 7종과 입력값

요청 본문의 document.type으로 서류를 고릅니다. 서류마다 필요한 입력값이 다르고, 빠뜨리면 API가 400 INVALID_REQUEST를 반환합니다. 홈택스 서류는 다섯 종류, 법인등기는 열람용과 제출용 두 종류입니다.

document.type

서류

입력값

한 건 요금

BUSINESS_REGISTRATION_PROOF

사업자등록증명

language: KO 또는 EN

500포인트

BUSINESS_REGISTRATION_CERTIFICATE

사업자등록증 재발급

reason: 재발급 사유, 10자 이내

500포인트

TAX_PAYMENT_CERTIFICATE

납세증명서

purpose: PAYMENT_RECEIPT(대금수령) 또는 OTHER(기타)

500포인트

VAT_TAX_BASE_PROOF

부가가치세 과세표준증명

from, to: 과세기간 YYYY-MM

500포인트

STANDARD_FINANCIAL_STATEMENT_PROOF

표준재무제표증명

fiscalYearEnd: 사업연도 종료 연월 YYYY-MM

500포인트

CORPORATE_REGISTRY_VIEW

법인등기사항전부증명서(열람용)

corporationNumber: 법인등록번호 13자리, cancelledEntries: INCLUDE 또는 EXCLUDE

2,000포인트

CORPORATE_REGISTRY_ISSUANCE

법인등기사항전부증명서(제출용)

corporationNumber, cancelledEntries(열람용과 같음)

3,000포인트

서류별로 알아 둘 점은 다음과 같습니다.

  • 사업자등록증명: 국문과 영문을 고릅니다. 영문은 홈택스에 등록된 사업자 영문 정보로 발급하므로, 표기를 바꾸려면 홈택스에서 영문 정보를 먼저 고치세요. 영문 발급은 이 서류만 지원합니다.

  • 사업자등록증 재발급: reason 값이 사업자등록증에 그대로 인쇄됩니다. "분실"처럼 실제 사유를 적으세요.

  • 부가가치세 과세표준증명: from은 01월이나 07월, to는 06월이나 12월로 넣습니다. 최대 5개 연도를 한 번에 발급합니다.

  • 표준재무제표증명: 12월 결산 법인의 2025 사업연도라면 2025-12를 넣습니다. 개인사업자는 연도만 봅니다.

  • 법인등기사항전부증명서: 인터넷등기소에서 발급합니다. 열람용은 내용 확인용이고, 관공서나 은행에 낼 서류라면 제출용을 요청하세요.

서류 발급 자동화 전에 확인할 이용 조건

홈택스 서류와 법인등기는 발급 대상과 준비물이 다릅니다. 연동 범위를 정하기 전에 아래 조건부터 맞춰 보세요.

  • 홈택스 서류 5종은 API 키가 속한 자사 사업자의 서류만 발급합니다. 거래처의 사업자등록증명을 대신 받는 용도로는 쓸 수 없습니다.

  • 홈택스 서류를 받으려면 볼타 대시보드에 공동인증서를 등록하세요. 미등록이거나 만료됐으면 API가 409 CERTIFICATE_REQUIRED를 반환합니다. 사업자 범용 공동인증서가 없다면 볼타 사업자 인증서 발급 안내에서 제휴가를 확인하세요.

  • 법인등기는 corporationNumber에 넣은 법인의 등기부를 발급합니다. 공동인증서가 필요 없고, 법인등록번호만 알면 다른 법인의 등기부도 받습니다.

  • 법인등기는 주식회사, 유한회사, 사단법인, 재단법인, 협동조합 등 문서에 나열된 종류를 지원합니다. 외국회사의 국내 영업소는 지원하지 않습니다.

요청 가능 시간도 서류마다 다릅니다. 시간 밖에 요청하면 API가 409 OUTSIDE_SERVICE_HOURS를 반환하고 포인트를 예약하지 않습니다.

서류

요청 가능 시간(한국 시간)

납세증명서

매일 06:00~22:00

법인등기사항전부증명서

인터넷등기소 점검 시간을 뺀 24시간

그 밖의 홈택스 서류

24시간

볼타는 인터넷등기소 점검 시작 10분 전부터 법인등기 요청을 받지 않습니다. 이미 접수한 요청은 점검이 끝난 뒤 이어서 발급합니다.

요청부터 원본 PDF 수령까지 흐름

빈 캡슐이 기계와 확인 지점을 지나 밀봉된 채 받침대로 나오는 컨베이어 장면
요청을 접수하고 상태를 확인한 뒤 원본 PDF를 받는 흐름을 그렸습니다.

흐름은 네 단계입니다. 서류 종류를 고르고, 발급을 요청하고, 결과를 조회한 뒤, 원본 PDF를 내려받습니다. 인증 헤더는 API 키 뒤에 콜론을 붙여 Base64로 인코딩한 값을 넣으세요. 개발 중에는 test_로 시작하는 테스트 키를 씁니다.

curl -X POST https://xapi.bolta.io/v1/documentIssuances \
  -H "Authorization: Basic {BASE64(API_KEY:)}" \
  -H "Bolta-Client-Reference-Id: {요청마다 새 관리번호}" \
  -H "Content-Type: application/json" \
  -d '{
    "document": { "type": "BUSINESS_REGISTRATION_PROOF", "language": "KO" }
  }'

Bolta-Client-Reference-Id는 필수 헤더이며 1~255자로 넣습니다. 응답을 받지 못했다면 같은 값과 같은 본문으로 다시 보내세요. API가 새로 발급하지 않고 기존 요청을 돌려줍니다. 같은 값에 다른 본문을 보내면 409 IDEMPOTENCY_CONFLICT가 납니다.

접수되면 API가 202 Accepted와 issuanceKey를 반환합니다. 이 키로 결과를 조회하세요.

curl https://xapi.bolta.io/v1/documentIssuances/{issuanceKey} \
  -H "Authorization: Basic {BASE64(API_KEY:)}"

홈택스 서류는 보통 30초 안에 끝나므로 5~10초 간격으로 조회하면 됩니다. 법인등기는 몇 분이 걸리고 요청이 몰리면 더 늦어집니다. 같은 사업자의 홈택스 서류를 여러 건 보내면 뒤 요청은 앞 요청이 끝난 뒤 시작합니다.

status

뜻

할 일

ACCEPTED

접수, 기관 신청 전

대기

SUBMITTED

기관 신청 완료, 결과 대기

대기

COMPLETED

발급 완료

downloadUrl로 PDF 수령

FAILED

발급 실패

원인 확인 후 새 관리번호로 재요청

ACTION_REQUIRED

볼타가 결과 확인 중

같은 서류 재요청 금지

COMPLETED 응답에는 발급일 issuedOn, 보관 만료 시각 retentionExpiresAt, PDF 주소 downloadUrl, 주소 만료 시각 downloadUrlExpiresAt이 채워집니다. 주소는 홈택스 서류 5분, 법인등기 1분 동안만 유효합니다. 만료됐다면 다시 조회해 새 주소를 받으세요. 볼타는 발급 후 30일 동안 파일을 보관하고, 그 뒤에는 downloadUrl이 null입니다.

내려받은 파일 이름은 서류명, 사업자등록번호, 발급일을 이어 붙인 형식이고, 법인등기는 사업자등록번호 자리에 법인등록번호가 들어갑니다. 같은 날 같은 서류를 여러 번 받으면 이름이 겹치니, 파일을 따로 저장할 때는 issuanceKey를 함께 기록하세요.

발급 실패와 서류별 발급 조건

API가 요청을 받아도 기관이 발급하지 않으면 상태가 FAILED로 끝납니다. 이때 포인트는 차감되지 않습니다. 자주 만나는 원인은 서류 자체의 발급 조건입니다.

  • 납세증명서: 국세 체납이 있으면 홈택스가 발급하지 않습니다. 유효기간은 발급일부터 30일입니다(국세징수법 시행령 제96조). 발급일 현재 납부고지된 국세가 있으면 유효기간을 그 국세의 지정납부기한까지로 정할 수 있고, 이때는 증명서에 사유와 유효기간이 적힙니다.

  • 표준재무제표증명: 법인세나 종합소득세 신고를 마친 사업연도만 발급됩니다. 끝나지 않은 사업연도를 넣으면 API가 400 PERIOD_NOT_CLOSED를 반환하고, 끝났지만 신고 전이면 FAILED로 끝납니다.

  • 영문 사업자등록증명: 홈택스에 영문 정보가 없거나 형식이 맞지 않으면 FAILED입니다.

  • 법인등기: 인터넷등기소에서 찾을 수 없는 번호, 청산종결이나 본점 이전으로 폐쇄된 등기부, 지원하지 않는 법인 종류는 실패합니다. 지점이 있거나 상호를 바꾼 법인은 본점의 현재 등기부로 발급합니다.

  • 홈택스 점검: 홈택스가 점검 등으로 신청을 받지 않으면 FAILED로 끝납니다. 잠시 뒤 다시 요청하세요.

접수 단계에서 막히는 경우도 있습니다. 처리 중인 요청이 5건이면 429 TOO_MANY_IN_FLIGHT가 오고, 같은 법인, 같은 등기 서류, 같은 말소사항 옵션(cancelledEntries)을 다른 요청이 발급하는 중이면 409 TARGET_BUSY가 옵니다. 대기 시간이 1시간을 넘긴 홈택스 요청은 FAILED로 바뀝니다. 재시도 로직을 짤 때는 FAILED와 ACTION_REQUIRED를 반드시 구분하세요. ACTION_REQUIRED는 볼타가 결과를 확인하는 상태라 같은 서류를 다시 요청하면 안 됩니다. 확인이 끝나면 COMPLETED나 FAILED로 바뀌니 조회만 이어 가세요.

요금과 테스트 키로 연동 검증하기

볼타 API는 사전 충전 포인트 차감 방식이고, 1포인트는 1원입니다. 포인트는 개발자센터에서 충전합니다. 서류 발급은 성공한 건에만 요금을 매기므로, 체납이나 미신고로 실패한 요청에는 비용이 들지 않습니다. 잔액이 부족하면 402 PAYMENT_REQUIRED, 진행 중인 다른 요청이 포인트를 예약해 지금 쓸 금액이 모자라면 409 AVAILABLE_POINTS_INSUFFICIENT가 옵니다.

테스트 키는 기관에 신청하지 않고 포인트도 차감하지 않습니다. 홈택스 서류는 항상 바로 COMPLETED로 끝나고, 조회 응답에 샘플 PDF 주소가 담깁니다. 법인등기는 문서가 지정한 테스트 법인등록번호 두 개로 완료와 실패를 각각 재현합니다. 그 밖의 번호는 400 INVALID_REQUEST를 반환합니다.

  1. 테스트 키로 서류마다 한 번씩 요청해 접수 응답과 issuanceKey 저장을 확인합니다.

  2. 조회 루프가 COMPLETED에서 멈추고 PDF를 내려받는지 봅니다.

  3. 5분 뒤 다시 조회해 만료된 주소를 새 주소로 바꾸는지 확인합니다.

  4. 법인등기 실패 번호로 FAILED 처리와 재요청 화면을 점검합니다.

  5. 라이브 키로 바꾸기 전에 포인트를 충전하고 공동인증서 등록을 마칩니다.

엔드포인트별 상세 명세와 오류 코드 전체 목록은 볼타 서류 발급 API 문서에 있습니다. 도입 조건과 연동용 프롬프트는 볼타 서류 발급 API 소개 페이지에서 확인하세요.

자주 묻는 질문

거래처의 사업자등록증명도 API로 받을 수 있나요?

받을 수 없습니다. 홈택스 서류는 API 키가 속한 자사 사업자의 서류만 발급합니다. 거래처가 법인이라면 법인등록번호로 법인등기사항전부증명서를 받으세요. 개인사업자 거래처의 서류는 이 API로 받을 수 없습니다.

법인등기부등본 API는 공동인증서가 필요한가요?

필요 없습니다. 법인등기사항전부증명서는 법인등록번호와 말소사항 포함 여부만 넣으면 됩니다. 열람용은 2,000포인트, 제출용은 3,000포인트를 차감합니다.

발급에 실패해도 포인트가 나가나요?

나가지 않습니다. 상태가 FAILED로 끝나면 차감하지 않고, 테스트 키 호출도 결과와 관계없이 무료입니다. 다시 요청할 때는 새 Bolta-Client-Reference-Id를 쓰세요.

납세증명서를 밤에 요청하면 어떻게 되나요?

납세증명서는 매일 06:00부터 22:00(한국 시간)까지만 요청할 수 있습니다. 그 밖의 시간에는 API가 409 OUTSIDE_SERVICE_HOURS를 반환하고 포인트를 예약하지 않으니, 요청 가능 시간에 다시 보내세요.

Share article