제품 및 API 안내

문서 생성

이 엔드포인트의 역할

한 번의 호출로 템플릿과 데이터를 완성된 파일로 만듭니다. 대기하는 동안 문서가 생성되고 응답에 다운로드 주소가 포함되므로 폴링할 필요가 없습니다. 긴 문서나 일괄 작업은 대기열 엔드포인트가 같은 작업을 백그라운드에서 처리합니다.

템플릿 코드와 데이터를 보내면 문서를 받습니다. 응답의 다운로드 URL은 기본 주소 기준 상대 URL이며 같은 API 키로 가져옵니다.

요청 
curl -X POST https://api.pdfgine.com/api/v1/render \
  -H "X-PDFgine-Key: $PDFGINE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "templateCode": "invoice",
        "format": "pdf",
        "locale": "ko",
        "purpose": "production",
        "data": {
          "document": { "title": "INV-2026-001" }
        }
      }'

format 필드는 "pdf" 또는 "docx"를 받습니다. 기존 클라이언트의 숫자 값도 계속 지원하며 1은 PDF, 2는 DOCX입니다. 응답은 형식을 숫자로 반환합니다.

purpose가 production이면 한도를 사용합니다. 템플릿을 시험할 때는 editor-test를 보내세요. 이 출력은 한도를 사용하지 않으며 게시되지 않은 초안 수정본을 사용합니다.

요청부터 다운로드까지

위 호출의 응답과 파일을 가져오는 호출입니다. 상태 202는 요청이 수락되었으며 문서가 준비되었다는 뜻입니다.

응답 
HTTP/1.1 202 Accepted
X-PDFgine-Pages: 1
X-PDFgine-Quota-Remaining: 4999

{
  "documentId": "doc_a96063f5dcd5400286ce9b3be9b0595b",
  "format": "pdf",
  "templateCode": "invoice",
  "templateVersion": 1,
  "templateVersionSource": "published",
  "downloadUrl": "/api/v1/documents/doc_a96063f5dcd5400286ce9b3be9b0595b/download/pdf",
  "pageCount": 1,
  "quotaRemaining": 4999,
  "meteringBasis": "pdf-equivalent"
}
cURL 
curl https://api.pdfgine.com/api/v1/documents/doc_a96063f5dcd5400286ce9b3be9b0595b/download/pdf \
  -H "X-PDFgine-Key: $PDFGINE_KEY" \
  -o invoice.pdf

자주 발생하는 문제

  • 생성 응답은 200이 아닌 202입니다. 200 이외의 응답을 실패로 처리하는 클라이언트는 성공을 오류로 보고합니다.
  • purpose는 두 가지를 결정합니다. production은 게시된 버전을 사용하고 한도를 소모하며 editor-test는 게시되지 않은 초안을 사용하고 한도를 소모하지 않습니다. production으로 테스트하면 템플릿을 시험하는 데 가장 많은 비용이 듭니다.
  • 422는 서버 장애가 아닙니다. 본문의 errors에 템플릿이 요구한 모든 필드가 표시되므로 재시도가 아닌 전송 데이터 수정이 필요합니다.
  • 402는 월 페이지 한도를 소진했다는 뜻입니다. X-PDFgine-Quota-Remaining 헤더로 소진 전에 잔여량을 확인할 수 있습니다.
  • downloadUrl은 API 주소 기준 상대 URL입니다. 절대 URL로 저장하면 주소가 바뀌는 날 사용할 수 없게 됩니다. documentId를 저장하고 주소를 구성하세요.
응답 →