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

alibaba.alsc.koubei.item.query (商品详情查询)

商品详情查询

公共参数

请求地址：

环境	HTTP请求地址	HTTPS请求地址
正式环境	http://gw.api.taobao.com/router/rest	https://eco.taobao.com/router/rest

公共请求参数：

名称	类型	是否必须	描述
method	String	是	API接口名称。
app_key	String	是	TOP分配给应用的AppKey。
target_app_key	String	否	被调用的目标AppKey，仅当被调用的API为第三方ISV提供时有效。
sign_method	String	是	签名的摘要算法，可选值为：hmac，md5。
sign	String	是	API输入参数签名结果，签名算法介绍请点击这里。
session	String	否	用户登录授权成功后，TOP颁发给应用的授权信息，详细介绍请点击这里。当此API的标签上注明：“需要授权”，则此参数必传；“不需要授权”，则此参数不需要传；“可选授权”，则此参数为可选。
timestamp	String	是	时间戳，格式为yyyy-MM-dd HH:mm:ss，时区为GMT+8，例如：2015-01-01 12:00:00。淘宝API服务端允许客户端请求最大时间误差为10分钟。
format	String	否	响应格式。默认为xml格式，可选值：xml，json。
v	String	是	API协议版本，可选值：2.0。
partner_id	String	否	合作伙伴身份标识。
simplify	Boolean	否	是否采用精简JSON返回格式，仅当format=json时有效，默认值为：false。

请求参数

名称	类型	是否必须	示例值	更多限制	描述
param_top_item_query_request	TopItemQueryRequest	必须			商品查询请求
└ item_id String 必须 633709315655 本地生活商品id └ request_id String 必须 e76487891803ff6122a1804048ff6d1048 业务请求id，每次请求都要变换请求id └ seller_id String 必须 2200781230370 商户sellerId

响应参数

