Developers
제휴사 연동

열람 여부 조회 API

회원이 전자책을 열거나 다운로드했는지 조회해 환불 판단에 사용하세요.

제휴사 서버에서 회원별 전자책 열람 여부를 실시간으로 조회합니다. 다운로드도 열람에 포함합니다.

한눈에 보기

항목내용
호출 주체제휴사 서버 → 쏠브
메서드·경로POST /api/v1/partner-connect/access-status
서버 주소쏠브 담당자가 전달한 API 서버 주소
인증Authorization: Bearer <콜백 인증 키>
대상표준 규약 제휴사
호출 한도호출 서버 IP 기준 분당 600회
타임아웃·재시도10초를 권장합니다. 5xx·타임아웃은 최대 2번 재시도하고, 429는 Retry-After만큼 기다리세요. 그 밖의 4xx는 요청·인증을 고친 뒤 호출하세요.

콜백 API와 같은 인증 키를 사용합니다. 쏠브가 키를 바꾸는 동안은 새 키와 옛 키 모두 사용할 수 있습니다. ⓐ 로그인 방식이라 콜백 키를 받지 않았다면 쏠브 담당자에게 발급을 요청하세요. 키는 서버 설정에만 보관하세요.

요청

curl로 조회하기
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·미등록 코드와 오류 응답을 구분합니다.
  • 다운로드도 열람이라는 점을 환불 정책에 반영합니다.

이 페이지 목차