Books API — 템플릿 기반

SweetBook 템플릿에 이미지·텍스트를 바인딩하여 책을 생성하는 방식의 API 레퍼런스입니다. 표지·내지 페이지를 템플릿 단위로 추가하고, 명시적인 최종화(finalize) 호출로 주문 가능 상태로 전환합니다.

이 방식이 적합한 경우

• SweetBook이 제공하는 표지·내지 템플릿을 활용하고 싶은 경우
• 이미지·텍스트만 입력하고 레이아웃은 템플릿에 맡기는 경우
• 여러 페이지를 다양한 템플릿(갤러리/베이스 레이어/간지/발행면 등)으로 조합하고 싶은 경우

지원 creationType

PDF_UPLOAD 방식은 표지·내지 모두 PDF 직접 업로드로 진행하며, 이 페이지의 템플릿 엔드포인트(/cover, /contents, /photos)는 사용할 수 없습니다.Books — PDF 기반을 참고하세요.

책 생성

새로운 책을 생성합니다. 생성 직후 status="draft" 상태이며, 이후 표지·내지 추가와 명시적인 최종화 단계를 거쳐 주문 가능 상태로 진입합니다.

Request Body

Request 예시

{
  "title": "일기장 샘플",
  "bookSpecUid": "SQUAREBOOK_HC",
  "creationType": "TEMPLATE",
  "externalRef": "PARTNER-ORDER-001"
}

{
  "title": "혼합 방식 샘플",
  "bookSpecUid": "SQUAREBOOK_HC",
  "creationType": "MIX_COVER_TEMPLATE",
  "pageCount": 24,
  "externalRef": "PARTNER-ORDER-002"
}

curl -X POST 'https://api-sandbox.sweetbook.com/v1/books' \
  -H 'Authorization: Bearer {YOUR_API_KEY}' \
  -H 'Idempotency-Key: unique-request-id-001' \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "일기장 샘플",
    "bookSpecUid": "SQUAREBOOK_HC",
    "creationType": "TEMPLATE",
    "externalRef": "PARTNER-ORDER-001"
  }'

응답 필드

Response 예시

{
  "success": true,
  "message": "책 생성 완료",
  "data": {
    "bookUid": "bk_3k2S********",
    "pageMeta": {
      "currentPageCount": 0,
      "pageMin": 24,
      "pageMax": 200,
      "pageIncrement": 1,
      "isValid": false
    }
  }
}

pageMeta: TEMPLATE 방식은 생성 직후 currentPageCount=0, isValid=false로 시작합니다. 콘텐츠 추가(POST /books/{bookUid}/contents) 호출에 따라 자동 증가합니다. MIX_COVER_TEMPLATE은 요청의 pageCount 값이 currentPageCount로 반영됩니다. isValid는 페이지 제약만 판정하며, finalize 가능 여부는 표지·내지 존재 여부 등 다른 조건도 포함되므로 POST /finalization 호출로 최종 확인하세요.

HTTP 상태 코드

본 엔드포인트의 주요 검증 실패 메시지(400 ERR_VALIDATION_FAILED):

• creationType 누락 또는 허용되지 않은 값 — errors[0]: "유효하지 않은 creationType: <값> (허용: TEMPLATE, PDF_UPLOAD, MIX_COVER_TEMPLATE)"
• MIX_COVER_TEMPLATE인데 pageCount 누락 — errors[0]: "creation_type=MIX_COVER_TEMPLATE는 pageCount(내지 페이지수)가 필수입니다."

TEMPLATE은 pageCount가 필요 없으므로 누락해도 에러가 발생하지 않으며, 값을 포함해도 서버에서 무시됩니다(실제 저장값은 0). 응답 6필드 shape, 다른 errorCode, 처리 가이드는 에러 코드 & 트러블슈팅을 참조하세요.

표지 추가

