데이터 형식 · PDFgine

데이터를 어떤 구조로 보내야 하는지 여기에서 확인할 수 있습니다. PDFgine은 받은 값을 그대로 출력하지 않고 템플릿에 지정된 서식을 문서 언어에 맞게 적용합니다.

원칙은 하나입니다. 데이터는 원시 형태로 받고 PDFgine이 서식을 지정합니다. 미리 서식을 적용한 값을 보내면 한 언어에서는 올바르게, 다른 언어에서는 잘못 표시됩니다.

필드 유형	전송 방법	입력 예시	출력
`date`	ISO 8601 형식입니다. 날짜만 필요하면 YYYY-MM-DD, 시간이 중요하면 전체 타임스탬프를 사용하세요. 현지 형식으로 변환하지 마세요.	`"2026-09-06"`	`2026. 9. 6.`
`number`	JSON 숫자입니다. 천 단위 구분 기호, 공백, 따옴표를 넣지 말고 소수 구분 기호는 점을 사용하세요.	`24000`	`24,000.00`
`currency`	금액은 가공하지 않은 숫자로 보내세요. 통화는 숫자에 포함하지 않고 열 서식 설정에서 ISO 4217 코드로 지정합니다.	`24000`	`24,000.00 USD`
`percent`	100을 기준으로 한 비율을 그대로 보냅니다. 18%라면 18을 보내세요. 기호는 문서에서 추가합니다.	`18`	`18.00%`
`string`	수신한 그대로 출력됩니다. 날짜, 금액, 비율을 문자열로 보내면 서식이 적용되지 않습니다.	`"Northwind Trading Ltd."`	`Northwind Trading Ltd.`
`boolean`	JSON true/false입니다. 조건부 블록은 이 값을 읽습니다.	`true`	조건 판단에 사용되며 텍스트로 출력되지 않음

서식은 세 곳에서 지정합니다. 표의 열과 요약 행의 "format" 필드, 단일 값을 출력하는 요소의 "dataRules.formatter", 여러 필드를 합치는 텍스트의 format_date 및 format_money 함수입니다.

데이터와 템플릿

{
  "issueDate": "2026-09-06",
  "currency": "USD",
  "lineItems": [
    { "name": "기업 웹사이트", "quantity": 1, "unitPrice": 24000, "total": 24000 }
  ]
}

// 템플릿 측:
// 표 열:   "format": { "kind": "currency", "currency": "USD", "decimals": 2 }
// 날짜 열:    "format": { "kind": "date", "dateStyle": "short" }
// 텍스트 요소:   "{{ referenceNo }} · {{ format_date issueDate }}"

IBAN, 전화번호, 납세자 번호도 표준 형식으로 전송합니다. IBAN에는 공백을 넣지 않고 전화번호는 E.164(+442071838750) 형식을 사용하세요. 묶음 구분은 표시 형식이며 데이터에 포함되지 않습니다.

다운로드되는 문서의 이름

다운로드한 문서의 이름은 "{document type} - {counterparty} - {reference no}"입니다. 세 부분은 전송 데이터의 document.title, customer, referenceNo에서 가져옵니다. 없는 부분은 생략하며 어떤 값으로도 사용할 수 있는 이름을 만들 수 없으면 quote-doc_94812af2.pdf와 같이 문서 식별자를 사용합니다.

응답 헤더

Content-Disposition: attachment;
  filename="Quote - Müller og Søn ApS - QUO-2026-0042.pdf";
  filename*=UTF-8''Quote%20-%20M%C3%BCller%20og%20S%C3%B8n%20ApS%20-%20QUO-2026-0042.pdf

동일한 헤더에 이름이 두 번 기록됩니다. 확장 필드는 문서의 언어를 유지하고, 기존 필드는 확장 필드를 읽지 못하는 클라이언트를 위해 읽기 쉬운 ASCII 표기를 제공합니다. 파일 시스템에서 허용하지 않는 문자(슬래시, 역슬래시, 콜론, 별표, 물음표, 따옴표, 작음 기호, 큼 기호, 세로줄)와 제어 문자는 제거하며, 모든 파일 시스템에서 사용할 수 있도록 이름 길이를 제한합니다.

이미지

템플릿의 이미지 요소를 데이터 필드에 바인딩하면 이미지 원본이 요청과 함께 전달됩니다. 업로드한 자산의 ID(ast_… — 반복 사용하는 로고, 도장, 서명용. 한 번 업로드하면 이후에는 ID만 전송)와 인라인 이미지(data:image/png;base64,… — 일회성 이미지용)의 두 가지 형식을 사용할 수 있습니다. 필드가 없거나 비어 있으면 템플릿 자체 이미지를 사용합니다. 값이 있지만 사용할 수 없으면 요청을 422로 거부하고 응답에 해당 데이터 필드 이름을 표시합니다.

요청

{
  "templateCode": "invoice",
  "format": "pdf",
  "data": {
    "logo": "ast_9f1c7b1f0f6b4f5f9f0a0d1e2c3b4a59",
    "signature": "data:image/png;base64,iVBORw0KGgo..."
  }
}

제한: 인라인 이미지는 PNG, JPEG, WebP여야 하며, 이미지당 최대 2 MB, 문서 내 모든 이미지의 합계는 최대 6 MB입니다. 업로드 자산은 최대 10 MB입니다. 임시 이미지에는 자산 업로드 시 expiresInMinutes를 지정하세요(1분~7일). 만료된 자산은 자동으로 삭제됩니다.

에셋

로고, 서명, 글꼴은 한 번 업로드한 후 ID로 참조합니다. 업로드 방법, 한도, 글꼴에서 허용하는 사용 범위는 전용 페이지에서 설명합니다.

에셋 →

자주 발생하는 문제

미리 서식을 적용한 값은 받은 그대로 출력됩니다. "1.234,56"은 한 언어에서는 올바르고 다른 언어에서는 잘못 표시되며 나중에 서식 설정으로 고칠 수 없습니다.
날짜는 ISO 8601이어야 합니다. 현지 형식은 텍스트로 수신되어 서식 적용, 정렬, 번역이 되지 않습니다.
통화를 금액에 포함하지 마세요. 숫자를 보내고 열 서식 설정에서 ISO 코드를 추가하도록 하세요.
비율은 100을 기준으로 보냅니다. 18%이면 18입니다. 0.18을 보내면 0.18퍼센트로 출력됩니다.
조건은 JSON 불리언을 읽습니다. 문자열 "false"는 비어 있지 않은 텍스트이므로 값이 있는 것으로 처리됩니다.