@hobby 2015-04-21T16:50:53.000000Z 字数 12645 阅读 1066

新版API

新版API

1. 核心数据结构

目前定义3种核心数据结构

Banner用于Banner、Tab、搜索分类的数据展现，后期可用于排序等需求的展现
Product用于商品信息的描述及展现
Brand用于品牌信息的描述及展现

1.1.1. 数据结构

Name	Type	Desc
id	int	内容id
sort	int	序号，从1开始
sys	String	内容来源哪个系统：XB-小编精选、CPC-CPC广告系统等
title	String	显示文字：如推荐、女装（搜索）、精选、衣服（品牌团）
subTitle	String	副标题文字, 20150324增加支持运营需求
description	String	描述
tag	String	标签，20141213增加
template	String	APP模板，表示调用哪个模板：SEARCH、BRAND、SPECIAL
query	String	请求内容，为native API请求或webview打开网页时使用
statUrl	String	用于向服务器发送统计请求，为空时忽略，不为空时在后台访问此url
imgUrl	String	banner图片链接
imgWidth	int	图片宽度
imgHeight	int	图片高度
isActive	int	是否选中：1-是、0-否

1.1.2. 返回示例

"todo"

1.2. Product

1.2.1. 数据结构

Name	Type	Desc
id	int	内容id
sort	int	序号，从1开始，可用于排行榜的排序
sys	String	内容来源哪个系统：XB-小编精选、CPC-CPC广告系统等
status	int	商品状态: 0-默认、1-新品，2-抢空, 3-新人 20150324加入`新人`枚举值支持运行需求
template	String	APP模板，表示调用哪个模板：SEARCH、BRAND、SPECIAL
query	String	请求内容，为native API请求或webview打开网页时使用
statUrl	String	用于向服务器发送统计请求，为空时忽略，不为空时在后台访问此url
taobaoId	String	淘宝商品id，如非淘宝商品则为空("")
chuchuId	String	商城商品id，如非商城品则为空("")
imgUrl	String	图片链接
imgWidth	int	图片宽度
imgHeight	int	图片高度
title	String	标题
saleCount	int	销售量
oldPrice	float	原价
newPrice	float	现价
discount	float	折扣
description	String	描述
shopUrl	String	商品店铺url（当商品是淘宝或者微店wap时使用）
tagList	Array of String	商品tag，没有：[]，有：["苹果","香蕉"]

注意 当template为CHUCHUITEM时，query参数中有trackId，请将此参数传送给商城Native API。

1.2.2. 返回示例

"todo"

1.3. Brand

1.3.1. 数据结构

Name	Type	Desc
id	int	内容id
sort	int	序号，从1开始
sys	String	内容来源哪个系统：XB-小编精选、CPC-CPC广告系统等
brandId	String	品牌id
status	int	品牌状态:默认为0、新品为1，抢空为2
title	String	标题
template	String	APP模板，表示调用哪个模板：SEARCH、BRAND、SPECIAL
query	String	请求内容，为native API请求或webview打开网页时使用
statUrl	String	用于向服务器发送统计请求，为空时忽略，不为空时在后台访问此url
endTime	int	品牌结束时间的时间戳
imgUrl	String	品牌图片url
imgWidth	int	图片宽度
imgHeight	int	图片高度
discount	float	折扣
description	String	描述
joinCount	int	参团人数
showType	int	品牌显示的样式（1：单列显示（这个时候下面的productList数组为空）；2：两列显示（下面的productList数组返回两个宝贝的相关数据）
productList	Array of Product	商品列表

1.3.2. 返回示例

"todo"

2. 核心业务接口

2.1. 9块9

涉及需求版本：V1.0.1
涉及需求：1.4 - 1.6

2.1.1. 请求参数

Query参数

Name	Type	Value	Desc
module	String	99	99模块
`function`	String	99、199、299	TAB内容，默认为99

function 客户端无需知道此参数的存在

POST参数

Name	Type	Value	Desc
page	int	可省略，默认为1	页数

2.1.2. 返回结构

