빠른 시작 가이드

Sandbox 환경에서 첫 포토북 생성부터 주문까지 완료하기

사전 준비

Sandbox API Key: 파트너 등록을 완료하고 Sandbox API Key를 발급받으세요
테스트 충전금: 파트너 포털의 충전금 관리에서 테스트 충전금을 원하는 금액으로 설정하세요
이미지 파일: 표지용 2장(front.jpg, back.jpg), 내지용 15장 이상
API 테스트 도구: curl, Postman 등

모든 API 호출은 Sandbox URL https://api-sandbox.sweetbook.com/v1을 사용합니다. 테스트 가격(100원 이하)이 적용되며, 실제 인쇄/배송은 진행되지 않습니다.

아래 예시에서 YOUR_API_KEY를 발급받은 Sandbox API Key로 교체하세요. 소요 시간: 약 10분

Step 1. 상품(BookSpec) 조회

먼저 사용 가능한 상품 목록을 조회합니다.

bash

curl -X GET 'https://api-sandbox.sweetbook.com/v1/book-specs' \
  -H 'Authorization: Bearer YOUR_API_KEY'

이 가이드에서는 SQUAREBOOK_HC를 사용합니다. 응답에서 원하는 specUid를 선택하세요.

Step 2. 템플릿 조회

표지와 내지에 사용할 템플릿을 조회합니다.

bash

curl -X GET 'https://api-sandbox.sweetbook.com/v1/templates?bookSpecUid=SQUAREBOOK_HC' \
  -H 'Authorization: Bearer YOUR_API_KEY'

응답에서 표지용(templateKind: cover)과 내지용(templateKind: content) 템플릿의 templateUid를 메모하세요.

Step 3. 책 생성

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"
}'

응답의 bookUid를 복사해두세요. 이후 모든 단계에서 사용됩니다.

Step 4. 표지 추가

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":"홍길동"}'

{bookUid}와 COVER_TEMPLATE_UID를 실제 값으로 교체하세요.

Step 5. 내지 추가 (반복)

최소 페이지 수(SQUAREBOOK_HC: 24페이지)를 충족할 때까지 반복하세요.

bash

# 여러 페이지를 빠르게 추가
for i in {1..15}; do
  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=@photo${i}.jpg;type=image/jpeg" \
    -F 'templateUid=CONTENT_TEMPLATE_UID'
done

지원 이미지: JPG, PNG, GIF, BMP, WebP, HEIC (SVG 미지원)

Step 6. 책 최종화

bash

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

Step 7. 견적 조회

Sandbox에서는 테스트 가격(100원 이하)이 적용됩니다.

bash

curl -X POST 'https://api-sandbox.sweetbook.com/v1/orders/estimate' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "items": [
    { "bookUid": "{bookUid}", "quantity": 1 }
  ]
}'

creditSufficient가 false이면 파트너 포털에서 테스트 충전금을 추가하세요.

Step 8. 주문 생성

주문 즉시 테스트 충전금이 차감되며, order.created 웹훅 이벤트가 발생합니다.

bash

curl -X POST 'https://api-sandbox.sweetbook.com/v1/orders' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "items": [
    { "bookUid": "{bookUid}", "quantity": 1 }
  ],
  "shipping": {
    "recipientName": "홍길동",
    "recipientPhone": "010-1234-5678",
    "postalCode": "06236",
    "address1": "서울특별시 강남구 테헤란로 123",
    "address2": "4층"
  }
}'

Sandbox에서는 주문 상태가 PAID(결제완료)에서 멈춥니다. 실제 인쇄/배송은 진행되지 않습니다.

완료!

전체 흐름을 완료했습니다. Live 환경으로 전환할 때는 Base URL과 API Key만 변경하면 됩니다.

웹훅 연동

주문 상태 변경을 실시간 수신

Orders API

주문 조회, 취소, 배송지 변경

Live 전환

운영 환경으로 전환하기

문제 해결

에러	원인	해결
`401 Unauthorized`	API Key 오류 또는 Sandbox Key로 Live URL 호출	API Key 확인, URL이 `api-sandbox`인지 확인
`402 Payment Required`	테스트 충전금 부족	파트너 포털에서 테스트 충전금 추가
최소 페이지 수 부족	상품의 최소 페이지 미충족	Step 5에서 더 많은 내지 추가
Template not found	잘못된 템플릿 UID	Step 2에서 조회한 정확한 `templateUid` 사용
이미지 업로드 실패	미지원 형식(SVG 등)	JPG, PNG, WebP, HEIC 등 지원 형식 사용