Developers
제휴사 연동

개념과 용어

연동의 2단계 구조, 꼭 알아야 할 용어, 로그인 방식 고르는 법을 설명합니다.

구현을 시작하기 전에 알아야 할 개념을 정리했습니다. 이 페이지만 읽어도 전체 구조를 이해할 수 있습니다.

연동은 두 단계입니다

  1. 연동(Linking): 회원이 쏠브 앱에서 제휴사 계정으로 로그인하면, 쏠브가 그 회원의 user_key 를 저장합니다. 회원당 한 번만 일어납니다.
  2. 동기화(Sync): 쏠브가 user_key 로 구매내역 API 를 호출해, 받은 상품코드에 맞는 책을 책장에 넣거나 뺍니다.

동기화는 쏠브가 필요할 때 제휴사 API 를 호출하는 방식(pull)입니다. 제휴사가 쏠브에 구매 소식을 따로 알려줄 필요는 없습니다. 환불·취소·탈퇴를 바로 반영해야 하면 선택 사항인 회수 알림 API를 쓰세요.

동기화 시점설명
연동 직후로그인이 끝나면 1회 자동으로 실행됩니다.
책장 열기회원이 쏠브 앱에서 책장 목록을 새로 불러올 때(앱을 연 뒤 책장을 처음 열 때, 폴더 이동·정렬 변경 등), 그 회원의 마지막 자동 동기화로부터 5분이 지났으면 쏠브 서버가 백그라운드로 실행합니다. 결과는 그다음 책장 목록부터 보입니다. 앱을 켜 둔 채 책장 탭에 다시 들어가는 것만으로는 목록을 새로 불러오지 않을 수 있습니다.
책장 새로고침회원이 쏠브 앱의 책장을 아래로 당겨 새로고침할 때 실행됩니다.
전체 동기화회원이 앱의 연동 계정 화면에서 "전체 동기화"를 누를 때 실행됩니다.

용어

용어뜻
user_key제휴사가 정하는 회원 식별자입니다. 한 번 정해지면 바뀌지 않고, 회원끼리 겹치지 않아야 합니다. 내부 회원번호를 권장합니다.
item_code제휴사의 상품코드입니다. 구매내역 API 응답과 쏠브 상품을 잇는 키입니다. 파트너 어드민에서는 연동코드라고 부릅니다.
연동코드파트너 어드민에서 전자책을 등록할 때 입력하는 값으로, item_code 와 같습니다.
시크릿쏠브가 제휴사 API 를 호출할 때 헤더에 담는 인증 값입니다. 제휴사가 발급해 쏠브에 전달합니다.
platform_type쏠브가 제휴사마다 부여하는 숫자 식별자입니다. ⓑ 방식의 콜백과 열람 여부 조회에 씁니다.

user_key 로 로그인 아이디나 이메일을 쓰지 마세요

아이디·이메일은 회원이 바꿀 수 있습니다. user_key 가 바뀌면 회원은 연동과 책장의 책을 모두 잃습니다. 탈퇴한 회원의 값을 다른 회원에게 다시 주는 것도 안 됩니다.

로그인 방식 고르기

ⓐ 자격증명 로그인 APIⓑ 호스팅 로그인 페이지
이럴 때자체 ID/PW 로그인만 운영카카오·네이버·구글·Apple 등 소셜 로그인을 함께 운영
제휴사가 만드는 것로그인 API 1개로그인 페이지 + 쏠브 콜백 호출
ID/PW 가 쏠브를 거치나요?예 (TLS, 로그에 남기지 않음)아니요
구현 난이도낮음중간
상세ⓐ 페이지ⓑ 페이지

소셜로 가입한 회원은 ID/PW 가 없어서 ⓐ 로는 연동할 수 없습니다. 소셜 로그인이 하나라도 있으면 ⓑ 를 고르세요.

쏠브가 정하는 것과 제휴사가 정하는 것

쏠브가 정합니다제휴사가 정합니다
user_key 는 불변·유일해야 한다는 규칙로그인 방식 (ⓐ 또는 ⓑ)
구매내역 응답 형식 (item_list[].item_code)API 엔드포인트 URL
ⓑ 콜백 형식 (id, platform_type)인증 헤더 이름과 방식
현재 유효한 구매만 돌려준다는 규칙내부 데이터 구조

이 페이지 목차