> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bolta.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 세금계산서 PDF 조회

> Open API로 발행한 세금계산서의 PDF를 내려받는 API의 이용 조건, 재호출 방법, 파일 이름 규칙, 오류를 안내합니다.

## 무엇을 조회하나요

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

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

## 이용 조건

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

## 요금

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

## PDF 조회

### 요청

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

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

### 응답

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

```http theme={"dark"}
HTTP/1.1 202 Accepted
Retry-After: 2
```

```json theme={"dark"}
{
  "issuanceKey": "8D529FAD3EBAE050B79CE943CCC7CEDE",
  "status": "PENDING",
  "downloadUrl": null,
  "downloadUrlExpiresAt": null,
  "filename": null
}
```

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

```json theme={"dark"}
{
  "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` 헤더로 같은 이름을 보냅니다. 한글 파일 이름을 지원하지 않는 클라이언트는 영문과 숫자만 남긴 이름으로 받습니다.

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

## 테스트 키

테스트 키로 발행한 건은 실제 세금계산서가 없습니다. 대신 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`보다 먼저 다시 호출하면 같은 오류를 받습니다.

## 관련 문서

* [세금계산서 PDF 조회 API](/api-reference/세금계산서-조회/세금계산서-pdf-조회)
* [전자세금계산서 내용 조회 API](/api-reference/세금계산서-조회/전자세금계산서-내용-조회)
* [세금계산서 웹훅](/docs/api-introduction/webhook-tax-invoice)
* [에러 코드](/docs/api-introduction/error-codes)