제휴사 연동
구매내역 API
사용자 키로 회원의 유효 구매 목록을 반환하는 API
구매내역 API
쏠브가 user_key 를 보내면, 그 회원이 지금 이용할 수 있는 구매 목록을 돌려주는 server-to-server API 입니다. 제휴사가 이 API 를 만들어 주시면 됩니다.
응답에는 현재 유효한 권한만 담아 주세요. 환불·만료된 항목은 빼고, 사라진 항목은 다음 동기화 때 권한 회수의 기준이 됩니다.
엔드포인트 URL 과 인증 헤더는 제휴사가 정합니다.
엔드포인트
POST {제휴사가 정의한 URL}- 모든 호출은 HTTPS 입니다.
- 본문(Body)은 JSON 입니다.
- 제휴사가 발급한 시크릿을 쏠브가 헤더에 담아 보냅니다 (헤더 이름과 스킴은 제휴사가 정합니다).
- 호출에 데이터 변경 같은 부작용이 없어야 합니다. 응답은 호출 시점의 최신 구매 상태를 반환하며, 구매·환불에 따라 이전 호출과 달라질 수 있습니다.
- 응답은 회원의 유효 구매 항목을 한 번에 모두 돌려주세요. 페이지네이션은 사용하지 않으며, 분할이 꼭 필요하다면 미리 협의해 주세요.
요청
user_key·string· 필수 — 연동할 때 발급한 회원 식별자.
{ "user_key": "ptn-9c1f0a7b-immutable" }응답
성공 (200)
item_list·array· 필수 — 현재 유효한 구매 항목 배열.item_list[].item_code·string· 필수 — 제휴사 상품 코드 (책 단위가 아닌 상품 단위). 상품 카탈로그와 연결할 때 사용하는 키이며, 하나의item_code에 여러 권의 책이 포함될 수 있습니다.item_list[].item_name·string· 선택 — 표시용 상품명.
{
"item_list": [
{ "item_code": "BOOK_TOEIC_2026", "item_name": "토익 실전 2026" },
{ "item_code": "LEC_GRAMMAR_01" }
]
}{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"required": ["item_list"],
"properties": {
"item_list": {
"type": "array",
"items": {
"type": "object",
"required": ["item_code"],
"properties": {
"item_code": { "type": "string", "description": "제휴사 상품 코드 (카탈로그 연결 키)" },
"item_name": { "type": "string" }
},
"additionalProperties": true
}
}
},
"additionalProperties": true
}응답 규칙과 에러 처리
- 환불·만료된 항목 —
item_list에서 빼주세요. 쏠브는 다음 동기화 때 해당 권한을 회수합니다. - 제휴사 API 장애·타임아웃 —
5xx또는 타임아웃으로 응답해 주세요. 쏠브가 자동 재시도하며, 이미 부여된 권한은 그대로 유지합니다 (장애가 곧바로 권한 회수로 이어지지 않도록 하기 위함입니다). user_key미존재 — 탈퇴 등으로 회원이 더 이상 존재하지 않으면 빈item_list(200) 로 응답해 주세요. 쏠브가 해당 권한을 회수합니다.404같은 오류로 응답하면 쏠브는 일시 장애로 간주해 기존 권한을 그대로 유지합니다.
item_list 가 빈 배열인 경우와 오류로 응답한 경우의 의미가 다릅니다. 정상 응답(200)으로 빈 배열이 오면 쏠브는 "구매 내역이 없음"으로 해석해 권한을 회수하고, 오류 응답은 권한 회수로 이어지지 않습니다.