변경 이력
제휴사 연동 API 버전 이력
변경 이력
2026-11-19 · 이용 시작(valid_from)으로 오픈 전 열람 막기 — 구매내역 API 1.1.0
구매내역 API의 contractVersion 을 1.1.0 으로 올렸습니다. valid_from 이 이제 이용 시작으로 동작합니다. 지금까지는 기록만 했지만, 이제 이 시각 전에는 책을 열 수 없습니다. valid_from 을 보내지 않거나 읽을 수 없는 값으로 보내던 구현은 지금처럼 바로 열립니다. 이미 미래 시각을 valid_from 으로 보내고 있었다면 그 시각까지 책이 열리지 않으니 확인해 주세요.
- 사전판매: 구매내역 항목의
valid_from을 이용 시작 시각으로 읽습니다(영구 소장·대여 모두). 이 시각 전에는 책이 책장에 보이지만 열리지 않고 시작 시각을 안내하며, 시각이 지나면 다시 조회하지 않아도 열립니다. 읽는 방법은valid_until과 같고, 날짜만 보내면 그날 00:00 한국 시간부터입니다. (구매내역 API) - 쏠브는 조회마다
valid_from을 새 값으로 바꿉니다. 바로 열리게 하려면valid_from을 빼거나 지난 시각을 보내 주세요. - 대여 항목의
valid_until이valid_from보다 앞서거나 같으면 이용 기간을 확인할 수 없어 열지 않습니다.valid_from이 미래인 대여 항목에valid_until이 없거나 읽을 수 없을 때도 같고, 시작 안내도 하지 않습니다.
2026-11-19 · 공개 샌드박스
샌드박스를 열었습니다. 운영과 따로 발급하는 샌드박스 콜백 시크릿으로 호스팅 로그인 흐름(1회용 토큰 규칙 포함), 구매내역 API 응답 검증과 책장 미리보기, 열람 여부·열람 기록·회수 알림 API 를 실제 회원·책·정산에 영향 없이 시험할 수 있습니다. 운영 계약은 바뀌지 않아 contractVersion 은 그대로입니다.
2026-11-19 · 회수 알림 API 와 책장 열기 동기화
기존 계약과 호환되어 contractVersion 은 그대로입니다. 기존 구현은 수정 없이 동작합니다.
- 회수 알림 API: 환불·취소·탈퇴를 쏠브에 알리면 그 회원의 책을 바로 열 수 없게 합니다. 상품코드 목록 또는
all: true(그 회원의 책 전부)로 보내고,idempotency_key로 같은 요청의 재시도를 구분합니다. 선택 사항이며, 보내도 구매내역 목록에서는 그 상품을 빼야 합니다. (회수 알림 API) - 모두 환불·탈퇴: 목록이 통째로 비는 회원은 회수 알림을
all: true로 보내면 책이 빠집니다. 빈 목록만으로는 지금처럼 빼지 않습니다. (구매내역 API) - 책장 열기 동기화: 회원이 쏠브 앱에서 책장 목록을 새로 불러올 때, 마지막 자동 동기화로부터 5분이 지났으면 쏠브가 백그라운드로 구매내역 API 를 호출합니다. 결과는 그다음 책장 목록부터 보입니다. (개념과 용어)
2026-11-19 · 열람 기록 조회 API 추가
표준 규약 제휴사 서버가 열람 기록 조회 API로 회원의 열람 기록을 시간 순서로 받을 수 있습니다. 상품코드·기간으로 좁히고 next_cursor로 나눠 받으며, 한 번에 최대 500건입니다. 기록마다 기기 종류와 운영체제 종류가 담기고(2026년 11월 이전 기록은 unknown), 기기 고유 식별자·모델 이름·버전은 담기지 않습니다. 열람 여부 조회와 같은 인증 키·호출 한도를 씁니다. 새 API 추가라 contractVersion은 그대로입니다.
2026-11-17 · 대여 항목 추가와 동기화 시점 정정
기존 계약과 호환되어 contractVersion 은 그대로입니다. access_type 이 없는 응답은 지금처럼 영구 소장으로 읽으므로 기존 구현은 수정 없이 동작합니다.
- 대여 항목: 구매내역 항목에 선택 필드
access_type을 추가했습니다."rental"이면 대여이며paid_at,valid_until,price를 함께 보내야 합니다. 판매와 같은 상품코드를 씁니다. (구매내역 API) - 대여 기간이 끝나면: 책은 책장에 남고, 열려고 하면 끝난 날짜를 안내하며 열리지 않습니다. 다시 대여하면 다시 열립니다. 끝난 대여 항목도 목록에 계속 보내 주세요.
- 셀프 점검 도구: 6번 점검이
access_type값과 대여 항목의paid_at·valid_until·price를 확인합니다. (테스트와 출시) - 동기화 시점 정정: 동기화는 책장에 들어갈 때가 아니라 책장 새로고침(아래로 당기기)과 연동 계정 화면의 "전체 동기화" 때 실행됩니다. (개념과 용어)
2026-11-04 — 회원 전체 열람 조회 추가
열람 여부 조회 API에서 items를 생략하면 해당 제휴사의 등록 연동코드를 공백 제거·중복 제거·코드 오름차순으로 반환합니다. 전체 기간의 최초 열람·다운로드를 조회하며, 미연동 회원도 같은 목록이 전부 미열람으로 반환됩니다. 최대 1000개이며 초과하면 truncated: true, 그 밖에는 이 키를 생략합니다. 기존 상품별 요청은 그대로 동작하고 빈 배열은 400입니다. 재구매 주문 환불 판단에는 상품코드와 purchased_at을 지정하세요. 하위 호환 변경으로 contractVersion은 그대로입니다.
2026-11-04 — 구매와 환불 안내 보강
구매·취소·환불·재구매에 따른 책장 처리와 빈 목록 예외를 정리했습니다. 환불 상태 전달은 선택 사항이며, 열람 여부를 확인해 환불을 판단하는 방법을 추가했습니다. (구매내역 API, 자주 묻는 질문)
2026-11-04 — 열람 여부 조회 API 추가
표준 규약 제휴사 서버가 열람 여부 조회 API를 호출해 회원·상품별 열람 여부를 실시간으로 확인할 수 있습니다. 다운로드도 열람에 포함하며, 구매 시각을 보내면 그 시각 이후의 이력만 조회합니다. 콜백과 같은 인증 키를 사용하고, 한 번에 최대 100개·분당 600회입니다. 기존 계약과 호환되어 contractVersion은 그대로입니다.
2026-10-03 — 응답 크기 상한 명시
contractVersion 은 그대로입니다. 구매내역 API 와 ⓐ 자격증명 로그인 API 의 응답 본문 크기 상한을 문서에 적었습니다.
- 응답은 1MB 이하: 응답 본문은 1MB(1,048,576바이트) 이하여야 합니다. 쏠브는 1MB 를 넘는 응답을 받지 않으며, 넘으면 그 호출은 실패로 처리하고 재시도하지 않습니다. 구매내역은 기존 책장을 유지합니다. (구매내역 API, ⓐ 자격증명 로그인 API)
item_code비교 설명 정정: 쏠브는item_code의 앞뒤 공백을 떼고 비교합니다. 그 밖은 대소문자까지 글자 그대로 같아야 합니다. (상품 연결)
2026-10-02 — 점검 도구 추가
규약은 바뀌지 않았습니다. 제휴사가 자기 PC 에서 돌리는 점검 도구를 추가했습니다.
- 셀프 점검 v2 (
solve-selfcheck.mjs): 구매내역 API 와 ⓐ 로그인 API 를 한 번에 점검합니다. 응답 형식, 선택 필드, 오류 응답, 응답 시간을 확인합니다. 기존 bash 스크립트는 "빠른 확인"으로 그대로 남아 있습니다. (테스트와 출시) - 콜백 흉내 도구 (
solve-callback-mock.mjs): ⓑ 방식 제휴사가 계약 전에도 자기 로그인 페이지의 콜백을 시험할 수 있습니다. (ⓑ 호스팅 로그인 페이지)
v1.1.0 — 2026-10-02
v1.0.0 과 호환됩니다. 기존 구현은 수정 없이 동작합니다.
- 구매내역 선택 필드 4개: 항목마다
price·paid_at·valid_from·valid_until을 선택으로 더 담을 수 있습니다. 없어도 동작하고, 형식이 틀리면 그 필드만 무시하며 책 지급에는 영향이 없습니다. (구매내역 API) price정산 규칙:price를 안 보내거나0이면 파트너 어드민에 등록한 가격으로 정산합니다.- 인증 실패 상태 코드 표기 통일: 시크릿 불일치는
401또는403으로 표기합니다. 쏠브는 둘을 구분하지 않고 같은 인증 실패로 처리합니다(둘 다 재시도하지 않습니다). 예시 코드는 그대로 유효합니다. (구매내역 API, ⓐ 자격증명 로그인 API) - 정정 — 시크릿 회전: 제휴사가 발급한 API 시크릿은 제휴사가 새 값과 옛 값을 함께 받아 주는 동안 쏠브가 새 값으로 바꿉니다(반영까지 최대 5분). 쏠브가 발급한 콜백 인증 시크릿은 쏠브가 일정 기간 새 값과 옛 값을 함께 받습니다. (보안 요구사항)
- 정정 — 롤백: 연동을 끄면 신규 연동과 동기화가 멈추고, 이미 들어간 책은 남습니다. (테스트와 출시)
- 기존 전자책 연동코드: 이미 등록한 전자책은 파트너 어드민 상품 상세에서 연동코드를 한 번 넣을 수 있습니다. (상품 연결)
- 정정 — 구매 후 사용자 안내: 앱의 연동 화면으로 바로 들어가는 링크는 제공하지 않습니다. 대신 쏠브북스 웹의 제휴사 연동 화면 주소를 안내합니다. (구매 후 사용자 안내)
2026-09-30 — ⓑ 콜백 인증 추가
- ⓑ 콜백 인증: 쏠브가 제휴사별로 발급한 시크릿을
Authorization: Bearer헤더로 보내야 합니다. 신규 제휴사는 처음부터 필수이며, 이미 운영 중인 제휴사는 쏠브와 일정을 맞춰 전환합니다(전환 전까지는 기존처럼 동작). 인증 실패는401입니다. (ⓑ 호스팅 로그인 페이지) redirect_url서명: 쏠브가redirect_url에 위변조 방지 서명 파라미터를 추가합니다. 제휴사는 지금처럼 URL 을 수정 없이 그대로 사용하면 됩니다.
2026-09-30 — 문서 개편
API 계약 변경은 없습니다. 읽기 쉽게 구조를 바꾸고 예시를 늘렸습니다.
- 새 페이지: 구현 순서, AI로 구현하기(통합 프롬프트), 자주 묻는 질문
- 구현 예시: 로그인·구매내역 API 페이지에 Node.js·Python·Java·PHP 예시와 curl 재현 명령을 추가했습니다.
- 셀프 점검: 테스트와 출시에 구매내역 API 점검 스크립트를 추가했습니다.
- 호출 조건 명시: 호출당 타임아웃 10초,
5xx·타임아웃 시 최대 2번 재시도,4xx는 재시도하지 않음. - 상황별 응답 표: 구매내역 API 의 응답별 쏠브 처리를 한 표로 정리했습니다.
- 정정 — 빈 목록 응답: 07-21 에 "빈
item_list(200)면 권한을 회수한다"고 적었으나, 실제로는 목록이 통째로 비면 회수하지 않습니다(장애 오탐 방지). 일부 항목이 빠진 경우에만 그 항목을 회수합니다. 구매내역 API의 상황별 응답 표를 확인해 주세요. - 로그인 방식 기준: 자체 ID/PW 와 소셜 로그인을 함께 운영하면 ⓑ 를 선택하도록 명시했습니다.
- 상품 연결: 파트너 어드민에 전자책을 등록하며 연동코드를 입력하면 카탈로그 파일이 필요 없음을 명시하고, 판매유형(
연동형·연동+쏠브북스)과 패키지 입력 방법을 정리했습니다. - AI 도구용 경로(
/llms.txt,/llms-full.txt, 페이지 URL +.md)와 페이지별 "마크다운 복사"·"AI로 열기" 버튼을 제공합니다.
2026-07-21 — 문서 정정
쏠브의 실제 동작에 맞게 서술을 바로잡았습니다. API 동작 자체가 바뀐 것은 아니지만, 아래 항목은 구현에 영향을 줄 수 있으니 확인해 주세요.
user_key미존재 응답 — 회원이 더 이상 존재하지 않으면 빈item_list(200)로 응답해야 권한이 회수됩니다.404같은 오류 응답은 일시 장애로 간주해 기존 권한을 유지합니다. (구매내역 API)- 시크릿 발급 주체 — server-to-server 시크릿은 제휴사가 발급하고, 쏠브가 헤더에 담아 보냅니다.
- ⓑ 콜백
id— 소셜 인증을 쓰더라도 소셜 프로필 ID·이메일이 아니라 제휴사 내부 회원의 불변 식별자를 보내야 합니다. - ⓑ 리다이렉트 — 연동을 시작한 브라우저(쏠브 앱이 연 웹뷰) 안에서
redirect_url로 이동해야 연동이 완료됩니다. (보안) - 동기화 시점 — 연동 직후 1회 자동으로 동기화합니다.
- 상품 카탈로그 — 파트너 어드민 등록 시 자동 매핑되는 방식과
item_code재사용 금지 규칙을 추가했습니다. - 구매 후 사용자 안내 페이지를 새로 만들었습니다.
2026-05-29 — 문서 보강
item_code가 책 단위가 아닌 상품 단위임을 명시하고, 패키지·혼합 세트 규칙과 권장 필드isbn_list를 추가했습니다. (상품 카탈로그)
v1.0.0 — 2026-05-19
표준 API 를 처음 공개했습니다.
변경 정책
- 호환되지 않는 변경은 라이브 제휴사에 미리 안내하고, 버전을 올려서 적용합니다.
- 호환되는 변경은 필드 추가처럼 하위 호환 범위 안에서만 진행합니다.
- 정식 deprecation 정책은 실제로 변경이 생길 때 이 페이지에 추가합니다.