Product Update API 文档

商品-更新-全量更新

接口信息

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

认证

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

Header 值
skill-access-token {your-skill-access-token} （请替换为你自己的 token）

请求参数 (Body - JSON)

顶层字段

字段 类型 必填 说明
product Object ✅ 必填 产品主体数据
productattr_info Array 选填 产品属性信息
images Array ✅ 必填 产品图片
videos Array 选填 产品视频列表
addition_group_id string/int 选填 附加分组 ID
variantremark_id string 选填 变体备注 ID
groupbuy_id string 选填 团购 ID
collection_ids Array[int] 选填 产品对应的专辑 ID 数组（多对多关系）
label_ids Array 选填 角标 ID 数组
options Array 选填 产品规格定义。单规格为空，多规格必填
variants Array ✅ 必填 产品变体（规格）。单规格产品数组只有一个子项
glasses Object 选填 眼镜类商品属性
mergeimages Array 选填 合并图片列表
tags Array 选填 商品 tag 数组
payafteruse int 选填 先用后付。1 先用后付商品，2 普通商品

product 字段详表

字段 类型 必填 说明
id int ✅ 必填（更新时） 产品 ID
spu string 选填 产品 SPU
title string ✅ 必填 产品标题
sub_title string 选填 产品副标题
body_html string ✅ 必填 产品描述（HTML）
handle string 选填 商品 URL handle。不填写则用 title 自动生成
status int 选填 产品状态。1 上架，2 下架。默认上架
type int ✅ 必填 产品规格类型。1 单规格，2 多规格
vendor string 选填 产品厂家/品牌名称
virtual_sales_count int 选填 产品虚拟销量
is_tax int 选填 是否收税。1 收税，2 不收税
variant_need_image int 选填 规格是否需要图片。1 需要，2 不需要。默认 1
variant_show_image int 选填 前台商城规格显示方式。1 显示文字，2 显示图片，3 使用插件默认配置
variant_need_note int 选填 变体是否需要备注。1 需要，2 不需要
inventory_police int 选填 是否跟踪库存。1 跟踪，2 不跟踪。默认 1
inventory_police_type int 选填 库存策略。1 库存为0允许购买，2 库存为0不允许购买，3 库存为0自动下架。默认 1
meta_is_edit int 选填 SEO 信息是否独立编辑。1 非独立编辑，2 独立编辑
meta_title string 选填 SEO 标题（meta title）
meta_keywords string 选填 SEO 关键字（meta keywords）
meta_description string 选填 SEO 描述（meta description）
feed_title string 选填 Feed 自定义 title
feed_description string/null 选填 Feed 自定义 description
translate_type int 选填 翻译类型。1 强制翻译，2 只翻译多语言为空的部分，3 不翻译
source_type int/string 选填 source 类型。1 代表 1688
template_type string 选填 模版装修的 template key
google_product_category int 选填 Google 商品分类 ID
google_product_type_id string 选填 Google 产品类型
description_json Object 选填 JSON 描述内容（模板装修数据）
description_json_status int 选填 描述是否使用 JSON 字段。1 开启，2 关闭
params_json Array 选填 参数 JSON 内容
params_json_status int 选填 参数是否使用 JSON。1 开启，2 关闭
short_description_json Array[Object] 选填 简短描述（JSON 格式数组，支持多语言）。每项含 text（默认文本）和 lang_params（多语言翻译对象）
collection_ids Array[int] 选填 产品对应的专辑 ID 数组
label_ids Array 选填 角标 ID 数组
short_description_json 结构说明

每项格式：

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

productattr_info 字段详表

字段 类型 必填 说明
attr_id int ✅ 必填 属性 ID
item_ids Array[int] ✅ 必填 属性值 ID 数组
id string 选填 记录 ID（更新时传入，新增为空字符串）

images 字段详表

字段 类型 必填 说明
src string ✅ 必填 产品图片路径
alt string 选填 图片 alt 文本
position int ✅ 必填 图片排序位置，从 1 开始依次递增。标识为 1 的将作为主图
id int 选填 图片 ID（更新已有图片时传入，新增可不传）
product_id int 选填 产品 ID
width int 选填 图片宽度（像素）
height int 选填 图片高度（像素）
ratio string 选填 宽高比
key float 选填 前端唯一标识 key

videos 字段详表

字段 类型 必填 说明
src string ✅ 必填 视频 URL 路径
alt string 选填 视频 alt 文本
position int ✅ 必填 排序位置
id int 选填 视频 ID（更新已有视频时传入，新增可不传）
product_id int 选填 产品 ID

