제휴사 연동
회수 알림 API
환불·취소·탈퇴가 일어나면 쏠브에 알려 회원의 책을 바로 열 수 없게 하세요.
제휴사 서버가 환불·취소·탈퇴를 쏠브에 알리면, 쏠브가 그 회원의 해당 책을 바로 끕니다. 구매내역 API 는 회원이 동기화할 때만 반영되지만, 이 API 는 호출한 순간 반영됩니다.
구매내역 목록에서도 빼야 합니다
회수 알림을 보낸 뒤에도 그 상품을 구매내역 API 목록에 계속 넣으면, 쏠브는 다음 동기화 때 그 책을 다시 지급합니다. 회수 알림과 함께 목록에서도 빼 주세요.
한눈에 보기
| 항목 | 내용 |
|---|---|
| 호출 주체 | 제휴사 서버 → 쏠브 |
| 메서드·경로 | POST /api/v1/partner-connect/revocations |
| 서버 주소 | 쏠브 담당자가 전달한 API 서버 주소 |
| 인증 | Authorization: Bearer <콜백 인증 키> — 콜백·열람 여부 조회와 같은 키 |
| 대상 | 표준 규약 제휴사 |
| 호출 한도 | 호출 서버 IP 기준 분당 600회 |
| 멱등 | 같은 idempotency_key 로 다시 호출하면 처음 응답을 그대로 돌려줍니다 |
| 타임아웃·재시도 | 10초를 권장합니다. 5xx·타임아웃은 같은 idempotency_key 로 재시도하세요. 429는 Retry-After만큼 기다리세요. |
요청
curl -X POST "$SOLVE_API_BASE_URL/api/v1/partner-connect/revocations" \
-H "Authorization: Bearer $SOLVE_CALLBACK_SECRET" \
-H 'Content-Type: application/json' \
-d '{"platform_type":17,"user_key":"member-123","items":[{"item_code":"BOOK_2026"}],"reason":"refund","idempotency_key":"refund-20261119-0001"}'curl -X POST "$SOLVE_API_BASE_URL/api/v1/partner-connect/revocations" \
-H "Authorization: Bearer $SOLVE_CALLBACK_SECRET" \
-H 'Content-Type: application/json' \
-d '{"platform_type":17,"user_key":"member-123","all":true,"reason":"withdrawal","idempotency_key":"withdrawal-member-123"}'| 필드 | 타입 | 필수 | 설명 |
|---|---|---|---|
platform_type | 양의 정수 | 필수 | 쏠브가 전달한 제휴사 번호입니다. 예시의 17을 발급받은 값으로 바꾸세요. |
user_key | 문자열 | 필수 | 로그인 시 전달한 회원의 불변 식별자입니다. 1~255자이며 대소문자를 구분합니다. |
items | 배열 | all 이 없으면 필수 | 회수할 상품 1~100개입니다. |
items[].item_code | 문자열 | 필수 | 상품 연결에 등록한 연동코드입니다. 최대 255자이며, 앞뒤 공백을 뗀 뒤 대소문자까지 정확히 비교합니다. |
all | true | items 가 없으면 필수 | 그 회원이 이 제휴사에서 받은 책 전부를 회수합니다. 모든 상품을 환불했거나 탈퇴한 회원에 씁니다. items 와 함께 보내면 400입니다. |
reason | 문자열 | 필수 | "refund"(환불), "cancel"(취소), "withdrawal"(탈퇴) 중 하나입니다. 처리 방법은 같고, 기록에 남습니다. |
idempotency_key | 문자열 | 필수 | 이 회수 요청을 구분하는 제휴사의 값입니다. 1~128자, 공백 없는 영문·숫자·기호이며 대소문자를 구분합니다. 주문번호·환불번호처럼 요청마다 다른 값을 쓰세요. |
응답
성공
{
"linked": true,
"revoked_count": 1,
"items": [
{ "item_code": "BOOK_2026", "revoked": true }
]
}| 필드 | 설명 |
|---|---|
linked | 그 회원의 쏠브 연동 정보가 있으면 true입니다. 없으면 false이고, 처리할 것이 없다는 뜻이지 오류가 아닙니다. |
revoked_count | 이번 호출로 끈 책의 수입니다. 한 상품코드에 여러 권이 들어 있으면 그만큼 셉니다. |
items | items 로 요청했으면 요청과 같은 순서·개수이며 item_code는 요청한 문자열 그대로입니다. all 로 요청했으면 이번에 끈 책의 상품코드 목록(중복 제거·오름차순)입니다. |
items[].revoked | 그 상품코드로 받은 책을 이번 호출로 껐으면 true입니다. 이미 꺼져 있었거나, 받은 적이 없거나, 등록되지 않은 코드면 false입니다. |
같은 idempotency_key 로 다시 호출하면 처음 응답 본문을 그대로 돌려주고, 응답 헤더에 Idempotent-Replayed: true 를 붙입니다. 다시 처리하지는 않습니다.
실패
{
"error": "Conflict",
"message": "Idempotency key reused with a different request"
}| HTTP 상태 | 의미 |
|---|---|
400 | 본문 형식 오류(items·all 을 둘 다 보내거나 둘 다 빠뜨림, 상품 수 범위 초과, 모르는 reason 등) 또는 표준 규약 대상이 아닌 제휴사 번호입니다. |
401 | 인증 헤더가 없거나 키가 틀렸거나, 쏠브에 콜백 인증 키가 설정되지 않았습니다. |
409 | 같은 idempotency_key 로 다른 내용(회원·상품·사유)을 보냈습니다. 새 요청에는 새 키를 쓰세요. |
429 | 호출 한도를 넘었습니다. Retry-After 헤더의 초만큼 기다리세요. |
500 | 처리 중 오류가 발생했습니다. 같은 idempotency_key 로 재시도하세요. |
쏠브가 하는 일
user_key로 연동된 쏠브 회원을 찾습니다. 없으면linked: false로 응답하고 끝납니다.- 그 회원이 이 제휴사에서 그 상품코드로 받은 책을 끕니다. 구매내역 목록에서 상품이 빠졌을 때와 같은 방법입니다. 다른 제휴사에서 받은 같은 책은 그대로입니다.
- 정산 기록에도 목록에서 빠졌을 때와 같이 환불로 남깁니다.
- 끈 책은 그 순간부터 열 수 없습니다. 회원 앱의 책장 목록에서는 다음 목록 갱신 때 빠집니다.
- 다시 구매하면 구매내역 목록에 다시 넣어 주세요. 다음 동기화 때 책이 다시 들어가고, 필기와 읽던 위치는 그대로 이어집니다.
- 회수 알림은 선택 사항입니다. 보내지 않아도 구매내역 목록에서 빼면 다음 동기화 때 빠집니다. 바로 막아야 할 때와, 목록이 통째로 비는 경우(모두 환불·탈퇴)에 쓰세요.
Node.js 예시
async function notifyRevocation(userKey, itemCodes, reason, idempotencyKey) {
const response = await fetch(`${process.env.SOLVE_API_BASE_URL}/api/v1/partner-connect/revocations`, {
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,
...(itemCodes === 'all' ? { all: true } : { items: itemCodes.map((item_code) => ({ item_code })) }),
reason,
idempotency_key: idempotencyKey, // 재시도해도 같은 값
}),
signal: AbortSignal.timeout(10_000),
});
if (response.status >= 500 || response.status === 429) throw new Error(`재시도 필요: HTTP ${response.status}`);
if (!response.ok) throw new Error(`회수 알림 실패: HTTP ${response.status}`);
return response.json();
}구현 체크리스트
- 브라우저가 아닌 서버에서 콜백 인증 키로 호출합니다.
- 환불·취소한 상품을 구매내역 API 목록에서도 뺍니다.
- 요청마다 다른
idempotency_key를 쓰고, 재시도할 때는 같은 값을 씁니다. - 모든 상품을 환불했거나 탈퇴한 회원은
all: true로 보냅니다. -
linked: false는 오류가 아니라 처리할 것이 없다는 뜻으로 다룹니다.