Books API — PDF 기반

파트너가 제작한 PDF 파일(표지·내지)을 직접 업로드하여 책을 생성하는 방식의 API 레퍼런스입니다. 템플릿 바인딩이 아닌 PDF 직접 업로드 흐름과 각 엔드포인트의 정확한 스펙을 다룹니다.

이 방식이 적합한 경우

• 이미 자체 제작한 PDF 파일이 있는 경우
• 인쇄용 PDF를 직접 디자인 도구(InDesign, Illustrator 등)로 제작하는 경우
• 레이아웃·폰트·이미지를 파트너가 완전히 제어하고 싶은 경우

지원 creationType

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

책 생성

새로운 책을 생성합니다. 생성 직후 status="draft" 상태이며, 이후 PDF 업로드와 최종화 단계를 거쳐 주문 가능 상태로 진입합니다.

Request Body

Request 예시

{
  "title": "PDF 업로드 샘플",
  "bookSpecUid": "SQUAREBOOK_HC",
  "creationType": "PDF_UPLOAD",
  "pageCount": 24,
  "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": "PDF 업로드 샘플",
    "bookSpecUid": "SQUAREBOOK_HC",
    "creationType": "PDF_UPLOAD",
    "pageCount": 24,
    "externalRef": "PARTNER-ORDER-001"
  }'

응답 필드

Response 예시

{
  "success": true,
  "message": "책 생성 완료",
  "data": {
    "bookUid": "bk_2h4L********",
    "pageMeta": {
      "currentPageCount": 24,
      "pageMin": 24,
      "pageMax": 130,
      "pageIncrement": 2,
      "isValid": true
    }
  }
}

pageMeta: PDF_UPLOAD·MIX_COVER_TEMPLATE 방식은 책 생성 시 pageCount를 입력받으므로 currentPageCount가 입력값과 동일하게 설정됩니다(예: pageCount: 24 → currentPageCount: 24). TEMPLATE 방식은 0으로 초기화됩니다. isValid는 pageMin ≤ currentPageCount ≤ pageMax 및 증분 규칙 만족 여부를 나타내며, 페이지 제약만 판정하고 표지·내지 PDF 업로드 여부는 별도입니다.

HTTP 상태 코드

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

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

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

PDF 파일 요건

표지·내지 PDF 업로드 시 PDF 형식·크기·페이지 수가 동기 검증됩니다. 검증에 실패하면 업로드가 차단됩니다(hard fail). 판형의 페이지 수 규칙은 그보다 앞서 책 생성 시 검증됩니다(아래 「페이지 수 규칙」). 업로드 전에 아래 요건을 충족하는지 확인하세요.

판형별 PDF 규격

정확한 PDF 규격(너비·높이 mm)은 판형(BookSpec)마다 다릅니다. 구조는 커버 타입(소프트/하드)에 따라 다음과 같이 분기되며, 실제 값은 GET /book-specs 또는 파트너 포털에서 확인하세요.

※ 제작 바코드는 표지 뒤표지의 왼쪽 아래와, 내지는 마지막 페이지(레이플랫은 마지막 펼침면) 한 곳의 왼쪽 아래에만 인쇄됩니다. 비워둘 영역은 PDF 표지/내지 사이즈 — 제작 바코드 영역을 참고하세요.

허용 오차

허용 오차는 판형의 pdfSize 정의값을 기준으로 적용됩니다. 대부분의 판형은 정의값과 정확히 일치(오차 0mm)하도록 설정되어 있습니다. 안전한 인쇄 품질을 위해 PDF 제작 시 다음 권고 마진 내로 제작하는 것을 권장합니다.

실제 허용치는 판형마다 다를 수 있습니다. 정의값 정확 일치를 목표로 제작하되, 위 권고 마진 내라면 일반적으로 안전합니다. 검증 실패 시 응답의 errors 배열에 실제 측정값과 허용 규격이 함께 표기됩니다.

공통 제약 (검증 실패 시 업로드 차단 — Hard Fail)

• 파일 형식: PDF (시그니처 %PDF- 확인)
• 파일 크기: 500MB 이하 (요청 크기 제한과 동일)
• PDF 구조 무결성: 손상되거나 파싱 불가능한 PDF는 차단
• 표지 페이지 수: 1페이지 고정
• 내지 페이지 수: 책 생성 시 지정한 pageCount와 정확히 일치
• PDF 크기(mm): 위 표의 권고 마진 내

페이지 수 규칙 (책 생성 시 검증)

