열람 여부 조회 API
회원이 전자책을 열거나 다운로드했는지 조회해 환불 판단에 사용하세요.
제휴사 서버에서 회원별 전자책 열람 여부를 실시간으로 조회합니다. 다운로드도 열람에 포함합니다.
한눈에 보기
| 항목 | 내용 |
|---|---|
| 호출 주체 | 제휴사 서버 → 쏠브 |
| 메서드·경로 | POST /api/v1/partner-connect/access-status |
| 서버 주소 | 쏠브 담당자가 전달한 API 서버 주소 |
| 인증 | Authorization: Bearer <콜백 인증 키> |
| 대상 | 표준 규약 제휴사 |
| 호출 한도 | 호출 서버 IP 기준 분당 600회 |
| 타임아웃·재시도 | 10초를 권장합니다. 5xx·타임아웃은 최대 2번 재시도하고, 429는 Retry-After만큼 기다리세요. 그 밖의 4xx는 요청·인증을 고친 뒤 호출하세요. |
콜백 API와 같은 인증 키를 사용합니다. 쏠브가 키를 바꾸는 동안은 새 키와 옛 키 모두 사용할 수 있습니다. ⓐ 로그인 방식이라 콜백 키를 받지 않았다면 쏠브 담당자에게 발급을 요청하세요. 키는 서버 설정에만 보관하세요.
요청
curl -X POST "$SOLVE_API_BASE_URL/api/v1/partner-connect/access-status" \
-H "Authorization: Bearer $SOLVE_CALLBACK_SECRET" \
-H 'Content-Type: application/json' \
-d '{"platform_type":17,"user_key":"member-123","items":[{"item_code":"BOOK_2026","purchased_at":"2026-11-04T09:00:00+09:00"}]}'| 필드 | 타입 | 필수 | 설명 |
|---|---|---|---|
platform_type | 양의 정수 | 필수 | 쏠브가 전달한 제휴사 번호입니다. 예시의 17을 발급받은 값으로 바꾸세요. |
user_key | 문자열 | 필수 | 로그인 시 전달한 회원의 불변 식별자입니다. 1~255자이며 대소문자를 구분합니다. |
items | 배열 | 선택 | 조회할 상품 1~100개입니다. 생략하면 해당 제휴사가 등록한 연동코드 전체를 조회합니다. 빈 배열([])은 400입니다. |
items[].item_code | 문자열 | 필수 | 상품 연결에 등록한 연동코드입니다. 최대 255자이며, 앞뒤 공백을 뗀 뒤 대소문자까지 정확히 비교합니다. |
items[].purchased_at | 문자열 | 선택 | ISO 8601 구매 시각입니다. 이 시각 이상인 열람만 셉니다. 오프셋이 없으면 한국 시간(+09:00), 날짜만 있으면 그날 00:00 한국 시간입니다. 생략하면 전체 기간을 조회합니다. 잘못된 날짜는 400입니다. |
응답
성공
{
"linked": true,
"items": [
{
"item_code": "BOOK_2026",
"viewed": true,
"first_viewed_at": "2026-11-04T12:00:00+09:00"
}
]
}| 필드 | 설명 |
|---|---|
linked | 해당 회원의 쏠브 연동 정보가 있으면 true입니다. 없으면 false이고 모든 항목이 미열람입니다. |
items | 상품을 지정하면 요청과 같은 순서·개수이며 item_code는 요청한 문자열 그대로입니다. 생략하면 등록 연동코드의 오름차순 목록입니다. |
truncated | 회원 전체 조회에서 등록 코드가 1000개를 넘으면 true입니다. 그 밖에는 키를 생략합니다. |
viewed | 해당 제휴사 경로로 받은 상품의 패키지 중 하나라도 열거나 다운로드했으면 true입니다. |
first_viewed_at | 조건에 맞는 최초 접근·다운로드 중 더 이른 시각입니다. 한국 시간(+09:00)으로 반환하며, 미열람이면 null입니다. |
등록되지 않은 연동코드는 viewed: false, first_viewed_at: null입니다. 다른 제휴사 경로로 받은 같은 책의 열람은 포함하지 않습니다. 정산 배치 결과가 아닌 현재 접근·다운로드 이력을 직접 조회하며, 조회 자체는 구매내역이나 책장 권한을 바꾸지 않습니다.
회원 전체 조회
고객센터에서 한 회원의 전체 상황을 확인하려면 items를 생략하세요. 해당 제휴사가 쏠브에 등록한 상품의 비어 있지 않은 연동코드를 앞뒤 공백 제거·중복 제거 후 대소문자를 구분하는 코드 오름차순으로 반환합니다. 구매 시각 경계 없이 전체 기간의 최초 열람·다운로드를 조회합니다.
curl -X POST "$SOLVE_API_BASE_URL/api/v1/partner-connect/access-status" \
-H "Authorization: Bearer $SOLVE_CALLBACK_SECRET" \
-H 'Content-Type: application/json' \
-d '{"platform_type":17,"user_key":"member-123"}'{
"linked": true,
"items": [
{ "item_code": "BOOK_2025", "viewed": true, "first_viewed_at": "2025-12-01T10:00:00+09:00" },
{ "item_code": "BOOK_2026", "viewed": false, "first_viewed_at": null }
]
}미연동 회원도 같은 등록 코드 목록을 반환하며, linked: false이고 전부 미열람입니다. 등록 코드가 없으면 items: []입니다. 등록 코드가 1000개를 넘으면 앞 1000개와 truncated: true를 반환합니다. 1000개 이하면 truncated 키는 생략합니다.
재구매 주문 환불 판단은 상품코드와 purchased_at을 함께 지정해서 조회하세요. 회원 전체 조회에는 이전 구매의 열람도 포함됩니다.
실패
{
"error": "Unauthorized",
"message": "Invalid partner credentials"
}| HTTP 상태 | 의미 |
|---|---|
400 | 본문 형식 오류, 상품 수 범위 초과, 잘못된 날짜 또는 표준 규약 대상이 아닌 제휴사 번호입니다. |
401 | 인증 헤더가 없거나 키가 틀렸거나, 쏠브에 콜백 인증 키가 설정되지 않았습니다. |
429 | 호출 한도를 넘었습니다. Retry-After 헤더의 초만큼 기다리세요. |
500 | 조회 중 오류가 발생했습니다. 미열람으로 처리하지 말고 재시도하세요. |
Node.js 예시
async function getAccessStatus(userKey, itemCode, purchasedAt) {
const response = await fetch(`${process.env.SOLVE_API_BASE_URL}/api/v1/partner-connect/access-status`, {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.SOLVE_CALLBACK_SECRET}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
platform_type: Number(process.env.SOLVE_PLATFORM_TYPE),
user_key: userKey,
items: [{ item_code: itemCode, ...(purchasedAt ? { purchased_at: purchasedAt } : {}) }],
}),
signal: AbortSignal.timeout(10_000),
});
if (!response.ok) throw new Error(`열람 조회 실패: HTTP ${response.status}`);
return response.json();
}환불 판단에 쓰는 법
환불을 처리하기 직전에 해당 주문의 구매 시각을 purchased_at으로 보내세요. 환불 후 다시 구매한 회원의 이전 열람을 새 구매에 섞지 않기 위해서입니다. 200 응답의 viewed와 제휴사의 환불 정책을 함께 적용하세요. 오류나 타임아웃을 미열람으로 간주하면 안 됩니다. 조회 직후에 새 열람이 생길 수 있으므로 이 API가 열람을 잠그거나 환불을 확정하지는 않습니다. 쏠브 책장 노출은 구매내역 API의 현재 이용 가능 목록으로 결정됩니다.
대여한 책의 열람 확인
대여 항목도 같은 방법으로 확인합니다. 그 대여의 paid_at 을 purchased_at 으로 보내면, 그 결제 이후의 열람만 셉니다. 열람 여부는 책 단위이며 판매와 대여를 구분하지 않습니다. 같은 책을 여러 번 대여했다면 환불하려는 결제의 paid_at 을 보내세요.
구현 체크리스트
- 브라우저가 아닌 서버에서 콜백 인증 키로 호출합니다.
- 재구매 주문은 해당 주문의 구매 시각을 보냅니다. 대여는 그 대여의
paid_at입니다. -
linked: false·미등록 코드와 오류 응답을 구분합니다. - 다운로드도 열람이라는 점을 환불 정책에 반영합니다.