지정한 표지 템플릿에 이미지·텍스트를 바인딩하여 책의 표지를 생성합니다. 이미지는 위 이미지 처리 → 이미지 전달 방식 섹션의 3가지 방식 중 어느 것으로든 제공할 수 있고, 한 요청에서 혼용도 가능합니다.

Request — multipart/form-data

템플릿의 변수 목록과 필수 여부는 Templates API의 템플릿 상세 조회로 확인할 수 있습니다. 템플릿 구조와 바인딩 동작 원리는 템플릿 구조와 바인딩을 참고하세요.

Request 예시

curl -X POST 'https://api-sandbox.sweetbook.com/v1/books/{bookUid}/cover' \
  -H 'Authorization: Bearer {YOUR_API_KEY}' \
  -F 'templateUid=79yjMH3qRPly' \
  -F 'coverPhoto=@front.jpg' \
  -F 'parameters={"title":"나의 하루 기록","dateRange":"26.01 - 26.04","coverPhoto":"$upload"}'

curl -X POST 'https://api-sandbox.sweetbook.com/v1/books/{bookUid}/cover' \
  -H 'Authorization: Bearer {YOUR_API_KEY}' \
  -F 'templateUid=79yjMH3qRPly' \
  -F 'parameters={"title":"나의 하루 기록","coverPhoto":"https://example.com/front.jpg"}'

curl -X POST 'https://api-sandbox.sweetbook.com/v1/books/{bookUid}/cover' \
  -H 'Authorization: Bearer {YOUR_API_KEY}' \
  -F 'templateUid=79yjMH3qRPly' \
  -F 'parameters={"title":"나의 하루 기록","coverPhoto":"photo250105143052123.JPG"}'

응답 필드

Response 예시

{
  "success": true,
  "message": "표지가 생성되었습니다",
  "data": {
    "result": "inserted",
    "pageMeta": {
      "currentPageCount": 0,
      "pageMin": 24,
      "pageMax": 200,
      "pageIncrement": 1,
      "isValid": false
    }
  }
}

표지는 내지 카운트(currentPageCount)에 포함되지 않으므로 표지 추가 후에도 값이 변하지 않습니다. pageMeta는 현재 내지 상태를 보고용으로 함께 노출됩니다.

HTTP 상태 코드

본 엔드포인트의 주요 검증 실패 메시지(400 ERR_VALIDATION_FAILED):

• 이미 표지가 등록됨 — errors[0]: "이미 표지가 존재합니다"
• 필수 이미지 파라미터 누락 — errors[0]: "필수 이미지 파라미터 '<name>' (<설명>)이 제공되지 않았습니다. form-data에 파일을 첨부하거나 parameters에 URL 또는 서버 파일명을 제공해야 합니다."

파라미터 이름(예: coverPhoto)과 설명(예: 앞표지 메인 사진)은 템플릿에 따라 달라집니다. Templates API에서 해당 템플릿의 필수 변수 목록을 먼저 확인하세요. 응답 6필드 shape, 다른 errorCode, 처리 가이드는 에러 코드 & 트러블슈팅을 참조하세요.

콘텐츠(내지) 추가

지정한 콘텐츠(내지) 템플릿에 이미지·텍스트를 바인딩하여 페이지를 추가합니다. 한 번 호출에 한 콘텐츠가 추가되며, 여러 페이지를 만들려면 반복 호출합니다. 이미지 전달 방식은 위 이미지 처리 → 이미지 전달 방식 섹션과 동일합니다.

Request — multipart/form-data

템플릿 종류와 변수 정보는 Templates API에서, 레이아웃 동작 원리(이어붙기 vs 새 페이지)는 레이아웃 동작 원리를 참고하세요. 갤러리 템플릿(다수 이미지 배치)은 갤러리 템플릿을 참고하세요.

Request 예시

curl -X POST 'https://api-sandbox.sweetbook.com/v1/books/{bookUid}/contents?breakBefore=page' \
  -H 'Authorization: Bearer {YOUR_API_KEY}' \
  -F 'templateUid=46VqZhVNOfAp' \
  -F 'photo=@image1.jpg' \
  -F 'parameters={"monthNum":"04","dayNum":"14","diaryText":"오늘의 일기","photo":"$upload"}'

