Developers
제휴사 연동

회수 알림 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자이며, 앞뒤 공백을 뗀 뒤 대소문자까지 정확히 비교합니다.
alltrueitems 가 없으면 필수그 회원이 이 제휴사에서 받은 책 전부를 회수합니다. 모든 상품을 환불했거나 탈퇴한 회원에 씁니다. 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이번 호출로 끈 책의 수입니다. 한 상품코드에 여러 권이 들어 있으면 그만큼 셉니다.
itemsitems 로 요청했으면 요청과 같은 순서·개수이며 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 로 재시도하세요.

쏠브가 하는 일

  1. user_key 로 연동된 쏠브 회원을 찾습니다. 없으면 linked: false 로 응답하고 끝납니다.
  2. 그 회원이 이 제휴사에서 그 상품코드로 받은 책을 끕니다. 구매내역 목록에서 상품이 빠졌을 때와 같은 방법입니다. 다른 제휴사에서 받은 같은 책은 그대로입니다.
  3. 정산 기록에도 목록에서 빠졌을 때와 같이 환불로 남깁니다.
  • 끈 책은 그 순간부터 열 수 없습니다. 회원 앱의 책장 목록에서는 다음 목록 갱신 때 빠집니다.
  • 다시 구매하면 구매내역 목록에 다시 넣어 주세요. 다음 동기화 때 책이 다시 들어가고, 필기와 읽던 위치는 그대로 이어집니다.
  • 회수 알림은 선택 사항입니다. 보내지 않아도 구매내역 목록에서 빼면 다음 동기화 때 빠집니다. 바로 막아야 할 때와, 목록이 통째로 비는 경우(모두 환불·탈퇴)에 쓰세요.

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 는 오류가 아니라 처리할 것이 없다는 뜻으로 다룹니다.

이 페이지 목차