简体中文

English

简体中文

English

显示模式

管理产品 ​

产品是店铺中销售的基本单位，包含名称、描述、价格、库存状态等基础信息。通过创建产品管理类应用，商家可以高效管理产品目录、实时更新详情，并确保多渠道展示数据的一致性。

本节向您展示如何使用 RESTful 接口来管理产品，包括创建、编辑、删除产品，以及如何进行身份验证与错误处理。

产品对象关系 ​

在开始具体的 API 操作（如查询、创建、编辑和删除产品）之前，了解系统中产品对象之间的关系至关重要。下文展示了产品、变体、系列和类别之间的关联，帮助您在进行产品操作时能够正确地传递和使用各类数据。

API 对象描述
产品售卖产品，包含基本信息（SPU：标题、描述、产品状态、产品类型等）。
变体即产品 SKU，包含商品信息，例如价格、库存、说明和图片。
可将其视为您可能希望客户看到的产品信息。产品与其关联的产品变体具有 1:N 的关系。
系列代表的是一组特定的产品池，是由用户根据某些规则或主题圈定的产品集合。
这个集合可以是基于不同的条件（如折扣、品牌、活动、季节等）来组织一批产品。产品与系列之间具有 M:N 的关系
类别产品类目，产品进行分类的方式或标准，用于将相似或相关的产品归为同一类别，便于产品管理、筛选、推荐等方面进行操作。 产品与类别之间具有 N:1 的关系

API 总览 ​

API Endpoint功能描述
/api/202412/category/search查询产品类目数据
/api/202412/collections查询产品系列数据
/api/202412/products创建新产品
/api/202412/products/{productId}获取、编辑或删除指定产品（根据 HTTP 方法区分）

业务场景 - 创建产品 ​

业务场景说明：在创建产品前，开发者需先查询已有的产品类目和系列数据，并在产品创建时将对应的类别和系列信息传入，确保产品归类正确。

步骤 1：查询类别信息 ​

说明：调用 产品类目 接口查询产品类目数据，从而获得需要在产品创建时使用的类别 ID。

请求：

GET /api/202412/category/search

请求示例：

bash
curl -X GET \ 
"https://{shop}.genmystore.com/api/202412/category/search?categoryName=pet" \ 
-H "X-Genstore-Access-Token: {access_token}" \

返回结果：

bash
HTTP/1.1 200 OK
{
  "productCategories": [
    {
      "parentCategoryId": "209148956144",
      "categoryName": "pet",
      "categoryId": "209148956145"
    }
  ]
}

步骤 2：查询系列信息 ​

说明：调用 系列 接口用于查询产品系列数据，从而获得创建产品时所需的系列 ID。

请求：

GET /api/202412/collections

请求示例：

bash
curl -X GET \ 
"https://{shop}.genmystore.com/api/202412/collections?title=CollectionTest&collectionType=1" \ 
-H "X-Genstore-Access-Token: {access_token}" \

返回结果：

bash
HTTP/1.1 200 OK
{
  "collections": [
    {
      "collectionType": "1",
      "image": {
        "src": "https://cdn.shopify.com/s/files/1/0600/8317/5513/files/wax-special_150x.png?v=1716260624"
      },
      "bodyHtml": "<p>Test Description</p>",
      "published": "true",
      "title": "CollectionTest",
      "collectionId": "102984300756584",
      "collects": "[102744899756584,102744899756583]",
      "countGoodsNum": "3"
    }
  ]
}

步骤 3：创建产品 ​

说明：在查询到产品类目和系列数据后，调用 产品 接口创建产品，并将查询结果中的 categoryId 和 collections（系列 ID）作为产品属性传入。

请求：

POST /api/202412/products

请求示例：

bash
curl -X POST \ 
"https://{shop}.genmystore.com/api/202412/products" \ 
-H "X-Genstore-Access-Token: {access_token}" \ 
-H "Content-Type: application/json" \ 
-d '{
	"product":{
		"isMultiVariant":"false",
		"images":[
			{
				"src":"https://blaze.com/s/files/[email protected]?v=1716260620",
				"position":"1"
			}
		],
		"variants":[
			{
				"inventoryManagement":"true",
				"price":"10",
				"costPrice":"3",
				"options":[
					{
						"name":"size",
						"position":"1",
						"value":{
							"name":"L",
							"position":"1"
						}
					}
				],
				"weight":"1",
				"isDisabled":"false",
				"sku":"P001",
				"compareOfPrice":"22",
				"barcode":"AXOYX49XOPEX6",
				"inventoryQuantities":[
					{
						"locationId":"50002",
						"available":"666"
					}
				],
				"weightUnit":"kg"
			}
		],
		"marketAssigns":[
			{
				"isAssigned":"true",
				"marketId":"6016662702584"
			}
		],
		"categoryId": "209148956145",
		"title":"shirt",
		"subTitle":"wool shirt",
		"collections":"[102984300756584]",
		"vendor":"nike",
		"options":[
			{
				"name":"size",
				"position":"1",
				"value":[
					{
						"name":"L",
						"position":"1"
					}
				]
			}
		],
		"bodyHtml":"<p>wool shirt</p>",
		"productType":"normal",
		"status":"active"
	}
}'

