Developers
제휴사 연동

샌드박스

실제 회원·책·정산에 영향 없이 호스팅 로그인, 구매내역 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=<번호>
샌드박스 APIhttps://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}'
응답 200
{ "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_INVALIDredirect_url 의 값이 바뀌었습니다같습니다
SIGNATURE_EXPIRED콜백을 받은 뒤 10분이 지나서 열었습니다같습니다
SIGNATURE_MISSINGredirect_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)은 운영과 같이 풀어서 읽습니다.

응답 필드설명
verdictpass 통과 · warn 확인 필요 · fail 실패
call결과 분류(outcome), HTTP 상태, 호출 횟수, 걸린 시간
sync_effect운영이었다면 이 응답으로 책장이 어떻게 바뀌는지
checks응답 전체에 대한 확인 결과
items[]항목별 해석 결과(access_type·valid_until 등), 항목별 확인 결과, 책장 미리보기(shelf.label)
shelf_preview책장에 보이는 책 수, 열리는 책 수, 열리지 않는 책 수, 안 보이는 항목 수
call.outcome뜻
ok운영 규칙으로 받아들였습니다
rejected4xx — 인증 헤더를 확인하세요
blocked_address주소가 사설망·루프백 등 공인이 아닌 IP 로 풀렸습니다 — 공인 주소를 등록하세요
redirect3xx — 최종 주소를 등록하세요
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"}]}'
응답 200
{
  "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원인
400SANDBOX_NOT_AVAILABLE이 platform_type 에는 샌드박스 자격이 없습니다
400SANDBOX_LOGIN_PAGE_MISSING시험 로그인 페이지 주소가 등록되지 않았습니다
401AUTH_HEADER_MISSINGAuthorization 헤더가 없습니다
401AUTH_INVALID시크릿이 틀렸습니다. 운영 시크릿이 아닌 샌드박스 시크릿을 쓰세요
409IDEMPOTENCY_KEY_REUSED같은 idempotency_key 로 다른 회수 요청을 보냈습니다
429분당 호출 한도를 넘었습니다
503SANDBOX_CREDENTIALS_UNAVAILABLE쏠브 쪽 일시 장애입니다. 잠시 뒤 다시 호출하세요

알아 둘 점

  • 샌드박스에서 연동해도 쏠브 앱에는 아무것도 나타나지 않습니다. 앱 화면은 출시 전 상태 + 시험 계정으로 확인합니다(테스트와 출시).
  • 샌드박스는 운영 서버 안에서 별도 경로로 동작합니다. 드물게 서버가 여러 대일 때 다 쓴 토큰이나 회수 알림의 멱등 기록을 다른 서버가 모를 수 있습니다. 같은 탭에서 진행하는 정상 흐름에는 영향이 없습니다.
  • 결과 화면의 확인이 성공했는데 그 응답이 오는 도중 연결이 끊기면, 「다시 시도」 는 TOKEN_USED 로 끝납니다. 연동 시작 주소부터 다시 하세요.
  • 샌드박스 응답의 진단 문구는 바뀔 수 있습니다. 코드에서는 code·outcome·verdict 같은 분류값만 쓰세요.

다음 단계

이 페이지 목차