상품 가이드

상품의 주요 속성에는 상품 유형, 상품 상태, 상품 옵션이 있으며, 상품은 가격 플랜과 밀접하게 연결이 됩니다. 상품은 가격 플랜과 1:N 관계이기 때문에 하나의 상품이 여러 개의 가격 플랜을 가질 수 있습니다.
예를들면 하나의 상품에 단건 가격 플랜, 구독 가격 플랜이 생성 될 수 있습니다. 또한 하나의 상품에 여러 구독 가격 플랜을 설정할 수 있습니다. 예를들어 주 단위 결제, 월 단위 결제, 연 단위 결제를 따로 설정할 수 있습니다.
상품과 가격 플랜은 API를 통해 각각 생성할 수는 있지만, 가격 플랜이 없는 상품을 주문할 수는 없습니다. 따라서 상품 생성 API를 통해 상품 생성 후 반드시 가격 플랜을 생성해야 합니다.

​

연관 가이드

• 가격 플랜 가이드

​

사전 준비 작업

• Secret-Token 확인하기

​

상품의 주요 속성

​

상품 유형

스텝페이의 상품은 네 가지 유형의 상품을 지원합니다.

​

상품 상태

스텝페이의 상품은 네 가지 유형의 상품 상태를 지원합니다.

​

상품 생성 및 관리

​

상품 옵션

스텝페이의 상품은 옵션 추가 기능을 제공합니다. 이 옵션은 사이즈, 색상, 패키지 유형 등 다양한 형태로 설정될 수 있습니다. 사용자는 상품을 생성할 때 이러한 옵션을 정의하고 추가할 수 있습니다. 옵션에는 두가지 타입이 있습니다.

• 조합형 옵션
  • 여러가지 옵션을 조합하여 여러 옵션을 생성할 수 있습니다.
  • 예를 들어, ‘사이즈’와 ‘색상’이라는 두 가지 옵션명이 있다면, 각각 ‘사이즈’ 옵션값 (라지, 미디움)과 ‘색상’ 옵션값 (빨강, 노랑)이 서로 조합되어 총 4가지의 제품 옵션을 생성합니다. 조합된 옵션에 대한 가격과 재고를 조합 옵션별로 관리 할 수 있습니다.
• 독립형 옵션
  • 개발 예정입니다.

​

무료 체험 설정

• 스텝페이의 구독 상품에는 무료 체험 여부를 적용할 수 있습니다. 무료 체험은은 일, 주, 월, 년 단위로 설정 할 수 있습니다.
• V1 API를 통해 무료 체험을 적용하기 위해서는 enabledDemo 필드를 ‘true’로 지정 한 후 demoPeriod(체험 기간) demoPeriodUnit(체험 기간 단위)를 적절하게 입력합니다.

​

상품 재고 관리

스텝페이의 모든 상품은 재고를 설정하여 재고를 파악 할 수 있습니다. 서비스 상품의 경우에는 재고를 설정하지 않으면 자동으로 재고가 무제한으로 설정됩니다.
또한, 상품 옵션을 설정 한 경우에도 각각의 옵션에 대한 재고를 설정할 수 있습니다. 재고는 다음과 같이 반영됩니다.

• 단건 가격 플랜에서 고객이 해당 상품을 주문 할 때 수량 만큼 차감 됩니다.
• 구독 가격 플랜에서 첫 주문 시 수량 만큼 차감 후, 구독이 갱신될 때 동일 수량 만큼 자동 차감됩니다.
• 구독 주기 이전에 주문 수량을 변경하면 구독이 갱신될 때 변경된 수량만큼 차감됩니다.
• 상품 재고가 없을 시 상품 상태가 품절 상태로 변경됩니다.
• 조합형 옵션을 설정한 경우 각각의 옵션 마다 재고를 지정 할 수 있습니다. 해당 옵션이 품절 되었을 때 해당 옵션의 상태가 품절 상태로 변하며, 다른 옵션의 재고가 있을 시 상품의 상태가 품절 상태로 변하지 않습니다.
• V1 API에서 quantity 필드를 통해 상품의 재고를 설정할 수 있습니다. ‘null’값 입력 시 재고가 무한대로 설정됩니다.
• 상품 옵션 또한 동일하게 해당 옵션의 quantity 필드를 통해 재고를 설정할 수 있습니다.

​

스텝페이 포탈 사용 예시

• [포탈 → 상품관리 → 새상품 등록] 메뉴로 이동합니다.
• 상품의 기본 정보를 입력하고 저장합니다. 포탈에서 상품을 생성할 때 가격 플랜과 함께 생성하지 않으면 임시저장 상태가 됩니다.

  V1 API를 통해 상품을 생성하면 가격 플랜이 상품과 함께 생성되지 않기 때문에 포탈에서 오류가 발생합니다.
  V1 API를 통해 상품을 생성하는 경우에는 반드시 가격 플랜도 함께 생성해야 합니다.

  

​

API 사용 예시

​

상품 생성