책 생성(POST /books) 시 지정한 pageCount가 판형의 페이지 규칙을 벗어나면 책 생성이 400 에러로 거부됩니다(ERR_INSUFFICIENT_PAGES / ERR_PAGECOUNT_INVALID). 규칙을 벗어난 페이지 수로는 책이 만들어지지 않으므로 PDF 업로드·주문 단계까지 진행되지 않습니다.

예를 들어 SQUAREBOOK_HC에서 pageCount=25로 책을 생성하면pageIncrement=2 단위 규칙에 맞지 않으므로 책 생성이 400(ERR_PAGECOUNT_INVALID)으로 거부됩니다. 책 생성 시점부터 판형 범위 내·배수 조건을 충족하도록 지정하세요.

{
  "cover": [
    { "minPage": 24, "maxPage": 64, "width": 544, "height": 288 },
    { "minPage": 65, "maxPage": 130, "width": 550, "height": 288 }
  ],
  "inner": { "width": 249, "height": 254 }
}

{
  "cover": { "width": 332, "height": 216 },
  "inner": { "width": 148, "height": 210 }
}

400 ERR_VALIDATION_FAILED: PDF 규격 검증 실패 시 errors 배열에 위반 항목이 모두 포함됩니다 (예: "내지 PDF 페이지수 불일치: 올바른 페이지수 24p, 업로드된 페이지수 30p", "PDF 너비 불일치: 실제 148.0mm, 허용 규격 249mm (+/-1mm)", "PDF 높이 불일치: 실제 210.0mm, 허용 규격 254.0mm (+/-1mm)"). LAYFLAT 제본은 페이지수 메시지에 책 페이지 환산값이 괄호로 부가됩니다(예: "... (책 페이지 환산: 올바른 페이지수 16p, 업로드된 페이지수 20p)"). 응답 shape 상세는 에러 코드 & 트러블슈팅 — ERR_VALIDATION_FAILED를 참조하세요.

표지 PDF

표지 PDF는 1페이지 고정입니다. 신규 등록(POST), 교체(PUT), 다운로드(GET) 세 가지 엔드포인트를 제공합니다. 업로드/교체 동작은 동일한 검증을 거치며 응답 본문 구조도 같습니다 (HTTP 상태 코드와 메시지만 다름).

공통 응답 필드 (POST · PUT)

HTTP 상태 코드 (POST · PUT 공통)

표지 PDF 신규 등록

표지 PDF를 최초로 등록합니다. 이미 등록된 상태에서 호출하면 409 Conflict가 반환되며, 이 경우 PUT으로 교체해야 합니다. 검증은 동기로 수행되어 응답 본문에 결과가 포함됩니다.

Request — multipart/form-data

업로드 Rate Limit은 upload 정책(API Key 단위 200 req/분)이 적용됩니다. Rate Limiting 가이드 참고.

Request 예시

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

Response 예시

{
  "success": true,
  "message": "표지 PDF가 업로드되었습니다",
  "data": {
    "bookUid": "bk_2h4L********",
    "kind": "cover",
    "valid": true,
    "pdfSizeMm": { "width": 544, "height": 288 },
    "messages": [],
    "warnings": [],
    "bookStatus": 1,
    "url": "https://api-sandbox.sweetbook.com/v1/books/bk_2h4L********/pdf-cover",
    "pageMeta": {
      "currentPageCount": 24,
      "pageMin": 24,
      "pageMax": 130,
      "pageIncrement": 2,
      "isValid": true
    }
  }
}

409 ERR_CONFLICT: 이미 등록된 표지에 POST 재호출 시 — errors[0]: "표지 PDF가 이미 등록되어 있습니다. 교체하려면 PUT 메서드를 사용하세요." 응답 shape 상세는 에러 코드 & 트러블슈팅 — ERR_CONFLICT를 참조하세요.

표지 PDF 교체

이미 등록된 표지 PDF를 교체합니다. 등록되지 않은 상태에서 호출하면 404가 반환되며, 이 경우 POST로 신규 등록해야 합니다.

Request — multipart/form-data

신규 등록(POST)과 동일한 파라미터를 사용합니다.

Request 예시

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

Response 예시

{
  "success": true,
  "message": "표지 PDF가 교체되었습니다",
  "data": {
    "bookUid": "bk_krW7********",
    "kind": "cover",
    "valid": true,
    "pdfSizeMm": { "width": 544, "height": 288 },
    "messages": [],
    "warnings": [],
    "bookStatus": 1,
    "url": "https://api-sandbox.sweetbook.com/v1/books/bk_krW7********/pdf-cover",
    "pageMeta": {
      "currentPageCount": 24,
      "pageMin": 24,
      "pageMax": 130,
      "pageIncrement": 2,
      "isValid": true
    }
  }
}