返回结果：

bash
HTTP/1.1 200 OK
{
  "product": {
    "isMultiVariant": "false",
    "images": [
      {
        "productId": "102745140756584",
        "src": "https://blaze.com/s/files/[email protected]?v=1716260620",
        "position": "1"
      }
    ],
    "productId": "102745140756584",
    "variants": [
      {
        "inventoryManagement": "true",
        "productId": "102744460756584",
        "costPrice": "3",
        "weight": "1",
        "compareOfPrice": "22",
        "inventoryQuantities": [
          {
            "locationId": "50002",
            "available": "666"
          }
        ],
        "price": "10",
        "options": [
          {
            "name": "size",
            "id": "10034623756584",
            "position": "1",
            "value": {
              "name": "L",
              "id": "10167791756584",
              "position": "1"
            }
          }
        ],
        "variantId": "107362030756584",
        "isDisabled": "false",
        "sku": "P001",
        "barcode": "AXOYX49XOPEX6",
        "weightUnit": "kg"
      }
    ],
    "marketAssigns": [
      {
        "isAssigned": "true",
        "marketId": "6016662702584"
      }
    ],
    "categoryId": "209148956145",
    "title": "shirt",
    "subTitle": "wool shirt",
    "collections": "[102984300756584]",
    "vendor": "nike",
    "options": [
      {
        "name": "size",
        "id": "10034623756584",
        "position": "1",
        "value": [
          {
            "name": "L",
            "id": "10167791756584",
            "position": "1"
          }
        ]
      }
    ],
    "bodyHtml": "<p>wool shirt</p>",
    "productType": "normal",
    "status": "active"
  }
}

业务场景 - 编辑产品 ​

业务场景说明：在产品创建后，开发者可以通过编辑接口获取现有产品信息并进行修改操作，以保持产品数据的最新状态。

步骤 1：获取产品信息 ​

说明：调用 产品 接口获取指定产品的详细信息，为编辑产品做准备。

GET /api/202412/products/{productId}

请求示例：

bash
curl -X GET \ 
"https://{shop}.genmystore.com/api/202412/products/{productId}" \ 
-H "X-Genstore-Access-Token: {access_token}" \

返回结果：

bash
HTTP/1.1 200 OK
{
  "product": {
    "isMultiVariant": "false",
    "salesChannels": [
      {
        "salesChannelCode": "onlineStore"
      }
    ],
    "images": [
      {
        "productId": "102745140756584",
        "src": "https://blaze.com/s/files/[email protected]?v=1716260620",
        "position": "1"
      }
    ],
    "productId": "102745140756584",
    "variants": [
      {
        "inventoryManagement": "true",
        "productId": "102744460756584",
        "costPrice": "3",
        "weight": "1",
        "compareOfPrice": "22",
        "inventoryQuantities": [
          {
            "locationId": "50002",
            "available": "666"
          }
        ],
        "price": "10",
        "options": [
          {
            "name": "size",
            "id": "10034623756584",
            "position": "1",
            "value": {
              "name": "L",
              "id": "10167791756584",
              "position": "1"
            }
          }
        ],
        "variantId": "107362030756584",
        "isDisabled": "false",
        "sku": "P001",
        "barcode": "AXOYX49XOPEX6",
        "weightUnit": "kg"
      }
    ],
    "marketAssigns": [
      {
        "isAssigned": "true",
        "marketId": "6016662702584"
      }
    ],
    "title": "shirt",
    "productCategory": {
      "categoryName": "pet",
      "categoryId": "209148956145"
    },
    "subTitle": "wool shirt",
    "collections": "[102984300756584]",
    "vendor": "nike",
    "options": [
      {
        "name": "size",
        "id": "10034623756584",
        "position": "1",
        "value": [
          {
            "name": "L",
            "id": "10167791756584",
            "position": "1"
          }
        ]
      }
    ],
    "bodyHtml": "<p>wool shirt</p>",
    "productType": "normal",
    "status": "active"
  }
}