名称	类型	示例值	描述
result	TopApiCommonResult		商品查询结果
data TopItemDetailResponse 商品查询结果 item_detail_info ItemDetailInfoDTO 商品详情 available_periods AvailablePeriodInfoDTO [] 商品可用时段列表。最多添加三条规则。该内容仅用于展示，不影响实际核销。如：周一、周二 10:00至22:00 └ available_week_days String [] 可用天列表，以星期周期的形式展示，周一到周日分别用1到7表示 └ time_end String 22:00 可用时段结束时间点，开始时间点不能晚于结束时间点 └ time_start String 10:00 可用时段开始时间点，开始时间点不能晚于结束时间点 buy_limit_list BuyerLimitInfoDTO [] 限购规则 └ limit_num Number 2 限购数量 └ limit_type String LIMIT_USER_PER_DAY 限购类型，单用户整个售卖周期限制：LIMIT_USER_FOREVER，用户每天数量限制：LIMIT_USER_PER_DAY。注意：每单限购规则由本地平台统一管控，如果有定制需要找接入产品提需求定制。 buyer_notes BuyerNotesInfoDTO [] 自定义购买须知 └ details String [] 标题下的描述 └ title String 购买须知标题 buyer_tips_template BuyerTipsTemplateDTO 购买须知模板信息 └ free_park Boolean true 是否免费停车 └ free_park_hours Number 2 免费停车小时数 └ free_wifi Boolean true 是否免费wifi └ invoice_types String [] 发票类型，电子发票：ELECTRONIC_INVOICE，纸质发票：PAPER_INVOICE └ limit_user_num Boolean true 是否限制用户数 └ need_reserve Boolean true 是否需要预约 └ park_fee_per_hour String 10 每小时停车费,单位元,只支持整数 └ park_fee_upper_bound_per_day String 30 每24小时封顶金额,单位元,只支持整数 └ reserve_note String 预约说明信息预约说明 └ supply_invoice Boolean true 是否提供发票 └ user_num_limited Number 3 限制多少人使用 └ category_id String 2020062900464093 本地生活平台商品所属的后台类目id，必须是叶子类目id └ cover String /i1/2200781230155/O1CN01cJAWH61D11w1tkWTP_!!2200781230155-0-koubei.jpg 商品首图，需要传通过素材接口上传后返回的素材短链，不支持外部图片链接直接上传。 └ display_channel String ALL 商品展示渠道，ALL表示正常投放，允许在口碑门店详情页、搜索结果、活动页、频道页中展示。ORIENTATION表示定向投放，仅限在活动页面投放或扫码购买，且定向投放的商品不会在高德侧展示。不填默认为ALL。 └ external_item_id String 1234114 外部商品id，核销方式为外部券码核销时，外部券商品必填 └ forbid_reverse Boolean false 是否禁止反圈，true为禁止反圈，false为不禁止反圈，不填默认false。设置禁止反圈后商品即不会在本地平台反圈活动中被圈选。 └ gmt_end Date 2021-03-31 23:59:59 商品售卖结束时间，当到达该时间时，商品暂停售卖，将不在客户端中继续展示，用户无法继续购买。注意：该时间不能晚于核销绝对有效期的结束时间。 └ gmt_start Date 2021-03-01 23:59:59 2021-03-01 23:59:59 商品售卖开始时间 └ inventory Number 100 商品剩余可售库存 item_combo_package ItemComboPackageDTO 套餐详情包信息，只有套餐商品需要设置 graphic_text_list GraphicTextDTO [] 套餐图文详情 └ desc String 招牌图片描述 └ image_urls String [] 图片列表，需要传通过素材接口上传后返回的素材短链，不支持外部图片链接直接上传。 └ title String 宫保鸡丁名称 └ type String SINGLE 图片类型，SINGLE：单品图片，PACKAGE：套餐图片 package_content_list PackageContentDTO [] 套餐详情内容 content_unit_list ContentUnitDTO [] 套餐组内容 └ content String 大份内容(菜品为规格) └ num Number 2 数量 └ price String 30.00 价格 └ title String 宫保鸡丁名称 └ unit String 份单位，不能包含数字 └ title String 小吃内容标题 └ package_notes String [] 补充说明 service_flow_list ServiceFlowDTO [] 服务流程 └ explanation String 补充说明补充说明 └ num Number 1 数量 └ service_content String 服务内容服务内容描述 └ unit String 份单位 └ item_id String 633709315655 本地生活商品id └ item_type String COMBO 商品类型，套餐（COMBO），次卡（TIMES_CARD），代金券（VOUCHER）等，目前只支持套餐和代金券类型 └ memo String 肯德基（蚂蚁金服店）首推新品商品备注信息。用于商户内部管理，用户页面不露出。 └ original_price String 10.00 商品原价，字符串类型，单位元，保留2位小数。代金券商品表示券面值。 └ picture_details String [] 商品轮播图片,跟在首图后面。尺寸大小与商品首图一致，最多5张。C端上展现时，自己会做性能优化(等比缩放，以图片中心为基准裁剪) └ price String 5.00 商品售价，字符串类型，单位元，保留2位小数。售价不能大于原价。 └ punish_audit_status String PASS 审核状态。审核通过：PASS；待整改：CAN_NOT_ACTIVITY；审核中：PROCESSING；审核驳回：REJECT └ punish_reason String 商品名称重复处罚原因 └ punish_type String NORMAL 处罚类型。CC处罚：ITEM_CC。处罚下架：ITEM_DOWN_SHELF。处罚删除：ITEM_DELETE。预cc处罚：ITEM_PRE_CC。处罚恢复=未处罚：NORMAL └ store_ids String [] 商品需要关联的本地侧门店id列表，即传入一个或多个store_id。 └ subject String 宫保鸡丁商品名称，最多不超过60个字符，255个字节，内容需要在gbk编码范围内，并且不包含非法字符："？","?","_","——","=","@","~","～","{","}","《","》","。","￥","◆","★","?","※" └ taobao_cover_image String /i1/2200781230155/O1CN01cJAWH61D11w1tkWTP_!!2200781230155-0-koubei.jpg 商品首图(1:1)版本，作为商品在淘宝渠道露出的首图。如果某个商品的本字段为空，则该商品无法在淘宝渠道露出。需要传通过素材接口上传后返回的素材短链，不支持外部图片链接直接上传。 └ test_item Boolean false 是否是测试商品，true为测试商品，false为非测试商品，默认为false，测试商品需要将display_channel设置为ORIENTATION(定向投放) └ ticket_display_mode String EXTERNAL_TICKET_CODE 商品购买凭证核销方式。枚举值为：USER_PAY_CODE代表付款码核销方式，如果选择付款码核销，则sku_id必填。TICKET_CODE代表券码核销方式，如果选择券码核销，则sku_id必须为空。EXTERNAL_TICKET_CODE表示外部券码核销方式。 unavailable_periods UnavailablePeriodInfoDTO [] 商品不可用日期区间 └ end_day String 2018-09-30 不可用时段结束日期，开始日期不能晚于结束日期 └ start_day String 2018-06-30 不可用时段开始日期，开始日期不能晚于结束日期 validity_info ValidityInfoDTO 核销有效期信息 └ range_from Date 2022-07-01 00:00:00 核销开始时间 └ range_to Date 2022-07-30 00:00:00 核销结束时间 └ validity_period Number 90 核销相对有效天数，单位天，有效期为RELATIVE时必填 └ validity_type String RELATIVE 核销有效期类型，绝对有效期：FIXED，相对有效期：RELATIVE └ verify_frequency String single 核销类型。single：单次核销商品(普通商品，包括套餐、代金券)；multi:多次核销商品(次卡) └ verify_times Number 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个字 └ item_status String EFFECTIVE 商品状态，包含状态有生效(EFFECTIVE)，暂停(PAUSE)，删除(INVALID) └ detail_html String https://xxxx.xxx.com/sample.html 商详html的url，需要先通过html渲染接口进行文本上传和切图后使用 refund_rule RefundRuleDTO 退款规则，如是否支持审核退 └ allow_check_refund Boolean false 是否支持审核退，审核退商品，用户申请退款需要审核通过后才会退款给用户。需要三方支持审核退产品能力。 └ error_code String SYSTEM_ERROR 错误码 └ error_desc String 系统繁忙失败原因描述 └ retry Boolean true 失败时是否重试 └ success Boolean true 是否成功