curl -X POST 'https://api-sandbox.sweetbook.com/v1/books/{bookUid}/contents' \
  -H 'Authorization: Bearer {YOUR_API_KEY}' \
  -F 'templateUid=46VqZhVNOfAp' \
  -F 'parameters={"monthNum":"04","dayNum":"14","diaryText":"오늘의 일기","photo":"https://example.com/photo.jpg"}'

curl -X POST 'https://api-sandbox.sweetbook.com/v1/books/{bookUid}/contents' \
  -H 'Authorization: Bearer {YOUR_API_KEY}' \
  -F 'templateUid={GALLERY_TEMPLATE_UID}' \
  -F 'parameters={"date":"2026-04-22","galleryPhotos":["https://example.com/1.jpg","https://example.com/2.jpg","https://example.com/3.jpg"]}'

응답 필드

Response 예시

{
  "success": true,
  "message": "내지가 생성되었습니다",
  "data": {
    "result": "inserted",
    "breakBefore": "page",
    "pageNum": 1,
    "pageSide": "right",
    "pageMeta": {
      "currentPageCount": 1,
      "pageMin": 24,
      "pageMax": 200,
      "pageIncrement": 1,
      "isValid": false
    }
  }
}

{
  "success": true,
  "message": "내지가 갱신되었습니다",
  "data": {
    "result": "updated",
    "breakBefore": "none",
    "pageNum": 2,
    "pageSide": "right",
    "pageMeta": {
      "currentPageCount": 2,
      "pageMin": 24,
      "pageMax": 200,
      "pageIncrement": 1,
      "isValid": false
    }
  }
}

HTTP 상태 코드

본 엔드포인트의 주요 검증 실패 메시지(400 ERR_VALIDATION_FAILED):

• 이미 최종화된 책 — errors[0]: "이미 최종화된 책입니다. 콘텐츠를 추가할 수 없습니다."
• 필수 이미지 파라미터 누락 — errors[0]: "필수 이미지 파라미터 '<name>' (<설명>)이 제공되지 않았습니다. form-data에 파일을 첨부하거나 parameters에 URL 또는 서버 파일명을 제공해야 합니다."
• 간지/발행면 템플릿에 잘못된 breakBefore — errors[0]: "template_kind='divider'인 특수 페이지에서는 breakBefore='none'를 사용할 수 없습니다. 'page'만 허용됩니다."

파라미터 이름과 설명은 템플릿에 따라 달라집니다. Templates API에서 해당 템플릿의 필수 변수 목록을 먼저 확인하세요. 간지(templateKind=divider)·발행면(templateKind=publish) 템플릿은 breakBefore를 생략하거나 page만 명시해야 합니다. 일반 내지(templateKind=content)는 세 값 모두 허용됩니다. 응답 6필드 shape, 다른 errorCode, 처리 가이드는 에러 코드 & 트러블슈팅을 참조하세요.

책 최종화

표지·콘텐츠(내지) 추가를 마친 뒤 이 엔드포인트를 호출해 책을 최종화합니다. 호출 시 책의 status가 draft에서 finalized로 전환되어 주문 가능 상태가 됩니다.

Request

요청 본문은 비어 있습니다. 다만 IIS 환경 특성상 Content-Length: 0 헤더가 필요합니다 (없으면 411 Length Required).

Request 예시

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

응답 필드

result 값 조건

파트너는 result 문자열 자체보다 응답 상태 코드(2xx)와 pageMeta.currentPageCount/finalizedAt 값으로 성공 여부를 확인하는 것을 권장합니다.

Response 예시

