淘宝开放平台

登录
文档中心 > API类目 > 本地生活API

本地生活API

alibaba.alsc.koubei.item.create (本地生活团购商品创建接口)

本地生活团购商品创建接口

公共参数

请求参数

名称 类型 是否必须 示例值 更多限制 描述
top_item_create_request TopItemCreateRequest 可选 商品创建请求
  • └ request_id
  • String
  • 必须
  • e76487891803ff6122a1804048ff6d1048
  • 业务请求id，每次请求都要变换请求id
  • item_form
  • ItemFormDTO
  • 必须
  • 商品发布表单
  • └ item_type
  • String
  • 必须
  • COMBO
  • 商品类型，套餐（COMBO），次卡（TIMES_CARD），代金券（VOUCHER）等，目前只支持套餐和代金券类型
  • └ original_price
  • String
  • 必须
  • 48.48
  • 商品原价，字符串类型，单位元，保留2位小数。代金券商品表示券面值。
  • └ subject
  • String
  • 可选
  • 鱼香肉丝杨梅汁套餐
  • 商品名称，最多不超过60个字符，255个字节，内容需要在gbk编码范围内，并且不包含非法字符："？","?","_","——","=","@","~","～","{","}","《","》","。","￥","◆","★","?","※"，套餐商品必填，代金券商品无需设置
  • └ ticket_display_mode
  • String
  • 必须
  • EXTERNAL_TICKET_CODE
  • 商品购买凭证核销方式。枚举值为：USER_PAY_CODE代表付款码核销方式，如果选择付款码核销，则sku_id必填。TICKET_CODE代表券码核销方式，如果选择券码核销，则sku_id必须为空。EXTERNAL_TICKET_CODE表示 外部券码核销方式。
  • └ memo
  • String
  • 可选
  • 肯德基（蚂蚁金服店）首推新品
  • 商品备注信息。用于商户内部管理，用户页面不露出。
  • └ inventory
  • Number
  • 必须
  • 20
  • 商品售卖总量，最大99999999
  • └ store_ids
  • String []
  • 必须
  • ["218679282","218682242"]
  • 商品需要关联的本地侧门店id列表，即传入一个或多个store_id。
  • └ cover
  • String
  • 必须
  • /i1/2200781230155/O1CN01cJAWH61D11w1tkWTP_!!2200781230155-0-koubei.jpg
  • 商品首图，需要传通过素材接口上传后返回的素材短链，不支持外部图片链接直接上传。
  • └ forbid_reverse
  • Boolean
  • 可选
  • false
  • 是否禁止反圈，true为禁止反圈，false为不禁止反圈，不填默认false。设置禁止反圈后商品即不会在本地平台反圈活动中被圈选。
  • └ gmt_end
  • Date
  • 必须
  • 2021-03-31 23:59:59
  • 商品售卖结束时间，当到达该时间时，商品暂停售卖，将不在客户端中继续展示，用户无法继续购买。 注意：该时间不能晚于核销绝对有效期的结束时间。
  • └ price
  • String
  • 必须
  • 28.12
  • 商品售价，字符串类型，单位元，保留2位小数。售价不能大于原价。
  • available_periods
  • AvailablePeriodInfoDTO []
  • 可选
  • 商品可用时段列表。最多添加三条规则。该内容仅用于展示，不影响实际核销。如：周一、周二 10:00至22:00
  • └ time_end
  • String
  • 可选
  • 21:32
  • 可用时段结束时间点，开始时间点不能晚于结束时间点
  • └ time_start
  • String
  • 可选
  • 17:35
  • 可用时段开始时间点，开始时间点不能晚于结束时间点
  • └ available_week_days
  • String []
  • 可选
  • 可用天列表，以星期周期的形式展示，周一到周日分别用1到7表示
  • └ verify_frequency
  • String
  • 可选
  • single
  • 核销类型。single：单次核销商品(普通商品，包括套餐、代金券)；multi:多次核销商品(次卡)
  • └ external_item_id
  • String
  • 可选
  • 1234114
  • 外部商品id，核销方式为外部券码核销时，外部券商品必填
  • item_combo_package
  • ItemComboPackageDTO
  • 可选
  • 套餐详情包信息，只有套餐商品需要设置
  • └ package_notes
  • String []
  • 可选
  • 补充说明
  • package_content_list
  • PackageContentDTO []
  • 可选
  • 套餐详情内容
  • content_unit_list
  • ContentUnitDTO []
  • 可选
  • 套餐组内容
  • └ unit
  • String
  • 可选
  • 份
  • 单位，不能包含数字
  • └ price
  • String
  • 可选
  • 12.12
  • 价格
  • └ num
  • Number
  • 可选
  • 4
  • 数量
  • └ title
  • String
  • 可选
  • 宫保鸡丁
  • 名称
  • └ content
  • String
  • 可选
  • 大份
  • 内容(菜品为规格)
  • └ title
  • String
  • 可选
  • 宫保鸡丁套餐
  • 内容标题，套餐标题。最多不超过15个汉字，30个字符
  • graphic_text_list
  • GraphicTextDTO []
  • 可选
  • 套餐图文详情
  • └ image_urls
  • String []
  • 可选
  • 图片列表，需要传通过素材接口上传后返回的素材短链，不支持外部图片链接直接上传。
  • └ title
  • String
  • 可选
  • 宫保鸡丁
  • 名称
  • └ desc
  • String
  • 可选
  • 图片描述
  • 图片描述
  • └ type
  • String
  • 可选
  • SINGLE
  • 图片类型，SINGLE：单品，PACKAGE：套餐
  • service_flow_list
  • ServiceFlowDTO []
  • 可选
  • 服务流程
  • └ unit
  • String
  • 可选
  • 份
  • 单位
  • └ service_content
  • String
  • 可选
  • 服务内容描述
  • 服务内容描述
  • └ num
  • Number
  • 可选
  • 1
  • 数量
  • └ explanation
  • String
  • 可选
  • 补充说明
  • 补充说明
  • buyer_notes
  • BuyerNotesInfoDTO []
  • 可选
  • 自定义购买须知
  • └ details
  • String []
  • 可选
  • 标题下的描述
  • └ title
  • String
  • 可选
  • 须知标题1
  • 标题
  • └ test_item
  • Boolean
  • 可选
  • true
  • 是否是测试商品，true为测试商品，false为非测试商品，默认为false，测试商品需要将display_channel设置为ORIENTATION(定向投放)
  • └ picture_details
  • String []
  • 可选
  • 商品轮播图片,跟在首图后面。尺寸大小与商品首图一致，最多5张。C端上展现时，自己会做性能优化(等比缩放，以图片中心为基准裁剪)；代金券商品不支持设置。
  • buyer_tips_template
  • BuyerTipsTemplateDTO
  • 可选
  • 购买须知模板信息
  • └ free_wifi
  • Boolean
  • 可选
  • true
  • 是否免费wifi
  • └ limit_user_num
  • Boolean
  • 可选
  • true
  • 是否限制用户数
  • └ reserve_note
  • String
  • 可选
  • 预约说明信息
  • 预约说明
  • └ invoice_types
  • String []
  • 可选
  • 发票类型，电子发票：ELECTRONIC_INVOICE，纸质发票：PAPER_INVOICE
  • └ park_fee_per_hour
  • String
  • 可选
  • 3
  • 每小时停车费,单位元,只支持整数
  • └ need_reserve
  • Boolean
  • 可选
  • true
  • 是否需要预约
  • └ supply_invoice
  • Boolean
  • 可选
  • true
  • 是否提供发票
  • └ free_park_hours
  • Number
  • 可选
  • 2
  • 免费停车小时数
  • └ user_num_limited
  • Number
  • 可选
  • 4
  • 限制多少人使用
  • └ free_park
  • Boolean
  • 可选
  • true
  • 是否免费停车
  • └ park_fee_upper_bound_per_day
  • String
  • 可选
  • 20
  • 每24小时封顶金额,单位元,只支持整数
  • unavailable_periods
  • UnavailablePeriodInfoDTO []
  • 可选
  • 商品不可用日期区间
  • └ start_day
  • String
  • 可选
  • 2018-06-30
  • 不可用时段开始日期，开始日期不能晚于结束日期
  • └ end_day
  • String
  • 可选
  • 2018-09-30
  • 不可用时段结束日期，开始日期不能晚于结束日期
  • └ gmt_start
  • Date
  • 可选
  • 2021-03-01 23:59:59
  • 商品售卖开始时间，商品状态有效并且到达生效时间后才可在客户端（消费者端）展示出来，如果商品生效时间小于当前时间，则立即生效。 说明：商品售卖开始时间不能早于创建当天的0点。商品售卖时间开始后，则不允许修改商品售卖开始时间
  • └ verify_times
  • Number
  • 可选
  • 3
  • 购买后可核销次数，默认为1
  • └ display_channel
  • String
  • 可选
  • ORIENTATION
  • 商品展示渠道，ALL表示正常投放，允许在口碑门店详情页、搜索结果、活动页、频道页中展示。ORIENTATION表示定向投放，仅限在活动页面投放或扫码购买，且定向投放的商品不会在高德侧展示。不填默认为ALL。
  • buy_limit_list
  • BuyerLimitInfoDTO []
  • 可选
  • 限购规则
  • └ limit_num
  • Number
  • 可选
  • 2
  • 限购数量
  • └ limit_type
  • String
  • 可选
  • LIMIT_USER_PER_DAY
  • 限购类型，单用户整个售卖周期限制：LIMIT_USER_FOREVER，用户每天数量限制：LIMIT_USER_PER_DAY。注意：每单限购规则由本地平台统一管控，如果有定制需要找接入产品提需求定制。
  • validity_info
  • ValidityInfoDTO
  • 必须
  • 核销有效期信息
  • └ validity_period
  • Number
  • 可选
  • 90
  • 核销相对有效天数，单位天，有效期为RELATIVE时必填
  • └ validity_type
  • String
  • 必须
  • RELATIVE
  • 核销有效期类型，绝对有效期：FIXED，相对有效期：RELATIVE
  • └ range_to
  • Date
  • 可选
  • 2022-04-17 00:00:00
  • 核销结束时间，有效期为FIXED时必填
  • └ range_from
  • Date
  • 可选
  • 2022-07-17 00:00:00
  • 核销开始时间，有效期为FIXED时必填
  • └ category_id
  • String
  • 可选
  • 2020062900464093
  • 本地生活平台商品所属的后台类目id，必须是叶子类目id，不填会自动通过算法推荐一个类目
  • └ taobao_cover_image
  • String
  • 可选
  • /i1/2200781230155/O1CN01cJAWH61D11w1tkWTP_!!2200781230155-0-koubei.jpg
  • 商品首图(1:1)版本，作为商品在淘宝渠道露出的首图。如果某个商品的本字段为空，则该商品无法在淘宝渠道露出。需要传通过素材接口上传后返回的素材短链，不支持外部图片链接直接上传。代金券商品不支持设置。
  • └ use_upload_detail_images
  • Boolean
  • 可选
  • true
  • 是否使用上传图文详情的方式，true时会忽略套餐详情包信息item_combo_package，代金券商品不支持设置。
  • └ upload_detail_images
  • String []
  • 可选
  • 上传图文详情，use_upload_detail_images为true时必填，代金券商品不支持设置。
  • └ real_service_merchant
  • String
  • 可选
  • 提供服务的平台名称
  • 真实提供服务的平台名称，会影响用户核销页面"请提示商家使用XXX核销券码"，建议不超过6个字
  • └ detail_html
  • String
  • 可选
  • https://xxxxx.xxx.com/sample.html
  • 商详html的url，需要先通过html渲染接口进行文本上传和切图后使用，代金券商品不支持设置。
  • refund_rule
  • RefundRuleDTO
  • 可选
  • 退款规则，如是否支持审核退。业务中有白名单配置，有需求使用请提前沟通。
  • └ allow_check_refund
  • Boolean
  • 可选
  • false
  • 是否支持审核退，审核退商品，用户申请退款需要审核通过后才会退款给用户。需要三方支持审核退产品能力。
  • └ seller_id
  • String
  • 必须
  • 2200781123456
  • 卖家sellerId，三方场景必填
  • └ pid
  • String
  • 必须
  • 208852112345678
  • 卖家partnerId(蚂蚁pid)，三方场景必填