请求示例

JAVA
.NET
PHP
CURL
Python
C/C++
NodeJS

TaobaoClient client = new DefaultTaobaoClient(url, appkey, secret);
AlibabaAlscKoubeiItemQueryRequest req = new AlibabaAlscKoubeiItemQueryRequest();
AlibabaAlscKoubeiItemQueryRequest.TopItemQueryRequest obj1 = new AlibabaAlscKoubeiItemQueryRequest.TopItemQueryRequest();
obj1.setItemId("633709315655");
obj1.setRequestId("e76487891803ff6122a1804048ff6d1048");
obj1.setSellerId("2200781230370");
req.setParamTopItemQueryRequest(obj1);
AlibabaAlscKoubeiItemQueryResponse rsp = client.execute(req);
System.out.println(rsp.getBody());

响应示例

XML示例
JSON示例

100

101

102

103

104

105

106

107

108

109

110

111

112

113

<alibaba_alsc_koubei_item_query_response>
    <result>
        <data>
            <item_detail_info>
                <available_periods>
                    <available_period_info_d_t_o>
                        <time_end>22:00</time_end>
                        <time_start>10:00</time_start>
                    </available_period_info_d_t_o>
                </available_periods>
                <buy_limit_list>
                    <buyer_limit_info_d_t_o>
                        <limit_num>2</limit_num>
                        <limit_type>LIMIT_USER_PER_DAY</limit_type>
                    </buyer_limit_info_d_t_o>
                </buy_limit_list>
                <buyer_notes>
                    <buyer_notes_info_d_t_o>
                        <title>购买须知</title>
                    </buyer_notes_info_d_t_o>
                </buyer_notes>
                <buyer_tips_template>
                    <free_park>true</free_park>
                    <free_park_hours>2</free_park_hours>
                    <free_wifi>true</free_wifi>
                    <limit_user_num>true</limit_user_num>
                    <need_reserve>true</need_reserve>
                    <park_fee_per_hour>10</park_fee_per_hour>
                    <park_fee_upper_bound_per_day>30</park_fee_upper_bound_per_day>
                    <reserve_note>预约说明信息</reserve_note>
                    <supply_invoice>true</supply_invoice>
                    <user_num_limited>3</user_num_limited>
                </buyer_tips_template>
                <category_id>2020062900464093</category_id>
                <cover>/i1/2200781230155/O1CN01cJAWH61D11w1tkWTP_!!2200781230155-0-koubei.jpg</cover>
                <display_channel>ALL</display_channel>
                <external_item_id>1234114</external_item_id>
                <forbid_reverse>false</forbid_reverse>
                <gmt_end>2021-03-31 23:59:59</gmt_end>
                <gmt_start>2021-03-01 23:59:59 2021-03-01 23:59:59</gmt_start>
                <inventory>100</inventory>
                <item_combo_package>
                    <graphic_text_list>
                        <graphic_text_d_t_o>
                            <desc>招牌</desc>
                            <title>宫保鸡丁</title>
                            <type>SINGLE</type>
                        </graphic_text_d_t_o>
                    </graphic_text_list>
                    <package_content_list>
                        <package_content_d_t_o>
                            <content_unit_list>
                                <content_unit_d_t_o>
                                    <content>大份</content>
                                    <num>2</num>
                                    <price>30.00</price>
                                    <title>宫保鸡丁</title>
                                    <unit>份</unit>
                                </content_unit_d_t_o>
                            </content_unit_list>
                            <title>小吃</title>
                        </package_content_d_t_o>
                    </package_content_list>
                    <service_flow_list>
                        <service_flow_d_t_o>
                            <explanation>补充说明</explanation>
                            <num>1</num>
                            <service_content>服务内容</service_content>
                            <unit>份</unit>
                        </service_flow_d_t_o>
                    </service_flow_list>
                </item_combo_package>
                <item_id>633709315655</item_id>
                <item_type>COMBO</item_type>
                <memo>肯德基（蚂蚁金服店）首推新品</memo>
                <original_price>10.00</original_price>
                <price>5.00</price>
                <punish_audit_status>PASS</punish_audit_status>
                <punish_reason>商品名称重复</punish_reason>
                <punish_type>NORMAL</punish_type>
                <subject>宫保鸡丁</subject>
                <taobao_cover_image>/i1/2200781230155/O1CN01cJAWH61D11w1tkWTP_!!2200781230155-0-koubei.jpg</taobao_cover_image>
                <test_item>false</test_item>
                <ticket_display_mode>EXTERNAL_TICKET_CODE</ticket_display_mode>
                <unavailable_periods>
                    <unavailable_period_info_d_t_o>
                        <end_day>2018-09-30</end_day>
                        <start_day>2018-06-30</start_day>
                    </unavailable_period_info_d_t_o>
                </unavailable_periods>
                <validity_info>
                    <range_from>2022-07-01 00:00:00</range_from>
                    <range_to>2022-07-30 00:00:00</range_to>
                    <validity_period>90</validity_period>
                    <validity_type>RELATIVE</validity_type>
                </validity_info>
                <verify_frequency>single</verify_frequency>
                <verify_times>1</verify_times>
                <use_upload_detail_images>true</use_upload_detail_images>
                <real_service_merchant>提供服务的平台名称</real_service_merchant>
                <item_status>EFFECTIVE</item_status>
                <detail_html>https://xxxx.xxx.com/sample.html</detail_html>
                <refund_rule>
                    <allow_check_refund>false</allow_check_refund>
                </refund_rule>
            </item_detail_info>
        </data>
        <error_code>SYSTEM_ERROR</error_code>
        <error_desc>系统繁忙</error_desc>
        <retry>true</retry>
        <success>true</success>
    </result>