{
  "success": true,
  "message": "책 최종화 완료",
  "data": {
    "result": "페이지를 추가하고 완료",
    "pageMeta": {
      "currentPageCount": 26,
      "pageMin": 24,
      "pageMax": 200,
      "pageIncrement": 1,
      "isValid": true
    },
    "finalizedAt": "2026-04-14T07:15:44.613Z"
  }
}

{
  "success": true,
  "message": "이미 최종화된 책입니다",
  "data": {
    "result": "updated",
    "pageMeta": {
      "currentPageCount": 26,
      "pageMin": 24,
      "pageMax": 200,
      "pageIncrement": 1,
      "isValid": true
    },
    "finalizedAt": "2026-04-14T07:15:44.613Z"
  }
}

전제조건별 에러코드 매핑

finalize 호출 시 전제조건을 충족하지 못하면 아래 표대로 errorCode + fieldErrors가 반환됩니다. 클라이언트는 fieldErrors[].field·fieldErrors[].constraint로 누락 항목을 식별해 사용자에게 안내하세요.

여러 전제조건이 동시에 깨지면 fieldErrors에 항목들이 함께 반환됩니다. 응답 예시는 위 "주요 에러 응답"과 페이지 제약 위반 에러 섹션을 참조하세요.

HTTP 상태 코드

book.pdfStatus 값

책 조회(GET /books) 응답의 pdfStatus 필드는 PDF 처리 상태를 나타내는 정수값입니다. TEMPLATE 방식은 finalize 후 시스템이 PDF를 비동기 렌더링하므로, finalize 직후엔 1(PENDING) 상태에서 2(COMPLETED)로 전환됩니다. 파트너는 일반적으로 책의 status 필드 또는 주문 상태 흐름의 PDF_READY 전환을 기준으로 처리하면 충분합니다.

본 엔드포인트의 finalize 특화 에러:

• 콘텐츠 미추가 상태에서 finalize 호출 — 400 ERR_FINALIZE_PREREQ_UNMET, fieldErrors[0].field: "contents"·constraint: "required". POST /books/{bookUid}/contents로 최소 1개 이상의 내지를 추가한 뒤 finalize를 호출하세요.
• 페이지 수 규칙 위반 — 판형의 pageMin/pageMax/pageIncrement 검증. 응답 예시는 아래 페이지 제약 위반 에러 섹션을 참조하세요.

응답 6필드 shape, 다른 errorCode, 처리 가이드는 에러 코드 & 트러블슈팅을 참조하세요.

이미지 처리

템플릿 표지·내지 추가 시 사용할 이미지를 어떻게 전달하고, 어떤 제약이 있는지 다룹니다. 본 묶음은 표지(POST /cover)·내지(POST /contents) 추가 단계의 사전 정보입니다.

이미지 전달 방식 (3가지, 혼용 가능)

표지·내지 추가 요청에서 이미지는 다음 3가지 방식 중 어느 것으로든 제공할 수 있고, 한 요청에서 혼용할 수도 있습니다. 템플릿의 이미지 필드명($변수명$)과 요청 필드명이 일치해야 합니다.

혼합 방식과 순서 제어 ($upload 플레이스홀더)

한 요청에서 위 3가지 방식을 섞어 쓸 수 있습니다. parameters의 배열 필드에 $upload 플레이스홀더를 넣으면 multipart로 첨부한 파일이 해당 위치에 차례로 들어갑니다.

{
  "photos": [
    "$upload",
    "https://example.com/photo2.jpg",
    "photo250105143052123.JPG",
    "$upload"
  ]
}

위 예시는 첫 번째 업로드 파일 → URL 이미지 → 사전 업로드한 서버 파일 → 두 번째 업로드 파일 순으로 배치됩니다. multipart로 첨부한 파일이 $upload 등장 순서대로 매핑됩니다.

EXIF 정보

업로드된 이미지의 EXIF 정보는 항상 보존됩니다. EXIF 보존 여부를 제어하는 별도 파라미터는 제공하지 않습니다.

파일 업로드 제한 (이미지)

