전체 워크플로우

Book Print API는 두 가지 방식으로 포토북을 제작할 수 있습니다. 파트너 환경에 맞는 방식을 선택하세요.

방식 선택

PDF 업로드 워크플로우

이미 제작된 PDF를 업로드하여 포토북을 만드는 방식입니다.

1. 책 생성 — POST /books

   creationType="PDF_UPLOAD" + pageCount 지정

2. 표지 업로드 — POST /books/{bookUid}/pdf-cover · PUT /books/{bookUid}/pdf-cover

   표지 PDF 파일 업로드 (크기 자동 검증). POST=신규(409 if exists) / PUT=교체(404 if missing)

3. 내지 업로드 — POST /books/{bookUid}/pdf-contents · PUT /books/{bookUid}/pdf-contents

   내지 PDF 파일 업로드 (페이지 수 검증). POST/PUT 동일 규약

4. 책 최종화 — POST /books/{bookUid}/finalization

   표지·내지 PDF 업로드를 마친 뒤 호출. 책이 FINALIZED 상태로 전환되어 주문 가능

5. 주문 생성 — POST /orders

   주문 생성 및 충전금 차감

6. 상태 추적 — Webhook

   주문 상태 변경 알림 수신

시퀀스 다이어그램

템플릿 기반 워크플로우

제공되는 템플릿에 텍스트와 이미지를 전달하여 포토북을 구성하는 방식입니다.

1. 책 생성 — POST /books

   DRAFT 상태의 빈 책 생성

2. 표지 추가 — POST /books/{bookUid}/cover

   표지 템플릿 적용 + 이미지/텍스트 바인딩

3. 내지 추가 — POST /books/{bookUid}/contents

   내지 템플릿 적용. 반복 호출하여 페이지 추가

4. 책 최종화 — POST /books/{bookUid}/finalization

   DRAFT → FINALIZED. 페이지 수 규칙 검증

5. 주문 생성 — POST /orders

   주문 생성 및 충전금 차감

6. 상태 추적 — Webhook

   주문 상태 변경 알림 수신

시퀀스 다이어그램

혼합 방식 워크플로우

표지는 템플릿으로 적용하고 내지는 PDF로 직접 업로드하는 방식입니다.

1. 책 생성 — POST /books

   creationType="MIX_COVER_TEMPLATE" + pageCount 지정

2. 표지 템플릿 적용 — POST /books/{bookUid}/cover

   표지 템플릿 + 이미지/텍스트 바인딩 (PDF 표지는 차단)

3. 내지 PDF 업로드 — POST /books/{bookUid}/pdf-contents · PUT /books/{bookUid}/pdf-contents

   내지 PDF 파일 업로드 (POST=신규, PUT=교체). 템플릿 내지는 차단

4. 책 최종화 — POST /books/{bookUid}/finalization

   표지·내지 입력 후 호출. 책이 FINALIZED 상태로 전환되어 주문 가능

5. 주문 생성 — POST /orders

   주문 생성 및 충전금 차감. 표지 렌더링 후 PDF_READY로 전환

6. 상태 추적 — Webhook

   주문 상태 변경 알림 수신

시퀀스 다이어그램

핵심 제약 조건

책 상태 규칙

• DRAFT: 표지/내지 추가, 사진 업로드 가능. 편집은 이 상태에서만 가능.
• FINALIZED: 최종화 완료. 더 이상 편집 불가. 주문은 이 상태에서만 가능.

페이지 수 규칙

최종화 시 다음 조건을 모두 만족해야 합니다:

• actualPageCount >= pageMin — 실제 페이지 수가 최소 페이지 수 이상
• actualPageCount <= pageMax — 실제 페이지 수가 최대 페이지 수 이하
• (actualPageCount - pageMin) % pageIncrement == 0 — 최소 페이지 수에서 증분 단위씩 증가한 값이어야 함

pageMin/pageMax/pageIncrement는 판형 조회(GET /book-specs) 응답에서 확인할 수 있습니다.

표지 규칙

• 책 1권당 표지는 1개만 허용 (중복 추가 시 에러)
• DRAFT 상태에서만 추가 가능

인증

• 모든 API 호출에 API Key 인증 필수

이미지 전달 방식 (템플릿 기반)

템플릿 기반 방식에서 표지/내지 추가 시 이미지를 전달하는 방법은 3가지입니다:

활용 시나리오

PDF 업로드형 (인쇄 대행)

