--- title: "商品创建" description: "当商品被创建时触发。" doc_type: openapi doc_category: openapi doc_version: v20270301 source_url: html: 'https://developer.shopline.com/zh-hans-cn/docs/webhook/product/product-created' md: 'https://developer.shopline.com/zh-hans-cn/docs/webhook/product/product-created.md' --- # 商品创建 当商品被创建时触发。 - **API Version:** v20270301 - **API Type:** Webhook - **API Protocol:** RESTful ## Request ### Request Headers * `Content-Type` string (required) 字段值固定为 `application/json; charset=utf-8`。 * `X-Shopline-Topic` string (required) 事件的唯一标识。 * `X-Shopline-Hmac-Sha256` string (required) 该请求的签名。收到请求后，你需要对该签名进行 [验签](https://developer.shopline.com/zh-hans-cn/docs/apps/api-instructions-for-use/generate-and-verify-signatures.md#post-请求操作步骤) 以验证数据的真实性和完整性。 * `X-Shopline-Shop-Domain` string (required) 店铺的域名。 * `X-Shopline-Shop-Id` string (required) 店铺 ID。 * `X-Shopline-Merchant-Id` string (required) 商家 ID。 * `X-Shopline-API-Version` string (required) API 版本号。 * `X-Shopline-Webhook-Id` string (required) 该 Webhook 事件的 ID。 ### Request Body * `body_html` string 商品的描述。 * `created_at` string 商品的创建时间。格式：[ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html)。 * `handle` string 商品的语义化的唯一标识，默认基于 `title` 生成。 * `id` string 商品的唯一标识 ID。 * `image` object 商品的封面图。 * `alt` string 图片的替代文本描述，通常是具有图片特征或内容的单词或短语。 * `src` string 图片的链接，以 URL 形式展示。 * `images` array 商品图片列表。 * `alt` string 商品图的替代文本描述，通常是具有图片特征或内容的单词或短语。 * `src` string 商品图的链接，以 URL 形式展示。 * `options` array 商品规格列表。 * `id` string 规格的唯一标识 ID。 * `name` string 规格的名称。 * `option_values` array 商品规格值列表。 * `id` string 规格值的唯一标识 ID。 * `value` string 规格值。 * `product_id` string 规格对应商品的唯一标识 ID。 * `values` array 规格值列表。 * `values_images` map 规格值与对应图片 URL 的映射关系。 * `path` string 商品的相对路径。 * `product_behavior` string 用于标识商品的特殊行为，只在特定情况下有值返回。例如，当商品有潜在风险时，返回一个值。 * `product_category` string 商家自定义的商品类型。 * `product_type` string 商品的来源。有效枚举值包含： - `NORMAL` : SHOPLINE 商家后台维护的商品 - `POD_TEMPORARY` : POD 应用的临时商品 - `TEMPORARY` : 其他临时商品 * `published_at` string 商品发布的时间。格式：[ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html)。 * `published_scope` string 商品的销售渠道发布范围。有效值固定为`web`，代表在线商店。 * `spu` string 商家为商品自定义的标识。 * `status` string 商品的状态。有效枚举值包含： - `active`: 上架 - `draft`: 下架 - `archived`: 归档 * `subtitle` string 商品的摘要。 * `tags` string 商品的标签。 * `template_path` string 商品的主题模板。 * `title` string 商品的标题。 * `updated_at` string 商品最近一次更新的时间。格式：[ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html)。 * `variants` array 商品款式列表。 * `barcode` string 款式的条形码。 * `compare_at_price` string 款式的原价，数值保留到小数点后两位。 * `id` string 款式的唯一标识 ID。 * `image` object 款式的图片。 * `alt` string 款式图的替代文本描述，通常是具有图片特征或内容的单词或短语。 * `src` string 款式图的链接，以 URL 形式展示。 * `inventory_item_id` string 库存单位的唯一标识 ID。 * `inventory_policy` string 表明款式是否允许超卖。 - `deny`：不允许超卖。 - `continue`：允许超卖。 * `inventory_quantity` integer 各存放地点的库存数量总和。 * `inventory_tracker` boolean 表明是否开启库存追踪。 - `true`：开启库存追踪。 - `false`：不开启库存追踪。 * `option1` string 款式第一个规格的信息。 * `option2` string 款式第二个规格的信息。 * `option3` string 款式第三个规格的信息。 * `option4` string 款式第四个规格的信息。 * `option5` string 款式第五个规格的信息。 * `price` string 款式的售价，数值保留到小数点后两位。 * `product_id` string 款式对应商品的唯一标识 ID。 * `required_shipping` boolean 表明款式是否需要运输。 - `true`：需要运输。 - `false`：不需要运输。 * `sku` string 商家为款式自定义的标识。 * `taxable` boolean 表明款式是否需要收税。 - `true`：需要收税。 - `false`：不需要收税。 * `title` string 款式的标题，由款式的规格值拼装而成。 * `weight` string 款式的重量，超过两位小数向上取整。 * `weight_unit` string 款式的重量单位。有效枚举值包含： - `g`：克 - `kg`：千克 - `lb`：磅 - `oz`：盎司 - `zh_kg`：公斤 * `vendor` string 商品的品牌或厂商。 ## Response ### Status Codes * `200` 收到 SHOPLINE 发送的 Webhook 通知后，你需要按照如下 SHOPLINE 要求的格式进行响应。 ``` HTTP/1.1 200 OK ``` 关于如何订阅 Webhooks 及更多 Webhook 响应规则说明，请参考 [Webhook 概述](https://developer.shopline.com/zh-hans-cn/docs/apps/api-instructions-for-use/webhooks/overview.md)。 ### Response Body #### 200 _No response body_ ## OpenAPI Definition ```json { "tags": [ "商品创建" ], "description": "当商品被创建时触发。", "externalDocs": { "description": "| 事件分组 | 事件标识 |\n| :------: | :------: |\n|products |products/create |\n", "url": "", "errorTableDescription": "" }, "operationId": "D996ADYa", "parameters": [ { "name": "Content-Type", "in": "header", "description": "字段值固定为 `application/json; charset=utf-8`。", "required": true, "schema": { "name": "Content-Type", "type": "string", "example": "application/json; charset=utf-8" } }, { "name": "X-Shopline-Topic", "in": "header", "description": "事件的唯一标识。", "required": true, "style": "string", "schema": { "name": "X-Shopline-Topic", "description": "事件的唯一标识。", "type": "string", "example": "orders/edited" }, "example": "orders/edited" }, { "name": "X-Shopline-Hmac-Sha256", "in": "header", "description": "该请求的签名。收到请求后，你需要对该签名进行 [验签](https://developer.shopline.com/zh-hans-cn/docs/apps/api-instructions-for-use/generate-and-verify-signatures.md#post-请求操作步骤) 以验证数据的真实性和完整性。", "required": true, "style": "string", "schema": { "name": "X-Shopline-Hmac-Sha256", "description": "该请求的签名。收到请求后，你需要对该签名进行 [验签](https://developer.shopline.com/zh-hans-cn/docs/apps/api-instructions-for-use/generate-and-verify-signatures.md#post-请求操作步骤) 以验证数据的真实性和完整性。", "type": "string", "example": "XWmrwMey6OsLMeiZKwP4FppHH3cmAiiJJAweH5Jo4bM=" }, "example": "XWmrwMey6OsLMeiZKwP4FppHH3cmAiiJJAweH5Jo4bM=" }, { "name": "X-Shopline-Shop-Domain", "in": "header", "description": "店铺的域名。", "required": true, "style": "string", "schema": { "name": "X-Shopline-Shop-Domain", "description": "店铺的域名。", "type": "string", "example": "example.myshopline.com" }, "example": "example.myshopline.com" }, { "name": "X-Shopline-Shop-Id", "in": "header", "description": "店铺 ID。", "required": true, "style": "string", "schema": { "name": "X-Shopline-Shop-Id", "description": "店铺 ID。", "type": "string", "example": "1610418123456" }, "example": "1610418123456" }, { "name": "X-Shopline-Merchant-Id", "in": "header", "description": "商家 ID。", "required": true, "style": "string", "schema": { "name": "X-Shopline-Merchant-Id", "description": "商家 ID。", "type": "string", "example": "2000001234" }, "example": "2000001234" }, { "name": "X-Shopline-API-Version", "in": "header", "description": "API 版本号。", "required": true, "style": "string", "schema": { "name": "X-Shopline-API-Version", "description": "API 版本号。", "type": "string", "example": "v20250601" }, "example": "v20250601" }, { "name": "X-Shopline-Webhook-Id", "in": "header", "description": "该 Webhook 事件的 ID。", "required": true, "style": "string", "schema": { "name": "X-Shopline-Webhook-Id", "description": "该 Webhook 事件的 ID。", "type": "string", "example": "b54557e48a5fbf7d70bcd043" }, "example": "b54557e48a5fbf7d70bcd043" } ], "requestBody": { "content": { "application/json": { "schema": { "name": "body", "type": "object", "properties": { "body_html": { "name": "body_html", "description": "商品的描述。", "type": "string" }, "created_at": { "name": "created_at", "description": "商品的创建时间。格式：[ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html)。", "type": "string", "example": "2025-03-06T02:20:26+08:00" }, "handle": { "name": "handle", "description": "商品的语义化的唯一标识，默认基于 `title` 生成。", "type": "string", "example": "product-handle" }, "id": { "name": "id", "description": "商品的唯一标识 ID。", "type": "string", "example": "16057850264845250791280282" }, "image": { "name": "image", "description": "商品的封面图。", "type": "object", "properties": { "alt": { "name": "alt", "description": "图片的替代文本描述，通常是具有图片特征或内容的单词或短语。", "type": "string", "example": "This is an image alt." }, "src": { "name": "src", "description": "图片的链接，以 URL 形式展示。", "type": "string", "example": "https://img.myshopline.com/image/official/e46e6189dd5641a3b179444cacdcdd2a.png" } }, "example": { "alt": "This is an image alt.", "src": "https://img.myshopline.com/image/official/e46e6189dd5641a3b179444cacdcdd2a.png" } }, "images": { "name": "images", "description": "商品图片列表。", "type": "array", "items": { "type": "object", "properties": { "alt": { "name": "alt", "description": "商品图的替代文本描述，通常是具有图片特征或内容的单词或短语。", "type": "string", "example": "This is an image alt." }, "src": { "name": "src", "description": "商品图的链接，以 URL 形式展示。", "type": "string", "example": "https://img.myshopline.com/image/official/e46e6189dd5641a3b179444cacdcdd2a.png" } }, "example": { "alt": "This is an image alt.", "src": "https://img.myshopline.com/image/official/e46e6189dd5641a3b179444cacdcdd2a.png" } }, "example": [ { "alt": "This is an image alt.", "src": "https://img.myshopline.com/image/official/e46e6189dd5641a3b179444cacdcdd2a.png" } ] }, "options": { "name": "options", "description": "商品规格列表。", "type": "array", "items": { "type": "object", "properties": { "id": { "name": "id", "description": "规格的唯一标识 ID。", "type": "string", "example": "16158068291703878544960282" }, "name": { "name": "name", "description": "规格的名称。", "type": "string", "example": "Color" }, "option_values": { "name": "option_values", "description": "商品规格值列表。", "type": "array", "items": { "type": "object", "properties": { "id": { "name": "id", "description": "规格值的唯一标识 ID。", "type": "string", "example": "16050375155238626683133099" }, "value": { "name": "value", "description": "规格值。", "type": "string", "example": "Red" } }, "example": { "id": "16050375155238626683133099", "value": "Red" } }, "example": [ { "id": "16050375155238626683133099", "value": "Red" } ] }, "product_id": { "name": "product_id", "description": "规格对应商品的唯一标识 ID。", "type": "string", "example": "16057850264845250791280282" }, "values": { "name": "values", "description": "规格值列表。", "type": "array", "items": { "type": "string", "example": "[\"Red\", \"Green\", \"White\"]" }, "example": [ "[\"Red\", \"Green\", \"White\"]" ] }, "values_images": { "name": "values_images", "description": "规格值与对应图片 URL 的映射关系。", "type": "map", "example": { "Red": "https://img.myshopline.com/image/official/e46e6189dd5641a3b179444cacdcdd2a.png" } } }, "example": { "id": "16158068291703878544960282", "name": "Color", "option_values": [ { "id": "16050375155238626683133099", "value": "Red" } ], "product_id": "16057850264845250791280282", "values": [ "[\"Red\", \"Green\", \"White\"]" ], "values_images": { "Red": "https://img.myshopline.com/image/official/e46e6189dd5641a3b179444cacdcdd2a.png" } } }, "example": [ { "id": "16158068291703878544960282", "name": "Color", "option_values": [ { "id": "16050375155238626683133099", "value": "Red" } ], "product_id": "16057850264845250791280282", "values": [ "[\"Red\", \"Green\", \"White\"]" ], "values_images": { "Red": "https://img.myshopline.com/image/official/e46e6189dd5641a3b179444cacdcdd2a.png" } } ] }, "path": { "name": "path", "description": "商品的相对路径。", "type": "string", "example": "/products/clothes" }, "product_behavior": { "name": "product_behavior", "description": "用于标识商品的特殊行为，只在特定情况下有值返回。例如，当商品有潜在风险时，返回一个值。", "type": "string", "example": "RISK,HIDDEN" }, "product_category": { "name": "product_category", "description": "商家自定义的商品类型。", "type": "string", "example": "Electronic" }, "product_type": { "name": "product_type", "description": "商品的来源。有效枚举值包含：\n- `NORMAL` : SHOPLINE 商家后台维护的商品\n- `POD_TEMPORARY` : POD 应用的临时商品\n- `TEMPORARY` : 其他临时商品", "type": "string" }, "published_at": { "name": "published_at", "description": "商品发布的时间。格式：[ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html)。", "type": "string", "example": "2025-03-06T02:20:26+08:00" }, "published_scope": { "name": "published_scope", "description": "商品的销售渠道发布范围。有效值固定为`web`，代表在线商店。", "type": "string" }, "spu": { "name": "spu", "description": "商家为商品自定义的标识。", "type": "string", "example": "S00000001" }, "status": { "name": "status", "description": "商品的状态。有效枚举值包含：\n- `active`: 上架\n- `draft`: 下架\n- `archived`: 归档", "type": "string" }, "subtitle": { "name": "subtitle", "description": "商品的摘要。", "type": "string", "example": "This is a subtitle" }, "tags": { "name": "tags", "description": "商品的标签。", "type": "string", "example": "tag1,tag2" }, "template_path": { "name": "template_path", "description": "商品的主题模板。", "type": "string", "example": "templates/product.product_template_name.json" }, "title": { "name": "title", "description": "商品的标题。", "type": "string", "example": "This is a product title" }, "updated_at": { "name": "updated_at", "description": "商品最近一次更新的时间。格式：[ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html)。", "type": "string", "example": "2025-03-06T02:20:26+08:00" }, "variants": { "name": "variants", "description": "商品款式列表。", "type": "array", "items": { "type": "object", "properties": { "barcode": { "name": "barcode", "description": "款式的条形码。", "type": "string", "example": "T00000001" }, "compare_at_price": { "name": "compare_at_price", "description": "款式的原价，数值保留到小数点后两位。", "type": "string", "example": "129.99" }, "id": { "name": "id", "description": "款式的唯一标识 ID。", "type": "string", "example": "18057039439794751459380282" }, "image": { "name": "image", "description": "款式的图片。", "type": "object", "properties": { "alt": { "name": "alt", "description": "款式图的替代文本描述，通常是具有图片特征或内容的单词或短语。", "type": "string", "example": "This is an image alt." }, "src": { "name": "src", "description": "款式图的链接，以 URL 形式展示。", "type": "string", "example": "https://img.myshopline.com/image/official/e46e6189dd5641a3b179444cacdcdd2a.png" } }, "example": { "alt": "This is an image alt.", "src": "https://img.myshopline.com/image/official/e46e6189dd5641a3b179444cacdcdd2a.png" } }, "inventory_item_id": { "name": "inventory_item_id", "description": "库存单位的唯一标识 ID。", "type": "string", "example": "59854602422372317075" }, "inventory_policy": { "name": "inventory_policy", "description": "表明款式是否允许超卖。\n- `deny`：不允许超卖。\n- `continue`：允许超卖。", "type": "string" }, "inventory_quantity": { "name": "inventory_quantity", "description": "各存放地点的库存数量总和。", "type": "integer", "example": 99 }, "inventory_tracker": { "name": "inventory_tracker", "description": "表明是否开启库存追踪。\n- `true`：开启库存追踪。\n- `false`：不开启库存追踪。", "type": "boolean" }, "option1": { "name": "option1", "description": "款式第一个规格的信息。", "type": "string", "example": "red" }, "option2": { "name": "option2", "description": "款式第二个规格的信息。", "type": "string", "example": "xl" }, "option3": { "name": "option3", "description": "款式第三个规格的信息。", "type": "string", "example": "cotton" }, "option4": { "name": "option4", "description": "款式第四个规格的信息。", "type": "string", "example": "short" }, "option5": { "name": "option5", "description": "款式第五个规格的信息。", "type": "string", "example": "casual" }, "price": { "name": "price", "description": "款式的售价，数值保留到小数点后两位。", "type": "string", "example": "90.22" }, "product_id": { "name": "product_id", "description": "款式对应商品的唯一标识 ID。", "type": "string", "example": "16057039432335097907370282" }, "required_shipping": { "name": "required_shipping", "description": "表明款式是否需要运输。\n- `true`：需要运输。\n- `false`：不需要运输。", "type": "boolean" }, "sku": { "name": "sku", "description": "商家为款式自定义的标识。", "type": "string", "example": "S00000001" }, "taxable": { "name": "taxable", "description": "表明款式是否需要收税。\n- `true`：需要收税。\n- `false`：不需要收税。", "type": "boolean" }, "title": { "name": "title", "description": "款式的标题，由款式的规格值拼装而成。", "type": "string", "example": "red · xl" }, "weight": { "name": "weight", "description": "款式的重量，超过两位小数向上取整。", "type": "string", "example": "0.23" }, "weight_unit": { "name": "weight_unit", "description": "款式的重量单位。有效枚举值包含：\n- `g`：克\n- `kg`：千克\n- `lb`：磅\n- `oz`：盎司\n- `zh_kg`：公斤", "type": "string" } }, "example": { "barcode": "T00000001", "compare_at_price": "129.99", "id": "18057039439794751459380282", "image": { "alt": "This is an image alt.", "src": "https://img.myshopline.com/image/official/e46e6189dd5641a3b179444cacdcdd2a.png" }, "inventory_item_id": "59854602422372317075", "inventory_policy": null, "inventory_quantity": 99, "inventory_tracker": null, "option1": "red", "option2": "xl", "option3": "cotton", "option4": "short", "option5": "casual", "price": "90.22", "product_id": "16057039432335097907370282", "required_shipping": null, "sku": "S00000001", "taxable": null, "title": "red · xl", "weight": "0.23", "weight_unit": null } }, "example": [ { "barcode": "T00000001", "compare_at_price": "129.99", "id": "18057039439794751459380282", "image": { "alt": "This is an image alt.", "src": "https://img.myshopline.com/image/official/e46e6189dd5641a3b179444cacdcdd2a.png" }, "inventory_item_id": "59854602422372317075", "inventory_policy": null, "inventory_quantity": 99, "inventory_tracker": null, "option1": "red", "option2": "xl", "option3": "cotton", "option4": "short", "option5": "casual", "price": "90.22", "product_id": "16057039432335097907370282", "required_shipping": null, "sku": "S00000001", "taxable": null, "title": "red · xl", "weight": "0.23", "weight_unit": null } ] }, "vendor": { "name": "vendor", "description": "商品的品牌或厂商。", "type": "string", "example": "SHOPLINE" } }, "example": { "body_html": null, "created_at": "2025-03-06T02:20:26+08:00", "handle": "product-handle", "id": "16057850264845250791280282", "image": { "alt": "This is an image alt.", "src": "https://img.myshopline.com/image/official/e46e6189dd5641a3b179444cacdcdd2a.png" }, "images": [ { "alt": "This is an image alt.", "src": "https://img.myshopline.com/image/official/e46e6189dd5641a3b179444cacdcdd2a.png" } ], "options": [ { "id": "16158068291703878544960282", "name": "Color", "option_values": [ { "id": "16050375155238626683133099", "value": "Red" } ], "product_id": "16057850264845250791280282", "values": [ "[\"Red\", \"Green\", \"White\"]" ], "values_images": { "Red": "https://img.myshopline.com/image/official/e46e6189dd5641a3b179444cacdcdd2a.png" } } ], "path": "/products/clothes", "product_behavior": "RISK,HIDDEN", "product_category": "Electronic", "product_type": null, "published_at": "2025-03-06T02:20:26+08:00", "published_scope": null, "spu": "S00000001", "status": null, "subtitle": "This is a subtitle", "tags": "tag1,tag2", "template_path": "templates/product.product_template_name.json", "title": "This is a product title", "updated_at": "2025-03-06T02:20:26+08:00", "variants": [ { "barcode": "T00000001", "compare_at_price": "129.99", "id": "18057039439794751459380282", "image": { "alt": "This is an image alt.", "src": "https://img.myshopline.com/image/official/e46e6189dd5641a3b179444cacdcdd2a.png" }, "inventory_item_id": "59854602422372317075", "inventory_policy": null, "inventory_quantity": 99, "inventory_tracker": null, "option1": "red", "option2": "xl", "option3": "cotton", "option4": "short", "option5": "casual", "price": "90.22", "product_id": "16057039432335097907370282", "required_shipping": null, "sku": "S00000001", "taxable": null, "title": "red · xl", "weight": "0.23", "weight_unit": null } ], "vendor": "SHOPLINE" } } } }, "required": true }, "responses": { "200": { "description": "收到 SHOPLINE 发送的 Webhook 通知后，你需要按照如下 SHOPLINE 要求的格式进行响应。\n\n``` HTTP/1.1 200 OK ``` \n\n关于如何订阅 Webhooks 及更多 Webhook 响应规则说明，请参考 [Webhook 概述](https://developer.shopline.com/zh-hans-cn/docs/apps/api-instructions-for-use/webhooks/overview.md)。" } }, "method": "post", "info": { "title": "商品创建", "version": "v20270301" } } ```