商品-创建

接口信息

• 接口地址: {your-site-url}/api/skill/product/create
• 基础 URL: {your-site-url} 需替换为你自己的独立站 URL 地址，如 https://your-domain.com/apimanager666
• 请求方式: POST
• Content-Type: application/json
• 说明: 此接口用于新增商品。

认证

请求头中需要携带 skill-access-token：

请求参数 (Body - JSON)

顶层字段

groupbuy_id 说明

groupbuy_id 是商品搭配组合购买（插件 prodattr）提供的数据。使用前需要：

1. 通过 商品组合购买-下拉条列表 获取下拉条列表
2. 在该 API 返回的参数 groups 中，选择一个子项的 id，作为 groupbuy_id 的值
3. 商品搭配组合购买是插件功能，使用前需要先判断插件是否存在：通过 获取店铺基本信息 返回的字段 addons，查看 prodattr 是否在 addons 数组中存在，如果存在则说明店铺存在插件：商品搭配组合购买

productattr_info 说明

productattr_info 是商品附加属性（插件 prodattr）提供的数据。使用前需要：

1. 通过 获取店铺基本信息 获取 addons 字段，检查 prodattr 是否在 addons 数组中存在
2. 如果存在，则通过 商品附加属性-所有属性以及子项列表 获取所有属性及其子项
3. 根据业务需要勾选属性和子项，构建 productattr_info 数组

示例格式：

[
    {"attr_id": 29, "item_ids": [52]},
    {"attr_id": 30, "item_ids": [55]},
    {"attr_id": 31, "item_ids": [56, 63]},
    {"attr_id": 32, "item_ids": [57]},
    {"attr_id": 33, "item_ids": [58, 61]}
]

addition_group_id 说明

addition_group_id 是自定义属性 ID，对应自定义属性插件。该字段是商品自定义属性 id 字段，需要先查看插件：商品自定义属性，店铺是否存在这个插件，并且，插件状态是否为开启。

该字段赋值条件：

1. 店铺存在插件：商品自定义属性

2. 店铺是否存在插件：商品自定义属性，是插件功能，因此，使用前需要先判断商品自定义属性插件：additionattr，是否存在插件：additionattr，可以通过 api：获取店铺基本信息 返回的字段：addons，查看：additionattr 是否在 addons 数组中存在，如果存在则说明店铺存在插件：商品自定义属性

3. 通过 api：商品自定义属性-下拉条列表，得到商品自定义属性下拉条列表，进行选择。因此，下拉条内容不为空，则可以选择商品自定义属性 id 的值，作为商品创建 api：addition_group_id 的值

collection_ids 说明

collection_ids 是商品专辑 ID 数组，可通过 商品专辑-列表 获取商品专辑 ID。

google_product_category 说明

google_product_category 是商品对应在 google category 的 ID，通过 商品-google categorys 获取数据。

product 字段详表

variant_show_image 说明

variant_show_image 该字段对应的是插件：商品规格图片，本来该字段是通过：商品规格图片-保存配置 的字段：default_show 进行，如果某个商品，不想通过统一配置，想要单独配置，那么就可以设置这个字段。

| variant_show_image | int | 选填 | 前台商城规格显示方式。1 显示文字，2 显示图片，3 使用插件默认配置 |

默认的值为：3，一般都是使用 3，也就是，使用插件默认配置，该值代表的意思是，以 api：商品规格图片-保存配置 的字段：default_show，这个字段为准。

对于值 1 和 2，代表自定义值，譬如某个商品的规格全部使用文字，那么就可以在这里自定义某个商品的规格的显示方式。

short_description_json 结构说明

每项格式：

{
    "text": "默认文本",
    "lang_params": {
        "text": {
            "cn": "中文翻译"
        }
    }
}

short_description_json 插件判断说明

short_description_json（商品列表描述）是插件：商品列表描述对应的字段。该字段进行编辑后，通过 api：商品列表描述-获取配置，来查看 status 是否开启，如果开启，则前台商城，商品详情页，将会显示商品的列表属性。