주요 에러: 404 ERR_NOT_FOUND 등록되지 않은 상태에서 PUT 호출 (errors[0]: "표지 PDF가 등록되어 있지 않습니다. 신규 등록은 POST 메서드를 사용하세요.") · 400 ERR_VALIDATION_FAILED 제작 확정 이후 교체 시도 (errors[0]: "제작 확정된 주문이 있어 PDF 교체가 불가합니다."). 응답 shape 상세는 에러 코드 & 트러블슈팅을 참조하세요.

표지 PDF 다운로드

저장된 표지 PDF를 다운로드합니다. 정상 응답은 JSON이 아닌 application/pdf 바이너리 스트림입니다.

응답 매트릭스

그룹 A — PDF_UPLOAD 책의 표지

그룹 B — MIX_COVER_TEMPLATE 책의 표지

공통 사전 검증

클라이언트 권장 행동

• ERR_PDF_NOT_UPLOADED (그룹 A): 해당 kind의 PDF를 업로드.
• ERR_PDF_NOT_GENERATED (그룹 B): POST /books/{bookUid}/finalization 호출 후 재시도.
• ERR_PDF_PENDING (그룹 B): 일정 간격(예: 10초~수십 초) 후 재시도. 무한 폴링 금지. 본 응답에는 Retry-After 헤더가 포함되지 않으므로 클라이언트가 자체 대기 간격을 결정해야 합니다.
• ERR_PDF_GENERATION_FAILED (그룹 B): 클라이언트 자체 해결 불가 — 사용자에게 실패 안내 + 고객지원팀 문의.
• ERR_PDF_FILE_MISSING (그룹 B): 서버 측 결함 — 고객지원팀 문의.

URL은 응답 본문이 아닌 표지 업로드 응답의 data.url 필드를 통해 확인할 수 있으며, 호출 도메인(api-sandbox.sweetbook.com / api.sweetbook.com)이 자동 적용됩니다.

Request 예시

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

출처별 errorCode 분기: creationType에 따라 그룹 A(PDF_UPLOAD·MIX 내지 — 404 ERR_PDF_NOT_UPLOADED) / 그룹 B(TEMPLATE·MIX 표지 — 409 ERR_PDF_NOT_GENERATED·ERR_PDF_PENDING·422 ERR_PDF_GENERATION_FAILED·500 ERR_PDF_FILE_MISSING). 응답 예시·처리 가이드는 에러 코드 & 트러블슈팅 — PDF 다운로드 분기를 참조하세요.

내지 PDF

내지 PDF는 책 생성 시 지정한 pageCount와 페이지 수가 정확히 일치해야 합니다. 표지와 마찬가지로 신규 등록(POST), 교체(PUT), 다운로드(GET) 세 엔드포인트를 제공하며, 응답 본문 구조는 표지와 동일합니다.

공통 응답 필드 (POST · PUT)

구조는 표지 PDF의 공통 응답 필드와 동일합니다 (bookUid / kind / valid / pageMeta / pdfSizeMm / messages / warnings / bookStatus / url). 내지의 경우 kind 값이 "contents"이고, 업로드 PDF의 페이지 수는 책 생성 시 지정한 pageCount와 정확히 일치해야 합니다 (불일치 시 400).

HTTP 상태 코드 (POST · PUT 공통)

표지와 동일합니다. POST 신규는 201 Created (이미 등록 시 409), PUT 교체는 200 OK (미등록 시 404, 제작 확정 후 400).환경(Sandbox/Live) 불일치 시 400도 표지와 동일하게 적용됩니다 — 표지 섹션의 환경 불일치 안내 박스를 참고하세요.

내지 PDF 신규 등록

내지 PDF를 최초로 등록합니다. 책 생성 시 지정한 pageCount와 PDF의 실제 페이지 수가 정확히 일치하지 않으면 400으로 차단됩니다.

Request — multipart/form-data

경고(warnings) 발생 조건

아래 조건이면 업로드 응답의 warnings 배열에 메시지가 포함됩니다. 다만 PDF 방식은 책 생성 시 같은 페이지 규칙을 이미 검증하므로(위 「페이지 수 규칙」) 일반적으로 발생하지 않습니다.

• 페이지 수가 판형의 pageMin 미만
• 페이지 수가 판형의 pageMax 초과
• 페이지 수가 판형의 pageIncrement의 배수가 아님

Request 예시

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'

Response 예시

