서류 발급

무엇을 발급하나요

홈택스 국세 증명 서류를 발급하고 원본 PDF를 내려받습니다. 발급은 요청 즉시 끝나지 않습니다. 접수 응답의 issuanceKey로 결과를 조회하세요.

경로	용도
`POST /v1/documentIssuances`	서류 발급 요청
`GET /v1/documentIssuances/{issuanceKey}`	발급 결과 조회

이용 조건

API 키가 속한 사업자의 서류만 발급합니다.
볼타 대시보드에 공동인증서를 등록하세요.
서류 한 건에 500포인트를 차감합니다. 발급에 실패하면 차감하지 않습니다.

지원 서류

`document.type`	서류	입력
`BUSINESS_REGISTRATION_PROOF`	사업자등록증명	`language`: `KO`, `EN`
`BUSINESS_REGISTRATION_CERTIFICATE`	사업자등록증 재발급	`reason`: 재발급 사유, 10자 이내
`TAX_PAYMENT_CERTIFICATE`	납세증명서	`purpose`: `PAYMENT_RECEIPT`(대금수령), `OTHER`(기타)
`VAT_TAX_BASE_PROOF`	부가가치세 과세표준증명	`from`, `to`: 과세기간 `YYYY-MM`
`STANDARD_FINANCIAL_STATEMENT_PROOF`	표준재무제표증명	`fiscalYearEnd`: 사업연도 종료 연월 `YYYY-MM`

사업자등록증 재발급: reason은 사업자등록증에 그대로 인쇄됩니다. 실제 사유를 적으세요(예: 분실). API가 앞뒤 공백을 제거합니다. 비었거나 10자를 넘거나 제어 문자가 있으면 400 INVALID_REQUEST를 반환합니다.
영문 사업자등록증명: 홈택스에 등록된 사업자 영문 정보로 발급합니다. 영문 정보가 없거나 형식이 맞지 않으면 FAILED로 끝나고 포인트를 차감하지 않습니다. 표기를 바꾸려면 홈택스에서 영문 정보를 먼저 수정하세요.
납세증명서: 국세 체납이 있으면 홈택스가 발급하지 않습니다. 해외이주용은 지원하지 않습니다. 유효기간은 발급일부터 30일입니다.
부가가치세 과세표준증명: from은 01월 또는 07월, to는 06월 또는 12월로 입력하세요. from은 to보다 늦을 수 없으며, 어기면 400 INVALID_REQUEST를 반환합니다. 최대 5개 연도까지 한 번에 발급합니다.
표준재무제표증명: 12월 결산 법인의 2025 사업연도라면 2025-12를 입력하세요. 개인사업자는 연도만 봅니다. 법인세나 종합소득세 신고를 마친 사업연도만 발급됩니다.

발급 요청

curl -X POST https://xapi.bolta.io/v1/documentIssuances \
  -H "Authorization: Basic {apiKey}" \
  -H "Bolta-Client-Reference-Id: order-20260919-001" \
  -H "Content-Type: application/json" \
  -d '{
    "businessRegistrationNumber": "1234567890",
    "document": { "type": "BUSINESS_REGISTRATION_PROOF", "language": "KO" }
  }'

Bolta-Client-Reference-Id에는 요청마다 새 값(1~255자)을 넣으세요. 응답을 받지 못했다면 같은 값과 본문으로 다시 보내세요. API가 기존 요청을 돌려줍니다. API는 202 Accepted와 아래 응답을 반환합니다.

{
  "issuanceKey": "00000000-0000-4000-8000-000000000001",
  "clientReferenceId": "order-20260919-001",
  "type": "BUSINESS_REGISTRATION_PROOF",
  "language": "KO",
  "status": "ACCEPTED",
  "requestedAt": "2026-09-19T03:00:00Z",
  "issuedOn": null,
  "retentionExpiresAt": null,
  "downloadUrl": null,
  "downloadUrlExpiresAt": null
}

응답의 language는 발급한 서류의 언어입니다. 사업자등록증명이 아닌 서류는 항상 KO입니다.

결과 조회

curl https://xapi.bolta.io/v1/documentIssuances/{issuanceKey} \
  -H "Authorization: Basic {apiKey}"

