사이즈 계산 API

판형 UID와 페이지 수만 전달하면 PDF 캔버스 사이즈를 계산해 반환하는 API입니다.

엔드포인트

Request

Request 예시

curl 'https://api-sandbox.sweetbook.com/v1/book-specs/PHOTOBOOK_A4_SC/calculated-size?pages=70' \
  -H 'Authorization: Bearer {YOUR_API_KEY}'

curl 'https://api-sandbox.sweetbook.com/v1/book-specs/SQUAREBOOK_HC/calculated-size?pages=50' \
  -H 'Authorization: Bearer {YOUR_API_KEY}'

응답 필드

※ 모든 수치는 소수점 둘째 자리까지 반올림됩니다.

Response 예시

{
  "success": true,
  "message": "성공",
  "data": {
    "bookSpecUid": "PHOTOBOOK_A4_SC",
    "pages": 70,
    "unit": "mm",
    "coverWidthMm": 430.78,
    "coverHeightMm": 303,
    "innerWidthMm": 216,
    "innerHeightMm": 303,
    "spineWidthMm": 4.78,
    "pdfToleranceMm": 1
  }
}

HTTP 상태 코드

페이지 수 입력에 따른 응답 변화

페이지 수가 늘어나면 책등 너비가 변하고 그에 따라 표지 펼침면 너비도 함께 변합니다. 그 외 값은 페이지에 무관합니다.

• 하드커버: spineWidthRules 구간(tier) 단위로 점프 (예: 24~64p는 동일, 65p부터 다른 값)
• 소프트커버: 페이지 1장당 pageThicknessMm만큼 점진적 증가

검산 예시

판형별로 페이지 수에 따라 본 API가 반환하는 값을 정리한 표입니다. 직접 계산식으로 검증할 때 참고하세요.

SQUAREBOOK_HC (하드커버, PUR 제본 — spineWidthRules 구간별 변동)

※ 64p → 66p 시점에 spineWidthRules 구간이 바뀌어 표지 너비·책등 너비가 6mm 점프합니다. coverHeightMm·innerWidthMm·innerHeightMm은 페이지와 무관하게 고정.

SQUAREBOOK_LAYFLAT_HC (하드커버, 레이플랫 제본 — 내지 펼침면)

※ pages 쿼리 파라미터는 책 페이지 단위 + 짝수로 전달합니다. innerWidthMm은 펼침면 한 장의 캔버스 크기이며, 업로드할 PDF 페이지수는 pages / 2입니다. 18p → 20p 사이에 spineWidthRules 구간이 바뀌어 표지 너비·책등 너비가 점프합니다.

{
  "success": true,
  "message": "성공",
  "data": {
    "bookSpecUid": "SQUAREBOOK_LAYFLAT_HC",
    "pages": 20,
    "unit": "mm",
    "coverWidthMm": 550,
    "coverHeightMm": 288,
    "innerWidthMm": 492,
    "innerHeightMm": 254,
    "spineWidthMm": 16,
    "pdfToleranceMm": 1
  }
}

PHOTOBOOK_A4_SC (소프트커버, PUR 제본 — 페이지 두께 누적)

※ 페이지마다 pageThicknessMm(0.054)만큼 책등·표지 너비가 점진적으로 증가합니다.

PHOTOBOOK_A5_SC (소프트커버, PUR 제본 — pageMin=50)

※ A5 SC는 pageMin=50이므로 50p 미만 요청 시 400 응답을 반환합니다.

±1mm 톨러런스

PDF 업로드 검증의 expected 사이즈는 본 API 응답과 동일한 출처를 사용합니다. 응답값 그대로 PDF를 만들면 검증이 반드시 통과하며, ±1mm 이내의 작은 오차도 허용됩니다.

PDF 너비 불일치: 실제 432.0mm, 허용 규격 430.78mm (+/-1mm)

클라이언트 통합 시나리오

파트너 서비스에서 본 API를 어떻게 활용하는지 흐름별로 안내합니다. 사이즈 계산 공식·도식은 자매 페이지 PDF 표지/내지 사이즈를 참고하세요.

시나리오 A — 자체 PDF를 만들어 업로드

가장 일반적인 흐름. 파트너 서비스가 사용자 데이터를 받아 PDF를 직접 생성하고 업로드합니다.

1. 판형/페이지 수 결정 — 사용 spec(예: PHOTOBOOK_A4_SC)과 페이지 수(예: 70p) 확정
2. 사이즈 계산 API 호출 — GET /book-specs/{bookSpecUid}/calculated-size?pages=70
   응답: { coverWidthMm: 430.78, coverHeightMm: 303, innerWidthMm: 216, innerHeightMm: 303, spineWidthMm: 4.78, pdfToleranceMm: 1 }
3. 응답 사이즈로 PDF 캔버스 만들고 디자인 채움
   • 표지: 430.78 × 303 mm (펼침면)
   • 내지: 216 × 303 mm × 70페이지 (PUR 제본 → 단면 PDF)
4. PDF 업로드 — POST /books/{bookUid}/pdf-cover·POST /books/{bookUid}/pdf-contents
   검증은 자동으로 calculated-size와 동일한 사이즈로 수행됩니다 (±1mm 톨러런스). 통과 → 200, 실패 → 400 + "PDF 너비 불일치" 메시지.
5. 책 최종화 — POST /books/{bookUid}/finalization

핵심: 2단계의 응답값 그대로 PDF를 만들면 4단계 검증 통과가 보장됩니다.

시나리오 B — 사이즈 미리보기 / 사용자 안내

파트너 서비스가 사용자에게 책의 인쇄 크기를 미리 보여줄 때 활용합니다.

1. 사용자가 페이지 수를 슬라이더로 조정 (예: 24p ↔ 100p)
2. 페이지 변경마다 GET /book-specs/{uid}/calculated-size?pages={N} 호출
   또는 GET /book-specs/{uid}로 한 번만 받아서 클라이언트가 직접 계산
3. 사용자에게 표시:
   "당신의 책 크기: 가로 308.40mm × 세로 216mm" / "책등 두께: 6.40mm"

팁: 파트너 측에서 직접 계산하려면 GET /book-specs/{uid} 응답의 bleedMm·coverThicknessMm·pageThicknessMm 등을 받아 자매 페이지의 계산식을 적용하세요.

시나리오 C — 사용자 PDF 업로드 사전 검증

사용자가 자체 PDF를 가져와 업로드 시도하는 경우, 파트너 서비스가 업로드 전에 사이즈를 미리 검증합니다.

1. 사용자 PDF 업로드 → 파트너 서비스가 PDF 크기 추출 (예: 432 × 303)
2. GET /book-specs/{uid}/calculated-size?pages=70 호출
   응답: { coverWidthMm: 430.78, pdfToleranceMm: 1, ... }
3. 파트너 서비스에서 검증:
   |userPdfWidth - coverWidthMm| ≤ pdfToleranceMm이면 업로드 진행, 아니면 "사이즈가 안 맞습니다. 가이드: 430.78 × 303 (±1mm)" 안내
4. 통과 시 SweetBook API에 업로드 → 동일 검증으로 한 번 더 통과 보장

자주 묻는 질문

관련 문서

• PDF 표지/내지 사이즈 — 도식·계산식·하드/소프트 분기
• Books — PDF 기반 — PDF 업로드 검증 동작
• BookSpecs API — 판형 일람·페이지 범위·신규 사이즈 입력 필드 응답 명세
• PDF 업로드 시나리오 — 책 생성부터 주문까지 흐름