홈▸개발문서▸책 생성 및 편집

Step 3: 책 생성 및 편집

책을 생성하고, 표지와 내지를 추가한 후 최종화하는 전체 과정을 안내합니다.

책 생성

POST /books로 새 책을 생성합니다. title과 bookSpecUid는 필수이며, 선택적으로 bookAuthor, specProfileUid, externalRef를 지정할 수 있습니다.

파라미터필수설명
titleO책 제목
bookSpecUidO상품 사양 UID (GET /book-specs에서 조회)
bookAuthor저자명
specProfileUid사양 프로필 UID
externalRef파트너 시스템의 내부 ID (매핑용)
bash
curl -X POST 'https://api-sandbox.sweetbook.com/v1/books' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "title": "나의 첫 포토북",
  "bookSpecUid": "SQUAREBOOK_HC",
  "bookAuthor": "홍길동",
  "externalRef": "partner-book-001"
}'
json
{
  "success": true,
  "message": "책 생성 완료",
  "data": {
    "bookUid": "bk_3dJTg8WOpR2e"
  }
}
Sandbox 환경: Sandbox에서는 creationType이 자동으로 TEST로 설정됩니다. 별도로 지정할 필요가 없습니다.

externalRef 활용 패턴

externalRef는 파트너 시스템의 내부 ID를 SweetBook의 책과 매핑하기 위한 필드입니다. 파트너 측 DB의 주문번호, 상품번호 등을 저장하면 양쪽 시스템 간의 데이터 추적이 용이합니다.

json
{
  "title": "졸업앨범 2025",
  "bookSpecUid": "SQUAREBOOK_HC",
  "externalRef": "my-system-order-12345"
}

이후 GET /books 응답에서 externalRef 값을 확인하여 파트너 시스템과 연동할 수 있습니다.

표지 추가

POST /books/{bookUid}/cover로 표지를 추가합니다. 템플릿 UID와 함께 앞표지/뒷표지 이미지를 업로드합니다.

bash
curl -X POST \
  'https://api-sandbox.sweetbook.com/v1/books/{bookUid}/cover' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: multipart/form-data' \
  -F 'frontPhoto=@front.jpg;type=image/jpeg' \
  -F 'backPhoto=@back.jpg;type=image/jpeg' \
  -F 'templateUid=COVER_TEMPLATE_UID' \
  -F 'parameters={"title":"나의 첫 포토북","author":"홍길동"}'
템플릿마다 요구하는 파라미터가 다릅니다. GET /templates/{templateUid}로 필수 파라미터를 확인하세요.

내지 추가 (반복)

POST /books/{bookUid}/contents로 내지 페이지를 추가합니다. 상품의 최소 페이지 수를 충족할 때까지 이 API를 반복 호출합니다.

파라미터위치설명
breakBeforeQuery페이지 나눔 방식 (예: page). 새 페이지에서 시작할지 제어
templateUidBody내지 템플릿 UID
filesBody이미지 파일 (multipart)
parametersBody템플릿 파라미터 (JSON)
bash
curl -X POST \
  'https://api-sandbox.sweetbook.com/v1/books/{bookUid}/contents?breakBefore=page' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: multipart/form-data' \
  -F 'files=@photo1.jpg;type=image/jpeg' \
  -F 'templateUid=CONTENT_TEMPLATE_UID' \
  -F 'parameters={"date":"2025-10-20","contents":"즐거운 여행의 시작"}'
여러 페이지를 빠르게 추가하려면 bash 반복문을 사용하세요. 지원 이미지 형식: JPG, PNG, GIF, BMP, WebP, HEIC (SVG 미지원)

내지 초기화

DELETE /books/{bookUid}/contents로 추가된 모든 내지 페이지를 삭제하고 처음부터 다시 시작할 수 있습니다. 표지는 유지됩니다.

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

페이지 수 관리

GET /books/{bookUid}로 현재 책의 상태와 페이지 수를 확인할 수 있습니다. 최종화 전에 상품의 최소 페이지 수를 충족하는지 반드시 확인하세요.

bash
curl -X GET 'https://api-sandbox.sweetbook.com/v1/books/{bookUid}' \
  -H 'Authorization: Bearer YOUR_API_KEY'
json
{
  "success": true,
  "data": {
    "bookUid": "bk_3dJTg8WOpR2e",
    "title": "나의 첫 포토북",
    "bookSpecUid": "SQUAREBOOK_HC",
    "externalRef": "partner-book-001",
    "pageCount": 28,
    "status": "EDITING",
    "creationType": "TEST",
    "createdAt": "2025-10-20T10:00:00Z"
  }
}
상품별 최소/최대 페이지 수는 GET /book-specs의 pageMin, pageMax에서 확인할 수 있습니다. 최소 페이지 수를 충족하지 않으면 최종화가 실패합니다.

책 최종화

POST /books/{bookUid}/finalization으로 편집을 완료합니다. 최종화가 완료된 책만 주문에 사용할 수 있습니다. 최소 페이지 수를 충족해야 합니다.

bash
curl -X POST \
  'https://api-sandbox.sweetbook.com/v1/books/{bookUid}/finalization' \
  -H 'Authorization: Bearer YOUR_API_KEY'
json
{
  "success": true,
  "message": "책 최종화 완료",
  "data": {
    "result": "페이지를 추가하지 않고 완료",
    "pageCount": 32,
    "finalizedAt": "2025-10-21T02:28:45.505Z"
  }
}

다음 단계