商品列表属性，是为了将商品的简要描述，在商品详情页更好地展示。简单来说，商品列表属性就是在前台商城的商品详情页，展示的一列商品属性文字——一行一段文字，多行显示。

使用前需要同时满足以下 2 个条件：

1. 店铺存在插件：商品列表描述。这是插件功能，使用前需要先判断商品列表描述插件：prodlistattr 是否存在。可以通过 api：获取店铺基本信息 返回的字段：addons，查看：prodlistattr 是否在 addons 数组中存在，如果存在则说明店铺存在插件：商品列表描述
2. 插件状态开启。通过 api：商品列表描述-获取配置 获取状态值 status 为 1 开启，则代表插件状态开启

template_type 说明

template_type 是模版装修的 template key。取值方式：

1. 通过 得到模版layout布局列表，传递 get 参数 page_type=product，即可获得 Template Types 列表
2. 从返回数据中的 template_types 中选择一个值，作为 template_type 的值
3. 一般来说，该值留空即可，除非用户进行指定
4. 如果用户提交了值，那么该值必须在该 API 返回的数据 template_types 中存在；如果不存在，则留空即可

images 字段详表

新增时不需要传 id，系统会自动生成。

videos 字段详表

新增时不需要传 id。

videos 插件判断说明

videos 是商品视频字段，需要先查看插件：商品视频，店铺是否存在这个插件，并且，插件状态是否为开启。

该字段赋值条件：这 2 个条件必须同时成立

1. 店铺存在插件：商品视频

2. 插件状态开启

3. 店铺是否存在插件：商品视频，是插件功能，因此，使用前需要先判断商品视频插件：prodvideo，是否存在插件：prodvideo。可以通过 api：获取店铺基本信息 返回的字段：addons，查看：prodvideo 是否在 addons 数组中存在，如果存在则说明店铺存在插件：商品视频

4. 通过 api：商品视频-获取配置，得到状态 status 为 1 开启，则代表插件状态开启

options 字段详表

单规格产品为空，多规格产品必填。新增时不需要传 id。

variants 字段详表

单规格产品数组只有一个子项。新增时不需要传 id。

variants 子项 image（变体图片）必填说明

variants 子项的 image 字段（变体图片路径）是否必填，由 product 的 variant_need_image 字段决定：

1. 当 product.variant_need_image 值为 1，则 variants 子项的字段：image（变体图片路径），必填，而且：注意：此图片必须存在于 images 数组中，否则无法保存
2. 当 product.variant_need_image 值不为 1，则 variants 子项的字段：image，不需要填写

variants 子项 images（商品规格多图）说明

商品规格多图，对应的是 variants 的子项的 images 字段。variants 字段是商品的规格字段，它的子项的 images 字段，保存的就是规格多图。

这个字段是商品规格多图，需要先判断插件：商品规格多图，店铺是否存在这个插件，并且，插件状态是否为开启。

该字段赋值条件：这 2 个条件必须同时成立

1. 店铺存在插件：商品规格多图

2. 插件状态开启

3. 店铺是否存在插件：商品规格多图，是插件功能，因此，使用前需要先判断商品规格多图插件：variantmutilimage，是否存在插件：variantmutilimage。可以通过 api：获取店铺基本信息 返回的字段：addons，查看：variantmutilimage 是否在 addons 数组中存在，如果存在则说明店铺存在插件：商品规格多图

4. 通过 api：商品规格多图-获取配置，得到状态 status 为 1 开启，则代表插件状态开启

variants 子项 images 示例（即规格多图）：