표지·내지 추가 요청의 multipart 파일 첨부, 사진 사전 업로드, URL 다운로드 모두에 동일한 이미지 제약이 적용됩니다.

파일 검증

• 매직 바이트 검증: 파일 확장자뿐만 아니라 매직 바이트(파일 시그니처)를 확인하여 실제 이미지 파일인지 검증합니다. 확장자만 변경한 파일은 거부됩니다.
• 자동 포맷 변환: GIF·WebP는 PNG로, BMP·HEIC·HEIF는 JPG로 자동 변환되어 저장됩니다.
• EXIF 보존: EXIF 정보는 항상 보존됩니다.

Rate Limit 초과 시 429 응답과 Retry-After 헤더가 반환됩니다. 자세한 정책은 Rate Limiting 가이드를 참고하세요.

사진 사전 업로드 [선택]

이미지를 표지·내지 추가 요청에 직접 첨부하지 않고 미리 업로드해 서버 파일명을 받아두는 보조 API입니다.표지/내지 추가 요청에 이미지를 직접 첨부(방식 ①)하거나 URL로 전달(방식 ②)한다면 이 단계는 생략 가능합니다. 여러 페이지에 같은 이미지를 반복 사용하거나, 다수 이미지를 한 번에 모아 업로드해두고 싶을 때 활용하세요.

호출 도메인 기준

사진 관련 4개 엔드포인트는 모두 API Key의 환경(Sandbox/Live)과 호출 도메인이 일치해야 합니다. 잘못된 조합으로 호출 시 403 ERR_ENV_MISMATCH가 반환됩니다.

권한 매트릭스

파트너 관점에서 사진 4개 엔드포인트의 호출 가능 여부입니다.

사진 업로드

한 번에 한 장씩 업로드하며, 응답으로 서버가 발급한 고유 파일명을 받습니다. 이후 표지·내지 추가 요청의 parameters에 이 파일명을 사용해 이미지를 참조합니다.

Request — multipart/form-data

제약 사항

• 파일 크기: 50MB 이하 (초과 시 400)
• 책당 최대 200장: 한 책에 사전 업로드할 수 있는 사진은 최대 200장입니다. 초과 전에 사진 목록 조회로 현재 수량을 확인하세요
• 책 상태 제약: draft 상태의 책에만 업로드 가능합니다. finalized(최종화) 또는 deleted(삭제) 상태의 책에는 업로드할 수 없습니다 — 최종화 전에 필요한 사진을 모두 업로드하세요
• 지원 포맷: JPEG · PNG · GIF · WebP · BMP · HEIC · HEIF — 그 외 형식은 400 거부. 매직 바이트로 실제 형식을 검증하므로 확장자만 바꾼 파일은 거부됨

Request 예시

curl -X POST 'https://api-sandbox.sweetbook.com/v1/books/{bookUid}/photos' \
  -H 'Authorization: Bearer {YOUR_API_KEY}' \
  -F 'file=@photo1.jpg'

응답 필드

Response 예시

{
  "success": true,
  "message": "Photo uploaded successfully",
  "data": {
    "fileName": "photo260423001516528.JPG",
    "originalName": "cover.jpg",
    "size": 382229,
    "mimeType": "image/jpeg",
    "uploadedAt": "2026-04-23T00:15:19.136Z",
    "isDuplicate": false,
    "hash": "1baf5077ae9f5a13787a73a08625a802"
  }
}

HTTP 상태 코드

본 엔드포인트의 주요 검증 실패 메시지:

• 400 ERR_VALIDATION_FAILED 지원되지 않는 파일 형식 — errors[0]: "지원되지 않는 파일 형식입니다: <파일명>. (확장자: <확장자>)"
• 400 ERR_VALIDATION_FAILED 파일 크기 초과 — errors[0]: "파일 크기가 50MB를 초과합니다"
• 400 ERR_VALIDATION_FAILED 파일 누락 — errors[0]: "파일이 없습니다"
• 400 ERR_CREATION_TYPE_UNSUPPORTED PDF_UPLOAD 타입 책에 사진 업로드 시도 — errors[0]: "PDF_UPLOAD 타입 책에서는 지원하지 않는 API입니다."
• 403 ERR_ENV_MISMATCH 환경 불일치 — errors[0]: "환경 불일치: 호출 도메인과 API Key의 환경(sandbox/live)이 일치하지 않습니다. 키에 맞는 도메인으로 재시도하세요."