options 字段详表

单规格产品为空，多规格产品必填。

字段 类型 必填 说明
name string ✅ 必填 规格名称（如 "Color"、"Size"）
position int ✅ 必填 规格排序，值只能为 1、2、3 中的一个，且每个 option 的 position 不可重复
items Array[string] ✅ 必填 规格子项数组（如 ["White", "Black"]）
id int 选填 Option ID（更新已有规格时传入，新增可不传）
product_id int 选填 产品 ID
shop_id int 选填 店铺 ID

variants 字段详表

单规格产品数组只有一个子项。

字段 类型 必填 说明
price float ✅ 必填 售卖价格
qty int ✅ 必填 变体库存，默认 0
weight string ✅ 必填 变体重量
weight_unit string ✅ 必填 重量单位。可选值：g（克）、kg（千克）、lb（磅）、oz（盎司）
option1 string 选填 规格值 1。其值必须存在于 options 中 position=1 所在行的 items 数组中
option2 string 选填 规格值 2。其值必须存在于 options 中 position=2 所在行的 items 数组中
option3 string 选填 规格值 3。其值必须存在于 options 中 position=3 所在行的 items 数组中
cost_price float 选填 成本价格
compare_at_price float 选填 划线价格
wholesale_price Array[Object] 选填 批发价格。每项含 qty（批发个数，int）和 price（批发价格，float）
sku string ✅/选填 产品 SKU。根据配置项决定必填唯一、选填唯一或选填非唯一
barcode string 选填 条形码
image string 选填 变体图片路径。注意：此图片必须存在于 images 数组中，否则无法保存
gram int 选填 重量（克）
note string 选填 变体备注
buy_min_count int 选填 最小起购数量
customervip Array[Object] 选填 VIP 会员价格。每项含 customervip_id（VIP等级ID，int）和 price（VIP价格，float）
id int 选填 变体 ID（更新已有变体时传入，新增可不传）
product_id int 选填 产品 ID
shop_id int 选填 店铺 ID
image_id int 选填 变体图片 ID（关联 images 表中的记录）
images Array 选填 变体图片列表

tags 字段详表

字段 类型 必填 说明
id int 选填 Tag ID（已有 tag 传入）
title string 选填 Tag 标题

glasses 字段详表

字段 类型 必填 说明
button_type int 选填 按钮类型
distance_min string 选填 最小距离
distance_max string 选填 最大距离
sex Object 选填 适用性别。含 value（默认值）和 language（多语言对象，如 {"cn": "性别"}）
lens_type Object 选填 镜片类型。含 value（默认值）和 language（多语言对象，如 {"cn": "风格"}）
material Object 选填 材质。含 value（默认值）和 language（多语言对象，如 {"cn": "材质"}）

mergeimages 字段详表

字段 类型 必填 说明
src string ✅ 必填 图片路径
position int ✅ 必填 图片位置排序
alt string 选填 图片 alt 文字
id int 选填 记录 ID（更新已有图片时传入，新增可不传）
product_id int 选填 产品 ID
width int 选填 图片宽度（像素）
height int 选填 图片高度（像素）
ratio string 选填 宽高比

请求示例

cURL