Name	Type	Desc
pageHeading	Banner	页首的可配入口支持用于支持`安卓2.6.7版本需求`(201504002加入)
pagePopup	Banner	页首弹窗广告用于支持`安卓2.6.7版本需求`(201504002加入)
bannerList	Array of Banner	用于`需求1.4`中顶部Banner
eventList	Array of Banner	用于`需求1.5`中的“9块9买iPhone”等活动
tabList	Array of Banner	用于99、199、299的TAB
productList	Array of Product	用于`需求1.6`中的宝贝列表
info	Info	用于每日更新宝贝
page	int	当前页数-productList
hasNext	int	是否有下一页，0-没有、1-有

info的内部定义

Name	Type	Desc	Comment
todayProductInfo	String	今日更新的99+199+299宝贝总数	20150126沟通需求
todayModuleProductInfo	String	今日更新的指定分类的宝贝总数(根据request中的module)	20150126沟通需求

显示规则

function	page	pageHeading	pagePopup	bannerList	eventList	tabList	productList
99	1	有	有	有	有	有	有
99	>=2	无	无	无	无	无	有
199、299	1	无	无	无	无	有	有
199、299	>=2	无	无	无	无	无	有

2.2. 值得买

涉及需求版本：V1.0.1
涉及需求：2.3 - 2.6

2.2.1. 请求参数

Query参数

Name	Type	Value	Desc
module	String	zdm	值得买模块
`function`	String	根据服务器返回定	顶部tab，默认为newest（服务器定）
sortBy	String	tab=rank时提供，也可省略，price-价格、volume-销量	排行维度，省略则服务器选择维度

function 客户端无需知道此参数的存在
增加function值pickedbanners，用于显示小编精选Banner列表，对应模板：ZDMPICKEDBANNERS

POST参数

Name	Type	Value	Desc
page	int	可省略，默认为1	页数
sortBy	String	function=rank时提供，也可省略，price-价格、volume-销量	排行维度，省略则服务器选择维度

2.2.2. 返回结构

Name	Type	Desc
tabList	Array of Banner	用于`需求2.4`中顶部的“最新推荐”、“小编精选”、“排行榜”
productList	Array of Product	用于`需求2.5`中的小编精选内容（Banner、Product混排）
bannerList	Array of Banner	用于2014年12月12日紫聿新提的小编精选Banner列表
info	Info	用于每日更新宝贝
page	int	当前页数-productList
hasNext	int	是否有下一页，0-没有、1-有

info的内部定义

Name	Type	Desc	Comment
todayProductInfo	String	今日更新的值得买宝贝总数	20150126沟通需求
todayModuleProductInfo	String	今日更新的指定分类的宝贝总数(根据request中的module)	20150126沟通需求：目前只计数“最新推荐”中的“今日”宝贝，对于其他tag返回空串

2.3. 品牌团-品牌列表

涉及需求版本：V1.0.1
涉及需求：3.3 - 3.6

2.3.1. 请求参数

Query参数

Name	Type	Value	Desc
module	String	brand	品牌团模块
function	String	list	功能-列表
`category`	String	根据服务器返回定	品牌团分类，默认为picked（服务器定）

category 客户端无需知道此参数存在

POST参数

Name	Type	Value	Desc
page	int	可省略，默认为1	页数

2.3.2. 返回结构

Name	Type	Desc
categoryList	Array of Banner	用于`需求3.3、3.4`中顶部品牌团分类，如“精选”、“衣服”、“鞋子”
bannerList	Array of Banner	用于`需求3.5`中的顶部轮训Banner
brandList	Array of Brand	用于`需求3.6`中的品牌列表
page	int	当前页数-brandList
hasNext	int	是否有下一页，0-没有、1-有

info的内部定义

Name	Type	Desc	Comment
todayProductInfo	String	暂不使用	20150126沟通需求
todayModuleProductInfo	String	今日更新的指定分类的品牌总数(根据request中的module)	20150126沟通需求：目前只计数"精选"分类中的品牌，其他分类返回空串

2.4. 品牌团-品牌内页

涉及需求版本：V1.0.1
涉及需求：3.7

2.4.1. 请求参数

Query参数

Name	Type	Value	Desc
`module`	String	brand	品牌团模块
`function`	String	info	功能-内页
`brandId`	String	1234	品牌id

module function brandId 客户端无需知道此参数存在

POST参数

Name	Type	Value	Desc
page	int	可省略，默认为1	页数

2.4.2. 返回结构