응답 6필드 shape, 다른 errorCode, 처리 가이드는 에러 코드 & 트러블슈팅을 참조하세요.

사진 목록 조회

해당 책에 사전 업로드한 사진 파일명 목록을 조회합니다.

Request 예시

curl -X GET 'https://api-sandbox.sweetbook.com/v1/books/{bookUid}/photos' \
  -H 'Authorization: Bearer {YOUR_API_KEY}'

응답 필드

사진 항목 필드 (data[])

Response 예시

{
  "success": true,
  "message": "Success",
  "data": [
    {
      "fileName": "photo260423001516528.JPG",
      "originalName": "cover.jpg",
      "size": 382229,
      "mimeType": "image/jpeg",
      "uploadedAt": "2026-04-23T00:15:18.977Z",
      "hash": "1baf5077ae9f5a13787a73a08625a802"
    }
  ],
  "pagination": {
    "total": 1,
    "limit": 100,
    "offset": 0,
    "hasNext": false
  }
}

HTTP 상태 코드

사진 삭제

사전 업로드한 사진을 삭제합니다. 응답 본문 없이 204 No Content를 반환합니다.

Path 파라미터

Request 예시

curl -X DELETE 'https://api-sandbox.sweetbook.com/v1/books/{bookUid}/photos/photo250105143052123.JPG' \
  -H 'Authorization: Bearer {YOUR_API_KEY}'

HTTP 상태 코드

사진 다운로드

업로드한 사진의 800px 썸네일 이미지 바이트를 반환합니다. 긴 변 기준으로 800px로 리사이즈된 썸네일이며, 원본(4000px)은 본 API로 제공되지 않습니다(내부 PDF 렌더링·인쇄 용도로만 사용). 업로드 정상 처리 여부 확인이나 사진 미리보기 UI 구성 용도로 사용하세요.

Path 파라미터

Request 예시

curl 'https://api-sandbox.sweetbook.com/v1/books/{bookUid}/photos/photo260424005709732.PNG' \
  -H 'Authorization: Bearer {YOUR_API_KEY}' \
  --output photo.png

응답 헤더

응답 본문

800px 썸네일 이미지 바이트 (바이너리). curl --output이나 파일 스트림으로 저장해 사용하세요.

Response 예시

HTTP/1.1 200 OK
Content-Type: image/png
Content-Length: 58217

<binary image bytes — 800px 썸네일>

HTTP 상태 코드

404 ERR_NOT_FOUND: 파일 없음 (삭제된 fileName 등) — errors[0]: "사진을 찾을 수 없습니다". 응답 shape 상세는 에러 코드 & 트러블슈팅 — ERR_NOT_FOUND를 참조하세요.

PDF 다운로드

책이 최종화되어 시스템이 표지·내지를 PDF로 렌더링한 뒤에는 다음 두 엔드포인트로 인쇄용 PDF를 다운로드할 수 있습니다.

• GET /books/{bookUid}/pdf-cover — 표지 PDF
• GET /books/{bookUid}/pdf-contents — 내지 PDF

정상 응답은 JSON이 아닌 application/pdf 바이너리 스트림입니다. 그 외 케이스는 6필드 JSON 에러 응답으로 errorCode·errors·fieldErrors가 포함됩니다.

curl -o cover.pdf \
  'https://api-sandbox.sweetbook.com/v1/books/{bookUid}/pdf-cover' \
  -H 'Authorization: Bearer {YOUR_API_KEY}'