"images": [
    {
        "id": "",
        "product_id": 7143,
        "variant_id": 50400,
        "position": 1,
        "src": "https://sc04.alicdn.com/kf/Hd4e2987843a8423ebe6dfced71a6128df.jpg",
        "width": "",
        "height": "",
        "ratio": "0.00"
    },
    {
        "id": "",
        "product_id": 7143,
        "variant_id": 50400,
        "position": 2,
        "src": "https://sc04.alicdn.com/kf/H8e2257c0fcf34dec8240ba8e647e710bP.jpg",
        "width": "",
        "height": "",
        "ratio": "0.00"
    }
]

images 说明：

• images 的子项的 src 字段，是图片的路径，对于值，可以是 http 开头的完整 url，也可以是只有 path 的图片路径（通过图片基础 url 拼接得到完整图片 url）
• images 的子项的 src 字段，是图片的路径，必须在 post 的参数：images 中存在，post 参数 images 指的是最外层的商品所有图片的字段 images

images 子项说明：

wholesale_price 插件判断说明

wholesale_price（商品批发价格）是商品批发价格插件提供的数据。注意：商品设置了批发价格数据后，店铺必须存在插件：商品批发价格，并且插件状态已开启，前台商品详情页才会显示商品的批发价格，顾客购买多个才会享受批发价格。

使用前需要同时满足以下 2 个条件：

1. 店铺存在插件：商品批发价格。这是插件功能，使用前需要先判断商品批发价格插件：wholesale_price 是否存在。可以通过 api：获取店铺基本信息 返回的字段：addons，查看：wholesale_price 是否在 addons 数组中存在，如果存在则说明店铺存在插件：商品批发价格
2. 插件状态开启。通过 api：商品批发价格-获取配置 获取状态值，判断插件是否开启

buy_min_count 插件判断说明

variants 子项的 buy_min_count（最小起购数量），是商品最低购买的个数。需要插件：cartlimit（商品加购限制）存在，并且插件状态为开启状态，前台商城，商品购买个数限制才会生效。

使用前需要同时满足以下 2 个条件：

1. 店铺存在插件：商品加购限制。这是插件功能，使用前需要先判断商品加购限制插件：cartlimit 是否存在。可以通过 api：获取店铺基本信息 返回的字段：addons，查看：cartlimit 是否在 addons 数组中存在，如果存在则说明店铺存在插件：商品加购限制
2. 插件状态开启。通过 api：商品加购限制-获取配置 返回的 status，状态为开启状态，前台商城，商品购买个数限制才会生效

如果店铺不存在插件：cartlimit，或者状态不开启，则前台商城，商品购买个数限制不会生效。

tags 字段详表

新增时传 id: ""（空字符串）。

值格式为：

[
    {
        "title": "beginner",
        "id": 199
    },
    {
        "title": "baby closthes",
        "id": 53
    },
    {
        "title": "4343",
        "id": ""
    }
]

对于 tags 的值：

• 可以从 tag 列表中进行选择：商品Tag-列表，这种方式可以填写 id 和 title
• 也可以直接填写 tags 的值，只填写 title，id 为空。保存商品的时候，会通过 tag title 去查询 tag：如果找到则直接返回 tag id，找不到则会创建 tag，然后返回 tag id

glasses 字段详表

mergeimages 字段详表

请求示例

cURL

