샌드박스
실제 회원·책·정산에 영향 없이 호스팅 로그인, 구매내역 API, 쏠브 API 호출을 끝까지 시험하는 공개 샌드박스입니다.
샌드박스는 개발 중인 제휴사가 쏠브 담당자를 거치지 않고 연동을 끝까지 시험하는 곳입니다. 운영과 같은 규칙으로 동작하지만 쏠브 회원은 가상 회원이고, 실제 회원의 책장·정산에는 아무것도 기록하지 않습니다.
샌드박스 자격은 운영 자격과 따로입니다
쏠브가 샌드박스 콜백 시크릿을 따로 드립니다. 운영 콜백 시크릿으로는 샌드박스가 열리지 않고, 샌드박스 시크릿으로는 운영 API 가 열리지 않습니다.
할 수 있는 것과 없는 것
| 시험 | 샌드박스 | 설명 |
|---|---|---|
| ⓑ 호스팅 로그인 흐름 | 됩니다 | 연동 시작 → 제휴사 로그인 페이지 → 콜백 → redirect_url → 「연동 완료」 화면까지 PC·휴대폰 브라우저에서 |
| 1회용 토큰 규칙 | 됩니다 | 5분 만료, 한 번만 사용, 다른 창·다른 브라우저에서 열면 실패 — 운영과 같습니다 |
| 구매내역 API | 됩니다 | 쏠브 서버가 등록된 시험 주소를 실제로 호출하고, 응답 검증 결과와 책장 미리보기를 보여 줍니다 |
| 열람 여부·열람 기록·회수 알림 API | 됩니다 | 운영과 같은 요청을 받아 가상 회원·가상 기록으로 응답합니다 |
| 쏠브 앱 화면에서 책 보기 | 안 됩니다 | 실제 앱 화면 시험은 운영의 출시 전 상태 + 시험 계정으로 합니다 (테스트와 출시) |
| ⓐ 자격증명 로그인 API | 안 됩니다 | 셀프 점검 도구로 확인하세요 |
| 실제 회수·정산 | 안 됩니다 | 회수 알림을 보내도 아무 책도 꺼지지 않습니다 |
1. 자격 받기
쏠브 담당자에게 아래를 알려 주세요. 쏠브가 등록하고 샌드박스 콜백 시크릿을 안전한 채널로 전달합니다. 시크릿 교체(회전)도 담당자에게 요청하세요. 교체 중에는 새 시크릿과 이전 시크릿이 함께 통합니다.
| 알려 줄 값 | 필수 | 설명 |
|---|---|---|
| 시험 로그인 페이지 주소 | ⓑ 방식이면 필수 | https:// 주소. 샌드박스 연동 시작 화면이 이 주소로 보냅니다 |
| 시험 구매내역 API 주소 | 구매내역 점검에 필수 | https:// 주소. 리다이렉트 없이 바로 응답하는 최종 주소 |
| 구매내역 인증 헤더 이름·값 | 위 주소가 있으면 필수 | 운영과 같은 방식. 값은 16자 이상 |
| 받는 값 | 설명 |
|---|---|
platform_type | 운영과 같은 제휴사 번호 |
| 샌드박스 콜백 시크릿 | 제휴사 서버 → 쏠브 샌드박스 API 인증. Authorization: Bearer <시크릿> |
2. 주소
| 용도 | 주소 |
|---|---|
| 연동 시작(브라우저) | https://partner-connection.solve.im/sandbox/connect?platform_type=<번호> |
| 샌드박스 API | https://solve-api.solve.im/api/v1/partner-sandbox/... |
| 샌드박스 API | 운영 API 와의 관계 |
|---|---|
POST /api/v1/partner-sandbox/sso-callback | 운영 콜백과 같은 요청·응답 |
POST /api/v1/partner-sandbox/purchase-history/check | 샌드박스 전용 — 구매내역 점검 |
POST /api/v1/partner-sandbox/access-status | 운영 열람 여부 조회와 같은 요청·응답 |
POST /api/v1/partner-sandbox/access-history | 운영 열람 기록 조회와 같은 요청·응답 |
POST /api/v1/partner-sandbox/revocations | 운영 회수 알림과 같은 요청·응답·멱등 규칙 |
제휴사 개발 서버에서는 주소와 시크릿만 바꾸면 운영 코드를 그대로 시험할 수 있습니다. 모든 샌드박스 API 는 분당 120회(연동 시작·완료 화면은 30회)까지입니다.
3. 호스팅 로그인 시험 (ⓑ)
연동 시작 주소를 엽니다. 쏠브 앱 대신 이 주소가 가상 쏠브 회원으로 1회용 토큰을 받고, 같은 탭에서 등록된 시험 로그인 페이지로 이동합니다.
로그인 뒤 제휴사 서버가 샌드박스 콜백을 호출합니다. 운영 콜백과 같은 본문이고, 주소와 시크릿만 다릅니다.
받은 redirect_url 로 같은 탭에서 이동합니다. 쏠브 연동 화면이 토큰과 서명을 확인하고 「연동 완료」를 보여 줍니다.
curl -X POST https://solve-api.solve.im/api/v1/partner-sandbox/sso-callback \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <샌드박스 콜백 시크릿>' \
-d '{"id": "100023", "platform_type": 17}'{ "redirect_url": "https://partner-connection.solve.im/sandbox/callback?platform_type=17&user_key=100023&sig=...&exp=..." }redirect_url 은 고치지 말고 그대로 여세요. 서명이 붙어 있어 user_key 를 바꾸면 실패합니다. 서명은 10분 동안 유효합니다.
실패도 운영과 같습니다
샌드박스 화면은 운영과 달리 실패 이유를 코드로 보여 줍니다.
| 화면의 코드 | 원인 | 운영에서도 |
|---|---|---|
TOKEN_NOT_IN_THIS_TAB | 연동을 시작한 탭이 아닌 다른 창·다른 브라우저에서 redirect_url 을 열었거나, 같은 주소를 다시 열었습니다 | 같은 이유로 실패합니다 |
TOKEN_EXPIRED | 연동 시작 뒤 5분이 지났습니다 | 같습니다 |
TOKEN_USED | 이미 한 번 쓴 토큰입니다 | 같습니다 |
SIGNATURE_INVALID | redirect_url 의 값이 바뀌었습니다 | 같습니다 |
SIGNATURE_EXPIRED | 콜백을 받은 뒤 10분이 지나서 열었습니다 | 같습니다 |
SIGNATURE_MISSING | redirect_url 에서 sig·exp 가 빠졌습니다 | 같습니다 |
로그인 페이지를 새 창·팝업으로 열거나 콜백 뒤 다른 브라우저로 넘기면 1회용 토큰이 없어 실패합니다. 로그인부터 redirect_url 이동까지 한 탭에서 진행하세요. 결과 화면에서 네트워크 오류 등으로 쏠브가 판정하지 못했으면 「다시 시도」 버튼이 나오고, 같은 탭의 토큰으로 다시 확인합니다.
4. 구매내역 API 시험
「연동 완료」 화면은 그 회원의 구매내역을 바로 불러와 보여 줍니다. 같은 점검을 제휴사 서버에서도 호출할 수 있습니다.
curl -X POST https://solve-api.solve.im/api/v1/partner-sandbox/purchase-history/check \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <샌드박스 콜백 시크릿>' \
-d '{"platform_type": 17, "user_key": "100023"}'쏠브 서버가 등록된 시험 주소를 운영과 같은 규칙으로 호출합니다. 호출당 10초, 5xx·타임아웃이면 2번 더 호출하고, 4xx·리다이렉트는 다시 호출하지 않으며, 1MB 를 넘는 응답은 받지 않습니다. 시험 주소는 인터넷에서 접속할 수 있는 공인 IP 로 풀려야 합니다 — 사설망·루프백·문서용 등 공인이 아닌 주소(IPv6 포함)로 풀리면 호출하지 않습니다. 압축 응답(gzip·deflate·br)은 운영과 같이 풀어서 읽습니다.
| 응답 필드 | 설명 |
|---|---|
verdict | pass 통과 · warn 확인 필요 · fail 실패 |
call | 결과 분류(outcome), HTTP 상태, 호출 횟수, 걸린 시간 |
sync_effect | 운영이었다면 이 응답으로 책장이 어떻게 바뀌는지 |
checks | 응답 전체에 대한 확인 결과 |
items[] | 항목별 해석 결과(access_type·valid_until 등), 항목별 확인 결과, 책장 미리보기(shelf.label) |
shelf_preview | 책장에 보이는 책 수, 열리는 책 수, 열리지 않는 책 수, 안 보이는 항목 수 |
call.outcome | 뜻 |
|---|---|
ok | 운영 규칙으로 받아들였습니다 |
rejected | 4xx — 인증 헤더를 확인하세요 |
blocked_address | 주소가 사설망·루프백 등 공인이 아닌 IP 로 풀렸습니다 — 공인 주소를 등록하세요 |
redirect | 3xx — 최종 주소를 등록하세요 |
server_error·timeout·network | 재시도까지 모두 실패했습니다 |
not_json·item_list_missing | 응답 형식이 틀렸습니다 |
item_invalid | 잘못된 항목이 하나라도 있어 목록 전체를 받지 않았습니다. items[].checks 에서 어느 항목인지 확인하세요 |
too_large | 응답이 1MB 를 넘었습니다 |
책장 미리보기는 상품코드가 파트너 어드민에 등록한 연동코드와 글자 그대로 같은지도 확인합니다. 아직 상품을 등록하기 전이면 「상품 연결을 확인하지 못했습니다」로 표시하고, 연결돼 있다고 가정한 결과를 보여 줍니다. 한 번에 확인하는 상품코드는 10,000개까지이며, 넘는 코드는 「확인하지 않았습니다」로 표시합니다.
5. 쏠브 API 시험 (가상 회원)
열람 여부·열람 기록·회수 알림 샌드박스 API 는 운영과 같은 요청을 받고, 아래 규칙으로 만든 가상 결과를 돌려줍니다. 같은 요청은 언제나 같은 응답입니다.
| 규칙 | 결과 |
|---|---|
user_key 가 unlinked 로 시작 | 쏠브에 연동되지 않은 회원(linked: false) |
그 밖의 user_key | 연동된 가상 회원 |
상품코드에 unviewed 가 들어 있음 | 열람 기록이 없는 책 |
상품코드에 notowned 가 들어 있음 | 쏠브에서 받은 적 없는 책 — 회수 알림에서 revoked: false |
| 상품코드를 보내지 않음 | 가상 상품코드 SANDBOX-EBOOK-001~003 을 씁니다 |
- 열람 여부: 열람한 책의
first_viewed_at은purchased_at뒤의 시각입니다. - 열람 기록: 상품코드 하나당 기록 10건(열람 7·내려받기 3)이고, 기본이면 모두 30건입니다.
page_size를 작게 주어next_cursor쪽 넘김을 끝까지 시험해 보세요. 커서는 그대로 돌려보내는 문자열로만 다루세요. - 회수 알림: 같은
idempotency_key로 같은 요청을 다시 보내면 처음 응답을 그대로 주고Idempotent-Replayed: true헤더를 붙입니다. 같은 키로 다른 요청을 보내면409입니다. 아무 책도 실제로 끄지 않습니다.
curl -X POST https://solve-api.solve.im/api/v1/partner-sandbox/access-status \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <샌드박스 콜백 시크릿>' \
-d '{"platform_type": 17, "user_key": "100023", "items": [{"item_code": "BOOK_2026"}, {"item_code": "BOOK_unviewed"}]}'{
"linked": true,
"items": [
{ "item_code": "BOOK_2026", "viewed": true, "first_viewed_at": "2026-11-02T14:00:00+09:00" },
{ "item_code": "BOOK_unviewed", "viewed": false, "first_viewed_at": null }
]
}오류 응답
샌드박스 API 의 오류는 운영과 같은 { "error", "message" } 에 무엇이 틀렸는지 알려 주는 code 를 더합니다.
| 상태 | code | 원인 |
|---|---|---|
400 | SANDBOX_NOT_AVAILABLE | 이 platform_type 에는 샌드박스 자격이 없습니다 |
400 | SANDBOX_LOGIN_PAGE_MISSING | 시험 로그인 페이지 주소가 등록되지 않았습니다 |
401 | AUTH_HEADER_MISSING | Authorization 헤더가 없습니다 |
401 | AUTH_INVALID | 시크릿이 틀렸습니다. 운영 시크릿이 아닌 샌드박스 시크릿을 쓰세요 |
409 | IDEMPOTENCY_KEY_REUSED | 같은 idempotency_key 로 다른 회수 요청을 보냈습니다 |
429 | 분당 호출 한도를 넘었습니다 | |
503 | SANDBOX_CREDENTIALS_UNAVAILABLE | 쏠브 쪽 일시 장애입니다. 잠시 뒤 다시 호출하세요 |
알아 둘 점
- 샌드박스에서 연동해도 쏠브 앱에는 아무것도 나타나지 않습니다. 앱 화면은 출시 전 상태 + 시험 계정으로 확인합니다(테스트와 출시).
- 샌드박스는 운영 서버 안에서 별도 경로로 동작합니다. 드물게 서버가 여러 대일 때 다 쓴 토큰이나 회수 알림의 멱등 기록을 다른 서버가 모를 수 있습니다. 같은 탭에서 진행하는 정상 흐름에는 영향이 없습니다.
- 결과 화면의 확인이 성공했는데 그 응답이 오는 도중 연결이 끊기면, 「다시 시도」 는
TOKEN_USED로 끝납니다. 연동 시작 주소부터 다시 하세요. - 샌드박스 응답의 진단 문구는 바뀔 수 있습니다. 코드에서는
code·outcome·verdict같은 분류값만 쓰세요.