curl -o contents.pdf \
  'https://api-sandbox.sweetbook.com/v1/books/{bookUid}/pdf-contents' \
  -H 'Authorization: Bearer {YOUR_API_KEY}'

응답 매트릭스 (그룹 B)

TEMPLATE 책의 PDF 다운로드는 책 상태(pdfStatus)에 따라 다음과 같이 분기됩니다. 클라이언트는 errorCode로 분기하며 errors[0]의 한글 메시지를 사용자에게 보여줄 수 있습니다.

공통 사전 검증

그룹 B 분기 응답 예시: 409 ERR_PDF_NOT_GENERATED (최종화 전) · 409 ERR_PDF_PENDING (생성 진행 중) · 422 ERR_PDF_GENERATION_FAILED (생성 실패) · 500 ERR_PDF_FILE_MISSING (서버 결함). 처리 가이드 포함 종합 안내는 에러 코드 & 트러블슈팅 — PDF 다운로드 분기를 참조하세요.

책 목록 조회

파트너가 생성한 책 목록을 조회합니다. 다양한 쿼리 파라미터로 필터링할 수 있으며, 페이지네이션을 지원합니다. 응답에는 PDF 방식·템플릿 방식 책이 모두 포함되며, creationType 필드로 구분할 수 있습니다.

Query 파라미터

페이지네이션 동작과 응답 구조(data.books 배열 + data.pagination 객체)는 페이지네이션 가이드를 참고하세요.

응답 필드

Response 예시

{
  "success": true,
  "message": "성공",
  "data": [
    {
      "bookUid": "bk_2dyG********",
      "accountUid": "u_b4b9********************",
      "title": "템플릿 방식 책",
      "author": null,
      "status": "draft",
      "pageCount": 0,
      "bookSpecUid": "SQUAREBOOK_HC",
      "specProfileUid": null,
      "creationType": "TEMPLATE",
      "createdAt": "2026-04-22T05:06:05.989Z",
      "updatedAt": "2026-04-22T05:06:05.989Z",
      "externalRef": null,
      "isTest": true,
      "pdfStatus": null,
      "pdfCreatedAt": null,
      "pdfRequestedAt": null,
      "thumbnailStatus": null
    },
    {
      "bookUid": "bk_2h4L********",
      "title": "PDF 업로드 샘플",
      "status": "finalized",
      "creationType": "PDF_UPLOAD",
      "pageCount": 24,
      "pdfStatus": 2,
      "pdfCreatedAt": "2026-04-22T07:46:24.000Z"
      /* ... 나머지 필드 생략 ... */
    }
  ],
  "pagination": {
    "total": 15,
    "limit": 5,
    "offset": 0,
    "hasNext": true
  }
}

HTTP 상태 코드

책 단건 조회

특정 책의 상세 정보를 조회합니다. v1.2에 신설된 RESTful 단건 조회 엔드포인트로, 편집 화면 진입이나 현재 페이지 수 제약 확인에 사용합니다. 응답에 pageMeta가 포함되어 "아직 N페이지 부족" 같은 힌트를 UI에 즉시 반영할 수 있습니다.

Path 파라미터

Request 예시

curl -X GET 'https://api-sandbox.sweetbook.com/v1/books/{bookUid}' \
  -H 'Authorization: Bearer {YOUR_API_KEY}'

응답 필드

Response 예시

{
  "success": true,
  "message": "성공",
  "data": {
    "bookUid": "bk_3k2S********",
    "accountUid": "u_b4b9********************",
    "title": "일기장 샘플",
    "bookSpecUid": "SQUAREBOOK_HC",
    "bookSpecName": "고화질 스퀘어북 (하드커버)",
    "specProfileUid": null,
    "creationType": "TEMPLATE",
    "status": 1,
    "coverTemplateUid": "tpl_cover_abc",
    "externalRef": "PARTNER-ORDER-001",
    "isTest": true,
    "pageMeta": {
      "currentPageCount": 18,
      "pageMin": 24,
      "pageMax": 200,
      "pageIncrement": 1,
      "isValid": false
    },
    "createdAt": "2026-04-22T03:00:00.000Z",
    "updatedAt": "2026-04-22T04:00:00.000Z"
  }
}