curl --location --request POST '{your-site-url}/api/skill/product/create' \
--header 'skill-access-token: {your-skill-access-token}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "product": {
        "spu": "3232323",
        "title": "Morden Lighting Nordic Fabric Shade Black White Floor Lamp",
        "sub_title": "Morden Lighting Nordic Fabric Shade Black White Floor Lamp subtitle",
        "body_html": "...（HTML 模板装修内容，详见下方 body_html 说明）...",
        "status": 1,
        "is_tax": 1,
        "payafteruse": 1,
        "virtual_sales_count": "33",
        "type": 2,
        "vendor": "Lighting Made",
        "variant_need_image": "1",
        "variant_show_image": 3,
        "inventory_police": "1",
        "inventory_police_type": 1,
        "meta_is_edit": "2",
        "meta_title": "Morden Lighting Nordic Fabric Shade Black White Floor Lamp",
        "meta_keywords": "Morden Lighting",
        "meta_description": "Morden Lighting Nordic Fabric Shade Black White Floor Lamp, ...",
        "feed_description": "google feed description",
        "feed_title": "google feed title",
        "handle": "morden-lighting-nordic-fabric-shade-black-white-floor-lamp",
        "translate_type": 3,
        "google_product_category": 111,
        "google_product_type_id": "light",
        "description_json": "（Object，模板装修 JSON 数据，包含 collage-tabs 和 brand-list 两个 section）",
        "description_json_status": 1,
        "params_json": [],
        "params_json_status": 2,
        "short_description_json": [
            {
                "text": "Morden Lighting Nordic Fabric Shade Black White Floor Lamp",
                "lang_params": {
                    "text": {
                        "cn": "摩登照明北欧布艺灯罩黑白落地灯"
                    }
                }
            },
            {
                "text": "Nordic Fabric Shade Black White Floor Lamp",
                "lang_params": {
                    "text": {
                        "cn": "北欧风格黑白布艺灯罩落地灯"
                    }
                }
            }
        ],
        "template_type": "product",
        "variant_need_note": "1"
    },
    "productattr_info": [
      {
        "attr_id": 33,
        "item_ids": [
          61
        ]
      },
      {
        "attr_id": 31,
        "item_ids": [
          56,
          63
        ]
      }
    ],
    "images": [
        {
            "src": "/product/15/image/2026/04/28/3fb5620f4acf97bdf9d056a6220b87e0.jpg",
            "position": 1,
            "alt": "",
            "width": 600,
            "height": 600,
            "ratio": "1.00"
        },
        {
            "src": "/product/15/image/2026/04/28/f6d04b41c743455948ed5dfea357a53e.jpg",
            "position": 2,
            "alt": "",
            "width": 600,
            "height": 600,
            "ratio": "1.00"
        },
        {
            "src": "/product/15/image/2026/04/28/858278fe4f6d493ece46810169a4df21.jpg",
            "position": 3,
            "alt": "",
            "width": 600,
            "height": 600,
            "ratio": "1.00"
        }
    ],
    "videos": [
        {
            "src": "https://cloud.video.taobao.com/play/u/2206786293671/p/1/e/6/t/1/453995116363.mp4",
            "position": 1,
            "alt": ""
        }
    ],
    "addition_group_id": 73,
    "variantremark_id": 9,
    "groupbuy_id": 12,
    "collection_ids": [342, 343],
    "label_ids": [],
    "options": [
        {
            "name": "Color",
            "position": 1,
            "items": ["grey", "white"]
        },
        {
            "name": "Size",
            "position": 2,
            "items": ["L", "M"]
        }
    ],
    "variants": [
        {
            "price": "59.99",
            "compare_at_price": "69.99",
            "cost_price": "29.99",
            "sku": "3232323-grey-L-1010805",
            "barcode": "1111",
            "image": "/product/15/image/2026/04/28/3fb5620f4acf97bdf9d056a6220b87e0.jpg",
            "qty": 8999,
            "option1": "grey",
            "option2": "L",
            "option3": "",
            "weight": "11",
            "weight_unit": "kg",
            "note": "grey l",
            "buy_min_count": 1,
            "wholesale_price": [
                {"qty": 2, "price": "45.88"},
                {"qty": 5, "price": "41.88"}
            ],
            "customervip": [
                {"customervip_id": 11, "price": 44},
                {"customervip_id": 10, "price": 45},
                {"customervip_id": 8, "price": 46},
                {"customervip_id": 7, "price": 47}
            ],
            "images": [
                {
                    "src": "/product/15/image/2026/04/28/3fb5620f4acf97bdf9d056a6220b87e0.jpg",
                    "position": 1
                },
                {
                    "src": "/product/15/image/2026/04/28/f6d04b41c743455948ed5dfea357a53e.jpg",
                    "position": 2
                }
            ]
        },
        {
            "price": "59.99",
            "compare_at_price": "69.99",
            "cost_price": "29.99",
            "sku": "3232323-grey-M-1010806",
            "barcode": "2222",
            "image": "/product/15/image/2026/04/28/3fb5620f4acf97bdf9d056a6220b87e0.jpg",
            "qty": 8999,
            "option1": "grey",
            "option2": "M",
            "option3": "",
            "weight": "11",
            "weight_unit": "kg",
            "note": "grey m",
            "buy_min_count": 1,
            "wholesale_price": [
                {"qty": 2, "price": "45.88"},
                {"qty": 5, "price": "41.88"}
            ],
            "customervip": [
                {"customervip_id": 11, "price": 44},
                {"customervip_id": 10, "price": 45},
                {"customervip_id": 8, "price": 46},
                {"customervip_id": 7, "price": 47}
            ],
            "images": [
                {
                    "src": "/product/15/image/2026/04/28/3fb5620f4acf97bdf9d056a6220b87e0.jpg",
                    "position": 1
                },
                {
                    "src": "/product/15/image/2026/04/28/f6d04b41c743455948ed5dfea357a53e.jpg",
                    "position": 2
                }
            ]
        },
        {
            "price": "59.99",
            "compare_at_price": "69.99",
            "cost_price": "29.99",
            "sku": "3232323-white-L-1010807",
            "barcode": "3333",
            "image": "/product/15/image/2026/04/28/858278fe4f6d493ece46810169a4df21.jpg",
            "qty": 8999,
            "option1": "white",
            "option2": "L",
            "option3": "",
            "weight": "11",
            "weight_unit": "kg",
            "note": "white l",
            "buy_min_count": 1,
            "wholesale_price": [
                {"qty": 2, "price": "45.88"},
                {"qty": 5, "price": "41.88"}
            ],
            "customervip": [
                {"customervip_id": 11, "price": 44},
                {"customervip_id": 10, "price": 45},
                {"customervip_id": 8, "price": 46},
                {"customervip_id": 7, "price": 47}
            ],
            "images": [
                {
                    "src": "/product/15/image/2026/04/28/858278fe4f6d493ece46810169a4df21.jpg",
                    "position": 1
                },
                {
                    "src": "/product/15/image/2026/04/28/f6d04b41c743455948ed5dfea357a53e.jpg",
                    "position": 2
                }
            ]
        },
        {
            "price": "59.99",
            "compare_at_price": "69.99",
            "cost_price": "29.99",
            "sku": "3232323-white-M-1010808",
            "barcode": "4444",
            "image": "/product/15/image/2026/04/28/858278fe4f6d493ece46810169a4df21.jpg",
            "qty": 8999,
            "option1": "white",
            "option2": "M",
            "option3": "",
            "weight": "11",
            "weight_unit": "kg",
            "note": "white m",
            "buy_min_count": 1,
            "wholesale_price": [
                {"qty": 2, "price": "45.88"},
                {"qty": 5, "price": "41.88"}
            ],
            "customervip": [
                {"customervip_id": 11, "price": 44},
                {"customervip_id": 10, "price": 45},
                {"customervip_id": 8, "price": 46},
                {"customervip_id": 7, "price": 47}
            ],
            "images": [
                {
                    "src": "/product/15/image/2026/04/28/858278fe4f6d493ece46810169a4df21.jpg",
                    "position": 1
                },
                {
                    "src": "/product/15/image/2026/04/28/f6d04b41c743455948ed5dfea357a53e.jpg",
                    "position": 2
                }
            ]
        }
    ],
    "glasses": {
        "button_type": 1,
        "distance_min": "11",
        "distance_max": "99",
        "sex": {
            "value": "sex",
            "language": {"cn": "性别"}
        },
        "lens_type": {
            "value": "style",
            "language": {"cn": "类型"}
        },
        "material": {
            "value": "type",
            "language": {"cn": "材料"}
        }
    },
    "mergeimages": [],
    "tags": [
        {"title": "white", "id": ""},
        {"title": "black", "id": ""}
    ]
}'