</alibaba_alsc_koubei_item_query_response>

{
    "alibaba_alsc_koubei_item_query_response":{
        "result":{
            "data":{
                "item_detail_info":{
                    "available_periods":{
                        "available_period_info_d_t_o":[
                            {,
                                "time_end":"22:00",
                                "time_start":"10:00"
                            }
                        ]
                    },
                    "buy_limit_list":{
                        "buyer_limit_info_d_t_o":[
                            {
                                "limit_num":2,
                                "limit_type":"LIMIT_USER_PER_DAY"
                            }
                        ]
                    },
                    "buyer_notes":{
                        "buyer_notes_info_d_t_o":[
                            {,
                                "title":"购买须知"
                            }
                        ]
                    },
                    "buyer_tips_template":{
                        "free_park":true,
                        "free_park_hours":2,
                        "free_wifi":true,
                        "limit_user_num":true,
                        "need_reserve":true,
                        "park_fee_per_hour":"10",
                        "park_fee_upper_bound_per_day":"30",
                        "reserve_note":"预约说明信息",
                        "supply_invoice":true,
                        "user_num_limited":3
                    },
                    "category_id":"2020062900464093",
                    "cover":"\/i1\/2200781230155\/O1CN01cJAWH61D11w1tkWTP_!!2200781230155-0-koubei.jpg",
                    "display_channel":"ALL",
                    "external_item_id":"1234114",
                    "forbid_reverse":false,
                    "gmt_end":"2021-03-31 23:59:59 ",
                    "gmt_start":"2021-03-01 23:59:59 2021-03-01 23:59:59 ",
                    "inventory":100,
                    "item_combo_package":{
                        "graphic_text_list":{
                            "graphic_text_d_t_o":[
                                {
                                    "desc":"招牌",
                                    "title":"宫保鸡丁",
                                    "type":"SINGLE"
                                }
                            ]
                        },
                        "package_content_list":{
                            "package_content_d_t_o":[
                                {
                                    "content_unit_list":{
                                        "content_unit_d_t_o":[
                                            {
                                                "content":"大份",
                                                "num":2,
                                                "price":"30.00",
                                                "title":"宫保鸡丁",
                                                "unit":"份"
                                            }
                                        ]
                                    },
                                    "title":"小吃"
                                }
                            ]
                        },
                        "service_flow_list":{
                            "service_flow_d_t_o":[
                                {
                                    "explanation":"补充说明\t",
                                    "num":1,
                                    "service_content":"服务内容",
                                    "unit":"份"
                                }
                            ]
                        }
                    },
                    "item_id":"633709315655",
                    "item_type":"COMBO",
                    "memo":"肯德基（蚂蚁金服店）首推新品",
                    "original_price":"10.00",
                    "price":"5.00",
                    "punish_audit_status":"PASS",
                    "punish_reason":"商品名称重复",
                    "punish_type":"NORMAL",
                    "subject":"宫保鸡丁",
                    "taobao_cover_image":"\/i1\/2200781230155\/O1CN01cJAWH61D11w1tkWTP_!!2200781230155-0-koubei.jpg",
                    "test_item":false,
                    "ticket_display_mode":"EXTERNAL_TICKET_CODE",
                    "unavailable_periods":{
                        "unavailable_period_info_d_t_o":[
                            {
                                "end_day":"2018-09-30",
                                "start_day":"2018-06-30"
                            }
                        ]
                    },
                    "validity_info":{
                        "range_from":"2022-07-01 00:00:00",
                        "range_to":"2022-07-30 00:00:00",
                        "validity_period":90,
                        "validity_type":"RELATIVE"
                    },
                    "verify_frequency":"single",
                    "verify_times":1,
                    "use_upload_detail_images":true,
                    "real_service_merchant":"提供服务的平台名称",
                    "item_status":"EFFECTIVE",
                    "detail_html":"https:\/\/xxxx.xxx.com\/sample.html",
                    "refund_rule":{
                        "allow_check_refund":false
                    }
                }
            },
            "error_code":"SYSTEM_ERROR",
            "error_desc":"系统繁忙",
            "retry":true,
            "success":true
        }
    }
}

异常示例

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

我要提问

返回
顶部

开放平台

本地生活API

alibaba.alsc.koubei.item.query (商品详情查询)

公共参数

请求参数

响应参数

请求示例

响应示例

异常示例

错误码解释

API工具

如何获得此API

FAQ