isv查询口碑餐饮商品详情
环境 | HTTPS请求地址 |
---|---|
正式环境 | https://openapi.alipay.com/gateway.do |
参数 | 类型 | 是否必填 | 最大长度 | 描述 | 示例值 |
---|---|---|---|---|---|
app_id | String | 是 | 32 | 支付宝分配给开发者的应用ID | 2014072300007148 |
method | String | 是 | 128 | 接口名称 | koubei.catering.item.query |
format | String | 否 | 40 | 仅支持JSON | JSON |
charset | String | 是 | 10 | 请求使用的编码格式,如utf-8,gbk,gb2312等 | utf-8 |
sign_type | String | 是 | 10 | 商户生成签名字符串所使用的签名算法类型,目前支持RSA2和RSA,推荐使用RSA2 | RSA2 |
sign | String | 是 | 344 | 商户请求参数的签名串,详见签名 | 详见示例 |
timestamp | String | 是 | 19 | 发送请求的时间,格式"yyyy-MM-dd HH:mm:ss" | 2014-07-24 03:07:50 |
version | String | 是 | 3 | 调用的接口版本,固定为:1.0 | 1.0 |
app_auth_token | String | 否 | 40 | 详见应用授权概述 | |
biz_content | String | 是 | - | 请求参数的集合,最大长度不限,除公共参数外所有请求参数都必须放在这个参数中传递,具体参照各产品快速接入文档 |
参数 | 类型 | 是否必填 | 最大长度 | 描述 | 示例值 |
---|---|---|---|---|---|
operator_type | String | 必须 | 20 | 操作人员身份类型。如果是isv代操作,请传入ISV;如果是商户操作请传入MERCHANT;如果是商户员工则传入M_STAFF | MERCHANT |
request_id | String | 必须 | 64 | 请求id。支持英文字母和数字,由开发者自行定义(不允许重复)。比如2016102903214476899999999 | 2016102903214476899999999 |
item_id | String | 必须 | 64 | 口碑体系内部商品的唯一标识 | 2015090300006123123213213 |
auth_code | String | 可选 | 64 | 服务商、服务商员工、商户、商户员工等口碑角色操作时必填,对应为《koubei.member.data.oauth.query》中的auth_code,默认有效期24小时;isv自身角色操作的时候,无需传该参数 | 6a8713a414da4a2dafdb7c24e597TX80 |
参数 | 类型 | 是否必填 | 最大长度 | 描述 | 示例值 |
---|---|---|---|---|---|
code | String | 是 | - | 网关返回码,详见文档 | 40004 |
msg | String | 是 | - | 网关返回码描述,详见文档 | Business Failed |
sub_code | String | 否 | - | 业务返回码,详见文档 | ACQ.TRADE_HAS_SUCCESS |
sub_msg | String | 否 | - | 业务返回码描述,详见文档 | 交易已被支付 |
sign | String | 是 | - | 签名,详见文档 | DZXh8eeTuAHoYE3w1J+POiPhfDxOYBfUNn1lkeT/V7P4zJdyojWEa6IZs6Hz0yDW5Cp/viufUb5I0/V5WENS3OYR8zRedqo6D+fUTdLHdc+EFyCkiQhBxIzgngPdPdfp1PIS7BdhhzrsZHbRqb7o4k3Dxc+AAnFauu4V6Zdwczo= |
参数 | 类型 | 是否必填 | 最大长度 | 描述 | 示例值 |
---|---|---|---|---|---|
request_id | String | 必填 | 64 | 请求id。支持英文字母和数字,由开发者自行定义(不允许重复)。比如2016102903214476899999999 | 2016102903214476899999999 |
item_id | String | 必填 | 64 | 口碑体系内部商品的唯一标识 | 2015090300006123123213213 |
ticket_display_mode | String | 必填 | 20 | 商品购买凭证核销方式。枚举值为:USER_PAY_CODE代表付款码核销方式,如果选择付款码核销,则sku_id必填。TICKET_CODE代表券码核销方式,如果选择券码核销,则sku_id必须为空 | USER_PAY_CODE |
subject | String | 必填 | 60 | 商品名称,请勿超过60个字符 | 鱼香肉丝杨梅汁套餐 |
category_id | String | 必填 | 64 | 口碑商品所属的后台类目id,ISV可通过开放接口koubei.item.category.children.batchquery来获得后台类目树,并选择叶子类目,作为该值传入 | 2017081400178386 |
original_price | Price | 必填 | 20 | 商品原价。字符串类型,单位元,2位小数。最高价格49998元 | 120.12 |
price | Price | 必填 | 20 | 商品现价。字符串类型,单位元,2位小数。最高价格49998元 | 119.99 |
cover | String | 必填 | 100 | 商品首图。支持bmp,png,jpeg,jpg,gif格式的图片,建议宽高比16:9,建议宽高:1242*698px 图片大小≤5M。图片大小超过5M,接口会报错。若图片尺寸不对,口碑服务器自身不会做压缩,但是口碑把这些图片放到客户端上展现时,自己会做性能优化(等比缩放,以图片中心为基准裁剪)。 | VZ4Uu9i-SEC0w6k7GxzNcwAAACMAAQQD |
item_packages | ItemPackageInfo [] | 必填 | - | 商品详情-商品套餐内容 | |
|
|||||
item_dishes | ItemDishInfo [] | 必填 | - | 商品详情-菜品图片详情 | |
|
|||||
inventory | Number | 必填 | 20 | 发布商品库存数量 | 1000 |
gmt_start | Date | 必填 | 50 |
商品生效时间,商品状态有效并且到达生效时间后才可在客户端(消费者端)展示出来,如果商品生效时间小于当前时间,则立即生效。
说明:商品的生效时间不能早于创建当天的0点 |
2016-10-07 11:30:24 |
validity_period | Number | 必填 | 16 | 购买有效期:商品自购买起多长时间内有效,取值范围 7-360,单位天。举例,如果是7的话,是到第七天晚上23:59:59失效。商品购买后,没有在有效期内核销,则自动退款给用户。举例:买了一个鱼香肉丝杨梅汁套餐的商品,有效期一个月,如果一个月之后,用户没有消费该套餐,则自动退款给用户 | 300 |
shop_ids | String [] | 必填 | 50000 | 商品关联门店id列表,即传入一个或多个shop_id。 | [2015100300077000000001860010, 2015100300077000000001860011] |
item_status | String | 必填 | 20 | 该商品当前的状态,共有5个状态:INIT(初始状态)EFFECTIVE(生效)PAUSE(暂停)FREEZE(冻结)INVALID(失效) | EFFECTIVE |
picture_details | String [] | 选填 | 500 | 商品详情图片列表。尺寸大小与商品首图一致,最多5张。C端上展现时,自己会做性能优化(等比缩放,以图片中心为基准裁剪) | [0yaPA96AQPqJDIju28pvAgAAACMAAQEC, VZ4Uu9i-SEC0w6k7GxzNcwAAACMAAQQD] |
sku_id | String | 选填 | 64 | 商品编码,由商家自定义,不可重复,用于商品核销。如果ticket_display_mode选择付款码核销方式(USER_PAY_CODE),则sku_id必填。如果ticket_display_mode选择券码核销方式(TICKET_CODE),则sku_id必须为空 | 2017071013300001 |
package_notes | String [] | 选填 | 1000 | 商品详情-补充说明列表 | 补充说明:套餐可以叠加使用 |
buyer_notes | BuyerNotesInfo [] | 选填 | - | 商品购买须知列表 | |
|
|||||
latest_notice | String | 选填 | 200 | 商家公告,最多不超过200个字符 | 本店周五休息不上班 |
memo | String | 选填 | 100 | 商品备注信息。用于商户内部管理,用户页面不露出。 | 备注:肯德基(蚂蚁金服店)首推新品 |
merchant_introduction | IntroductionInfo | 选填 | - | 商品详情-商家介绍图文详情 | |
|
|||||
weight | String | 选填 | 10 | 商品顺序权重,必须是整数,不传默认为0,权重数值越大排序越靠前 | 2 |
available_periods | AvailablePeriodInfo [] | 选填 | - | 商品可用时段列表。最多添加三条规则。该内容仅用于展示,不影响实际核销。 | |
|
|||||
unavailable_periods | UnavailablePeriodInfo [] | 选填 | - | 商品不可用日期区间。该内容仅用于展示,不影响实际核销。 | |
|
|||||
taobao_cover_image | String | 必填 | 100 | 商品首图(1:1)版本,作为商品在淘宝渠道露出的首图。支持bmp,png,jpeg,jpg,gif格式的图片。如果某个商品的本字段为空,则该商品无法再淘宝渠道露出 | VZ4Uu9i-SEC0w6k7GxzNcwAAACMAAQQD |
AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do","app_id","your private_key","json","GBK","alipay_public_key","RSA2"); KoubeiCateringItemQueryRequest request = new KoubeiCateringItemQueryRequest(); request.setBizContent("{" + "\"operator_type\":\"MERCHANT\"," + "\"request_id\":\"2016102903214476899999999\"," + "\"item_id\":\"2015090300006123123213213\"," + "\"auth_code\":\"6a8713a414da4a2dafdb7c24e597TX80\"" + " }"); KoubeiCateringItemQueryResponse response = alipayClient.execute(request); if(response.isSuccess()){ System.out.println("调用成功"); } else { System.out.println("调用失败"); }
{ "koubei_catering_item_query_response":{ "msg":"Success", "original_price":120.12, "taobao_cover_image":"VZ4Uu9i-SEC0w6k7GxzNcwAAACMAAQQD", "picture_details":[ "[0yaPA96AQPqJDIju28pvAgAAACMAAQEC", " VZ4Uu9i-SEC0w6k7GxzNcwAAACMAAQQD]" ], "code":"10000", "buyer_notes":[ { "details":[ "小标题下方的描述文案" ], "title":"小标题" } ], "subject":"鱼香肉丝杨梅汁套餐", "merchant_introduction":{ "image_urls":[ "0yaPA96AQPqJDIju28pvAgAAACMAAQEC", "0yaPA96AQPqJDIju28pvAgAAACMAAQEC" ], "title":"肯德基(蚂蚁金服店)店内环境。不得超过15个中文字符" }, "package_notes":[ "补充说明:套餐可以叠加使用" ], "memo":"备注:肯德基(蚂蚁金服店)首推新品", "inventory":1000, "cover":"VZ4Uu9i-SEC0w6k7GxzNcwAAACMAAQQD", "gmt_start":"2016-10-07 11:30:24", "category_id":"2017081400178386", "price":119.99, "unavailable_periods":[ { "end_day":"2017-05-03", "start_day":"2017-05-01" } ], "shop_ids":[ "[2015100300077000000001860010", " 2015100300077000000001860011]" ], "item_id":"2015090300006123123213213", "validity_period":300, "weight":"2", "sku_id":"2017071013300001", "item_status":"EFFECTIVE", "available_periods":[ { "time_start":"08:30", "available_week_days":"\"1,2\"", "time_end":"22:30" } ], "item_dishes":[ { "image_urls":[ "0yaPA96AQPqJDIju28pvAgAAACMAAQEC", "0yaPA96AQPqJDIju28pvAgAAACMAAQEC" ], "title":"鱼香肉丝", "desc":"鱼香肉丝盖浇饭" } ], "ticket_display_mode":"USER_PAY_CODE", "item_packages":[ { "item_units":[ { "amount":100, "unit":"份", "price":88.12, "title":"宫保鸡丁", "spec":"大份" } ], "title":"鱼香肉丝套餐" } ], "request_id":"2016102903214476899999999", "latest_notice":"本店周五休息不上班" }, "sign":"ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE" }
{ "koubei_catering_item_query_response":{ "msg":"Service Currently Unavailable", "code":"20000", "sub_msg":"系统繁忙", "sub_code":"isp.unknow-error" }, "sign":"ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE" }
错误码 | 错误描述 | 解决方案 |
---|---|---|
ITEM_OPERATION_ERROR | 商品操作异常 | 检查商品信息是否录入正确 |
SYSTEM_ERROR | 系统繁忙 | 联系口碑商品开放技术人员进行问题排查 |
ITEM_ILLEGAL_PARAMS | 商品操作参数异常 | 检查调用商品操作接口时入参 |
ITEM_FROBIDDEN_WORD | 商品操作包含违禁词 | 检查并修改违禁词 |
ITEM_SPECIAL_CHAR | 商品操作包含特殊字符 | 检查并修改商品操作中特殊字符 |
QUERY_NO_DATA | 查询无相关商品数据 | 检查查询入参是否正确 |
INVALID_PARAMETER | 参数有误 | 校验入参是否正常 |
SYSTEM_UPDATE | 系统升级中,请稍后再试 | 请稍后再试,或联系客服询问具体原因 |
AUTH_CODE_VALIDATE_FAIL | authcode检查失败 可能不存在或已失效 | 根据文案提示自查 是否为合法authcode 且 authcode授权是否已失效 |
ITEM_UNIQUE_VIOLATION | 唯一性约束报错,重复请求 | 当前request_id的请求已经被受理,如果是新请求,需更换request_id |
SYSTEM_ERROR | 系统繁忙 | 重试或联系技术人员协助 |
NO_PERMISSION | 无调用接口权限 | 请联系工作人员添加权限 |
BIZ_ERROR | 业务异常 | 根据错误描述排查问题 |
INVALID_PARAMETER | 参数有误biz_content的json格式错误 | 检查入参后重新请求 |