响应参数

名称 类型 示例值 描述
result TopApiCommonResult 返回结果
  • data
  • TopItemSimpleResponse
  • 业务结果数据
  • └ item_id
  • String
  • 633709315655
  • 本地生活商品id
  • └ external_item_id
  • String
  • 3124124214
  • 外部商品id，外部券商品有
  • └ error_desc
  • String
  • 系统繁忙
  • 失败原因描述
  • └ success
  • Boolean
  • true
  • 是否成功
  • └ error_code
  • String
  • SYSTEM_ERROR
  • 错误码
  • └ retry
  • Boolean
  • true
  • 失败是否需要重试

请求示例

  • JAVA
  • .NET
  • PHP
  • CURL
  • Python
  • C/C++
  • NodeJS
TaobaoClient client = new DefaultTaobaoClient(url, appkey, secret);
AlibabaAlscKoubeiItemCreateRequest req = new AlibabaAlscKoubeiItemCreateRequest();
AlibabaAlscKoubeiItemCreateRequest.TopItemCreateRequest obj1 = new AlibabaAlscKoubeiItemCreateRequest.TopItemCreateRequest();
obj1.setRequestId("e76487891803ff6122a1804048ff6d1048");
AlibabaAlscKoubeiItemCreateRequest.ItemFormDTO obj2 = new AlibabaAlscKoubeiItemCreateRequest.ItemFormDTO();
obj2.setItemType("COMBO");
obj2.setOriginalPrice("48.48");
obj2.setSubject("鱼香肉丝杨梅汁套餐");
obj2.setTicketDisplayMode("EXTERNAL_TICKET_CODE");
obj2.setMemo("肯德基（蚂蚁金服店）首推新品");
obj2.setInventory(20L);
obj2.setStoreIds(""218679282","218682242"");
obj2.setCover("/i1/2200781230155/O1CN01cJAWH61D11w1tkWTP_!!2200781230155-0-koubei.jpg");
obj2.setForbidReverse(false);
obj2.setGmtEnd(StringUtils.parseDateTime("2021-03-31 23:59:59"));
obj2.setPrice("28.12");
List<AlibabaAlscKoubeiItemCreateRequest.AvailablePeriodInfoDTO> list4 = new ArrayList<AlibabaAlscKoubeiItemCreateRequest.AvailablePeriodInfoDTO>();
AlibabaAlscKoubeiItemCreateRequest.AvailablePeriodInfoDTO obj5 = new AlibabaAlscKoubeiItemCreateRequest.AvailablePeriodInfoDTO();
list4.add(obj5);
obj5.setTimeEnd("21:32");
obj5.setTimeStart("17:35");
obj5.setAvailableWeekDays("");
obj2.setAvailablePeriods(list4);
obj2.setVerifyFrequency("single");
obj2.setExternalItemId("1234114");
AlibabaAlscKoubeiItemCreateRequest.ItemComboPackageDTO obj6 = new AlibabaAlscKoubeiItemCreateRequest.ItemComboPackageDTO();
obj6.setPackageNotes("");
List<AlibabaAlscKoubeiItemCreateRequest.PackageContentDTO> list8 = new ArrayList<AlibabaAlscKoubeiItemCreateRequest.PackageContentDTO>();
AlibabaAlscKoubeiItemCreateRequest.PackageContentDTO obj9 = new AlibabaAlscKoubeiItemCreateRequest.PackageContentDTO();
list8.add(obj9);
List<AlibabaAlscKoubeiItemCreateRequest.ContentUnitDTO> list12 = new ArrayList<AlibabaAlscKoubeiItemCreateRequest.ContentUnitDTO>();
AlibabaAlscKoubeiItemCreateRequest.ContentUnitDTO obj13 = new AlibabaAlscKoubeiItemCreateRequest.ContentUnitDTO();
list12.add(obj13);
obj13.setUnit("份");
obj13.setPrice("12.12");
obj13.setNum(4L);
obj13.setTitle("宫保鸡丁");
obj13.setContent("大份");
list10.setContentUnitList(list12);
obj9.setTitle("宫保鸡丁套餐");
obj6.setPackageContentList(list8);
List<AlibabaAlscKoubeiItemCreateRequest.GraphicTextDTO> list15 = new ArrayList<AlibabaAlscKoubeiItemCreateRequest.GraphicTextDTO>();
AlibabaAlscKoubeiItemCreateRequest.GraphicTextDTO obj16 = new AlibabaAlscKoubeiItemCreateRequest.GraphicTextDTO();
list15.add(obj16);
obj16.setImageUrls("");
obj16.setTitle("宫保鸡丁");
obj16.setDesc("图片描述");
obj16.setType("SINGLE");
obj6.setGraphicTextList(list15);
List<AlibabaAlscKoubeiItemCreateRequest.ServiceFlowDTO> list18 = new ArrayList<AlibabaAlscKoubeiItemCreateRequest.ServiceFlowDTO>();
AlibabaAlscKoubeiItemCreateRequest.ServiceFlowDTO obj19 = new AlibabaAlscKoubeiItemCreateRequest.ServiceFlowDTO();
list18.add(obj19);
obj19.setUnit("份");
obj19.setServiceContent("服务内容描述");
obj19.setNum(1L);
obj19.setExplanation("补充说明");
obj6.setServiceFlowList(list18);
obj2.setItemComboPackage(obj6);
List<AlibabaAlscKoubeiItemCreateRequest.BuyerNotesInfoDTO> list21 = new ArrayList<AlibabaAlscKoubeiItemCreateRequest.BuyerNotesInfoDTO>();
AlibabaAlscKoubeiItemCreateRequest.BuyerNotesInfoDTO obj22 = new AlibabaAlscKoubeiItemCreateRequest.BuyerNotesInfoDTO();
list21.add(obj22);
obj22.setDetails("");
obj22.setTitle("须知标题1");
obj2.setBuyerNotes(list21);
obj2.setTestItem(true);
obj2.setPictureDetails("");
AlibabaAlscKoubeiItemCreateRequest.BuyerTipsTemplateDTO obj23 = new AlibabaAlscKoubeiItemCreateRequest.BuyerTipsTemplateDTO();
obj23.setFreeWifi(true);
obj23.setLimitUserNum(true);
obj23.setReserveNote("预约说明信息");
obj23.setInvoiceTypes("");
obj23.setParkFeePerHour("3");
obj23.setNeedReserve(true);
obj23.setSupplyInvoice(true);
obj23.setFreeParkHours(2L);
obj23.setUserNumLimited(4L);
obj23.setFreePark(true);
obj23.setParkFeeUpperBoundPerDay("20");
obj2.setBuyerTipsTemplate(obj23);
List<AlibabaAlscKoubeiItemCreateRequest.UnavailablePeriodInfoDTO> list25 = new ArrayList<AlibabaAlscKoubeiItemCreateRequest.UnavailablePeriodInfoDTO>();
AlibabaAlscKoubeiItemCreateRequest.UnavailablePeriodInfoDTO obj26 = new AlibabaAlscKoubeiItemCreateRequest.UnavailablePeriodInfoDTO();
list25.add(obj26);
obj26.setStartDay("2018-06-30");
obj26.setEndDay("2018-09-30");
obj2.setUnavailablePeriods(list25);
obj2.setGmtStart(StringUtils.parseDateTime("2021-03-01 23:59:59"));
obj2.setVerifyTimes(3L);
obj2.setDisplayChannel("ORIENTATION");
List<AlibabaAlscKoubeiItemCreateRequest.BuyerLimitInfoDTO> list28 = new ArrayList<AlibabaAlscKoubeiItemCreateRequest.BuyerLimitInfoDTO>();
AlibabaAlscKoubeiItemCreateRequest.BuyerLimitInfoDTO obj29 = new AlibabaAlscKoubeiItemCreateRequest.BuyerLimitInfoDTO();
list28.add(obj29);
obj29.setLimitNum(2L);
obj29.setLimitType("LIMIT_USER_PER_DAY");
obj2.setBuyLimitList(list28);
AlibabaAlscKoubeiItemCreateRequest.ValidityInfoDTO obj30 = new AlibabaAlscKoubeiItemCreateRequest.ValidityInfoDTO();
obj30.setValidityPeriod(90L);
obj30.setValidityType("RELATIVE");
obj30.setRangeTo(StringUtils.parseDateTime("2022-04-17 00:00:00"));
obj30.setRangeFrom(StringUtils.parseDateTime("2022-07-17 00:00:00"));
obj2.setValidityInfo(obj30);
obj2.setCategoryId("2020062900464093");
obj2.setTaobaoCoverImage("/i1/2200781230155/O1CN01cJAWH61D11w1tkWTP_!!2200781230155-0-koubei.jpg");
obj2.setUseUploadDetailImages(true);
obj2.setUploadDetailImages("");
obj2.setRealServiceMerchant("提供服务的平台名称");
obj2.setDetailHtml("https://xxxxx.xxx.com/sample.html");
AlibabaAlscKoubeiItemCreateRequest.RefundRuleDTO obj31 = new AlibabaAlscKoubeiItemCreateRequest.RefundRuleDTO();
obj31.setAllowCheckRefund(false);
obj2.setRefundRule(obj31);
obj1.setItemForm(obj2);
obj1.setSellerId("2200781123456");
obj1.setPid("208852112345678");
req.setTopItemCreateRequest(obj1);
AlibabaAlscKoubeiItemCreateResponse rsp = client.execute(req);
System.out.println(rsp.getBody());

响应示例

  • XML示例
  • JSON示例
<alibaba_alsc_koubei_item_create_response>
    <result>
        <data>
            <item_id>633709315655</item_id>
            <external_item_id>3124124214</external_item_id>
        </data>
        <error_desc>系统繁忙</error_desc>
        <success>true</success>
        <error_code>SYSTEM_ERROR</error_code>
        <retry>true</retry>
    </result>
</alibaba_alsc_koubei_item_create_response>

异常示例

  • XML示例
  • JSON示例
<error_response>
    <code>50</code>
    <msg>Remote service error</msg>
    <sub_code>isv.invalid-parameter</sub_code>
    <sub_msg>非法参数</sub_msg>
</error_response>

错误码解释

错误码 错误描述 解决方案

API工具

API测试工具 错误码查询工具 SDK下载

如何获得此API

FAQ

我要提问
返回
顶部