제품 및 API 안내

템플릿 목록 조회

템플릿이란

템플릿은 선택한 코드로 저장되는 문서 디자인입니다. 계속 편집하는 초안과 실제 생성에 사용하는 게시된 버전이 동시에 존재합니다. 저장만으로는 게시되지 않으므로 미완성 변경이 고객에게 전달되지 않습니다.

워크스페이스의 템플릿과 게시된 버전 번호를 반환합니다. 생성할 때는 템플릿 코드를 사용합니다.

요청

curl https://api.pdfgine.com/api/v1/templates \
  -H "X-PDFgine-Key: $PDFGINE_KEY"

응답

[
  {
    "templateId": "tpl_eca4c9985ad74913902f0469469936a1",
    "code": "invoice",
    "name": "기업 청구서",
    "version": 5,
    "publishedVersion": 1,
    "publishedAt": "2026-08-23T08:23:21+00:00"
  }
]

페이지 번호 서식

페이지 번호 요소의 content는 서식입니다. {{ page }}는 현재 페이지, {{ pages }}는 전체 페이지 수로 바뀝니다. “{{ page }} / {{ pages }}”를 입력하면 “3 / 12”로 인쇄됩니다. PDF에서는 페이지 카운터, Word에서는 PAGE/NUMPAGES 필드 코드를 사용하므로 페이지가 추가되면 자동으로 갱신됩니다. 자리표시자가 없으면 content는 무시하고 페이지 번호만 출력합니다.

버전 저장

저장할 때는 현재 편집 중이라고 인식한 버전을 보냅니다. 그사이에 다른 사람이 저장했으면 409와 현재 버전이 반환되므로 아무 알림 없이 덮어쓰지 않습니다.

cURL

curl -X POST https://api.pdfgine.com/api/v1/templates \
  -H "X-PDFgine-Key: $PDFGINE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "code": "invoice",
        "name": "기업 청구서",
        "saveMode": "manual",
        "expectedVersion": 5,
        "changeReason": "로고를 오른쪽 여백으로 옮겼습니다.",
        "definition": {
          "page": { "size": "A4", "orientation": "portrait" },
          "elements": [
            { "type": "text", "text": "기업 청구서", "fontSize": 24 }
          ]
        }
      }'

응답

HTTP/1.1 409 Conflict

{
  "type": "https://pdfgine.dev/problems/template-conflict",
  "templateCode": "invoice",
  "currentVersion": 6,
  "currentDraftRevision": 0
}

expectedVersion은 선택 사항이지만 권장합니다. 지정하지 않으면 마지막 작성자의 값이 적용되고 이전 변경 사항은 흔적 없이 사라집니다.

자주 발생하는 문제

409는 무작정 재시도할 오류가 아닙니다. currentVersion을 읽고 최신 정의 위에 변경 사항을 적용한 후 다시 저장하세요.
저장과 게시는 다릅니다. 초안을 게시하기 전까지 실제 생성은 마지막으로 게시된 버전을 계속 사용합니다.
목록은 최대 200개 템플릿을 반환합니다. 더 있으면 rel="next"가 포함된 Link 헤더를 따라가세요. 첫 페이지가 전체 라이브러리라고 가정하지 마세요.
읽기에는 templates:read, 저장에는 templates:write가 필요합니다. 읽기 전용 키로 저장하면 401이 아닌 403으로 응답합니다.
다른 모든 호출은 코드로 템플릿을 찾습니다. 템플릿 이름은 자유롭게 바꿀 수 있지만 코드를 바꾸면 새 템플릿이 됩니다.