Name	Type	Desc
brandInfo	Brand	品牌信息
bannerList	Array of Banner	用于`需求3.7`中的品牌内页Banner
productList	Array of Product	用于`需求3.7`中的品牌内页商品列表
relatedBrandList	Array of Banner	用于`需求3.7`中的品牌内页相似品牌
page	int	当前页数-productList
hasNext	int	是否有下一页，0-没有、1-有

//to confirm
当hasNext为0时，relatedBrandList有内容，否则relatedBrandList为空数组

2.5. 搜索-分类展示

涉及需求版本：V1.0.1
涉及需求：4.3 - 4.6

2.5.1. 请求参数

Query参数

Name	Type	Value	Desc
module	String	search	搜索模块
function	String	index	功能-首页
`category`	String	recommend	可省略，默认为recommend-推荐（服务器定）

category 客户端无需知道此参数存在

POST参数

Name	Type	Value	Desc
page	int	可省略，默认为1	页数

2.5.2. 返回结构

Name	Type	Desc
categoryList	Array of Banner	用于`需求4.3、4.5`中的一级分类
bannerList	Array of Banner	用于`需求4.6`中的分类List的顶部Banner
keywordList	Array of Banner	用于`需求4.6`中的关键词列表
page	int	当前页数-keywordList
hasNext	int	是否有下一页，0-没有、1-有

2.6. 搜索-关键词搜索|分类搜索

涉及需求版本：V1.0.1
涉及需求：5.3 - 5.4

2.6.1. 请求参数

Query参数

Name	Type	Value	Desc
module	String	search	搜索模块
function	String	keyword	功能-关键词搜索
`fq`	String	area@上海	用于分类搜索、条件筛选

fq APP端不需要知道此参数存在

POST参数

Name	Type	Value	Desc
page	int	可省略，默认为1	页数
q	String	连衣裙	搜索关键词
sort	string	price_asc、price_desc、addtime_desc、soldQuantity_desc、favcount_desc，默认为default	排序策略

2.6.2. 返回结构

Name	Type	Desc
productList	Array of Product	用于`需求5.5`中的搜索结果呈现
page	int	当前页数-productList
hasNext	int	是否有下一页，0-没有、1-有
template	String	APP模板，表示调用哪个模板：SEARCH、BRAND、SPECIAL
query	String	请求内容，为native API请求或webview打开网页时使用

2014-12-19 搜索结果新增template、query，用于在搜索后跳转至相应的模块(template)及调用相应的请求（query）

2.7. 搜索-热词推荐

涉及需求版本：V1.0.1
涉及需求：5.3

2.7.1. 请求参数

Query参数

Name	Type	Value	Desc
module	String	search	搜索模块
function	String	hotkeywords	功能-热词推荐

2.7.2. 返回结构

Name	Type	Desc
keywordList	Array of String	用于`需求5.3`中的热词结果

2.8. 搜索-搜索词建议

涉及需求版本：V1.0.1
涉及需求：5.3

2.8.1. 请求参数

Query参数

Name	Type	Value	Desc
module	String	search	搜索模块
function	String	suggestkeywords	功能-搜索词建议

POST参数

Name	Type	Value	Desc
q	String	皮鞋	词干

2.8.2. 返回结构

Name	Type	Desc
keywordList	Array of String	用于`需求5.3`中的自动词干搜索

2.9. 专题模块

涉及需求版本：V1.0.3
涉及需求：11.1

2.9.1. 请求参数

Query参数

Name	Type	Value	Desc
`module`	String	special	专题模块
`specialId`	int	123456	专题id

module specialId 客户端无需知道此参数存在

2.9.2. 返回结构

Name	Type	Desc
specialInfo	Banner	专题标题、描述、顶部Banner等信息
productList	Array of productList	需求`11.4`图文列表、单列、两列商品及专题

2.10. 搜索-新版分类展示

2015-01-29 支持需求 新版分类 TAB 需求 v1.2, 此接口在 2.6 搜索-关键词搜索|分类搜索基础上扩展形成.

涉及需求版本：V1.0.1?? TODO: 更新版本
涉及需求：4?? TODO: 更新

以下页面复用此业务接口, 通过Query细节参数(category, secCategory)进行区分
- 分类 TAB 首页
- 分类 TAB 详情页
- 关键词 List 页