步骤 2：编辑产品 ​

说明：调用 产品 接口更新指定产品的信息，修改后可使产品数据保持最新状态。

请求：

PUT /api/202412/products/{productId}

请求示例：

bash
curl -X PUT \ 
"https://{shop}.genmystore.com/api/202412/products/{productId}" \ 
-H "X-Genstore-Access-Token: {access_token}" \ 
-H "Content-Type: application/json" \ 
-d '{
	"product":{
		"isMultiVariant":"false",
		
		"images":[
			{
				"productId":"102745140756584",
				"src":"https://blaze.com/s/files/[email protected]?v=1716260620",
				"position":"1"
			}
		],
		"productId":"102745140756584",
		"variants":[
			{
				"inventoryManagement":"true",
				"productId":"102744460756584",
				"costPrice":"3",
				"weight":"1",
				"compareOfPrice":"22",
				"inventoryQuantities":[
					{
						"locationId":"50002",
						"available":"666"
					}
				],
				"price":"10",
				"options":[
					{
						"name":"size",
						"id":"10034623756584",
						"position":"1",
						"value":{
							"name":"L",
							"id":"10167791756584",
							"position":"1"
						}
					}
				],
				"variantId":"107362030756584",
				"isDisabled":"false",
				"sku":"P001",
				"barcode":"AXOYX49XOPEX6",
				"weightUnit":"kg"
			}
		],
		"marketAssigns":[
			{
				"isAssigned":"true",
				"marketId":"6016662702584"
			}
		],
		"categoryId": "209148956145",
		"title":"shirt",
		"subTitle":"wool shirt",
		"collections":"[107363170756584]",
		"vendor":"nike",
		"options":[
			{
				"name":"size",
				"id":"10034623756584",
				"position":"1",
				"value":[
					{
						"name":"L",
						"id":"10167791756584",
						"position":"1"
					}
				]
			}
		],
		"bodyHtml":"<p>wool shirt</p>",
		"productType":"normal",
		"status":"active"
	}
}'

返回结果：

bash
HTTP/1.1 200 OK
{
  "product": {
    "isMultiVariant": "false",
    "images": [
      {
        "productId": "102745140756584",
        "src": "https://blaze.com/s/files/[email protected]?v=1716260620",
        "position": "1"
      }
    ],
    "productId": "102745140756584",
    "variants": [
      {
        "inventoryManagement": "true",
        "productId": "102744460756584",
        "costPrice": "3",
        "weight": "1",
        "compareOfPrice": "22",
        "inventoryQuantities": [
          {
            "locationId": "50002",
            "available": "666"
          }
        ],
        "price": "10",
        "options": [
          {
            "name": "size",
            "id": "10034623756584",
            "position": "1",
            "value": {
              "name": "L",
              "id": "10167791756584",
              "position": "1"
            }
          }
        ],
        "variantId": "107362030756584",
        "isDisabled": "false",
        "sku": "P001",
        "barcode": "AXOYX49XOPEX6",
        "weightUnit": "kg"
      }
    ],
    "marketAssigns": [
      {
        "isAssigned": "true",
        "marketId": "6016662702584"
      }
    ],
    "categoryId": "209148956145",
    "title": "shirt",
    "subTitle": "wool shirt",
    "collections": "[102984300756584]",
    "vendor": "nike",
    "options": [
      {
        "name": "size",
        "id": "10034623756584",
        "position": "1",
        "value": [
          {
            "name": "L",
            "id": "10167791756584",
            "position": "1"
          }
        ]
      }
    ],
    "bodyHtml": "<p>wool shirt</p>",
    "productType": "normal",
    "status": "active"
  }
}

业务场景 - 删除产品 ​

业务场景说明：调用 产品 接口可删除指定产品信息，通常在产品下架或不再销售时使用。

请求：

DELETE /api/202412/products/{productId}

请求示例：

bash
curl -X DELETE \ 
"https://{shop}.genmystore.com/api/202412/products/{productId}" \ 
-H "X-Genstore-Access-Token: {access_token}" \

返回结果：

bash
HTTP/1.1 200 OK
{}

Webhook ​

业务场景说明：您的应用可以订阅以下 Webhook 以实时获取产品数据的创建、更新和删除事件。

Webhook 主题描述
products/create产品创建
products/update产品更新
products/delete产品删除