구매내역 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_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 를 돌려주시거나, 404 같은 명시적 오류로 응답해 주세요.

item_list 가 빈 배열인 경우와 API 장애로 응답하지 못한 경우의 의미가 다릅니다. 정상 응답으로 빈 배열이 오면 쏠브는 "구매 내역이 없음"으로 해석해 권한을 회수할 수 있습니다.

시퀀스

관련 문서

• 상품 카탈로그 · 개요와 용어 · 보안 요구사항