curl --location --request POST '{your-site-url}/api/skill/product/update' \
--header 'skill-access-token: {your-skill-access-token}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "product": {
        "source_type": "",
        "spu": "7218746753195",
        "title": "先用后付，测试：Morden Lighting Nordic Fabric Shade Black White Floor Lamp",
        "sub_title": "",
        "body_html": "...（HTML 模板装修内容，详见下方 body_html 字段说明）...",
        "status": 1,
        "is_tax": 1,
        "virtual_sales_count": 54,
        "type": 2,
        "vendor": "Lighting Made",
        "variant_need_note": "1",
        "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 Nordic",
        "meta_description": "Introducing the Morden Lighting Nordic Fabric Shade Black White Floor Lamp! This sleek and stylish floor lamp is perfect for any modern home. The sleek black and white design is perfect for any room in your house, and the fabric shade provides a warm and inviting glow. The height of 160cm makes it perfect for any corner in your room, and the stand width of 30cm ensures that it will fit perfectly in any space.",
        "feed_description": null,
        "feed_title": "",
        "handle": "morden-lighting-big-nordic-fabric-shade-black-or-white-floor-lamp-em7v0pso",
        "translate_type": 3,
        "google_product_category": 111,
        "google_product_type_id": "light",
        "description_json": "（Object，模板装修 JSON 数据，详见下方 description_json 字段说明）",
        "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": "北欧风格黑白布艺灯罩落地灯"
                    }
                }
            },
            {
                "text": "This sleek and stylish floor lamp is perfect for any modern home",
                "lang_params": {
                    "text": {
                        "cn": "这款时尚且造型优美的落地灯非常适合任何现代风格的家居"
                    }
                }
            }
        ],
        "label_ids": [],
        "collection_ids": [],
        "template_type": "",
        "id": 4646
    },
    "productattr_info": [
        {"id": "", "attr_id": 31, "item_ids": [63, 56]},
        {"id": "", "attr_id": 29, "item_ids": [52, 53]},
        {"id": "", "attr_id": 35, "item_ids": [60]},
        {"id": "", "attr_id": 33, "item_ids": [61]},
        {"id": "", "attr_id": 32, "item_ids": [57]},
        {"id": "", "attr_id": 28, "item_ids": [62]}
    ],
    "images": [
        {
            "id": 30335,
            "product_id": 4646,
            "position": 1,
            "src": "/product/15/image/2026/02/08/90526227fa14ac859b88ada1058092d8.jpg",
            "alt": "",
            "width": 800,
            "height": 800,
            "ratio": "1.00"
        },
        {
            "id": 30336,
            "product_id": 4646,
            "position": 2,
            "src": "/product/15/image/2026/02/08/a8a35a02b70921ca44932dac0ba334aa.jpg",
            "alt": "",
            "width": 750,
            "height": 845,
            "ratio": "0.89"
        },
        {
            "id": 30337,
            "product_id": 4646,
            "position": 3,
            "src": "/product/15/image/2026/02/08/66a079e058435607e41c97ae7fd45c40.jpg",
            "alt": "",
            "width": 750,
            "height": 453,
            "ratio": "1.66"
        },
        {
            "id": 30338,
            "product_id": 4646,
            "position": 4,
            "src": "/product/15/image/2026/02/08/ca8fd9c91436c98254e8d2525fe01ba4.jpg",
            "alt": "",
            "width": 750,
            "height": 564,
            "ratio": "1.33"
        }
    ],
    "videos": [
        {
            "id": 868,
            "product_id": 4646,
            "position": 1,
            "src": "https://cloud.video.taobao.com/play/u/2206786293671/p/1/e/6/t/1/453995116363.mp4",
            "alt": ""
        }
    ],
    "addition_group_id": 73,
    "variantremark_id": "",
    "groupbuy_id": "",
    "collection_ids": [349, 345],
    "label_ids": [],
    "options": [
        {
            "id": 5153,
            "shop_id": 15,
            "product_id": 4646,
            "name": "Color",
            "position": 1,
            "items": ["White", "Black"]
        },
        {
            "id": 5189,
            "shop_id": 15,
            "product_id": 4646,
            "name": "Size",
            "position": 2,
            "items": ["L", "M"]
        }
    ],
    "variants": [
        {
            "id": 44774,
            "shop_id": 15,
            "product_id": 4646,
            "title": "White / L",
            "price": "68.99",
            "compare_at_price": "89.99",
            "cost_price": "38.99",
            "wholesale_price": [
                {"qty": 2, "price": "58.99"},
                {"qty": 5, "price": "53.99"}
            ],
            "sku": "7218746753195-White-L-1010799",
            "gram": 0,
            "barcode": "",
            "image_id": 30335,
            "qty": 999,
            "option1": "White",
            "option2": "L",
            "option3": "",
            "weight": "2",
            "weight_unit": "kg",
            "note": "",
            "image": "/product/15/image/2026/02/08/90526227fa14ac859b88ada1058092d8.jpg",
            "customervip": [
                {"customervip_id": 11, "price": 54},
                {"customervip_id": 10, "price": 55},
                {"customervip_id": 8, "price": 56},
                {"customervip_id": 7, "price": 57}
            ],
            "images": [],
            "buy_min_count": 1
        },
        {
            "id": 44775,
            "shop_id": 15,
            "product_id": 4646,
            "title": "White / M",
            "price": "68.99",
            "compare_at_price": "89.99",
            "cost_price": "38.99",
            "wholesale_price": [
                {"qty": 2, "price": "58.99"},
                {"qty": 5, "price": "53.99"}
            ],
            "sku": "7218746753195-White-M-1010800",
            "gram": 0,
            "barcode": "",
            "image_id": 30335,
            "qty": 999,
            "option1": "White",
            "option2": "M",
            "option3": "",
            "weight": "2",
            "weight_unit": "kg",
            "note": "",
            "image": "/product/15/image/2026/02/08/90526227fa14ac859b88ada1058092d8.jpg",
            "customervip": [
                {"customervip_id": 11, "price": 54},
                {"customervip_id": 10, "price": 55},
                {"customervip_id": 8, "price": 56},
                {"customervip_id": 7, "price": 57}
            ],
            "images": [],
            "buy_min_count": 1
        },
        {
            "id": 44776,
            "shop_id": 15,
            "product_id": 4646,
            "title": "Black / L",
            "price": "68.99",
            "compare_at_price": "89.99",
            "cost_price": "38.99",
            "wholesale_price": [
                {"qty": 2, "price": "58.99"},
                {"qty": 5, "price": "53.99"}
            ],
            "sku": "7218746753195-Black-L-1010801",
            "gram": 0,
            "barcode": "",
            "image_id": 30336,
            "qty": 999,
            "option1": "Black",
            "option2": "L",
            "option3": "",
            "weight": "2",
            "weight_unit": "kg",
            "note": "",
            "image": "/product/15/image/2026/02/08/a8a35a02b70921ca44932dac0ba334aa.jpg",
            "customervip": [
                {"customervip_id": 11, "price": 54},
                {"customervip_id": 10, "price": 55},
                {"customervip_id": 8, "price": 56},
                {"customervip_id": 7, "price": 57}
            ],
            "images": [],
            "buy_min_count": 1
        },
        {
            "id": 44777,
            "shop_id": 15,
            "product_id": 4646,
            "title": "Black / M",
            "price": "68.99",
            "compare_at_price": "89.99",
            "cost_price": "38.99",
            "wholesale_price": [
                {"qty": 2, "price": "58.99"},
                {"qty": 5, "price": "53.99"}
            ],
            "sku": "7218746753195-Black-M-1010802",
            "gram": 0,
            "barcode": "",
            "image_id": 30336,
            "qty": 999,
            "option1": "Black",
            "option2": "M",
            "option3": "",
            "weight": "2",
            "weight_unit": "kg",
            "note": "",
            "image": "/product/15/image/2026/02/08/a8a35a02b70921ca44932dac0ba334aa.jpg",
            "customervip": [
                {"customervip_id": 11, "price": 54},
                {"customervip_id": 10, "price": 55},
                {"customervip_id": 8, "price": 56},
                {"customervip_id": 7, "price": 57}
            ],
            "images": [],
            "buy_min_count": 1
        }
    ],
    "glasses": {
        "button_type": 1,
        "distance_min": "1.00",
        "distance_max": "22.00",
        "sex": {
            "value": "sex",
            "language": {"cn": "性别"}
        },
        "lens_type": {
            "value": "style",
            "language": {"cn": "风格"}
        },
        "material": {
            "value": "type",
            "language": {"cn": "材质"}
        }
    },
    "mergeimages": [],
    "tags": [
        {"id": 25, "title": "white"},
        {"id": 79, "title": "black"}
    ],
    "payafteruse": 1
}'