2.10.1. 请求参数

Query参数

Name	Type	Value	Desc
module	String	search	搜索模块
function	String	new	功能-新版分类TAB
`category`	String	-	指定显示首页或详情页. 空值-显示首页, 其他值-显示对应的详情页
~~`secCategory`~~	String	-	~~处理`关键词 List 页`的请求参数~~
shopCids	String	-	微店分类列表, 作为查询宝贝列表的key值

参数构造细节说明 (客户端无须关注此细节, 服务端 Query 传回约定)

20150130更新: 不使用 secCategory, 而是 shopCids 构成 query 参数

Page	category	shopCids
分类 TAB 首页	空	空
分类 TAB 详情页	有效	有效
关键词 List 页	空	有效

POST参数

Name	Type	Value	Desc	附注
page	int	展示商品的页数	页数

2.10.2. 返回结构

Name	Type	Desc
categoryList	Array of Banner	用于`需求4.3、4.5`中的一级分类
bannerList	Array of Banner	用于`需求4.6`中的分类List的顶部Banner
keywordList	Array of Banner	用于`需求4.6`中的关键词列表
productList	Array of Product	用于`需求x.x (TODO)`分类TAB中的商品列表
page	int	当前页数-productList
hasNext	int	是否有下一页，0-没有、1-有
title	String	分类 List 页, 页首显示文案

3. 其他业务接口

3.1. 微店、淘宝收藏夹-收藏、取消收藏

涉及需求版本：V1.0.1
涉及需求：6.4

3.1.1. 请求参数

Query参数

Name	Type	Value	Desc
module	String	favorite	收藏夹模块
function	String	add/remove	功能：add-收藏、remove-取消收藏

POST参数

Name	Type	Value	Desc
type	string	taobao、chuchu	淘宝、商城收藏夹
taobaoIdList	Array of String	默认为空，["123456","234567"]	淘宝taobaoId数组，type=taobao有效
chuchuIdList	Array of String	默认为空，["123456","234567"]	商城chuchuId数组，type=chuchu有效

3.1.2. 返回结构

无，通过统一的code判断是否成功|失败

3.2. 淘宝收藏夹-上传老版本收藏信息 `兼容性`

涉及需求版本：无
涉及需求：老用户数据迁移

3.2.1. 请求参数

Name	Type	Value	Desc
module	String	favorite	收藏夹模块
function	String	syncOldData	功能：同步旧数据
oldDataList	Array of String	["99-24123","199-3267"]	旧版本本地收藏数据，格式为“模块-id”

3.2.2. 返回结构

无，通过统一的code判断是否成功|失败

3.3. 淘宝、微店收藏夹-列表

涉及需求版本：V1.0.1
涉及需求：6.4

3.3.1. 请求参数

Name	Type	Value	Desc
module	String	favorite	收藏夹模块
function	String	list	功能：获得列表

POST参数

Name	Type	Value	Desc
type	string	taobao、chuchu	淘宝、商城收藏夹
page	int	可省略，默认为1	页数

3.3.2. 返回结构

Name	Type	Desc
productList	Array of Product	用于收藏夹结果呈现
page	int	当前页数-productList
hasNext	int	是否有下一页，0-没有、1-有

3.4. 应用推荐

涉及需求版本：V1.0.1
涉及需求：6.5

3.4.1. 请求参数

Name	Type	Value	Desc
module	String	applist	应用推荐模块

POST参数

Name	Type	Value	Desc
page	int	可省略，默认为1	页数

3.4.2. 返回结构

Name	Type	Desc
appList	Array of App	推荐APP集合
page	int	当前页数-productList
hasNext	int	是否有下一页，0-没有、1-有

App数据结构：

Name	Type	Desc
id	int	内容id
sort	int	序号，从1开始
sys	String	内容来源哪个系统：XB-小编精选、CPC-CPC广告系统等
packageName	String	APP的包名
title	String	APP的名称
description	String	APP的相关描述
downloadCount	String	APP的下载数量
bytes	String	APP的大小,以M为单位
imgUrl	String	APP对应图片的地址
imgWidth	int	APP对应图片的宽
imgHeight	int	APP对应图片的高
downloadUrl	String	APP的下载地址

4. 请求方法

4.1. 请求参数

