Book Print API의 모든 엔드포인트가 Sandbox 도메인과 Live 도메인에서 어떻게 동작하는지를 정리한 단일 진실원입니다. 클라이언트 입장에서 "이 API를 Sandbox에서 호출할 수 있나?"와 "호출은 되는데, 어떤 데이터가 영향받나?"를 한눈에 판단할 수 있도록 구성되어 있습니다.
도메인 식별
환경
도메인
Sandbox
api-sandbox.sweetbook.com
Live
api.sweetbook.com
서버가 요청 도메인으로 환경을 자동 판별합니다.
한눈에 보기 — 4가지 분류
서버의 모든 엔드포인트는 다음 4가지 동작 중 하나를 합니다. 각 엔드포인트의 분류는 아래 컨트롤러별 표의 분류 컬럼에서 확인할 수 있습니다.
코드
이름
Sandbox 호출 결과
Live 호출 결과
클라가 알아야 할 것
A
환경 분리
✅ 호출 가능 — Sandbox 데이터(is_test=true)만 처리
✅ 호출 가능 — Live 데이터(is_test=false)만 처리
양 환경이 서로 다른 데이터 풀을 본다. Sandbox에서 만든 책/주문/크레딧은 Live에서 안 보임
B
공통 자원
✅ 호출 가능 — 단일 데이터 풀 처리
✅ 호출 가능 — 단일 데이터 풀 처리
양 환경이 같은 데이터를 본다. 계정·템플릿 등 환경 무관 공통 자원. ⚠️ Sandbox에서 운영 데이터 직접 영향 가능
C
외부 — 테스트 모드
✅ 호출 가능 — 외부 시스템에 테스트 모드로 호출 (실 부수효과 X)
✅ 호출 가능 — 외부 시스템에 운영 모드로 호출
알림톡·SMS 등. Sandbox 호출은 안전 (실제 발송 안 됨)
D
Sandbox 차단
❌ 501 + ERR_SANDBOX_UNSUPPORTED
✅ 정상 동작
Sandbox에서 호출하면 차단됨. 외부 결제망 등 실 부수효과를 안전하게 막을 수 없는 경우
✅ = "호출 자체가 통과한다"는 의미. 데이터에 어떤 영향이 가는지는 분류(A/B/C/D)에 따라 다릅니다. 단순 호출 가능 여부만 보지 말고 분류도 같이 확인하세요.
Sandbox에서 호출 불가능한 엔드포인트
분류 D에 해당하는 엔드포인트만 모음. Sandbox 도메인에서 호출 시 501 + ERR_SANDBOX_UNSUPPORTED 반환.
메서드
경로
사유
POST
/payments/inicis/confirm
Sandbox 호출 시 외부 결제망에 그대로 통신되기 때문에 안전 차단 필요
위 외 모든 엔드포인트는 Sandbox에서 호출 가능합니다. 다만 데이터 영향은 분류(A/B/C)에 따라 다릅니다.
자동 재시도 주의: HTTP 501은 일반적으로 "서버 미구현" 의미로 해석되지만, 본 케이스(ERR_SANDBOX_UNSUPPORTED)는 의도적 차단이라 재시도해도 동일 결과입니다. 자동 재시도 로직 화이트리스트에서 제외하세요. 응답 분기는 HTTP 상태가 아닌 errorCode로 하는 것을 권장합니다.
컨트롤러별 매트릭스
표 읽는 법
컬럼
의미
메서드 / 경로
HTTP 메서드 + 경로
Sandbox
Sandbox 도메인에서 호출 결과 (✅ = 가능, ❌ = 차단)
Live
Live 도메인에서 호출 결과 (✅ = 가능)
분류
위 "한눈에 보기" 표의 A/B/C/D
비고
보조 설명
Accounts (/accounts)
메서드
경로
Sandbox
Live
분류
비고
POST
/accounts/images
✅
✅
B
이미지 업로드
GET
/accounts/images
✅
✅
B
DELETE
/accounts/images
✅
✅
B
PATCH
/accounts/images
✅
✅
B
GET
/accounts/me
✅
✅
B
personal도 Live OK
PATCH
/accounts/me
✅
✅
B
DELETE
/accounts/me
✅
✅
B
AccountConfigs (/account-configs)
메서드
경로
Sandbox
Live
분류
비고
GET
/account-configs/me
✅
✅
B
POST
/account-configs
✅
✅
B
PATCH
/account-configs/{accountUid}
✅
✅
B
ApiKeys (/keys)
메서드
경로
Sandbox
Live
분류
비고
GET
/keys
✅
✅
A
키마다 env(test/live) 필드. 양 환경 별도 풀
POST
/keys
✅
✅
A
발급 시 도메인 환경에 맞춘 env로 저장
PATCH
/keys/{keyPrefix}
✅
✅
A
DELETE
/keys/{keyPrefix}
✅
✅
A
Books (/books)
메서드
경로
Sandbox
Live
분류
비고
GET
/books
✅
✅
A
POST
/books
✅
✅
A
생성 시 도메인 환경에 맞춰 is_test 저장
GET
/books/{bookUid}
✅
✅
A
POST
/books/{bookUid}/finalization
✅
✅
A
DELETE
/books/{bookUid}
✅
✅
A
PATCH
/books/{bookUid}/pdf-status
✅
✅
A
POST
/books/{bookUid}/pdf-result
✅
✅
A
레거시
POST
/books/{bookUid}/cover
✅
✅
A
POST
/books/{bookUid}/contents
✅
✅
A
DELETE
/books/{bookUid}/contents
✅
✅
A
POST
/books/{bookUid}/photos
✅
✅
A
환경 불일치 시 403 ERR_ENV_MISMATCH
GET
/books/{bookUid}/photos
✅
✅
A
GET
/books/{bookUid}/photos/{fileName}
✅
✅
A
DELETE
/books/{bookUid}/photos/{fileName}
✅
✅
A
POST
/books/{bookUid}/pdf-cover
✅
✅
A
POST
/books/{bookUid}/pdf-contents
✅
✅
A
PUT
/books/{bookUid}/pdf-cover
✅
✅
A
PUT
/books/{bookUid}/pdf-contents
✅
✅
A
GET
/books/{bookUid}/pdf-cover
✅
✅
A
GET
/books/{bookUid}/pdf-contents
✅
✅
A
BookSpecs (/book-specs)
메서드
경로
Sandbox
Live
분류
비고
GET
/book-specs
✅
✅
B
공통 카탈로그
GET
/book-specs/{bookSpecUid}
✅
✅
B
Templates (/templates)
메서드
경로
Sandbox
Live
분류
비고
GET
/templates
✅
✅
B
GET
/templates/{templateUid}
✅
✅
B
TemplateCategories (/template-categories)
메서드
경로
Sandbox
Live
분류
비고
GET
/template-categories
✅
✅
B
GET
/template-categories/{key}
✅
✅
B
SpecProfiles (/spec-profiles)
메서드
경로
Sandbox
Live
분류
비고
GET
/spec-profiles
✅
✅
B
Orders (/orders)
메서드
경로
Sandbox
Live
분류
비고
POST
/orders
✅
✅
A
생성 시 도메인 환경에 맞춰 is_test 저장
POST
/orders/estimate
✅
✅
A
GET
/orders
✅
✅
A
GET
/orders/{orderUid}
✅
✅
A
POST
/orders/{orderUid}/cancel
✅
✅
A
POST
/orders/{orderUid}/items/{itemUid}/cancel
✅
✅
A
PATCH
/orders/{orderUid}/shipping
✅
✅
A
PATCH
/orders/{orderUid}/status
✅
✅
A
Credits (/credits)
메서드
경로
Sandbox
Live
분류
비고
GET
/credits
✅
✅
A
양 환경 별도 잔액
GET
/credits/transactions
✅
✅
A
POST
/credits/sandbox/charge
✅
(의미 없음)
—
Sandbox 전용 테스트 충전
POST
/credits/sandbox/deduct
✅
(의미 없음)
—
Sandbox 전용 테스트 차감
Payments (/payments)
메서드
경로
Sandbox
Live
분류
비고
POST
/payments/inicis/confirm
❌ 501
✅
D
ERR_SANDBOX_UNSUPPORTED 반환. Sandbox에서 외부 결제망 호출 방지
Notifications (/notifications)
메서드
경로
Sandbox
Live
분류
비고
GET
/notifications/config
✅
✅
B
PATCH
/notifications/config
✅
✅
B
GET
/notifications
✅
✅
B
POST
/notifications/send
✅
✅
C
Sandbox 호출 시 외부 발송 시스템 테스트 모드로 전달 — 실 SMS/알림톡 안 나감
Webhooks (/webhooks)
메서드
경로
Sandbox
Live
분류
비고
PUT
/webhooks/config
✅
✅
B
GET
/webhooks/config
✅
✅
B
DELETE
/webhooks/config
✅
✅
B
POST
/webhooks/test
✅
✅
B
사용자가 등록한 본인 webhookUrl로 실 HTTP 송신 (양 환경 동일)
GET
/webhooks/deliveries
✅
✅
B
자주 헷갈리는 케이스 (FAQ)
QSandbox에서 POST /orders 호출하면 Live 운영 주문이 만들어지나요?
A아니요. 분류 A(환경 분리)이므로 Sandbox에서 만든 주문은 is_test=true로 저장되며 Live에서 안 보입니다.
QSandbox에서 POST /notifications/send 호출하면 실제로 SMS가 발송되나요?
A아니요. 분류 C(외부 — 테스트 모드)로 외부 발송 시스템에 테스트 모드로 전달되어 실 발송이 일어나지 않습니다.
QSandbox에서 POST /payments/inicis/confirm 호출하면 어떻게 되나요?