• Request
  curl --request POST \
       --url https://api.steppay.kr/api/v1/products \
       --header 'Secret-Token: {Secret-Token}' \
       --header 'accept: */*' \
       --header 'content-type: application/json' \
       --data '
  {
    "type": "SOFTWARE",
    "status": "SALE",
    "enabledDemo": false,
    "demoPeriodUnit": "DAY",
    "useCombination": true,
    "name": "TEST_PRODUCT",
  }
  '
  
• Response
  {
    "id": 6878,
    "code": "product_L6ySWX1F2",
    "type": "SOFTWARE",
    "status": "SALE",
    "name": "TEST_PRODUCT",
    "subTitle": null,
    "featuredImageUrl": "",
    "imageUrls": [],
    "description": "",
    "summary": null,
    "reasonOfReject": null,
    "sku": null,
    "quantity": null,
    "combinedProducts": [],
    "optionGroups": [],
    "useCombination": true,
    "optionCombinations": [],
    "prices": [],
    "createdAt": "2023-06-19T01:54:14.656027",
    "modifiedAt": "2023-06-19T01:54:14.656027",
    "enabledDemo": false,
    "demoPeriod": 7,
    "demoPeriodUnit": "DAY",
    "categories": [],
    "vendorUuid": "{Vendor UUID}",
    "productOrder": 0,
    "isOnetimePurchasable": false,
    "eventBadge": [],
    "notice": null,
    "useWidget": {
      "useDemo": false,
      "useEventBadge": false,
      "useOnetimePurchasable": false,
      "useNotice": false
    },
    "groupId": null,
    "countrySetting": null
  }
  

​

상품 생성 - 옵션 추가

상품의 옵션을 추가하기 위해 우선 상품 옵션을 정의해야 합니다. 각 옵션은 이름과 값으로 구성됩니다. 예를 들면, 색상 옵션을 추가하는 경우 옵션명은 “색상”이고 값은 “블랙”, “화이트” 등이 될 수 있습니다.

• Request
  curl --request POST \
       --url https://api.steppay.kr/api/v1/products \
       --header 'Secret-Token: {Secret-Token}' \
       --header 'accept: */*' \
       --header 'content-type: application/json' \
       --data '
  {
    "type": "BOX",
    "status": "SALE",
    "enabledDemo": false,
    "demoPeriodUnit": "DAY",
    "optionGroups": [
      {
        "type": "SELECT",
        "options": [
          {
            "name": "BLACK",
            "quantity": 10,
            "addQuantity": 1000
          },
          {
            "name": "WHITE",
            "addQuantity": 10,
            "price": 2000
          }
        ],
        "name": "COLOR
      }
    ],
    "useCombination": true,
    "name": "OPTION_PRODUCT",
  }
  '
  

​

상품 목록 조회

• Request
  curl --request GET \
       --url https://api.steppay.kr/api/v1/products \
       --header 'Secret-Token: {Secret-Token}' \
       --header 'accept: */*'
  
• Response
  {
    "content": [
      {
        "id": 6879,
        "code": "product_VQyHoGO8c",
        "type": "SOFTWARE",
        "status": "SALE",
        "name": "[API]TEST_PRODUCT",
        "quantity": null,
        "featuredImageUrl": "",
        "prices": [],
        "createdAt": "2023-06-19T01:55:11",
        "modifiedAt": "2023-06-19T01:55:11",
        "description": "",
        "categories": [],
        "vendorUuid": "{Vendor UUID}",
        "enabledDemo": false,
        "isOnetimePurchasable": null,
        "productOrder": 0,
        "countrySetting": null
      }
      ...
    ]
  }
  

​

상품 상세 조회

• Request
  curl --request GET \
       --url https://api.steppay.kr/api/v1/products/product_VQyHoGO8c \
       --header 'Secret-Token: {Secret-Token}' \
       --header 'accept: */*'
  
• Response
  {
    "id": 6879,
    "code": "product_VQyHoGO8c",
    "type": "SOFTWARE",
    "status": "SALE",
    "name": "[API]TEST_PRODUCT",
    "subTitle": null,
    "featuredImageUrl": "",
    "imageUrls": [],
    "description": "",
    "summary": null,
    "reasonOfReject": null,
    "sku": null,
    "quantity": null,
    "combinedProducts": [],
    "optionGroups": [],
    "useCombination": true,
    "optionCombinations": [],
    "prices": [],
    "createdAt": "2023-06-19T01:55:11",
    "modifiedAt": "2023-06-19T01:55:11",
    "enabledDemo": false,
    "demoPeriod": 7,
    "demoPeriodUnit": "DAY",
    "categories": [],
    "vendorUuid": "{Vendor UUID}",
    "productOrder": 0,
    "isOnetimePurchasable": false,
    "eventBadge": [],
    "notice": null,
    "useWidget": {
      "useDemo": false,
      "useEventBadge": false,
      "useOnetimePurchasable": false,
      "useNotice": false
    },
    "groupId": null,
    "countrySetting": null
  }