Name	Type	Value	Desc	Note
client	JSON of Client	{"gender":"0"...}	客户端信息
query	JSON of Request	{"module":""}	模块请求信息
strategy	String	123df9mcfdaf	展示策略信息,来自settings里的strategyId	20150326加入,控制展现策略

4.1.1. 请求示例

Client原始数据：

Client
(
    [platform] => android
    [package] => com.culiu.purchase
    [version] => 2.6.0
    [gender] => 0
    [channel] => QD_yyb
    [imei] => 7894636568
    [xinggeToken] => 7c9795d77dc543d27e74d329e3b4b5dc
    [deviceToken] =>
    [userId] => 12345
    [sessionId] => 47454e81fb1a91574960531fdfd5dfba,
    [deviceId] => ff454e81fb1bcdef4960531fdfd5d121
)

Query原始数据（以品牌团列表为例）：

Request
(
    [module] => brand
    [function] => list
)

分别进行JSON编码，得到2个字符串：

{"platform":"android","package":"com.culiu.purchase","version":"2.6.0","gender":"0","channel":"QD_yyb","imei":"7894636568","xinggeToken":"7c9795d77dc543d27e74d329e3b4b5dc","deviceToken":"","userId":"12345","sessionId":"47454e81fb1a91574960531fdfd5dfba"}

{"module":"brand","function":"list"}

对其进行HTTP POST请求拼接，拼接公式：

"client="+urlencode(Client)+"&query="+urlencode(Query)

拼接后的结果(451 Bytes)：

client=%7B%22platform%22%3A%22android%22%2C%22package%22%3A%22com.culiu.purchase%22%2C%22version%22%3A%222.6.0%22%2C%22gender%22%3A%220%22%2C%22channel%22%3A%22QD_yyb%22%2C%22imei%22%3A%227894636568%22%2C%22xinggeToken%22%3A%227c9795d77dc543d27e74d329e3b4b5dc%22%2C%22deviceToken%22%3A%22%22%2C%22userId%22%3A%2212345%22%2C%22sessionId%22%3A%2247454e81fb1a91574960531fdfd5dfba%22%7D&query=%7B%22module%22%3A%22brand%22%2C%22function%22%3A%22list%22%7D

发送给服务器端：

Connection: keep-alive
Content-Length: 451
Cache-Control: max-age=0
Accept: application/json
User-Agent: Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko)
Content-Type: application/x-www-form-urlencoded
Accept-Encoding: gzip,deflate
Accept-Language: zh-CN,zh;q=0.8,en;q=0.6,zh-TW;q=0.4
client=%7B%22platform%22%3A%22android%22%2C%22package%22%3A%22com.culiu.purchase%22%2C%22version%22%3A%222.6.0%22%2C%22gender%22%3A%220%22%2C%22channel%22%3A%22QD_yyb%22%2C%22imei%22%3A%227894636568%22%2C%22xinggeToken%22%3A%227c9795d77dc543d27e74d329e3b4b5dc%22%2C%22deviceToken%22%3A%22%22%2C%22userId%22%3A%2212345%22%2C%22sessionId%22%3A%2247454e81fb1a91574960531fdfd5dfba%22%7D&query=%7B%22module%22%3A%22brand%22%2C%22function%22%3A%22list%22%7D

4.2. 返回结果

服务器正确情况下的返回（JSON）：

{
    "code":0,
    "msg":"",
    "time":1416514446,
    "data":{
        "categoryList":{
            //Banner的JSON结构
        },
        "bannerList":{
            //Banner的JSON结构
        },
        "brandList":{
            //Brand的JSON结构
        },
        "page":1,
        "hasNext":0
    },
    "userId":"1234567",
    "sessionId":"20c8c43a2dc688d5cc79f199eecd84d5",
    "deviceId":"ffc8c43a2dc688d5cc79f199eecd84ff"
}

服务器错误情况下的返回(JSON)：

{
    "code":400,
    "msg":"讨厌，您的访问太频繁了啦",
    "time":1416514446,
    "userId":"1234567",
    "sessionId":"20c8c43a2dc688d5cc79f199eecd84d5",
    "deviceId":"ffc8c43a2dc688d5cc79f199eecd84ff"
}

4.3. 关于分页

