V兔API开放平台

接口介绍： 此接口用于新增一个淘宝商品
商品的属性和 sku 的属性有包含的关系，商品的价格要位于 sku 的价格区间之中（例如，sku 价格有 5 元、10 元两种，那么商品的价格就需要大于等于 5 元，小于等于 10 元，否则新增商品会失败）
商品的类目和商品的价格、sku 的价格都有一定的相关性（具体的关系要通过类目属性查询接口获得）
商品的运费承担方式和邮费设置有相关性，卖家承担运费不用设置邮费，买家承担运费需要设置邮费
当关键属性值选择了"其他”的时候，需要输入 input_pids 和 input_str 商品才能添加成功。

请求方式： POST

返回格式： JSON

接口收费： 联系客服

频率限制： 10 次/秒

请求头参数

参数	类型	必选	值	示例
Authorization	string	是	授权 access_token	Bearer 1798c6aadec33d1bc2f5b707f1049aefexxxx

请使用新的生成 token 接口点击查看详情

请求参数

参数	类型	必选	描述
shop_id	Number	是	店铺 id
sku_spec_ids	String	否	此参数暂时不起作用
sku_delivery_times	String	否	此参数暂时不起作用
sku_hd_length	String	否	家装建材类目，商品 SKU 的长度，正整数，单位为 cm，部分类目必选。数据和 SKU 一一对应，用，分隔，如：20,30,30
sku_hd_height	String	否	家装建材类目，商品 SKU 的高度，单位为 cm，部分类目必选。天猫和淘宝格式不同。天猫：可选值为："0-15", "15-25", "25-50", "50-60", "60-80", "80-120", "120-160", "160-200"。数据和 SKU 一一对应，用，分隔，格式如：15-25,25-50,25-50。淘宝：正整数，单位为 cm,格式如：20,30,30
sku_hd_lamp_quantity	String	否	家装建材类目，商品 SKU 的灯头数量，正整数，大于等于 3，部分类目必选。天猫商家专用。数据和 SKU 一一对应，用，分隔，如：3,5,7
input_str	String	否	用户自行输入的子属性名和属性值，结构："父属性值;一级子属性名;一级子属性值;二级子属性名;自定义输入值，....",如："耐克;耐克系列;科比系列;科比系列;2K5,Nike 乔丹鞋;乔丹系列;乔丹鞋系列;乔丹鞋系列;json5”，多个自定义属性用","分割，input_str 需要与 input_pids 一一对应，注：通常一个类目下用户可输入的关键属性不超过 1 个。所有属性别名加起来不能超过 3999 字节。此处不可以使用"其他”、"其它”和"其她”这三个词。
input_pids	String	否	用户自行输入的类目属性 ID 串，结构："pid1,pid2,pid3"，如："20000"（表示品牌）注：通常一个类目下用户可输入的关键属性不超过 1 个。
sku_properties	String	否	更新的 sku 的属性串，调用 taobao.itemprops.get 获取。格式：pid1:vid;pid2:vid,多个 sku 属性之间用逗号分隔。该字段内的属性需要在 props 字段同时包含。如果新增商品包含了 sku，则此字段一定要传入，字段长度要控制在 512 个字节以内。
sku_quantities	String	否	Sku 的数量串，结构如：num1,num2,num3 如：2,3
sku_prices	String	否	Sku 的价格串，结构如：10.00,5.00,… 精确到 2 位小数;单位：元。如：200.07，表示：200 元 7 分
sku_outer_ids	String	否	Sku 的外部 id 串，结构如：1234,1342,… sku_properties, sku_quantities, sku_prices, sku_outer_ids 在输入数据时要一一对应，如果没有 sku_outer_ids 也要写上这个参数，入参是","(这个是两个 sku 的示列，逗号数应该是 sku 个数减 1)；该参数最大长度是 512 个字节
sku_barcode	String	否	sku 层面的条形码，多个 SKU 情况，与 SKU 价格库存格式类似，用逗号分隔
need_delivery_time	String	否	设置是否使用发货时间，商品级别，sku 级别
delivery_time_type	String	否	发货时间类型：绝对发货时间或者相对发货时间
delivery_time	String	否	商品级别设置的发货时间。设置了商品级别的发货时间，相对发货时间，则填写相对发货时间的天数（大于 3）；绝对发货时间，则填写 yyyy-mm-dd 格式，如 2013-11-11
ms_payment.reference_price	String	否	参考价。该商品订单首次支付价格为订金价格，用户可根据参考价估算全款。详见说明：http://bangpai.taobao.com/group/thread/15031186-303287205.htm
voucher_price	String	否	尾款可抵扣金额。详见说明：http://bangpai.taobao.com/group/thread/15031186-303287205.htm
price	String	是	订金。在"线上付订金线下付尾款”模式中，有订金、尾款可抵扣金额和参考价，三者需要同时填写。该商品订单首次支付价格为订金价格，用户可根据参考价估算全款。该模式有别于"一口价”付款方式，针对一个商品，只能选择两种付款方式中的一种，其适用于家装、二手车等场景。详见说明：http://bangpai.taobao.com/group/thread/15031186-303287205.htm
obs	String	否	预约门店是否支持门店自提，1:是
version	String	否	新版电子凭证字段
packageid	String	否	新版电子凭证包 id
prd_license_no	String	否	生产许可证号
design_code	String	否	产品标准号
factory	String	否	厂名
factory_site	String	否	厂址
contact	String	否	厂家联系方式
mix	String	否	配料表
plan_storage	String	否	储藏方法
period	String	否	保质期，默认有单位，传入数字
food_additive	String	否	食品添加剂
supplier	String	否	供货商
product_date_start	String	否	生产开始日期，格式必须为 yyyy-MM-dd
product_date_end	String	否	生产结束日期，格式必须为 yyyy-MM-dd
stock_date_start	String	否	进货开始日期，要在生产日期之后，格式必须为 yyyy-MM-dd
stock_date_end	String	否	进货结束日期，要在生产日期之后，格式必须为 yyyy-MM-dd
health_product_no	String	否	健字号，保健品/膳食营养补充剂这个类目下特有的信息，此类目下无需填写生产许可证编号（QS），如果填写了生产许可证编号（QS）将被忽略不保存；保存宝贝时，标题前会自动加上健字号产品名称一起作为宝贝标题；
state	String	是	所在地省份。如浙江
city	String	是	所在地城市。如杭州。
num	Number	是	商品数量。取值范围：0-900000000 的整数。且需要等于 Sku 所有数量的和。拍卖商品中增加拍只能为 1，荷兰拍要在[2,500)范围内。
price	Price	否	商品价格。取值范围：0-100000000;精确到 2 位小数;单位：元。如：200.07，表示：200 元 7 分。需要在正确的价格区间内。拍卖商品对应的起拍价。
type	String	是	发布类型。可选值：fixed(一口价),auction(拍卖)。B 商家不能发布拍卖商品，而且拍卖商品是没有 SKU 的。拍卖商品发布时需要附加拍卖商品信息：拍卖类型(paimai_info.mode，拍卖类型包括三种：增价拍[1]，荷兰拍[2]以及降价拍[3])，商品数量(num)，起拍价(price)，价格幅度(increament)，保证金(paimai_info.deposit)。另外拍卖商品支持自定义销售周期，通过 paimai_info.valid_hour 和 paimai_info.valid_minute 来指定。对于降价拍来说需要设置降价周期(paimai_info.interval)和拍卖保留价(paimai_info.reserve)。注意：通过 taobao.item.get 接口获取拍卖信息时，会返回除了 valid_hour 和 valid_minute 之外的所有拍卖信息。
stuff_status	String	是	新旧程度。可选值：new(新)，second(二手)。B 商家不能发布二手商品。如果是二手商品，特定类目下属性里面必填新旧成色属性
title	String	是	宝贝标题。不能超过 30 字符，受违禁词控制。天猫图书管控类目最大允许 120 字符；
desc	String	是	宝贝描述。字数要大于 5 个字符，小于 25000 个字符，受违禁词控制
approve_status	String	否	商品上传后的状态。可选值：onsale(出售中),instock(仓库中);默认值：onsale
cid	Number	是	叶子类目 id
props	String	否	商品属性列表。格式：pid:vid;pid:vid。属性的 pid 调用 taobao.itemprops.get 取得，属性值的 vid 用 taobao.itempropvalues.get 取得 vid。如果该类目下面没有属性，可以不用填写。如果有属性，必选属性必填，其他非必选属性可以选择不填写。属性不能超过 35 对。所有属性加起来包括分割符不能超过 549 字节，单个属性没有限制。如果有属性是可输入的话，则用字段 input_str 填入属性的值
freight_payer	String	否	运费承担方式。可选值：seller（卖家承担）,buyer(买家承担);默认值：seller。卖家承担不用设置邮费和 postage_id.买家承担的时候，必填邮费和 postage_id 如果用户设置了运费模板会优先使用运费模板，否则要同步设置邮费（post_fee,express_fee,ems_fee）
valid_thru	Number	否	有效期。可选值：7,14;单位：天;默认值：14
has_invoice	Boolean	否	是否有发票。可选值：true,false (商城卖家此字段必须为 true);默认值：false(无发票)
has_warranty	Boolean	否	是否有保修。可选值：true,false;默认值：false(不保修)
has_showcase	Boolean	否	橱窗推荐。可选值：true,false;默认值：false(不推荐)
seller_cids	String	否	商品所属的店铺类目列表。按逗号分隔。结构：",cid1,cid2,...,"，如果店铺类目存在二级类目，必须传入子类目 cids。
has_discount	Boolean	否	支持会员打折。可选值：true,false;默认值：false(不打折)
post_fee	Price	否	平邮费用。取值范围：0.01-999.00;精确到 2 位小数;单位：元。如：5.07，表示：5 元 7 分。注：post_fee,express_fee,ems_fee 需要一起填写
express_fee	Price	否	快递费用。取值范围：0.01-999.00;精确到 2 位小数;单位：元。如：15.07，表示：15 元 7 分
ems_fee	Price	否	ems 费用。取值范围：0.01-999.00;精确到 2 位小数;单位：元。如：25.07，表示：25 元 7 分
list_time	Date	否	定时上架时间。(时间格式：yyyy-MM-dd HH:mm:ss)
increment	Price	否	加价(降价)幅度。如果为 0，代表系统代理幅度。对于增价拍和荷兰拍来说是加价幅度，对于降价拍来说是降价幅度。
image	byte[]	否	商品主图片。类型：JPG,GIF;最大长度：3M。（推荐使用 pic_path 字段，先把图片上传到卖家图片空间）
postage_id	Number	否	宝贝所属的运费模板 ID。取值范围：整数且必须是该卖家的运费模板的 ID（可通过 taobao.delivery.template.get 获得当前会话用户的所有邮费模板）
auction_point	Number	否	商品的积分返点比例。如：5,表示：返点比例 0.5%. 注意：返点比例必须是 >0 的整数，而且最大是 90,即为 9%.B 商家在发布非虚拟商品时，返点必须是 5 的倍数，即 0.5% 的倍数。其它是 1 的倍数，即 0.1% 的倍数。无名良品商家发布商品时，复用该字段记录积分宝返点比例，返点必须是对应类目的返点步长的整数倍，默认是 5，即 0.5%。注意此时该字段值依旧必须是 >0 的整数，最高值不超过 500，即 50%
property_alias	String	否	属性值别名。如 pid:vid:别名;pid1:vid1:别名 1 ，其中：pid 是属性 id vid 是属性值 id。总长度不超过 800 个字符，如"123:333:你好"，引号内的是 10 个字符。
lang	String	否	商品文字的字符集。繁体传入"zh_HK"，简体传入"zh_CN"，不传默认为简体
outer_id	String	否	商品外部编码，该字段的最大长度是 64 个字节
product_id	Number	否	商品所属的产品 ID(B 商家发布商品需要用)
pic_path	String	否	（推荐）商品主图需要关联的图片空间的相对 url。这个 url 所对应的图片必须要属于当前用户。pic_path 和 image 只需要传入一个，如果两个都传，默认选择 pic_path
auto_fill	String	否	代充商品类型。在代充商品的类目下，不传表示不标记商品类型（交易搜索中就不能通过标记搜到相关的交易了）。可选类型： no_mark(不做类型标记) time_card(点卡软件代充) fee_card(话费软件代充)
is_taobao	Boolean	否	是否在淘宝上显示（如果传 FALSE，则在淘宝主站无法显示该商品）
is_ex	Boolean	否	是否在外店显示
is_3D	Boolean	否	是否是 3D
sell_promise	Boolean	否	是否承诺退换货服务！虚拟商品无须设置此项！
cod_postage_id	Number	否	此为货到付款运费模板的 ID，对应的 Java 类型是 long,如果 COD 卖家应用了货到付款运费模板，此值要进行设置。该字段已经废弃
is_lightning_consignment	Boolean	否	实物闪电发货
weight	Number	否	商品的重量(商超卖家专用字段)
is_xinpin	Boolean	否	商品是否为新品。只有在当前类目开通新品，并且当前用户拥有该类目下发布新品权限时才能设置 is_xinpin 为 true，否则设置 true 后会返回错误码：isv.invalid-permission:add-xinpin。同时只有一口价全新的宝贝才能设置为新品，否则会返回错误码：isv.invalid-parameter:xinpin。不设置该参数值或设置为 false 效果一致。
sub_stock	Number	否	商品是否支持拍下减库存：1 支持;2 取消支持(付款减库存);0(默认)不更改集市卖家默认拍下减库存;商城卖家默认付款减库存
scenic_ticket_pay_way	Number	否	景区门票类宝贝发布时候，当卖家签订了支付宝代扣协议时候，需要选择支付方式：全额支付和订金支付。当 scenic_ticket_pay_way 为 1 时表示全额支付，为 2 时表示订金支付
scenic_ticket_book_cost	String	否	景区门票在选择订金支付时候，需要交的预订费。传入的值是 1 到 20 之间的数值，小数点后最多可以保留两位（多余的部分将做四舍五入的处理）。这个数值表示的是预订费的比例，最终的预订费为 scenic_ticket_book_cost 乘一口价除以 100
item_size	String	否	表示商品的体积，如果需要使用按体积计费的运费模板，一定要设置这个值。该值的单位为立方米（m3），如果是其他单位，请转换成成立方米。该值支持两种格式的设置：格式 1：bulk:3,单位为立方米(m3),表示直接设置为商品的体积。格式 2：length:10;breadth:10;height:10，单位为米（m）。体积和长宽高都支持小数类型。在传入体积或长宽高时候，不能带单位。体积的单位默认为立方米（m3），长宽高的单位默认为米(m)该值支持两种格式的设置：格式 1：bulk:3,单位为立方米(m3),表示直接设置为商品的体积。格式 2：length:10;breadth:10;height:10，单位为米（m）
item_weight	String	否	商品的重量，用于按重量计费的运费模板。注意：单位为 kg。只能传入数值类型（包含小数），不能带单位，单位默认为 kg。
sell_point	String	否	商品卖点信息，最长 150 个字符。天猫商家和集市卖家都可用。
barcode	String	否	商品条形码
newprepay	String	否	该宝贝是否支持【7 天无理由退货】，卖家选择的值只是一个因素，最终以类目和选择的属性条件来确定是否支持 7 天。填入字符 0，表示不支持；未填写或填人字符 1，表示支持 7 天无理由退货；
qualification	String	否	商品资质信息
o2o_bind_service	Boolean	否	汽车 O2O 绑定线下服务标记，如不为空，表示关联服务，否则，不关联服务。
features	String	否	宝贝特征值，格式为：【key1:value1;key2:value2;key3:value3;】，key 和 value 用【:】分隔，key&value 之间用【;】分隔，只有在 Top 支持的特征值才能保存到宝贝上，目前支持的 Key 列表为：mysize_tp
ignorewarning	String	否	忽略警告提示。
after_sale_id	Number	否	售后说明模板 id
change_prop	String	否	基础色数据，淘宝不使用
desc_modules	String	否	已废弃
is_offline	String	否	是否是线下商品。1：线上商品（默认值）；2：线上或线下商品；3：线下商品。
wireless_desc	String	否	无线的宝贝描述
spu_confirm	Boolean	否	手机类目 spu 优化，信息确认字段
video_id	Number	否	主图视频 id
interactive_id	Number	否	主图视频互动信息 id，必须填写主图视频 id 才能有互动信息 id
lease_extends_info	String	否	租赁扩展信息
brokerage	String	否	仅淘小铺卖家需要。佣金比例(15.3 对应的佣金比例为 15.3%).只支持小数点后 1 位。多余的位数四舍五入(15.32 会保存为 15.3%
biz_code	String	否	业务身份编码。淘小铺编码为"taobao-taoxiaopu"
image_urls	String[]	否	此字段已经废弃，不再使用
choose_logis	String	否	发布电子凭证宝贝时候表示是否使用邮寄 0: 代表不使用邮寄； 1：代表使用邮寄；如果不设置这个值，代表不使用邮寄
expirydate	String	否	本地生活电子交易凭证业务，目前此字段只涉及到的信息为有效期;如果有效期为起止日期类型，此值为 2012-08-06,2012-08-16 如果有效期为【购买成功日至】类型则格式为 2012-08-16 如果有效期为天数类型则格式为 15
network_id	String	否	网点 ID
merchant	String	否	码商信息，格式为码商 id:nick
verification	String	否	核销打款 1 代表核销打款 0 代表非核销打款
refund_ratio	Number	否	退款比例，百分比 % 前的数字，1-100 的正整数值
onsale_auto_refund_ratio	Number	否	电子凭证售中自动退款比例，百分比 % 前的数字，介于 1-100 之间的整数
refundmafee	String	否	退款码费承担方。发布电子凭证宝贝的时候会增加"退款码费承担方”配置项，可选填：(1)s（卖家承担） (2)b(买家承担)
eticket	String	否	电子凭证业务属性，数据字典是： 1、is_card:1 (暂时不用) 2、consume_way:4 （1 串码，4 身份证）3、consume_midmnick ：(核销放行账号：用户 id-用户名，支持多个，用逗号分隔，例如 1234-测试账号 35,1345-测试账号 56）4、market:eticket (电子凭证商品标记) 5、has_pos:1 (1 表示商品配置线下门店，在 detail 上进行展示，没有或者其他值只不展示)格式是： k1:v2;k2:v2;........ 如：has_pos:1;market:eticket;consume_midmnick:901409638-OPPO;consume_way:4
mode	Number	否	拍卖商品选择的拍卖类型，拍卖类型包括三种：增价拍(1)，荷兰拍(2)和降价拍(3)。
deposit	Number	否	拍卖宝贝的保证金。对于增价拍和荷兰拍来说保证金有两种模式：淘宝默认模式（首次出价金额的 10%），自定义固定保证金（固定冻结金额只能输入不超过 30 万的正整数），并且保证金只冻结 1 次。对于降价拍来说保证金只有淘宝默认的（竞拍价格的 10% * 竞拍数量），并且每次出价都需要冻结保证金。对于拍卖宝贝来说，保证金是必须的，但是默认使用淘宝默认保证金模式，只有用户需要使用自定义固定保证金的时候才需要使用到这个参数，如果该参数不传或传入 0 则代表使用默认。
interval	Number	否	降价拍宝贝的降价周期(分钟)。降价拍宝贝的价格每隔 paimai_info.interval 时间会下降一次 increment。
reserve	Price	否	降价拍宝贝的保留价。对于降价拍来说，paimai_info.reserve 必须大于 0，且小于 price-increment，而且（price-paimai_info.reserve）/increment 的计算结果必须为整数
valid_hour	Number	否	自定义销售周期的小时数。拍卖宝贝可以自定义销售周期，这里指定销售周期的小时数。注意，该参数只作为输入参数，不能通过 taobao.item.get 接口获取。
valid_minute	Number	否	自定义销售周期的分钟数。拍卖宝贝可以自定义销售周期，这里是指定销售周期的分钟数。自定义销售周期的小时数。拍卖宝贝可以自定义销售周期，这里指定销售周期的小时数。注意，该参数只作为输入参数，不能通过 taobao.item.get 接口获取。
global_stock_type	String	否	全球购商品采购地（库存类型），有两种库存类型：现货和代购参数值为 1 时代表现货，值为 2 时代表代购。注意：使用时请与全球购商品采购地（地区/国家）配合使用
global_stock_country	String	否	全球购商品采购地（地区/国家）,默认值只在全球购商品采购地（库存类型选择情况生效），地区国家值请填写法定的国家名称，类如（美国，香港，日本，英国，新西兰，德国，韩国，荷兰，法国，意大利，台湾，澳门，加拿大，瑞士，西班牙，泰国，新加坡，马来西亚，菲律宾），不要使用其他
support_custom_made	Boolean	否	是否支持定制市场 true 代表支持，false 代表支持，如果为空代表与之前保持不变不会修改
custom_made_type_id	String	否	定制工具 Id 如果支持定制市场，这个值不填写，就用之前的定制工具 Id，之前的定制工具 Id 没有值就默认为-1
global_stock_delivery_place	String	否	全球购商品发货地，发货地现在有两种类型："国内”和"海外及港澳台”，参数值为 1 时代表"国内”，值为 2 时代表"海外及港澳台”，默认为国内。注意：卖家必须已经签署并启用"海外直邮”合约，才能选择发货地为"海外及港澳台”
global_stock_tax_free_promise	Boolean	否	全球购商品卖家包税承诺，当值为 true 时，代表卖家承诺包税。注意：请与"全球购商品发货地”配合使用，包税承诺必须满足：1、发货地为海外及港澳台 2、卖家已经签署并启用"包税合约”合约
input_custom_cpv	String	否	针对当前商品的自定义属性值，目前是针对销售属性值自定义的，所以调用方需要把自定义属性值对应的虚拟属性值 ID（负整数，例如例子中的 -1 和-2）像标准属性值值的 id 一样设置到 SKU 上，如果自定义属性值有属性值图片，也要设置到属性图片上
cpv_memo	String	否	针对当前商品的标准属性值的补充说明，让买家更加了解商品信息减少交易纠纷
vvtype	Number	否	2 高级版（必须填 2,不填默认是 2）

请求示例

请求代码示例

cURL请求代码示例

PHP请求代码示例

JAVA请求代码示例

响应参数

名称	类型	示例值	描述
item	Item		商品结构，仅有 numIid 和 created 返回
--iid	String	13232	商品 iid
--num_iid	Number	1489161932	商品数字 id
--created	Date	2000-01-01 00:00:00	Item 的发布时间，目前仅供 taobao.item.add 和 taobao.item.get 可用
withholding_money	Number		该接口扣费金额（点券）

返回数据

{"code": 0, "msg": "操作成功", "msec": 1469, "time": 1617270403, "data": {"item_add_response": {"item": {"iid": "13232", "num_iid": 1489161932, "created": "2000-01-01 00:00:00"}}}}

响应代码

代码	代码描述	解决方案
0	成功
100	请求参数错误	检查您的请求参数是否正确
101	请求超时，请重试	检查您的网络情况或者联系客服解决
103	旺旺账号不存在	检查您输入的旺旺号是否正确
200	系统错误，请联系客服	检查您的接口地址填写是否正确，其他问题联系客服解决
203	暂不支持当前接口
204	请求异常：无该接口权限，请前往官网开通正式接口。	前往官网开通该接口权限
204	请求异常：API 调用次数不足，请前往网站兑换次数。	前往官网充值该接口调用次数
302	未授权店铺	根据返回链接进行扫码授权

添加一个商品