HTTP 상태 코드

단건 조회 vs 목록 조회 (bookUid 필터) 차이

기존 목록 조회의 bookUid 필터(GET /books?bookUid=...)와 본 단건 조회는 의미·응답 타입·권한 처리가 다릅니다. 용도에 맞게 선택하세요.

• 책 UID를 알고 있고 상세 정보(특히 pageMeta)가 필요하면 → 단건 조회
• 존재 여부만 빠르게 확인하거나 여러 조건과 조합해야 하면 → 목록 조회
• 없는 책과 권한 없는 책을 명확히 구별해야 하면 → 단건 조회 (목록은 둘 다 빈 배열로 동일)

404 ERR_NOT_FOUND: 존재하지 않는 bookUid — errors[0]: "책을 찾을 수 없습니다: bk_xxx". 응답 shape 상세는 에러 코드 & 트러블슈팅 — ERR_NOT_FOUND를 참조하세요.

페이지 제약 위반 에러

콘텐츠(내지) 추가·최종화 시 페이지 제약을 위반하면 아래 3종 에러 중 하나가 반환됩니다. fieldErrors[0].constraint로 어떤 제약이 위반됐는지 분기할 수 있습니다. 전체 에러 체계 상세는 에러 코드 & 트러블슈팅을 참고하세요.

• ERR_INSUFFICIENT_PAGES (constraint: "min") — finalize 시점에 최소 페이지 미달
• ERR_PAGECOUNT_INVALID (constraint: "max") — 콘텐츠 추가·finalize 시점에 최대 페이지 초과
• ERR_PAGECOUNT_INVALID (constraint: "increment") — 증분 규칙 위반. requiredValue는 {min, increment} 객체 형태

응답 예시(fieldErrors 배열에 currentValue·requiredValue·constraint 포함)는 errors 페이지의 각 errorCode 카드를 참조하세요: ERR_INSUFFICIENT_PAGES, ERR_PAGECOUNT_INVALID.

책 삭제

책을 삭제 처리합니다. 물리적 삭제가 아닌 소프트 삭제(상태값 변경)로 처리되어, 이후 목록 조회 결과에서 제외됩니다. 표지·콘텐츠 페이지·사전 업로드한 사진은 별도 정리되지 않고 보관 상태로 남으며, 책 자체에 대한 추가 작업(표지·콘텐츠 추가/수정/finalize/주문)은 모두 차단됩니다.

Path 파라미터

Request 예시

curl -X DELETE 'https://api-sandbox.sweetbook.com/v1/books/{bookUid}' \
  -H 'Authorization: Bearer {YOUR_API_KEY}'

응답 필드

Response 예시

{
  "success": true,
  "message": "책이 삭제되었습니다",
  "data": {
    "bookUid": "bk_3k2S********",
    "status": "deleted"
  }
}

HTTP 상태 코드

404 ERR_NOT_FOUND: 존재하지 않는 bookUid — 응답 shape 상세는 에러 코드 & 트러블슈팅 — ERR_NOT_FOUND를 참조하세요.

관련 문서

• 템플릿 기반 시나리오 — 책 생성부터 주문까지 단계별 흐름
• 혼합 방식 시나리오 — 표지=템플릿, 내지=PDF 흐름
• BookSpecs API — 판형 정보 (페이지 수 규칙 포함) 조회
• Templates API — 표지·내지 템플릿 목록 및 변수 정보 조회
• 템플릿 구조와 바인딩 — 변수, 파라미터, 이미지 매칭 동작 원리
• 레이아웃 동작 원리 — breakBefore, 페이지 흐름
• 갤러리 템플릿 — 다수 이미지 배치 (collageGallery, rowGallery)
• 베이스 레이어 — 표지·내지 공통 배경 레이어