分页参数page支持在query与POST中设置
如：
POST数据：client=...&query={page:3}&page=2
服务器会优先取POST的page，取不到则取query的page，取不到则为默认（一般为1）

因此实现分页时，只需要client=...&query=...&page={PAGE}，设置{PAGE}的值即可

5. 模块调用

Banner、Product、Brand类中都有一组定义：

Name	Type	Desc
template	String	APP模板，表示调用哪个模板：SEARCH、BRAND、SPECIAL
query	String	请求内容，为native API请求或webview打开网页时使用
statUrl	String	用于向服务器发送统计请求，为空时忽略，不为空时在后台访问此url

表示在点击（或Tab滑动到位置）事件产生后，应用所需要作出的响应：

5.1. 微店Native

调用微店Native模块，query为JSON并会在其中传递productId和shopId。

5.2. WebView

调用WebView模块，打开query为JSON并会在其中传递url、title。

5.3. 其他Native接口 `调用做活`

调用template中定义的模板，并将query作为请求时的query参数使用
举例：
某首页Banner的type=2 template=ZDMPICKED query={"module":"zdm","function":"picked"}
则客户端将会唤起ZDMPICKED模板（模块），并请求{"module":"zdm","function":"picked"}，最后页面呈现：
值得买模块-小编精选被选中-小编精选内容出现
可通过相应的缓存策略在第二次访问时不进行网络请求而直接进入模块及展示缓存中的内容

5.3.1. 应用场景

只需要实现分类页排版、结果页排版，即可实现分类页->搜索结果的功能，无需拼参数（服务器在结果中帮你拼好了）
模块内、模块间任意调用成为可能

6. 模块整理

6.1. 服务器模块整理

module	模块名称	功能
99	9块9	你懂的
zdm	值得买	值得买
special	专题	专题模块
brand	品牌团	品牌团
search	搜索	分类、搜索
favorite	收藏	收藏夹
applist	应用推荐	应用推荐
settings	设置	客户端设置、开关

新版API

1. 核心数据结构

目前定义3种核心数据结构

1.1. Banner

1.1.1. 数据结构

1.1.2. 返回示例

1.2. Product

1.2.1. 数据结构

1.2.2. 返回示例

1.3. Brand

1.3.1. 数据结构

1.3.2. 返回示例

2. 核心业务接口

2.1. 9块9

2.1.1. 请求参数

Query参数

POST参数

2.1.2. 返回结构

info的内部定义

显示规则

2.2. 值得买

2.2.1. 请求参数

2.2.2. 返回结构

2.3. 品牌团-品牌列表

2.3.1. 请求参数

2.3.2. 返回结构

2.4. 品牌团-品牌内页

2.4.1. 请求参数

2.4.2. 返回结构

2.5. 搜索-分类展示

2.5.1. 请求参数

2.5.2. 返回结构

2.6. 搜索-关键词搜索|分类搜索

2.6.1. 请求参数

2.6.2. 返回结构

2.7. 搜索-热词推荐

2.7.1. 请求参数

2.7.2. 返回结构

2.8. 搜索-搜索词建议

2.8.1. 请求参数

2.8.2. 返回结构

2.9. 专题模块

2.9.1. 请求参数

2.9.2. 返回结构

2.10. 搜索-新版分类展示

2.10.1. 请求参数

2.10.2. 返回结构

3. 其他业务接口

3.1. 微店、淘宝收藏夹-收藏、取消收藏

3.1.1. 请求参数

3.1.2. 返回结构

3.2. 淘宝收藏夹-上传老版本收藏信息 兼容性

3.2.1. 请求参数

3.2.2. 返回结构

3.3. 淘宝、微店收藏夹-列表

3.3.1. 请求参数

3.3.2. 返回结构

3.4. 应用推荐

3.4.1. 请求参数

3.4.2. 返回结构

4. 请求方法

4.1. 请求参数

4.1.1. 请求示例

4.2. 返回结果

4.3. 关于分页

5. 模块调用

5.1. 微店Native

5.2. WebView

5.3. 其他Native接口 调用做活

5.3.1. 应用场景

6. 模块整理

6.1. 服务器模块整理

内容目录

选择主题

3.2. 淘宝收藏夹-上传老版本收藏信息 `兼容性`

5.3. 其他Native接口 `调用做活`