혼합 방식 시나리오 (템플릿 표지 + PDF 내지)

표지는 템플릿으로 렌더링하고 내지는 파트너가 직접 제작한 PDF로 업로드하는 혼합 방식입니다. 표지 디자인을 SweetBook 템플릿 시스템에 맡기면서, 내지 편집은 파트너 시스템에서 제어하고 싶을 때 사용합니다.

개요

호출 시퀀스

• 책 생성 — creationType=MIX_COVER_TEMPLATE, pageCount(내지 페이지 수) 지정
• 표지 추가 — POST /books/{bookUid}/cover로 템플릿 기반 표지 적용
• 내지 PDF 업로드 — POST /books/{bookUid}/pdf-contents로 내지 PDF 업로드
• 책 최종화 — POST /books/{bookUid}/finalization 호출로 책을 FINALIZED 상태로 전환
• 주문 생성 — POST /orders (TEMPLATE과 동일 흐름)
• 주문 상태 추적 — 웹훅으로 렌더링·배송 진행 수신

사용 케이스

표지는 SweetBook이 제공하는 테마별 표지 템플릿의 디자인을 활용하면서, 내지는 파트너 자체 편집 도구에서 만든 PDF를 그대로 인쇄하고 싶을 때 사용합니다. 표지 디자인 품질과 내지 편집 자율성을 동시에 얻을 수 있습니다.

예시 환경

이 페이지의 모든 curl 예시는 아래 값을 기준으로 작성되어 있습니다. 복붙해서 실행할 때는 {YOUR_API_KEY}를 본인 API Key로, {bookUid} 플레이스홀더를 실제 값으로 교체하세요.

1. 책 생성

혼합 방식 책을 생성합니다. creationType="MIX_COVER_TEMPLATE"와 pageCount(내지 페이지 수)를 함께 지정합니다.

Request Body

에러 응답

curl -X POST 'https://api-sandbox.sweetbook.com/v1/books' \
  -H 'Authorization: Bearer {YOUR_API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
  "title": "mix_verify_20260422",
  "bookSpecUid": "SQUAREBOOK_HC",
  "creationType": "MIX_COVER_TEMPLATE",
  "pageCount": 24
}'

{
  "success": true,
  "message": "책 생성 완료",
  "data": {
    "bookUid": "bk_2IyK********"
  }
}

2. 표지 템플릿 적용

템플릿 기반 표지를 적용합니다. 템플릿 UID와 템플릿이 요구하는 parameters(텍스트·이미지 바인딩)를 함께 전송합니다.

MIX 방식에서는 PDF 표지(/pdf-cover)가 차단됩니다. 아래 에러 표와 제약사항 섹션 참조.

템플릿 파라미터 규약·이미지 전달 방법 등 상세는 템플릿 기반 시나리오 및 템플릿 구조 문서를 참조하세요.

curl -X POST 'https://api-sandbox.sweetbook.com/v1/books/{bookUid}/cover' \
  -H 'Authorization: Bearer {YOUR_API_KEY}' \
  -F 'templateUid=79yjMH3qRPly' \
  -F 'parameters={"title":"MIX Test","coverPhoto":"https://example.com/cover.jpg","dateRange":"26.01 - 26.04"}'

{
  "success": true,
  "message": "Cover created successfully",
  "data": {
    "result": "inserted"
  }
}

3. 내지 PDF 업로드

내지 PDF를 업로드합니다. 실제 페이지 수가 책 생성 시 지정한 pageCount와 정확히 일치해야 합니다 (불일치 시 400).

• POST — 신규 등록 전용. 이미 등록되어 있으면 409 Conflict
• PUT — 교체 전용. 등록되어 있지 않으면 404 Not Found

Request/Response 필드 상세 및 에러 규약은 PDF 업로드 시나리오의 4. 내지 PDF 업로드 섹션과 동일합니다 (POST/PUT 분리, 409/404 에러, pdfSizeMm 검증 등).

curl -X POST 'https://api-sandbox.sweetbook.com/v1/books/{bookUid}/pdf-contents' \
  -H 'Authorization: Bearer {YOUR_API_KEY}' \
  -F 'file=@hardcontents24.pdf;type=application/pdf'

