무엇을 조회하나요
Open API로 발행한 전자세금계산서를 PDF로 내려받습니다. 볼타 대시보드에서 받는 PDF와 같은 양식입니다.이용 조건
- 정발행(
issue), 역발행(issueRequest), 수정세금계산서(amend)로 발행한 건을 모두 받습니다. - 발행이 끝난 건만 받습니다. 발행 결과 웹훅(
TAX_INVOICE_ISSUANCE_SUCCESS)을 받았거나 내용 조회 API가 발행 완료로 답한 뒤 호출하세요. - 역발행은 공급자가 승인해 발행을 마친 뒤에 받습니다. 승인 전이거나 공급자가 거절한 건은 API가
400 TAX_INVOICE_RETRIEVE_NOT_AVAILABLE을 반환합니다. - 수정세금계산서 PDF는 제목에 수정분 또는 취소분을 표시하고 수정사유를 함께 싣습니다.
- 발행을 요청한 API 키로 호출하세요. 키를 교체하거나 폐기하면 그 키로 발행한 건의 PDF도 받을 수 없으니 키를 바꾸기 전에 필요한 PDF를 받아 두세요.
요금
포인트를 차감하지 않습니다.PDF 조회
요청
issuanceKey에는 발행 요청 응답의 값을 넣으세요.
응답
웹훅은 PDF 생성과 별개로 발행이 완료되면 전송하므로, 웹훅을 받은 뒤에도 이 API를 호출하세요. 준비된 PDF가 있으면 API가 첫 조회에서도200 OK와 다운로드 주소를 반환합니다.
202 Accepted와 Retry-After 헤더를 반환합니다. 첫 조회나 이후 조회에서 202를 받으면 헤더의 초만큼 기다린 뒤 같은 요청을 다시 보내세요.
downloadUrl, downloadUrlExpiresAt, filename은 READY일 때만 값이 있습니다. 주소가 만료되면 같은 요청을 다시 보내 새 주소를 받으세요. 주소에는 서명값이 들어 있으니 로그나 분석 도구에 주소 전체를 남기지 마세요.
파일 이름은 {종류}_{작성일자}_{공급받는자 상호}_{승인번호}.pdf입니다. 다운로드 주소가 Content-Disposition 헤더로 같은 이름을 보냅니다. 한글 파일 이름을 지원하지 않는 클라이언트는 영문과 숫자만 남긴 이름으로 받습니다.
테스트 키
테스트 키로 발행한 건은 발행 완료를 확인한 뒤 조회하세요. 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가 준비되면 다음 건을 요청하세요.
오류
PDF_GENERATION_FAILED를 받은 뒤 Retry-After보다 먼저 다시 호출하면 같은 오류를 받습니다.
