테스트와 출시
셀프 점검, 쏠브에 보낼 테스트 자료, 쏠브 검증 항목, 출시 체크리스트를 정리했습니다.
구현이 끝나면 셀프 점검 → 테스트 자료 전달 → 쏠브 검증 → 출시 순서로 진행합니다. 공개 샌드박스는 없으며, 제휴사 테스트 환경(또는 운영 환경의 테스트 계정)으로 검증합니다.
1. 셀프 점검
쏠브에 자료를 보내기 전에, 제휴사 서버가 규약대로 응답하는지 아래 도구로 확인해 보세요. 두 도구 모두 제휴사 PC 에서 돌리며, 쏠브 서버로는 아무것도 보내지 않습니다.
ⓑ 호스팅 로그인 페이지 방식이라면 콜백 주소와 시크릿을 계약 뒤에야 받습니다. 그 전에는 콜백 흉내 도구로 자기 로그인 페이지가 콜백을 규약대로 보내는지 미리 확인해 보세요.
전체 점검 (Node)
Node.js 18 이상이 있으면 구매내역 API 와 ⓐ 로그인 API 를 한 번에 점검할 수 있습니다. 응답 형식, 선택 필드(v1.1), 오류 응답, 응답 시간(10초)까지 확인하고 점검마다 PASS·WARN·FAIL·SKIP 으로 알려 줍니다.
solve-selfcheck.mjs 내려받기 — 파일 하나이며 설치할 것이 없습니다. 브라우저에 코드가 그대로 열리면 "다른 이름으로 저장"으로 받아 주세요.
먼저 설정 파일 틀을 만듭니다. 같은 이름의 파일이 이미 있으면 덮어쓰지 않습니다.
node solve-selfcheck.mjs --init만들어진 solve-selfcheck.config.json 에 제휴사 값을 적습니다.
{
"purchaseUrl": "https://api.partner.example.com/solve/purchases",
"authHeaderName": "X-Solve-Secret",
"secret": "여기에-점검용-시크릿",
"userKey": "여기에-구매-내역이-있는-회원의-user_key",
"loginUrl": "",
"loginId": "",
"loginPassword": ""
}| 설정 | 설명 |
|---|---|
purchaseUrl | 구매내역 API URL. 2048자 이하이고 공백이나 아이디:비밀번호@ 를 넣을 수 없습니다 |
authHeaderName, secret | 쏠브가 보낼 인증 헤더 이름과 값. 이름은 영문·숫자·기호 64자 이하이며 Host·Content-Type·Cookie·Proxy-*·X-Forwarded-* 같은 이름은 쓸 수 없습니다. 값은 16자 이상 4096자 이하이고 앞뒤에 공백이나 탭이 없어야 합니다 |
userKey | 구매 내역이 있는 테스트 회원의 user_key. 앞뒤 공백까지 그대로 씁니다 |
loginUrl, loginId, loginPassword | ⓐ 방식만 적습니다. 로그인 API URL 과 테스트 계정입니다. 비워 두면 로그인 점검은 건너뜁니다 |
node solve-selfcheck.mjs solve-selfcheck.config.json쏠브 셀프 점검 v2 (도구 1.0.0)
구매내역 API: https://api.partner.example.com (경로와 쿼리는 화면에 싣지 않습니다)
로그인 API: https://api.partner.example.com
호출마다 10.00초 제한을 두고 걸린 시간을 보여 드립니다.
PASS [1] 구매내역 · 구매 회원 조회 (HTTP 200, 0.21초) item_list 2개, 모든 항목에 item_code 가 있습니다
PASS [2] 구매내역 · 없는 회원 조회 (HTTP 200, 0.09초) 200 과 빈 item_list 로 응답했습니다
PASS [3] 구매내역 · 틀린 시크릿 (HTTP 403, 0.05초) 403 응답으로 거절했습니다
PASS [4] 구매내역 · 인증 헤더 없음 (HTTP 403, 0.04초) 403 응답으로 거절했습니다
PASS [5] 구매내역 · user_key 없는 요청 (HTTP 400, 0.04초) 400 응답으로 거절했습니다
SKIP [6] 구매내역 · 선택 필드 형식 선택 필드 없음 — 없어도 됩니다
PASS [8] 로그인 · 맞는 아이디·비밀번호 (HTTP 200, 0.12초) user_key 를 받았습니다 (6자)
PASS [9] 로그인 · 틀린 비밀번호 (HTTP 401, 0.10초) 401 응답으로 거절했습니다
PASS [10] 로그인 · 틀린 시크릿 (HTTP 403, 0.04초) 403 응답으로 거절했습니다
PASS [11] 로그인 + 구매내역 · 로그인과 구매내역의 user_key 로그인이 돌려준 user_key 가 설정의 userKey 와 같습니다
PASS [7] 공통 · 응답 시간 모든 호출이 10.00초 안에 끝났습니다 (가장 느린 호출 0.21초)
PASS [12] 공통 · 주소가 https 인지 https 입니다 (같은 PC 의 localhost 는 예외)
요약: 통과 11 · 주의 0 · 실패 0 · 건너뜀 1
실패는 없습니다.
참고: 이 도구의 통과는 운영 등록 가능의 증거가 아닙니다. http 주소는 실제 등록에서 거부됩니다.FAIL 이나 WARN 이 나오면 바로 아래에 고치는 방법과 응답 요약이 함께 나옵니다. 응답 요약은 본문의 바이트 수, JSON 의 종류, 규약에 있는 필드의 타입과 길이, 그 밖의 필드 개수만 보여 줍니다. 이 도구는 응답의 본문·헤더 원문과 시크릿·비밀번호를 화면에 싣지 않으며, 주소도 경로와 쿼리 없이 https://호스트 까지만 보여 줍니다.
FAIL [2] 구매내역 · 없는 회원 조회 (HTTP 404, 0.04초) 200 이 아니라 404 응답을 보냈습니다
고치는 방법: 없는 회원은 404 나 오류가 아니라 200 과 { "item_list": [] } 로 응답해 주세요.
응답 요약: 본문 21바이트 · JSON 객체 · error: 문자열 9자| 결과 | 뜻 |
|---|---|
PASS | 규약대로입니다 |
WARN | 쏠브는 동작하지만 권장과 다릅니다. 고치는 방법을 확인해 주세요 |
FAIL | 규약과 다릅니다. 고친 뒤 다시 실행해 주세요 |
SKIP | 해당하지 않아 건너뛰었습니다 (선택 필드가 없거나 로그인 주소를 적지 않은 경우) |
이 도구는 쏠브가 응답을 읽는 방식과 같은 기준으로 판정합니다. 쏠브가 응답 전체를 쓰지 못하는 경우는 FAIL, 응답은 받되 그 필드만 버리는 경우는 WARN 입니다. 위 설정 값이 쏠브가 받아 주는 조건을 어기면 점검하지 않고 종료 코드 2 로 끝납니다.
| 점검 | FAIL — 쏠브가 응답을 쓰지 못합니다 | WARN — 쏠브가 그 필드만 버립니다 |
|---|---|---|
| 1·2번 구매내역 응답 | 200 이 아님(3xx 포함) · JSON 객체가 아님 · item_list 가 배열이 아님 · 항목이 객체가 아님 · item_code 가 문자열이 아니거나, 앞뒤 공백을 뗀 뒤 비어 있거나 255자를 넘음. 항목 하나만 틀려도 목록 전체를 버립니다 | — |
| 6번 선택 필드 | — | price 가 0 이상의 안전한 정수(9007199254740991 이하)나 1paid_at 이 존재하는 날짜의 ISO 8601 이 아니거나 오프셋의 시가 23, 분이 59 를 넘음 · valid_from·valid_until 이 앞뒤 공백을 뗀 뒤 1item_name 이 문자열이 아님. null 은 보내지 않은 것과 같습니다 |
| 8번 로그인 응답 | 200 이 아님(3xx 포함) · JSON 객체가 아님 · user_key 가 문자열이 아니거나 공백뿐이거나 255자를 넘음 | — |
응답 본문은 1MB(1,048,576바이트) 까지만 읽습니다. 정확히 1MB 는 통과하고, 1바이트라도 넘으면 그 호출은 "응답이 1MB 를 넘습니다. 쏠브는 1MB 를 넘는 응답을 받지 않습니다." 와 함께 FAIL 입니다. 쏠브도 1MB 를 넘는 응답을 받지 않기 때문입니다. 잘린 본문으로는 어떤 점검도 PASS 로 판정하지 않습니다. 구매내역·로그인 응답은 필요한 필드만 담아 1MB 이하로 줄여 주세요.
종료 코드는 FAIL 이 없으면 0, 하나라도 있으면 1, 설정이나 실행 환경에 문제가 있으면 2 입니다. 이 도구는 설정 파일에 적은 주소만 호출하고 점검 하나에 호출 하나만 보내며, 리다이렉트를 따라가지 않습니다. 쏠브도 다른 주소로 넘기는 응답을 따라가지 않으므로 3xx 응답은 FAIL 이고, 이때는 설정에 최종 주소를 적어 주세요. 쏠브 서버 주소는 점검 대상이 아니라서 호출하지 않고 종료 코드 2 로 끝납니다. 로그인 점검은 틀린 비밀번호로 한 번 로그인을 시도하므로, 계정 잠금 정책이 있다면 테스트 계정으로 하세요.
이 도구의 통과는 운영 등록 가능의 증거가 아닙니다. 12번이 WARN 인 http 주소는 종료 코드 0 이어도 쏠브에 실제로 등록할 때 거부됩니다.
빠른 확인 (bash)
curl 과 bash 만 있으면 구매내역 API 3건을 바로 확인할 수 있습니다. 맨 위 4개 값만 바꾸면 됩니다.
#!/usr/bin/env bash
# 쏠브 연동 셀프 점검 — 구매내역 API
URL="https://api.partner.example.com/solve/purchases" # 구매내역 API URL
SECRET_HEADER="X-Solve-Secret: 여기에-시크릿" # 쏠브가 보낼 인증 헤더
USER_KEY="100023" # 구매 내역이 있는 테스트 회원
UNKNOWN_KEY="solve-selfcheck-no-such-user" # 존재하지 않는 회원
BODY_FILE=$(mktemp)
call() { # $1=인증 헤더 $2=요청 본문 → "상태코드 소요초" 출력
curl -s -o "$BODY_FILE" -w '%{http_code} %{time_total}' --max-time 10 \
-X POST "$URL" -H 'Content-Type: application/json' -H "$1" -d "$2"
}
report() { # $1=점검명 $2=통과 여부(0/1) $3=상세
if [ "$2" = 1 ]; then echo "PASS $1 ($3)"; else echo "FAIL $1 ($3)"; fi
echo " 응답: $(head -c 300 "$BODY_FILE")"
}
read -r code secs <<<"$(call "$SECRET_HEADER" "{\"user_key\":\"$USER_KEY\"}")"
ok=0; [ "$code" = 200 ] && tr -d ' \n\r\t' < "$BODY_FILE" | grep -q '"item_code":"' && ok=1
report "구매 회원 → 200 + item_code 포함" $ok "HTTP $code, ${secs}s"
read -r code secs <<<"$(call "$SECRET_HEADER" "{\"user_key\":\"$UNKNOWN_KEY\"}")"
ok=0; [ "$code" = 200 ] && tr -d ' \n\r\t' < "$BODY_FILE" | grep -q '"item_list":\[\]' && ok=1
report "없는 회원 → 200 + 빈 item_list" $ok "HTTP $code, ${secs}s"
read -r code secs <<<"$(call "X-Solve-Secret: wrong-secret" "{\"user_key\":\"$USER_KEY\"}")"
ok=0; [[ "$code" =~ ^4 ]] && ok=1
report "틀린 시크릿 → 4xx" $ok "HTTP $code, ${secs}s"
rm -f "$BODY_FILE"PASS 구매 회원 → 200 + item_code 포함 (HTTP 200, 0.21s)
PASS 없는 회원 → 200 + 빈 item_list (HTTP 200, 0.09s)
PASS 틀린 시크릿 → 4xx (HTTP 403, 0.05s)ⓐ 방식이라면 로그인 API 의 curl 예시로 맞는 비밀번호(200 + user_key)와 틀린 비밀번호(4xx)도 확인해 보세요.
2. 쏠브에 보낼 테스트 자료
아래 자료를 쏠브 담당자 이메일로 보내주세요. 담당자 주소는 계약 시 안내해 드립니다.
| 자료 | ⓐ 자격증명 API | ⓑ 호스팅 로그인 페이지 |
|---|---|---|
| 로그인 | 로그인 API URL | 쏠브 전용 로그인 페이지 URL |
| 구매내역 | 구매내역 API URL | 구매내역 API URL |
| 인증 | 시크릿과 헤더 이름 | 시크릿과 헤더 이름 |
| 테스트 계정 | ID/PW (구매 내역이 있는 계정) | 로그인 가능한 테스트 회원 + 그 회원의 user_key |
| 비교용 | 그 계정이 보유한 item_code 와 상품명 | 같음 |
시크릿·소셜 계정처럼 민감한 정보는 메일 본문 대신 별도 보안 채널로 전달 방법을 협의합니다.
3. 쏠브가 확인하는 것
| 구분 | 확인 내용 |
|---|---|
| API | 응답 형식, user_key 가 매번 같은지, 환불 항목이 빠지는지, 오류 코드 구분 |
| 연동 | 쏠브 앱에서 로그인 → 연동 완료까지 (ⓑ 는 같은 웹뷰 안에서 끝나는지) |
| 책장 | 테스트 계정의 item_code 에 맞는 책이 책장에 보이는지 |
| 회수 | 테스트 계정에서 상품을 뺐을 때 다음 동기화에 책장에서 빠지는지 |
제휴사에서도 같은 계정으로 응답을 점검해 주세요.
4. 출시 전 체크리스트
- 로그인(ⓐ 또는 ⓑ)이 동작하고,
user_key가 불변·유일하다 - 구매내역 API 가 환불·만료 항목을 빼고, 없는 회원에게 빈 배열(200)을 준다
- 장애·부분 조회 실패 때는
5xx로 응답한다 - 판매 중인 전자책마다 연동코드가 입력됐다 (카탈로그 파일 방식이면 전체 목록을 전달했다)
- 모든 통신이 HTTPS 이고, 서버 간 호출에 시크릿 인증이 적용됐다
- 테스트 계정으로 쏠브 앱 책장에 책이 보인다
- 롤백 방법과 연락 창구를 양쪽이 합의했다
출시 후
- 회원 안내: 연동은 회원이 쏠브 앱에서 직접 시작하므로, 제휴사 사이트에서 쏠브 앱을 안내하면 이용률이 크게 올라갑니다. 구매 후 사용자 안내를 참고하세요.
- 시크릿 회전·URL 변경: 미리 알려 주세요. 새 값(주소)과 옛 값(주소)을 함께 받아 주시는 동안 쏠브가 새 값으로 바꿉니다(반영까지 최대 5분). 바뀐 것을 확인하신 뒤 옛 값을 폐기하시면 됩니다. (보안 요구사항)
- 롤백: 연동을 끄면 신규 연동과 동기화가 멈춥니다. 이미 들어간 책은 남습니다. 회수가 필요하면 쏠브 담당자와 범위·시점을 협의해 주세요.