제품 및 API 안내
응답
반환되는 내용
성공한 모든 생성은 같은 객체를 반환합니다. 보관할 만한 두 필드가 있습니다. documentId는 보관 기간 동안 파일을 식별하고 pageCount는 월 청구의 기준이 됩니다.
응답
{
"documentId": "doc_5bd26de32c324a4bb8cffad2c80edd01",
"jobId": "job_00b96f006b034258b00b650d724d0207",
"fileName": "invoice-doc_5bd26de32c324a4bb8cffad2c80edd01.pdf",
"format": "pdf",
"templateCode": "invoice",
"templateVersion": 5,
"templateVersionSource": "published",
"downloadUrl": "/api/v1/documents/doc_5bd2.../download/pdf",
"previewUrl": null,
"pageCount": 1,
"quotaRemaining": 4999,
"meteringBasis": "pdf-equivalent",
"createdAt": "2026-08-28T13:23:32+00:00"
}생성 결과는 비공개이며 다운로드하려면 API 키가 필요합니다. 만료되는 고객용 링크가 의도적으로 필요할 때만 미리보기 엔드포인트를 사용하세요.
응답 헤더
모든 생성 응답의 헤더에도 집계 수치가 포함되므로 추가 호출 없이 한도를 추적할 수 있습니다.
X-PDFgine-Pages | 이 문서의 페이지 수 |
|---|---|
X-PDFgine-Job | 생성 작업 식별자 |
X-PDFgine-Quota-Remaining | 작업 후 남은 페이지 수 |
X-PDFgine-Metering-Basis | 집계 단위 |
필드별 설명
pdf, docx, html에서 같은 필드가 반환되며 fileName만 달라집니다.
| 필드 | 의미 |
|---|---|
documentId | 생성된 파일의 식별자입니다. 다운로드, 상태 확인, 공유에 모두 사용되므로 보관해야 할 값입니다. |
downloadUrl | API 주소 기준 상대 경로이며 같은 키로 가져옵니다. 공개 링크가 아닌 경로입니다. |
templateVersion | 이 파일을 생성한 템플릿 버전입니다. 보관하면 몇 달 후 재출력한 결과를 설명할 수 있습니다. |
templateVersionSource | 실제 생성에는 published, purpose가 editor-test일 때는 draft입니다. |
pageCount | 생성된 페이지 수이며 한도는 이 값으로 집계합니다. |
quotaRemaining | 이 응답 시점의 이번 달 잔여 페이지 수입니다. |
meteringBasis | 청구에서 한 페이지가 무엇을 의미하는지 나타냅니다. pdf-equivalent는 docx 또는 html 출력을 PDF로 만들었을 때와 같은 페이지 수로 계산합니다. |
previewUrl | 문서를 공유했을 때만 값이 있으며 그 외에는 null입니다. |
자주 발생하는 문제
- downloadUrl은 경로입니다. API 주소와 키 없이 브라우저에 붙여 넣으면 파일이 아닌 404 또는 401을 받습니다.
- 전체 응답이 아닌 documentId를 저장하세요. 요금제의 보관 기간이 지나면 파일이 삭제되며 저장된 URL은 아무것도 가리키지 않게 됩니다.
- quotaRemaining은 그 시점의 스냅샷이며 실시간 카운터가 아닙니다. 동시에 두 번 호출하면 둘 다 같은 수를 읽을 수 있습니다.
- pageCount는 파일 수가 아닌 청구 단위입니다. 10페이지 문서는 pdf든 docx든 10페이지를 사용합니다.
- previewUrl이 null이라고 공유 실패를 의미하지는 않습니다. 해당 생성 결과가 공유되지 않았다는 뜻입니다. 공유는 별도로 호출합니다.