전체 워크플로우
SweetBook API를 사용하여 포토북을 제작하고 주문하는 전체 과정을 안내합니다. 각 단계별 API 엔드포인트와 연동 시나리오를 설명합니다.
전체 흐름
포토북 제작부터 주문 완료까지 다음 단계를 순서대로 진행합니다.
1상품 선택→2템플릿 선택→3책 생성→4사진 업로드→5표지 추가→6내지 추가 (반복)→7최종화→8견적 조회→9주문 생성→10웹훅 수신
단계별 API 엔드포인트
각 단계에서 호출하는 API 엔드포인트와 역할입니다.
| 단계 | API 엔드포인트 | 설명 |
|---|---|---|
| 1. 상품 선택 | GET /book-specs | 사용 가능한 상품(판형) 목록 조회 |
| 2. 템플릿 선택 | GET /templates | 상품에 맞는 표지/내지 템플릿 조회 |
| 3. 책 생성 | POST /books | 초안(draft) 상태의 책 생성 |
| 4. 사진 업로드 | POST /books/{bookUid}/photos | 갤러리 템플릿에 사용할 사진 업로드 |
| 5. 표지 추가 | POST /books/{bookUid}/cover | 표지 템플릿 적용 및 파라미터 전달 |
| 6. 내지 추가 | POST /books/{bookUid}/contents | 내지 템플릿 적용 (반복 호출 가능) |
| 7. 최종화 | POST /books/{bookUid}/finalization | 책 완성 처리 (페이지 수 검증) |
| 8. 견적 조회 | POST /orders/estimate | 주문 전 예상 비용 확인 |
| 9. 주문 생성 | POST /orders | 주문 생성 및 충전금 차감 |
| 10. 웹훅 수신 | Webhook | 주문 상태 변경 알림 수신 |
시나리오 A: 사용자 선택형 (앨범 앱)
사용자가 직접 템플릿을 선택하고 사진을 업로드하여 포토북을 만드는 시나리오입니다. 앨범 앱, 사진 편집 앱 등에 적합합니다.
text
[사용자 앱 UI] [파트너 서버] [SweetBook API]
| | |
| 1. 상품 목록 요청 | |
|-------------------------------------->| GET /book-specs |
| |------------------------------>|
| 2. 상품 목록 표시 | <-- 상품 목록 응답 |
|<--------------------------------------| |
| | |
| 3. 템플릿 선택 | |
|-------------------------------------->| GET /templates?bookSpecUid=.. |
| |------------------------------>|
| 4. 템플릿 목록 표시 | <-- 템플릿 목록 응답 |
|<--------------------------------------| |
| | |
| 5. 사진 선택 + 주문 요청 | |
|-------------------------------------->| POST /books |
| | POST /books/{id}/photos |
| | POST /books/{id}/cover |
| | POST /books/{id}/contents x N |
| | POST /books/{id}/finalization |
| | POST /orders |
| |------------------------------>|
| 6. 주문 완료 | <-- 주문 응답 |
|<--------------------------------------| |상품 목록과 템플릿 목록은 자주 변경되지 않으므로 캐시하여 사용하는 것을 권장합니다.
시나리오 B: 서버 자동 생성형 (일기장/알림장 앱)
서버가 데이터(일기, 알림장 등)를 기반으로 자동으로 포토북을 생성하는 시나리오입니다. 사용자는 기간만 선택하면 서버가 나머지를 처리합니다.
text
[사용자 앱 UI] [파트너 서버] [SweetBook API]
| | |
| 1. "3월 일기장 만들기" 요청 | |
|-------------------------------------->| |
| | 2. DB에서 3월 일기 데이터 조회 |
| | |
| | 3. 자동 제작 |
| | POST /books |
| | POST /books/{id}/photos |
| | POST /books/{id}/cover |
| | -- 일기 데이터마다 반복 -- |
| | POST /books/{id}/contents |
| | -- 반복 끝 -- |
| | POST /books/{id}/finalization |
| |------------------------------>|
| | |
| | 4. POST /orders/estimate |
| |------------------------------>|
| 5. 견적 표시 + 결제 확인 | <-- 견적 응답 |
|<--------------------------------------| |
| | |
| 6. 결제 확인 | |
|-------------------------------------->| POST /orders |
| |------------------------------>|
| 7. 주문 완료 | <-- 주문 응답 |
|<--------------------------------------| |서버 자동 생성 시나리오에서는 템플릿
templateUid와 파라미터 매핑을 서버에 미리 설정해 두는 것이 일반적입니다.단계별 상세 가이드
각 단계의 자세한 사용법은 아래 가이드를 참고하세요.
- Step 1: 상품(BookSpec) 선택 — 판형 조회 및 선택
- Step 2: 템플릿 선택 및 이해 — 템플릿 조회 및 파라미터 바인딩
- Step 3: 책 생성 — Books API로 책 생성
- Step 4: 이미지 업로드 — 지원 포맷 및 업로드 가이드
- Step 5~7: 표지/내지 추가 및 최종화 — Books API 상세
- Step 8~9: 견적 조회 및 주문 — Orders API
- Step 10: 웹훅 수신 — Webhook 설정 및 이벤트