변경 이력

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 정책은 실제로 변경이 생길 때 이 페이지에 추가합니다.