{
  "success": true,
  "message": "내지 PDF가 업로드되었습니다",
  "data": {
    "bookUid": "bk_2h4L********",
    "kind": "contents",
    "valid": true,
    "pdfSizeMm": { "width": 249, "height": 254 },
    "messages": [],
    "warnings": [],
    "bookStatus": 1,
    "url": "https://api-sandbox.sweetbook.com/v1/books/bk_2h4L********/pdf-contents",
    "pageMeta": {
      "currentPageCount": 24,
      "pageMin": 24,
      "pageMax": 130,
      "pageIncrement": 2,
      "isValid": true
    }
  }
}

pageMeta.currentPageCount는 내지 PDF 실제 페이지 수를 반영합니다. 기존 pageCount 필드는 v1.2에서 제거됐으며 pageMeta.currentPageCount로 대체됐습니다.

주요 에러: 400 ERR_VALIDATION_FAILED 페이지 수 불일치 (errors[0]: "내지 PDF 페이지수 불일치: 올바른 페이지수 24p, 업로드된 페이지수 30p". LAYFLAT 제본은 책 페이지 환산값이 괄호로 부가) · 409 ERR_CONFLICT 이미 등록됨 (errors[0]: "내지 PDF가 이미 등록되어 있습니다. 교체하려면 PUT 메서드를 사용하세요."). 응답 shape 상세는 에러 코드 & 트러블슈팅을 참조하세요.

내지 PDF 교체

등록된 내지 PDF를 교체합니다. 표지 교체와 동일하게 제작 확정(CONFIRMED) 이후에는 차단됩니다. 교체 시에도 책 생성 시 지정한 pageCount와 일치해야 합니다 (책의 pageCount는 변경되지 않음).

Request — multipart/form-data

신규 등록(POST)과 동일한 파라미터를 사용합니다.

Request 예시

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

Response 예시

{
  "success": true,
  "message": "내지 PDF가 교체되었습니다",
  "data": {
    "bookUid": "bk_2h4L********",
    "kind": "contents",
    "valid": true,
    "pdfSizeMm": { "width": 249, "height": 254 },
    "messages": [],
    "warnings": [],
    "bookStatus": 1,
    "url": "https://api-sandbox.sweetbook.com/v1/books/bk_2h4L********/pdf-contents",
    "pageMeta": {
      "currentPageCount": 24,
      "pageMin": 24,
      "pageMax": 130,
      "pageIncrement": 2,
      "isValid": true
    }
  }
}

404 ERR_NOT_FOUND: 등록되지 않은 상태에서 PUT 호출 — errors[0]: "내지 PDF가 등록되어 있지 않습니다. 신규 등록은 POST 메서드를 사용하세요." 응답 shape 상세는 에러 코드 & 트러블슈팅 — ERR_NOT_FOUND를 참조하세요.

내지 PDF 다운로드

저장된 내지 PDF를 다운로드합니다. 정상 응답은 JSON이 아닌 application/pdf 바이너리 스트림입니다.

응답 매트릭스 (그룹 A)

공통 사전 검증

Request 예시

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

404 ERR_PDF_NOT_UPLOADED: 내지 PDF 미업로드 (그룹 A) — errors[0]: "PDF 파일이 업로드되지 않았습니다." 응답 shape·다른 errorCode·처리 가이드는 에러 코드 & 트러블슈팅 — ERR_PDF_NOT_UPLOADED를 참조하세요.

책 최종화

표지·내지 PDF 업로드를 마친 뒤 이 엔드포인트를 호출해 책을 최종화합니다. 호출 시 책의 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'

응답 필드

이미 FINALIZED 상태에서 다시 호출하면 200 OK + message: "이미 최종화된 책입니다" + result: "updated"로 멱등 응답합니다 (실제 상태 재변경은 일어나지 않음).

Response 예시

{
  "success": true,
  "message": "책 최종화 완료",
  "data": {
    "result": "created",
    "pageMeta": {
      "currentPageCount": 24,
      "pageMin": 24,
      "pageMax": 130,
      "pageIncrement": 2,
      "isValid": true
    },
    "finalizedAt": "2026-04-22T07:46:24.099Z"
  }
}

{
  "success": true,
  "message": "이미 최종화된 책입니다",
  "data": {
    "result": "updated",
    "pageMeta": {
      "currentPageCount": 24,
      "pageMin": 24,
      "pageMax": 130,
      "pageIncrement": 2,
      "isValid": true
    },
    "finalizedAt": "2026-04-22T07:46:24.099Z"
  }
}

전제조건별 에러코드 매핑

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

