템플릿 JSON 스키마

정의 구조

템플릿 정의는 용지를 지정하는 page와 그 위에 그릴 순서 있는 목록인 elements, 두 부분으로 구성된 하나의 객체입니다.

{
  "page": {
    "size": "A4",
    "orientation": "portrait",
    "margin": { "top": 48, "right": 48, "bottom": 48, "left": 48 }
  },
  "elements": [
    {
      "id": "invoice-title",
      "type": "heading",
      "placementMode": "flow",
      "content": { "text": "Invoice" },
      "layout": { "width": 100, "widthUnit": "percent", "height": 40 },
      "style": { "fontSize": 24, "textStyle": "bold" }
    }
  ]
}

용지 크기: A4 · A3 · Letter. 방향은 portrait 또는 landscape이며 여백은 인치당 96개의 CSS 픽셀 단위입니다.

각 요소에서 허용되는 필드

모든 요소는 id, type, placementMode를 포함합니다. 나머지는 유형에 따라 달라집니다. 아래 표는 검증기와 같은 규칙 집합에서 생성되므로 제품 사양보다 뒤처지지 않습니다.

해당 유형의 행에 없는 필드는 무시되지 않고 검증에 실패합니다. 필드를 조용히 버리면 요청은 성공한 것처럼 보이지만 문서 내용이 누락되므로 더 좋지 않습니다.

placementMode

요소가 용지에서 위치를 정하는 방식입니다. 이 모드에 따라 layout.x와 layout.y를 읽을지 여부도 결정됩니다.

• flow — 페이지 아래 방향으로 차례로 배치합니다. x와 y는 무시하며 요소는 콘텐츠에 따라 늘어납니다
• free — layout.x와 layout.y에 지정한 정확한 위치에 배치합니다
• band — 머리글이나 바닥글처럼 요소에서 지정한 영역에 모든 페이지마다 반복됩니다

dataset 요소

dataset은 표가 아닌 컬렉션을 출력합니다. 방문 기록, 사진, 서명 목록 등을 열 대신 템플릿에서 지정한 레이아웃으로 그립니다.

{
  "id": "maintenance-visits",
  "type": "dataset",
  "placementMode": "flow",
  "binding": "visits",
  "layout": { "width": 100, "widthUnit": "percent", "height": 160 },
  "style": { "fontSize": 11 },
  "dataRules": { "required": true }
}

binding은 표에서와 똑같이 데이터의 배열을 지정합니다. 각 항목의 표시 방식은 layout과 style에 따라 결정되므로 같은 컬렉션도 한 템플릿에서는 표로, 다른 템플릿에서는 dataset으로 사용할 수 있습니다.

dataset에는 content 필드가 없습니다. binding으로만 데이터를 받습니다. 이전에는 content에 입력해도 출력에 반영되지 않았으므로 효과 없는 입력란으로 남겨 두지 않고 해당 필드를 제거했습니다.

생성 전 데이터 검증

검증 엔드포인트는 한도를 사용하지 않고 생성 시와 같은 질문, 즉 이 데이터가 템플릿 요구 사항을 충족하는지 확인합니다.

curl -X POST https://api.pdfgine.com/api/v1/templates/invoice/validate-data \
  -H "X-PDFgine-Key: $PDFGINE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "data": { "referenceNo": "DOC-2026-0042", "currency": "USD" } }'

자주 발생하는 문제

• 요소 유형에 해당하지 않는 필드는 무시하지 않고 검증에 실패합니다. 조용히 버리면 내용이 빠진 문서가 만들어지고 누구도 없는 내용을 찾지 않기 때문에 의도한 동작입니다.
• flow 배치에서는 layout.x와 layout.y를 전혀 읽지 않습니다. 설정해도 움직이지 않는다는 질문이 가장 흔한 스키마 질문입니다.
• dataset에는 content 필드가 없으며 binding으로만 데이터를 받습니다. content에 넣은 텍스트는 출력되지 않습니다.
• 여백과 크기는 밀리미터가 아닌 인치당 96개의 CSS 픽셀 단위입니다. 20을 밀리미터라고 생각하고 지정하면 약 3분의 1 크기로 출력됩니다.
• 데이터가 맞는지 알아보려고 생성하면 페이지를 사용합니다. 검증 엔드포인트는 같은 확인을 무료로 수행합니다.