이미 편집 도구로 PDF를 제작하는 파트너가 인쇄/배송만 위탁하는 시나리오입니다.

• 파트너가 PDF 크기와 페이지 수를 직접 관리
• 표지·내지 PDF 업로드 후 POST /books/{bookUid}/finalization 호출로 FINALIZED 상태 전환
• 별도 템플릿 조회 불필요 (PDF로 최종 레이아웃 완성)

PDF 업로드 시나리오 상세 가이드 →

사용자 선택형 (앨범 앱)

사용자가 직접 사진을 선택하고 포토북을 만드는 시나리오입니다. 앨범 앱, 사진 편집 앱 등에 적합합니다.

• 사용자의 로컬 사진을 사용하므로 POST /books/{bookUid}/photos로 사전 업로드 후 서버 파일명을 참조하는 방식 사용
• 판형/템플릿 목록은 자주 변경되지 않으므로 캐시 권장
• 사용자가 사진 수를 자유롭게 선택하므로 내지 추가 횟수가 가변적

템플릿 기반 시나리오 상세 가이드 →

const result = await client.books.create({ title, bookSpecUid: 'SQUAREBOOK_HC' });
const bookUid = result.bookUid;

for (const file of localFiles) {
    await client.photos.upload(bookUid, file);
}

await client.covers.create(bookUid, templateUid, { frontPhoto, backPhoto, dateRange });

for (const entry of entries) {
    await client.contents.insert(bookUid, templateUid, { photos: entry.photos }, { breakBefore: 'page' });
}

서버 자동 생성형 (일기장/알림장 앱)

서버가 데이터(일기, 알림장 등)를 기반으로 자동으로 포토북을 생성하는 시나리오입니다. 사용자는 기간만 선택하면 서버가 나머지를 처리합니다.

• 사진이 이미 서버에 URL로 존재하므로 사전 업로드 불필요 (URL로 직접 전달)
• 템플릿 UID와 파라미터 매핑을 서버에 미리 설정
• 간지(챕터 구분) 페이지, 발행면 등 특수 페이지도 POST /books/{bookUid}/contents로 추가

템플릿 기반 시나리오 상세 가이드 →

const result = await client.books.create({ title: bookTitle, bookSpecUid: 'SQUAREBOOK_HC' });
const bookUid = result.bookUid;

await client.covers.create(bookUid, tplCover, { coverPhoto: photoUrl, title, dateRange });

for (const entry of entries) {
    if (entry.type === 'ganji') {
        await client.contents.insert(bookUid, tplGanji, { chapterNum, year, monthTitle }, { breakBefore: 'page' });
    } else if (entry.type === 'naeji_a') {
        await client.contents.insert(bookUid, tplNaejiA, { monthNum, dayNum, diaryText, photo: photoUrl }, { breakBefore: 'page' });
    } else if (entry.type === 'naeji_gallery') {
        await client.contents.insert(bookUid, tplGallery, { collagePhotos: [url1, url2, '...'] }, { breakBefore: 'none' });
    }
}

await client.contents.insert(bookUid, tplPublish, { photo, title, publishDate, author, hashtags }, { breakBefore: 'page' });

혼합형 (템플릿 표지 + PDF 내지)

표지 디자인은 SweetBook이 제공하는 테마별 표지 템플릿을 활용하고, 내지는 파트너 자체 편집 도구에서 만든 PDF를 업로드하는 시나리오입니다.

• 표지는 템플릿(POST /books/{bookUid}/cover)으로만 적용 — PDF 표지는 차단
• 내지는 PDF(POST /books/{bookUid}/pdf-contents)로만 업로드 — 템플릿 내지는 차단
• 표지·내지 입력 후 POST /books/{bookUid}/finalization으로 최종화
• 주문 흐름은 TEMPLATE과 동일 (PAID → 렌더링 후 PDF_READY)

혼합 방식 시나리오 상세 가이드 →

관련 문서

• PDF 업로드 시나리오 — 기본 권장. 책 생성·표지·내지·최종화·주문 단계별 안내
• 템플릿 기반 시나리오 — 사진·텍스트 입력으로 책 구성
• 혼합 방식 시나리오 — 표지=템플릿, 내지=PDF
• Orders API — 주문 생성·취소·조회
• Credits API — 충전금 잔액·거래 내역 조회
• Webhook Events — 9개 이벤트별 페이로드 구조와 예시