{
  "success": true,
  "message": "contents PDF uploaded successfully",
  "data": {
    "bookUid": "bk_2IyK********",
    "kind": "contents",
    "valid": true,
    "pageCount": 24,
    "pdfSizeMm": { "width": 249, "height": 254 },
    "messages": [],
    "warnings": [],
    "bookStatus": 1,
    "url": "https://api-sandbox.sweetbook.com/v1/books/bk_2IyK********/pdf-contents"
  }
}

4. 책 최종화

책을 최종화하여 주문 가능한 상태로 전환합니다. 내지 PDF가 업로드되어 있어야 하며, 표지 템플릿은 finalize 후 백그라운드에서 PDF로 렌더링됩니다.

pageCount는 책 생성 시 지정한 값(내지 페이지 수)이 그대로 유지됩니다.

에러 응답

curl -X POST 'https://api-sandbox.sweetbook.com/v1/books/{bookUid}/finalization' \
  -H 'Authorization: Bearer {YOUR_API_KEY}' \
  -H 'Content-Length: 0'

{
  "success": true,
  "message": "책 최종화 완료",
  "data": {
    "result": "페이지를 추가하고 완료",
    "pageCount": 24,
    "finalizedAt": "2026-04-22T01:03:11.323Z"
  }
}

5. 주문 생성

주문을 생성합니다. 혼합 방식은 TEMPLATE 방식과 동일한 주문 흐름을 따릅니다 — 주문 즉시 PAID 상태로 진입하며, 렌더링이 완료되면 PDF_READY로 전이합니다.

(PDF 업로드 방식과 달리 PDF_READY 즉시 전환은 일어나지 않습니다.)

주문 요청 바디·배송 필드 상세는 Orders API 문서를 참조하세요.

curl -X POST 'https://api-sandbox.sweetbook.com/v1/orders' \
  -H 'Authorization: Bearer {YOUR_API_KEY}' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: mix-order-001' \
  -d '{
  "items": [ { "bookUid": "bk_2IyK********", "quantity": 1 } ],
  "shipping": {
    "recipientName": "김영수",
    "recipientPhone": "010-0000-0000",
    "postalCode": "06234",
    "address1": "서울시 강남구 테헤란로 1",
    "address2": "101호"
  }
}'

{
  "success": true,
  "message": "주문이 생성되었습니다",
  "data": {
    "orderUid": "or_184U********",
    "orderStatus": "PAID",
    "orderStatusDisplay": "결제완료",
    "totalAmount": 3100.00,
    "paidCreditAmount": 3410,
    "items": [
      {
        "itemUid": "oi_34Hu********",
        "bookUid": "bk_2IyK********",
        "bookSpecUid": "SQUAREBOOK_HC",
        "quantity": 1,
        "pageCount": 24,
        "itemStatus": "PAID",
        "itemStatusDisplay": "결제완료"
      }
    ]
  }
}

6. 주문 상태 추적

주문 생성 이후의 상태 전이와 웹훅 이벤트는 TEMPLATE 방식과 동일합니다. 상태 코드·흐름은 주문 상태 흐름, 웹훅 이벤트 목록은 Webhook Events를 참조하세요.

제약사항 / 흔한 실수

혼합 방식은 표지와 내지에 서로 다른 API를 사용하므로, 반대 방향으로 호출하면 400 에러가 반환됩니다.

다른 방식과의 선택 기준

• 표지·내지 모두 템플릿으로 처리 → TEMPLATE
• 표지·내지 모두 PDF로 업로드 → PDF_UPLOAD
• 표지 템플릿 + 내지 PDF (이 페이지) → MIX_COVER_TEMPLATE

관련 문서

• Books — PDF 기반 — 내지 PDF 업로드 엔드포인트 명세
• Books — 템플릿 기반 — 표지 템플릿 추가 엔드포인트 명세
• Templates API — 표지 템플릿 카탈로그·변수 정보
• BookSpecs API — 판형 정보 (PDF 검증 기준 포함)
• Orders API — 주문 생성·취소·조회
• 주문 상태 흐름 — PAID/PDF_READY 이후 상태 전이