제휴사 연동
열람 기록 조회 API
회원의 전자책 열람 기록을 시간 순서로 조회해 관리자 화면과 마이페이지에 보여 주세요.
제휴사 서버에서 회원별 전자책 열람 기록을 시간 순서로 조회합니다. 처음·최근 열람 일시, 진행률, 마지막 기기는 이 기록으로 계산하세요. 열람 여부만 필요하면 열람 여부 조회 API가 더 간단합니다.
열람 기록에는 개인정보가 들어 있습니다. 회원 본인의 마이페이지와 제휴사의 고객 응대·환불 판단·관리자 화면에만 쓰고, 그 밖의 목적(마케팅·프로파일링·제3자 제공)으로는 쓰지 마세요. 아래 개인정보 항목과 이용 목적을 함께 확인하세요.
한눈에 보기
| 항목 | 내용 |
|---|---|
| 호출 주체 | 제휴사 서버 → 쏠브 |
| 메서드·경로 | POST /api/v1/partner-connect/access-history |
| 서버 주소 | 쏠브 담당자가 전달한 API 서버 주소 |
| 인증 | Authorization: Bearer <콜백 인증 키> — 열람 여부 조회와 같은 키 |
| 대상 | 표준 규약 제휴사 |
| 호출 한도 | 호출 서버 IP 기준 분당 600회 |
| 한 번에 받는 기록 | 기본 100건, 최대 500건. 더 있으면 next_cursor 로 이어서 받습니다. |
| 타임아웃·재시도 | 10초를 권장합니다. 5xx·타임아웃은 최대 2번 재시도하고, 429는 Retry-After만큼 기다리세요. 그 밖의 4xx는 요청·인증을 고친 뒤 호출하세요. |
요청
curl -X POST "$SOLVE_API_BASE_URL/api/v1/partner-connect/access-history" \
-H "Authorization: Bearer $SOLVE_CALLBACK_SECRET" \
-H 'Content-Type: application/json' \
-d '{"platform_type":17,"user_key":"member-123","item_code":"BOOK_2026","page_size":50}'| 필드 | 타입 | 필수 | 설명 |
|---|---|---|---|
platform_type | 양의 정수 | 필수 | 쏠브가 전달한 제휴사 번호입니다. |
user_key | 문자열 | 필수 | 로그인 시 전달한 회원의 불변 식별자입니다. 1~255자이며 대소문자를 구분합니다. |
item_code | 문자열 | 선택 | 상품 연결에 등록한 연동코드 하나입니다. 앞뒤 공백을 뗀 뒤 대소문자까지 정확히 비교합니다. 생략하면 등록한 모든 연동코드의 책을 조회합니다. |
from | 문자열 | 선택 | ISO 8601 시각입니다. 이 시각 이상인 기록만 반환합니다. 오프셋이 없으면 한국 시간, 날짜만 있으면 그날 00:00 한국 시간입니다. |
to | 문자열 | 선택 | ISO 8601 시각입니다. 이 시각 미만인 기록만 반환합니다. from보다 늦어야 합니다. |
order | 문자열 | 선택 | desc(최근 기록부터, 기본값) 또는 asc(오래된 기록부터)입니다. |
page_size | 정수 | 선택 | 한 번에 받을 기록 수입니다. 1~500, 기본 100입니다. |
cursor | 문자열 | 선택 | 앞 응답의 next_cursor를 그대로 넣습니다. 첫 요청에는 넣지 않습니다. |
다음 쪽을 받을 때는 cursor만 바꾸고 나머지 필드는 첫 요청과 같게 보내세요. 커서의 정렬 방향과 order가 다르면 400입니다.
응답
성공
{
"linked": true,
"records": [
{
"type": "view",
"occurred_at": "2026-11-18T21:04:10+09:00",
"item_codes": ["BOOK_2026"],
"book_id": "c0a8f3e2-5d1b-4c3e-9f2a-7b6d5e4c3b2a",
"isbn": "9791100000001",
"device": { "type": "tablet", "os": "ios" }
},
{
"type": "view",
"occurred_at": "2026-11-18T21:03:55+09:00",
"item_codes": ["BOOK_2026"],
"book_id": "c0a8f3e2-5d1b-4c3e-9f2a-7b6d5e4c3b2a",
"isbn": "9791100000001",
"device": { "type": "mobile", "os": "ios" }
}
],
"next_cursor": "eyJ2IjoxLCJvIjoiZGVzYyIsInQiOjE3OTUwMDM0MzUwMDAsImsiOjAsInAiOiJjMGE4ZjNlMi01ZDFiLTRjM2UtOWYyYS03YjZkNWU0YzNiMmEifQ"
}| 필드 | 설명 |
|---|---|
linked | 해당 회원의 쏠브 연동 정보가 있으면 true입니다. 없으면 false이고 records는 빈 배열입니다. |
records | 기록 목록입니다. order 방향의 시간 순서이며, 같은 초에 생긴 기록도 매번 같은 순서로 나옵니다. |
records[].type | 대부분 view입니다. 책 파일을 기기에 받아 둔 기록은 download이며, 열람으로 함께 세세요(열람 여부 조회 API와 같습니다). |
records[].occurred_at | 기록 시각입니다. 한국 시간(+09:00), 초 단위입니다. |
records[].item_codes | 이 책이 연결된 연동코드입니다. 한 책이 단품과 패키지 등 여러 코드에 들어 있으면 모두 담깁니다. item_code를 지정했으면 그 코드만 담깁니다. |
records[].book_id | 쏠브 전자책 식별자입니다. 한 상품코드에 여러 권이 묶여 있을 때 어느 책인지 구분하는 데 쓰세요. |
records[].isbn | 그 전자책의 ISBN입니다. 등록되지 않았으면 null입니다. |
records[].device | 그 열람에 쓴 기기의 종류와 운영체제입니다. 아래 표를 보세요. |
next_cursor | 더 받을 기록이 있으면 다음 요청에 넣을 값입니다. 마지막 쪽이면 null입니다. |
device 는 쏠브 앱이 알려 준 기기 정보에서 종류만 판정한 값입니다. 판정할 수 없거나 2026년 11월 이전 기록이면 unknown입니다.
| 필드 | 값 |
|---|---|
device.type | mobile(휴대폰) · tablet(태블릿) · desktop(PC) · unknown(모름) |
device.os | ios · android · windows · macos · unknown(모름) |
범위는 열람 여부 조회 API와 같습니다. 해당 제휴사 경로로 받은 책 가운데 등록한 연동코드에 연결된 책의 기록만 반환합니다. 다른 제휴사 경로나 쏠브에서 직접 받은 같은 책의 기록은 포함하지 않습니다. 판매와 대여는 같은 책이므로 구분하지 않습니다. 조회는 현재 기록을 그대로 읽으며 책장이나 구매내역을 바꾸지 않습니다.
실패
{
"error": "Unauthorized",
"message": "Invalid partner credentials"
}| HTTP 상태 | 의미 |
|---|---|
400 | 본문 형식 오류, 잘못된 날짜(1000~9999년 밖 포함)·커서, from이 to보다 늦거나 같음, 커서와 order 불일치, page_size 범위 밖, 또는 표준 규약 대상이 아닌 제휴사 번호입니다. |
401 | 인증 헤더가 없거나 키가 틀렸거나, 쏠브에 콜백 인증 키가 설정되지 않았습니다. |
429 | 호출 한도를 넘었습니다. Retry-After 헤더의 초만큼 기다리세요. |
500 | 조회 중 오류가 발생했습니다. 기록이 없는 것으로 처리하지 말고 재시도하세요. |
Node.js 예시
async function getAccessHistory(userKey, { itemCode, order = 'desc', pageSize = 100 } = {}) {
const records = [];
let cursor;
do {
const response = await fetch(`${process.env.SOLVE_API_BASE_URL}/api/v1/partner-connect/access-history`, {
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,
...(itemCode ? { item_code: itemCode } : {}),
order,
page_size: pageSize,
...(cursor ? { cursor } : {}),
}),
signal: AbortSignal.timeout(10_000),
});
if (!response.ok) throw new Error(`열람 기록 조회 실패: HTTP ${response.status}`);
const page = await response.json();
if (!page.linked) return { linked: false, records: [] };
records.push(...page.records);
cursor = page.next_cursor;
} while (cursor);
return { linked: true, records };
}화면에 쓰는 법
- 최근 열람 일시:
order: "desc",page_size: 1로 첫 기록을 받으세요. - 처음 열람 일시:
order: "asc",page_size: 1로 첫 기록을 받으세요. 구매 이후만 보려면from에 구매 시각을 넣으세요. - 진행률: 한 상품코드에 묶인 책 가운데 기록이 있는
book_id의 수로 계산하세요. 상품에 묶인 책 목록은 상품 연결에 등록한 ISBN과isbn을 맞춰 보세요. - 마지막 기기:
order: "desc"로 받은 기록 가운데device.type이unknown이 아닌 첫 기록의device를 보여 주세요. - 매번 전체를 읽지 말고 필요한 기간(
from·to)이나 상품(item_code)으로 좁혀 조회하세요.
개인정보 항목과 이용 목적
이 API는 회원 한 명의 이용 기록을 제휴사에 제공합니다. 제공 항목은 아래로 한정됩니다.
| 제공 항목 | 제공하지 않는 항목 |
|---|---|
| 열람 시각과 종류, 연동코드, 쏠브 전자책 식별자와 ISBN, 열람한 기기의 종류와 운영체제 종류 | 기기 고유 식별자, 기기 모델 이름, 운영체제 버전, 앱 버전, 쏠브 회원 번호 |
- 받은 기록은 해당 회원에게 제공하는 서비스(마이페이지의 열람 이력 표시)와 고객 응대·환불 판단·관리자 화면에서만 사용하세요.
- 다른 목적으로 쓰거나 제3자에게 제공하지 마세요. 화면에 표시하는 데 필요한 기간을 넘겨 따로 저장하지 마세요.
- 제휴사의 개인정보 처리방침에 쏠브로부터 받는 이 항목과 이용 목적을 적어 두세요.
구현 체크리스트
- 브라우저가 아닌 서버에서 콜백 인증 키로 호출합니다.
-
next_cursor가null이 될 때까지 같은 조건으로 이어서 받습니다. -
linked: false와 빈 기록, 오류 응답을 구분합니다. -
device가unknown인 기록(오래된 기록 포함)을 화면에서 "알 수 없음"으로 처리합니다. - 받은 기록을 위 이용 목적 안에서만 씁니다.