返回结果

code 为 200 表示调用成功；code 不为 200 表示调用失败。

成功响应

{
    "code": 200,
    "data": {
        "product_id": 4693
    },
    "message": "success"
}

返回字段说明

错误响应

{
    "code": 100701001,
    "message": "error message"
}

错误码说明

Create vs Update 区别

/api/skill/product/update 和 /api/skill/product/create 参数结构几乎一致，主要区别：

注意事项

1. productattr_info 插件判断：使用前先通过 获取店铺基本信息 检查 addons 中是否包含 prodattr。如果存在，则通过 商品附加属性-所有属性以及子项列表 获取所有属性及其子项后构建此字段。
2. body_html 为商品详情页的 HTML 模板装修内容，与 description_json 对应。
3. 变体的 image 字段必须已存在于 images 数组中，否则无法保存。
4. images[].position 必须从 1 开始连续递增，position=1 的图片为主图。
5. options[].position 只能为 1、2、3，且每个 option 的 position 不可重复。
6. variants 中的 option1/2/3 值必须与对应 position 的 options[].items 中的值匹配。
7. wholesale_price 为变体的批发价格数组，每个元素包含 qty（起批数量）和 price（批发单价）。
8. weight_unit 支持 g、kg、lb、oz 四种单位。
9. description_json 为模板装修数据（Object），非数组；description_json_status 为 1 时才生效。
10. short_description_json 每项包含 text（默认文本）和 lang_params.text.{语言}（多语言翻译）。
11. 新增时所有实体的 id 字段均不需要传（或传空），系统会自动生成。
12. videos 插件判断：videos 是商品视频字段，赋值条件：① 通过 获取店铺基本信息 检查 addons 中是否包含 prodvideo（店铺存在插件：商品视频）；② 通过 商品视频-获取配置 得到状态 status 为 1 开启（插件状态开启）。2 个条件必须同时成立。
13. variants 子项 images 插件判断：variants 子项的 images 字段（商品规格多图），赋值条件：① 通过 获取店铺基本信息 检查 addons 中是否包含 variantmutilimage（店铺存在插件：商品规格多图）；② 通过 商品规格多图-获取配置 得到状态 status 为 1 开启（插件状态开启）。2 个条件必须同时成立。
14. variants 子项 images 中的 src 必须是 http 开头的完整 url，或者只有 path 的图片路径（通过图片基础 url 拼接得到完整图片 url），且该 src 必须存在于最外层的 post 参数 images 中。
15. wholesale_price 插件判断：wholesale_price（商品批发价格）是插件功能，赋值条件：① 通过 获取店铺基本信息 检查 addons 中是否包含 wholesale_price（店铺存在插件：商品批发价格）；② 通过 商品批发价格-获取配置 获取状态值（插件状态开启）。2 个条件必须同时成立，前台商品详情页才会显示批发价格，购买多个才会享受批发价格。
16. short_description_json 插件判断：short_description_json（商品列表描述）是插件功能，赋值条件：① 通过 获取店铺基本信息 检查 addons 中是否包含 prodlistattr（店铺存在插件：商品列表描述）；② 通过 商品列表描述-获取配置 得到状态 status 为 1 开启（插件状态开启）。2 个条件必须同时成立，前台商品详情页才会显示商品的列表属性。
17. buy_min_count 插件判断：variants 子项的 buy_min_count（最小起购数量）是商品最低购买的个数，赋值条件：① 通过 获取店铺基本信息 检查 addons 中是否包含 cartlimit（店铺存在插件：商品加购限制）；② 通过 商品加购限制-获取配置 返回的 status 为开启状态（插件状态开启）。2 个条件必须同时成立，前台商城商品购买个数限制才会生效；如果店铺不存在插件：cartlimit，或者状态不开启，则前台商城商品购买个数限制不会生效。