보통 30초 안에 끝납니다. 5~10초 간격으로 조회하세요. 볼타는 한 사업자의 요청을 한 건씩 차례로 처리합니다. 여러 건을 한꺼번에 보내면 뒤 요청은 앞 요청이 끝난 뒤 시작합니다.

`status`	뜻	할 일
`ACCEPTED`	접수	기다리세요
`SUBMITTED`	홈택스 신청 완료, 결과 대기	기다리세요
`COMPLETED`	발급 완료	`downloadUrl`로 내려받으세요
`FAILED`	발급 실패	인증서, 체납, 신고 여부를 확인하고 새 `Bolta-Client-Reference-Id`로 다시 요청하세요
`ACTION_REQUIRED`	볼타가 결과 확인 중	같은 서류를 다시 요청하지 마세요. 확인이 끝나면 `COMPLETED` 또는 `FAILED`로 바뀝니다

COMPLETED 응답에는 다음 값이 채워집니다.

필드	설명
`issuedOn`	원본 PDF에 적힌 발급일 `YYYY-MM-DD`
`retentionExpiresAt`	보관 만료 시각. 발급 후 30일
`downloadUrl`	원본 PDF 주소. 5분 동안 유효
`downloadUrlExpiresAt`	주소 만료 시각

주소가 만료되면 다시 조회해 새 주소를 받으세요. 보관 기간이 지나면 downloadUrl은 null입니다. 내려받은 파일 이름은 {서류명}_{사업자등록번호}_{발급일}.pdf입니다. 예를 들어 사업자등록증명_123-45-67890_20260919.pdf이고, 영문 증명은 사업자등록증명(영문)_...으로 시작합니다. 한글 파일 이름을 지원하지 않는 클라이언트는 business-registration-proof_1234567890_20260919.pdf 같은 영문 이름으로 받습니다. 같은 날 같은 서류를 여러 번 받으면 파일 이름이 같습니다. 파일을 따로 저장한다면 issuanceKey와 함께 기록하세요.

테스트 키

테스트 키는 홈택스에 신청하지 않고 포인트도 차감하지 않습니다. 아래 사업자등록번호만 받습니다.

사업자등록번호	결과
`1000000014`	바로 `COMPLETED`
`1000000071`	바로 `FAILED`

1000000014의 COMPLETED 조회 응답에는 샘플 PDF 주소가 담깁니다. 샘플은 실제 서류가 아니며 서류 종류와 관계없이 내용이 같습니다. 발급일은 2026년 1월 1일로 고정입니다. 주소 유효 시간(5분), 만료 뒤 재조회, 파일 이름 규칙은 실제 발급과 같으니 다운로드 연동을 테스트 키로 확인하세요.

오류

상태 코드	에러 코드	발생 조건
`400`	`INVALID_REQUEST`	요청 형식 오류, 테스트 키로 안내 목록 밖 번호 요청
`401`	-	API 키 인증 실패. 응답 본문 없음
`402`	`PAYMENT_REQUIRED`	포인트 잔액 부족. 개발자센터에서 충전하세요
`403`	`TARGET_NOT_ALLOWED`	API 키가 속한 사업자가 아닌 번호
`404`	`DOCUMENT_ISSUANCE_NOT_FOUND`	없는 `issuanceKey`
`409`	`CERTIFICATE_REQUIRED`	공동인증서 미등록 또는 만료
`409`	`IDEMPOTENCY_CONFLICT`	같은 `Bolta-Client-Reference-Id`에 다른 본문
`409`	`POINT_RESERVED_BY_IN_FLIGHT_REQUESTS`	처리 중인 요청까지 합치면 잔액 부족. 충전하거나 끝난 뒤 다시 요청하세요
`429`	`TOO_MANY_IN_FLIGHT`	처리 중인 요청이 5건. 동시에 보낸 요청도 5건까지만 접수합니다. 끝난 뒤 다시 요청하세요

API 소개

API 가이드

사용 사례

SDK/노코드 연동

무엇을 발급하나요

이용 조건

지원 서류

발급 요청

결과 조회

테스트 키

오류

​무엇을 발급하나요

​이용 조건

​지원 서류

​발급 요청

​결과 조회

​테스트 키

​오류

무엇을 발급하나요

이용 조건

지원 서류

발급 요청

결과 조회

테스트 키

오류