返回结果

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

成功响应

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

返回字段说明

字段 类型 说明
code Number 状态码，200 表示成功
message String 执行结果的文字描述
data.product_id int 更新后的产品 ID

错误响应

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

错误码说明

错误码 说明
100701003 商品id为空
100701001 商品保存报错
其他错误码 商品保存报错
  1. product.id 在更新时必须传入，否则可能被当作新增处理
  2. 变体的 image 字段必须已存在于 images 数组中，否则无法保存
  3. images[].position 必须从 1 开始连续递增，position=1 的图片为主图
  4. options[].position 只能为 1、2、3，且每个 option 的 position 不可重复
  5. variants 中的 option1/2/3 值必须与对应 position 的 options[].items 中的值匹配
  6. wholesale_price 为变体的批发价格数组，每个元素包含 qty（起批数量）和 price（批发单价）
  7. weight_unit 支持 g、kg、lb、oz 四种单位
  8. 更新已有数据时传入 id（图片 ID、变体 ID、Option ID 等），新增数据时不传 id
  9. description_json 为模板装修数据（Object），非数组；description_json_status 为 1 时才生效
  10. short_description_json 每项包含 text（默认文本）和 lang_params.text.{语言}（多语言翻译）
Copyright © fecify.com 2025 all right reserved，powered by Gitbook该文件修订时间： 2026-05-07 18:35:30

results matching ""

    No results matching ""