여러 전제조건이 동시에 깨지면 fieldErrors에 항목들이 함께 반환됩니다(예: 표지·내지 PDF 둘 다 없으면 두 항목 모두 포함). 응답 예시는 위 페이지 제약 위반 에러 섹션과 케이스 C(ERR_FINALIZE_PREREQ_UNMET 다중 필드)를 참조하세요.

HTTP 상태 코드

book.pdfStatus 값

책 조회(GET /books) 응답에 포함되는 pdfStatus 필드는 PDF 처리 상태를 나타내는 정수값입니다. 파트너는 일반적으로 책의 status 필드만 참조하면 충분하며, pdfStatus는 PDF 준비 완료 여부를 직접 확인하고 싶을 때 부가 정보로 활용할 수 있습니다.

400 ERR_FINALIZE_PREREQ_UNMET: 표지/내지 PDF 미업로드 등 전제조건 미충족. 위의 전제조건별 에러코드 매핑 표가 정확한 매핑을 제공하며, 표지만 업로드되고 내지가 없으면 fieldErrors에 contentsPdf만, 반대면 coverPdf만 포함됩니다. 응답 예시(다중 fieldErrors)와 처리 가이드는 에러 코드 & 트러블슈팅 — ERR_FINALIZE_PREREQ_UNMET를 참조하세요.

책 목록 조회

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

Query 파라미터

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

Request 예시

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

curl -X GET 'https://api-sandbox.sweetbook.com/v1/books?status=finalized&pdfStatus=2&limit=20' \
  -H 'Authorization: Bearer {YOUR_API_KEY}'

응답 필드

Response 예시

{
  "success": true,
  "message": "성공",
  "data": [
    {
      "bookUid": "bk_2h4L********",
      "accountUid": "u_b4b9********************",
      "title": "PDF 업로드 샘플",
      "author": null,
      "status": "finalized",
      "pageCount": 24,
      "bookSpecUid": "SQUAREBOOK_HC",
      "specProfileUid": null,
      "creationType": "PDF_UPLOAD",
      "createdAt": "2026-04-22T07:45:05.759Z",
      "updatedAt": "2026-04-22T07:46:24.099Z",
      "externalRef": "PARTNER-ORDER-001",
      "isTest": true,
      "pdfStatus": 2,
      "pdfCreatedAt": "2026-04-22T07:46:24.000Z",
      "pdfRequestedAt": null,
      "thumbnailStatus": null
    },
    {
      "bookUid": "bk_5EdC********",
      "title": "DRAFT 상태 PDF 책",
      "status": "draft",
      "creationType": "PDF_UPLOAD",
      "pageCount": 24,
      "pdfStatus": null,
      "pdfCreatedAt": null
      /* ... 나머지 필드 생략 ... */
    }
  ],
  "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_2h4L********",
    "accountUid": "u_b4b9********************",
    "title": "PDF 업로드 샘플",
    "bookSpecUid": "SQUAREBOOK_HC",
    "bookSpecName": "고화질 스퀘어북 (하드커버)",
    "specProfileUid": null,
    "creationType": "PDF_UPLOAD",
    "status": 1,
    "coverTemplateUid": null,
    "externalRef": "PARTNER-ORDER-001",
    "isTest": true,
    "pageMeta": {
      "currentPageCount": 24,
      "pageMin": 24,
      "pageMax": 130,
      "pageIncrement": 2,
      "isValid": true
    },
    "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를 참조하세요.

페이지 제약 위반 에러

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

• ERR_INSUFFICIENT_PAGES (constraint: "min") — 최소 페이지 미달
• ERR_PAGECOUNT_INVALID (constraint: "max") — 최대 페이지 초과
• ERR_PAGECOUNT_INVALID (constraint: "increment") — 증분 규칙 위반. requiredValue는 {min, increment} 객체 형태

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

책 삭제

책을 삭제 처리합니다. 물리적 삭제가 아닌 소프트 삭제(상태값 변경)로 처리되어, 이후 목록 조회 결과에서 제외됩니다. 업로드한 PDF 파일은 별도 정리되지 않고 보관 상태로 남으며, 책 자체에 대한 추가 작업(업로드/교체/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_2h4L********",
    "status": "deleted"
  }
}

HTTP 상태 코드

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

관련 문서

• PDF 업로드 시나리오 — 책 생성부터 주문까지 단계별 흐름
• 혼합 방식 시나리오 — 표지=템플릿, 내지=PDF 흐름
• BookSpecs API — 판형 정보 (PDF 규격 포함) 조회
• Orders API — 책 주문 생성, 상태 추적, 취소