세금계산서 PDF 조회

무엇을 조회하나요

Open API로 발행한 전자세금계산서를 PDF로 내려받습니다. 볼타 대시보드에서 받는 PDF와 같은 양식입니다.

경로	용도
`GET /v1/taxInvoices/{issuanceKey}/pdf`	세금계산서 PDF 다운로드 주소 조회

이용 조건

정발행(issue), 역발행(issueRequest), 수정세금계산서(amend)로 발행한 건을 모두 받습니다.
발행이 끝난 건만 받습니다. 발행 결과 웹훅(TAX_INVOICE_ISSUANCE_SUCCESS)을 받았거나 내용 조회 API가 발행 완료로 답한 뒤 호출하세요.
역발행은 공급자가 승인해 발행을 마친 뒤에 받습니다. 승인 전이거나 공급자가 거절한 건은 API가 400 TAX_INVOICE_RETRIEVE_NOT_AVAILABLE을 반환합니다.
수정세금계산서 PDF는 제목에 수정분 또는 취소분을 표시하고 수정사유를 함께 싣습니다.
발행을 요청한 API 키로 호출하세요. 키를 교체하거나 폐기하면 그 키로 발행한 건의 PDF도 받을 수 없으니 키를 바꾸기 전에 필요한 PDF를 받아 두세요.

요금

포인트를 차감하지 않습니다.

PDF 조회

요청

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

issuanceKey에는 발행 요청 응답의 값을 넣으세요.

응답

첫 호출이 PDF 생성을 시작합니다. 만드는 중이면 API가 202 Accepted와 Retry-After 헤더를 반환합니다. 헤더의 초만큼 기다린 뒤 같은 요청을 다시 보내세요.

HTTP/1.1 202 Accepted
Retry-After: 2

{
  "issuanceKey": "8D529FAD3EBAE050B79CE943CCC7CEDE",
  "status": "PENDING",
  "downloadUrl": null,
  "downloadUrlExpiresAt": null,
  "filename": null
}

준비되면 API가 200 OK와 다운로드 주소를 반환합니다. 한 번 만든 PDF는 다시 만들지 않으므로 이후 호출은 바로 200을 받습니다.

{
  "issuanceKey": "8D529FAD3EBAE050B79CE943CCC7CEDE",
  "status": "READY",
  "downloadUrl": "https://example.com/tax-invoice-pdfs/8D529FAD3EBAE050B79CE943CCC7CEDE.pdf",
  "downloadUrlExpiresAt": "2026-09-24T03:05:00Z",
  "filename": "전자세금계산서_20260924_공급받는자 상호_20260924-10000000-00000001.pdf"
}

필드	형식	설명
`issuanceKey`	string	요청한 `issuanceKey`
`status`	string	`PENDING`(생성 중), `READY`(준비 완료)
`downloadUrl`	string 또는 null	PDF 주소. 5분 동안 유효
`downloadUrlExpiresAt`	string 또는 null	주소 만료 시각(UTC)
`filename`	string 또는 null	내려받을 때 저장되는 파일 이름

downloadUrl, downloadUrlExpiresAt, filename은 READY일 때만 값이 있습니다. 주소가 만료되면 같은 요청을 다시 보내 새 주소를 받으세요. 주소에는 서명값이 들어 있으니 로그나 분석 도구에 주소 전체를 남기지 마세요. 파일 이름은 {종류}_{작성일자}_{공급받는자 상호}_{승인번호}.pdf입니다. 다운로드 주소가 Content-Disposition 헤더로 같은 이름을 보냅니다. 한글 파일 이름을 지원하지 않는 클라이언트는 영문과 숫자만 남긴 이름으로 받습니다.

공급받는자가 개인이면 발행 요청 때 보낸 주민등록번호가 PDF에 가려지지 않고 그대로 나옵니다. 파일을 보관하거나 전달할 때 개인정보로 다루세요.

테스트 키

테스트 키로 발행한 건은 실제 세금계산서가 없습니다. 대신 API가 바로 200과 샘플 PDF 주소를 반환합니다. 샘플은 모든 발행 건에 같은 내용입니다. 주소 유효 시간(5분), 만료 뒤 재조회, 파일 이름 전달 방식은 라이브 키와 같으니 다운로드 연동을 테스트 키로 확인하세요. 테스트 키는 202를 반환하지 않습니다. Retry-After를 따라 다시 호출하는 로직은 라이브 키로 확인하세요.

호출 한도

같은 사업자에서 만드는 중인 PDF가 10건이거나 같은 API 키로 만드는 중인 PDF가 20건이면 API가 429 TOO_MANY_IN_FLIGHT와 Retry-After 헤더를 반환합니다. 이 한도는 새로 만들어야 하는 PDF에만 적용합니다. 이미 요청해 만드는 중이거나 준비된 PDF를 다시 조회하는 호출은 막지 않습니다. 여러 건을 한꺼번에 받으려면 사업자당 10건, 키 전체 20건을 넘지 않게 나눠 요청하세요. 먼저 요청한 PDF가 준비되면 다음 건을 요청하세요.

오류

상태 코드	에러 코드	발생 조건
`400`	`TAX_INVOICE_RETRIEVE_NOT_AVAILABLE`	발행 완료 전이거나 발행 실패. 역발행은 공급자 승인 전이거나 거절. 발행 결과를 확인한 뒤 다시 호출하세요
`400`	`INVALID_DOCUMENT`	볼타에 저장된 문서 정보로 PDF를 만들 수 없음. `issuanceKey`와 함께 볼타에 문의하세요
`401`	-	API 키 인증 실패. 응답 본문 없음
`403`	`FORBIDDEN`	발행을 요청한 API 키가 아님. 키를 교체하거나 폐기한 뒤 이전 키로 발행한 건도 해당
`404`	`NOT_FOUND`	없는 `issuanceKey`
`429`	`TOO_MANY_IN_FLIGHT`	같은 사업자에서 만드는 중인 PDF 10건 또는 같은 API 키로 만드는 중인 PDF 20건. `Retry-After`(60초) 뒤 다시 호출하세요
`500`	`INTERNAL_SERVER_ERROR`	서버 내부 오류
`503`	`PDF_GENERATION_FAILED`	여러 번 시도했지만 PDF를 만들지 못함. `Retry-After`(600초) 뒤 같은 요청을 보내면 다시 만듭니다. 계속되면 `issuanceKey`와 함께 볼타에 문의하세요
`503`	`SERVICE_UNAVAILABLE`	일시적인 내부 API 통신 오류

PDF_GENERATION_FAILED를 받은 뒤 Retry-After보다 먼저 다시 호출하면 같은 오류를 받습니다.

API 소개

API 가이드

사용 사례

SDK/노코드 연동

무엇을 조회하나요

이용 조건

요금

PDF 조회

요청

응답

테스트 키

호출 한도

오류

관련 문서

​무엇을 조회하나요

​이용 조건

​요금

​PDF 조회

​요청

​응답

​테스트 키

​호출 한도

​오류

​관련 문서

무엇을 조회하나요

이용 조건

요금

PDF 조회

요청

응답

테스트 키

호출 한도

오류

관련 문서