@hobby 2015-04-03T03:25:33.000000Z 字数 26229 阅读 1691

楚楚街APP新版API

楚楚街 新版 APP Android iOS

楚楚街APP新版API

本文档固定链接地址(作业部落) https://www.zybuluo.com/hobby/note/83525
之前的链接废弃不用(自2015年04月02日开始): ~~https://www.zybuluo.com/luyue/note/47883~~

日期	时间	修改内容	修改人
2014-11-21	17:09	增加`3.5.2.Statis数据`；增加`6.模块整理`；增加`2.8.搜索词建议`	璐玥
2014-11-22	11:28	修改3.1.1.``3.2.1.``3.3.1.``6.1.中将英式的`favourite`改为美式的`favorite`	璐玥
2014-11-22	12:10	`Banner`类型增加`description`描述属性	璐玥
2014-11-22	12:38	服务器端、APP端增加`专题模块`	璐玥
2014-11-22	14:33	客户端模块`module`命名修改为模板`template`，并全部大写；请求服务器参数`data`修改为`query`	璐玥
2014-11-22	16:20	增加`MixedCell`类型；所有数据类型中增加内容来源`sys`字段	璐玥
2014-11-22	16:20	在POST参数中支持分页参数`page`，且优先级大于`query`中的`page`，便于客户端拼接	璐玥
2014-11-22	16:48	在值得买返回中增加cellList值，用于需求中Banner、Product混排的情况	璐玥
2014-11-23	16:40	在`Banner`、`Brand`类型中增加`chuchuId`	璐玥
2014-11-24	01:56	修改`品牌团内页`调用参数`function`值为`info`（原为`product`）	璐玥
2014-11-24	02:56	删除`值得买`返回值`productList`、`eventList`，统一使用混排`cellList`	璐玥
2014-11-24	02:56	移除`MixedCell`类型，`值得买`、`专题`返回值`cellList`改为`productList`	璐玥
2014-11-25	18:53	从`配置信息`中移除`userId`和`sessionId`，将它们放到每次请求的返回中	璐玥
2014-11-25	22:41	删除`2.9.2`中图文专题`articleList`，改为`productList`返回	璐玥
2014-11-26	15:40	删除`type`、`url`，增加`stat_url`用于发送统计请求	璐玥
2014-11-26	15:47	`2.6.1`、`2.8.1`中的关键词参数放到POST中，并统一命名为`q`	璐玥
2014-11-26	15:55	删除`Banner`、`Brand`类型中的`chuchuId`	璐玥
2014-11-27	14:25	增加推送数据结构	璐玥
2014-11-27	15:21	CcjJSBridge定义	璐玥
2014-11-27	21:29	删除`query`中的分页参数`page`；为品牌详情页增加`brand`字段；为`applist`增加`packageName`字段	璐玥
2014-11-30	18:52	增加友盟统计模块开关；增加Setting模块的版本控制	璐玥
2014-12-01	23:29	在99模块中增加tabList：99、199、299	璐玥
2014-12-03	14:27	修改部分（99、值得买）`query`中的`tab`参数，改名为`function`	璐玥
2014-12-04	16:07	增加请求中的参数shopToken，补充关于deviceId、sessionId的说明	璐玥
2014-12-04	21:07	`stat_url`改为`statUrl`	璐玥
2014-12-13	15:25	`banner`类型增加`tag`属性；增加模板ZDMPICKEDBANNERS	璐玥
2014-12-17	05:48	`settings`增加`showCoupon`是否显示优惠券	璐玥
2014-12-19	22:08	`settings`增加搜索模式及相关配置	璐玥
2014-12-23	15:57	`settings`增加匿名购买开关	璐玥
2015-01-03	15:53	`settings`增加匿名支付开关	璐玥
2015-01-07	20:13	增加模板SHOPLOGIN及相关的CcjJSBridge接口定义	璐玥
2014-01-13	18:13	在99模块page=1中增加info	严伟森
2014-01-20	23:45	在settings中增加ipList，用于DNS错误情况下的请求发送	璐玥
2014-01-24	15:13	在99、199、299、值得买模块page=1中增加info，info中增加本模块更新todayModuleProductCount	璐玥
2015-01-26	14:50	新功能今日更新数量提醒（需求编号51）: 99提醒(99, 199, 299)，值得买今日，品牌团. 内容：info中增加todayProductInfo和todayModuleProductInfo	尹志伟
2015-01-26	14:55	试衣模板，更新6.2章节	尹志伟
2015-01-26	15:05	接口调整：info当中的int型技术丢弃不用(2.1.2, 2.2.2, 2.3.2)	尹志伟
2015-01-27	21:37	`setting`增加`optimizePicture`属性，控制是否进行图片优化	尹志伟
2015-01-29	15:10	新功能: 新版分类 TAB 需求 v1.2, 新增`搜索-新版分类展示`, 增加业务接口`搜索-新版分类展示`	尹志伟
2015-01-30	19:30	新功能: 新版分类 TAB 需求, query 接口参数微调, 去掉 `secCategory`, 加入 `shopCids`	尹志伟
2015-02-02	12:30	增加发送错误报告相关settings：uploadErrorLog、uploadErrorLogUrl	璐玥
2015-03-02	11:40	client中包含年龄组字段`AgeGroup`,以支持对不同年龄用户的细分处理	尹志伟
2015-03-02	14:25	年龄组`AgeGroup`枚举值ALL描述更新,年龄组变量规范命名`ageGroup`	尹志伟
2015-03-02	21:50	应客户端要求, settings加入新参数`majorVersionUpdate`	尹志伟
2015-03-03	15:45	`majorVersionUpdate`移动到合适的章节	尹志伟
2015-03-19	21:45	应客户端要求, settings加入新参数`customerSupportType`和`showEventNotice`	尹志伟
2015-03-24	14:45	banner结构更新,加入`sub_title`. product结构更新, `status`扩展枚举值	尹志伟
2015-03-24	15:10	banner结构更新,字段规范命名从`sub_title`到`subTitle`	尹志伟
2015-03-26	17:00	控制展现策略:settings加入新参数`strategyId`和`strategyExpire`(3.5.2), 请求方法添加post参数`strategy`(4.2)	尹志伟
2015-04-02	18:00	客户端需求支持: 9块9支持可配置的页首`pageHeading`(2.1.2)	尹志伟
2015-04-02	18:00	客户端需求支持: 9块9支持弹窗广告`pagePopup`(2.1.2)	孙俊

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的下载地址

3.5. 配置信息

3.5.1. 请求参数

Query参数:

Name	Type	Value	Desc
module	String	settings	配置信息模块

POST参数：

Name	Type	Value	Desc
version	int	112	当前配置版本号

3.5.2. 返回结构

Name	Type	Desc
settings	Settings	配置信息

Settings数据结构：

Name	Type	Desc	附注
version	int	配置版本号
jsCode	String	WebView运行的全局js
jsDomain	Array of String	WebView需要运行js的url数组，如：["http://www.qq.com/","https://www.alipay.com/"]
showLogin	int	显示登录区域 0不显示 1显示
showChuchuOrder	int	显示查看楚楚直营订单 0不显示 1显示
showChuchuShopCart	int	显示查看楚楚直营购物车 0不显示 1显示
showAddress	int	显示登录区域内页本地地址 0不显示 1显示
showAppList	int	显示应用墙 0不显示 1显示
showApp	int	显示猜你喜欢应用列表 0不显示 1显示
showCoupon	int	显示优惠券 0不显示 1显示
allowAnonymousBuy	int	允许匿名购买 0-不允许 1-允许
taobaoOrderUrl	String	淘宝订单url，默认为空或者不返回
taobaoShopCartUrl	String	淘宝购物车url，默认为空或者不返回
taobaoFavUrl	String	淘宝收藏夹url，默认为空或者不返回
searchMode	int	顶栏搜索模式 0-Native 1-WebView
searchUrl	int	当searchMode=0时，调用搜索的地址，如：http://s.taobao.com/search?q=，请将关键词`urlencode`后拼接到searchUrl后面
statis	Statis	统计Config
ipList	Array of String	API的IP列表，用于DNS解析异常情况下的重试，默认为54.223.166.150（请客户端在代码中配置）
optimizePicture	int	客户端图片分辨率优化开关，0-不优化，1-优化。更新在配置版本17 (`version`=17)
uploadErrorLog	int	发送错误日志，0-不发送，1-发送
uploadErrorLogUrl	String	发送错误报告提交到的URL
majorVersionUpdate	int	主要版本更新标志根据client->version, 决定是否通知客户端提醒用户更新APP版本 0-无须更新主要版本; 1-需要更新主要版本	20150303添加
customerSupportType	int	客户服务入口类型 0 - 融云 (默认值) 1 - QQ 其他值未定	20150319添加, 版本28
showEventNotice	int	活动通知的开关, 加入支持活动:挖矿寻宝 0 - 不展现通知 1 - 展现通知(默认值)	20150319添加, 版本28
strategyId	String	展现策略控制, 服务端用其检索具体的展现策略	20150326加入,控制展现策略
strategyExpire	int	展现策略的到期时间(时间戳类型,精确到秒)	20150326加入,控制展现策略

Statis数据结构：

Name	Type	Desc
nativeLog	int	Native采样开关，0-关、1-开
umengStat	int	友盟统计开关，0-关、1-开
upload	int	上报开关，0-关、1-开
url	String	上报地址url
mobileTimeInterval	int	移动模式上传时长间隔，单位秒，默认10*60秒
wifiTimeInterval	int	Wifi模式上传时长间隔，单位秒，默认5*10秒
effectiveTime	int	有效时间，单位秒，默认8*3600秒
packageLength	int	每次上传条数，默认50条

Info数据结构：

Name	Type	Desc
todayProductCount	int	每日更新宝贝数提示
todayModuleProductCount	int	本模块每日更新宝贝数提示

4. 请求方法

4.1. API地址

正式地址：
POST http://api.chuchujie.com/api/?v=1.0

测试地址：
POST http://api-dev.chuchujie.com/api/?v=1.0

4.2. 请求参数

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

Client数据结构：

Name	Type	Value	Desc	Note
platform	String	android、iphone	平台标识
packageName	String	com.culiu.purchase	包名
version	String	2.6.0	APP版本号
gender	String	0-女、1-男	用户性别
channel	String	QD_yyb	渠道号，安卓使用
imei	String	45623423685	手机识别IMEI、iOS使用UUID
xingeToken	String	12345678	信鸽token，安卓使用
deviceToken	String	12345678	iOS推送token
shopToken	String	abcdef123456	微店Token，没有留空
userId	String	abcdef123456	微店用户id
sessionId	String	abcdef123456	会话id
deviceId	String	abcdef123456	设备id
ageGroup	String	'AG_0to24': 25岁以下, 'AG_25to35': 25-35岁, 'AG_35toMax': 35岁以上 'ALL': 不区分(服务端默认)	年龄组	20150302添加, 支持细化的年龄

Request数据结构：见各模块调用请求参数

deviceId、SessionId、userId说明：

1、服务器通过shopToken来确定userId，若无对应userId，则返回中userId=0；若客户端提供的userId与shopToken不对应，服务器会返回正确的userId，请客户端保存。
2、服务器通过以下顺序读取device信息：deviceId、md5(xinggeToken)、md5(deviceToken)、md5(imei)、md5(随机字符串)；读到device信息则认为该deviceId合法，否则会按照以上顺序（除客户端提供的deviceId外）设置新的deviceId；请客户端保存deviceId，原则上同一台设备的deviceId不会改变。

关于deviceId的引申
如果客户端有正确的xinggeToken、deviceToken、imei，则总是可以得到一个唯一的deviceId，且与服务器无关。
在没有deviceId的情况下，如果客户端以上3个参数均为空，服务器会返回一串随机的字符串作为deviceId，请客户端永久性保存。
如果客户单向服务器提供的deviceId服务器没有找到，服务器会为客户端生成新的deviceId，顺序是：md5(xinggeToken)、md5(deviceToken)、md5(imei)、md5(随机字符串)。

3、sessionId表示当前会话的id；每个session有过期时间，取决于当前行为和上一次行为之间的间隔，超过这个间隔则服务器端session被销毁，并为新的请求生成新的sessionId并发给客户端。
4、客户端仅需要将保存的sessionId发送给服务器，并在服务器返回新的deviceId、sessionId时保存。

4.2.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
)

todoStrategy原始数据

分别进行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

发送给服务器端：

POST http://api.chuchujie.com/api/?v=1.0 HTTP/1.1
Host: api.chuchujie.com
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.3. 返回结果

服务器正确情况下的返回（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"
}

2014-11-25更新 其中userId与sessionId为服务器返回的当前用户的账号id（楚楚街商城）及会话Id。
如userId为空则说明当前用户为匿名用户；
如sessionId与客户端发送的不同，则表示服务器需要客户端更新sessionId。

2014-11-28更新 增加deviceId，该值由服务器根据客户端的imei等信息（client中的信息）来确定，并返回给客户端。客户端需尽可能长得保存此信息，并在每次请求的时候发送此信息给服务器。
deviceId仅在第一次设置 如服务器返回了一个新的deviceId给客户端，与客户端所保存的deviceId冲突，则客户端仍然使用本地的deviceId，不理会服务器的新deviceId。

4.4. 关于分页

分页参数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	设置	客户端设置、开关

6.2. APP模板整理

template	模板名称	附注
JKJ	9块9
ZDMNEWEST	值得买最新推荐
ZDMPICKEDLIST1	值得买小编推荐-1列
ZDMPICKEDLIST2	值得买小编推荐-2列
ZDMPICKEDBANNERS	值得买小编推荐-Banner列表
ZDMRANK	值得买排行榜
BRAND	品牌团列表页
BRANDINFO	品牌团详情页
CATEGORY	分类页
SEARCH	搜索结果页
SPECIALARTICLE	专题模块-图文列表
SPECIALLIST1	专题模块-商品List1版
SPECIALLIST2	专题模块-商品List2版
CHUCHUITEM	楚楚街Native宝贝详情
WEB	网页
PERSONAL	个人中心
MYORDER	我的订单
MYCART	我的购物车
MYFAVORITE	我的收藏
APPLIST	推荐应用内页
CHECKUPDATE	检查更新
SHOPLOGIN	微店Native登陆页
DRESSING	试衣功能	20150126加入

7. 调用地址

99：
http://api-dev.chuchujie.com/api/?query={%22module%22:%2299%22}
//有bannerList、eventList、productList

http://api-dev.chuchujie.com/api/?query={%22module%22:%2299%22}&page=2
//无bannerList、eventList，有productList

http://api-dev.chuchujie.com/api/?query={%22module%22:%2299%22}&page=3
//有productList，9个宝贝、hasNext=false

值得买-最新推荐：
http://api-dev.chuchujie.com/api/?query={%22module%22:%22zdm%22,%22function%22:%22newest%22}
//有tabList、productList、hasNext=true

http://api-dev.chuchujie.com/api/?query={%22module%22:%22zdm%22,%22function%22:%22newest%22}&page=2
//无tabList、有productList、hasNext=true

http://api-dev.chuchujie.com/api/?query={%22module%22:%22zdm%22,%22function%22:%22newest%22}&page=3
//无tabList、有productList、hasNext=false

值得买-小编精选：//请别在意query参数
http://api-dev.chuchujie.com/api/?query={%22module%22:%22zdm%22,%22function%22:%22picked%22}

值得买-排行榜：//请别在意query参数
http://api-dev.chuchujie.com/api/?query={%22module%22:%22zdm%22,%22function%22:%22rank%22}

品牌团-列表：
http://api-dev.chuchujie.com/api/?query={%22module%22:%22brand%22,%22function%22:%22list%22}
//有categoryList、bannerList、brandList

http://api-dev.chuchujie.com/api/?query={%22module%22:%22brand%22,%22function%22:%22list%22}&page=2
//无categoryList、bannerList、有brandList

品牌团-内页
http://api-dev.chuchujie.com/api/?query={%22module%22:%22brand%22,%22function%22:%22info%22}
//有bannerList、productList、无relatedBrandList

http://api-dev.chuchujie.com/api/?query={%22module%22:%22brand%22,%22function%22:%22info%22}&page=3
//无bannerList、有productList、relatedBrandList

分类-首页
http://api-dev.chuchujie.com/api/?query={%22module%22:%22search%22,%22function%22:%22index%22}
//有categoryList、bannerList、keywordList

搜索-关键词
http://api-dev.chuchujie.com/api/?query={%22module%22:%22search%22,%22function%22:%22keyword%22}

搜索-热词推荐：
http://api-dev.chuchujie.com/api/?query={%22module%22:%22search%22,%22function%22:%22hotkeywords%22}

搜索-搜索词建议
http://api-dev.chuchujie.com/api/?query={%22module%22:%22search%22,%22function%22:%22suggestkeywords%22}
http://api-dev.chuchujie.com/api/?query={%22module%22:%22search%22,%22function%22:%22suggestkeywords%22,%22q%22:%22%E7%94%A8%E6%88%B7%E5%A1%AB%E5%86%99%E7%9A%84%E8%AF%8D%E5%B9%B2%22}

专题-图文：
http://api-dev.chuchujie.com/api/?query={%22module%22:%22special%22,%22specialId%22:1}
//有specialInfo、productList

专题-列表：
http://api-dev.chuchujie.com/api/?query={%22module%22:%22special%22,%22specialId%22:2}
//有specialInfo、productList

收藏夹-添加、删除
http://api-dev.chuchujie.com/api/?query={%22module%22:%22favorite%22,%22function%22:%22add%22}
http://api-dev.chuchujie.com/api/?query={%22module%22:%22favorite%22,%22function%22:%22remove%22}

收藏夹-同步老数据
http://api-dev.chuchujie.com/api/?query={%22module%22:%22favorite%22,%22function%22:%22syncOldData%22}

收藏家-列表
http://api-dev.chuchujie.com/api/?query={%22module%22:%22favorite%22,%22function%22:%22list%22}

应用列表
http://api-dev.chuchujie.com/api/?query={%22module%22:%22applist%22}

配置：
http://api-dev.chuchujie.com/api/?query={%22module%22:%22settings%22}

8. 推送

8.1. 推送数据结构

Name	Type	Desc
ticker	String	通知栏消息
title	String	通知栏标题
text	String	通知栏文本信息
silent	int	是否是静默推送：1-静默推送，0-非静默推送
template	String	需要推送到的模板
query	String	需要推送到的模板的请求信息
backTemplate	String	返回时调用的模板
backQuery	String	返回时调用模板的请求信息
adType	int	广告类型：0-首屏广告，1-内页广告
adImgUrl	String	图片链接：目前仅推送闪屏广告和内页广告需要
startTime	int	推送开始时间，为unix时间戳
endTime	int	推送结束时间，为unix时间戳，通过startTime和endTime来判断推送的有效性

格式实例：

{"ticker":"通知栏消息","title":"标题","text":"文本信息","silent":0,"template":"JKJ","query":"{\"module\":\"99\"}","backTemplate":"JKJ","backQuery":"{\"module\":\"99\"}","adType":0,"adImgUrl":"","startTime":1417017600,"endTime":1417104000}

9. JS Bridge

JSBridge使得网页与App通过JS的方式互相通信。
JSBridge命名：CcjJSBridge

9.1. Web端

例子：
Web端通过

document.addEventListener('CcjJSBridgeReady', callback_function, false);

来定义当CCjJSBridgeReady事件发生后，callback_function被执行：

function callback_function(){
    CcjJSBridge.call('clearCookies');
}

APP端：
实现CcjJSBridge.call中的方法，实现原则：
假设分享到微信
APP端实现方法：

CcjJSBridgeInstance.shareToWeixin(title, imgUrl, url, desc);

其中title、imgUrl、url、desc顺序与文档中的顺序一致

在完成调用后，APP端通过调用

callback_shareToWeixin(res)

来完成回调

客户端可调用的方法：

9.1.1. 分享到微信

Web调用：

CcjJSBridge.call(
    'shareToWeixin',
    data,
    function(res){} // 回调函数，在动作完成后调用
);

data结构：

Name	Type	Desc
title	string	分享标题
imgUrl	string	分享图片
url	string	分享网址
desc	string	分享描述

返回res内容：

Name	Type	Desc
code	int	0-成功、401-分享失败，301-取消分享、444-不存在此方法

9.1.2. 统计

CcjJSBridge.call(
    'webLog',
    uri,
    function(res){}
);

uri为统计事件，格式为：purchase://item/old/taobao/12345678/pay, 具体参考《9块9包邮购用户行为统计》文档定义：

收藏按钮： purchase://item/old///fav
立即购买按钮: purchase://item/old/// buy
加入购物车按钮：purchase://item/old///cart
店铺按钮： purchase://item/old///shop

值：taobao、tmall、chuchujie

返回res内容：

Name	Type	Desc
code	int	0-成功、402-处理失败

9.1.3. 后台打开WebView

CcjJSBridge.call(
    'backgroundOpenUrl',
    url,
    function(res){}
);

url为要打开的网址

返回res内容：

Name	Type	Desc
code	int	0-成功、403-后台打开WebView失败、444-不存在此方法

9.1.4. 清除Cookies

CcjJSBridge.call(
    'clearCookies',
    function(res){}
);

返回res内容：

Name	Type	Desc
code	int	0-成功、404-清除Cookies失败、444-不存在此方法

9.1.5. 设置Cookie值

CcjJSBridge.call(
    'setCookie',
    data,
    function(res){}
);

data结构：

Name	Type	Desc
key	string	Cookie key
value	string	Cookie value
expire	string	Cookie过期的时间戳, GMT格式
domain	string	Cookie domain，默认为当前网站域名
path	string	Cookie path, 默认为/

返回res内容：

Name	Type	Desc
code	int	0-成功、405-设置Cookie值失败、444-不存在此方法

9.1.5.1. 调用示例

CcjJSBridge.call(
    'setCookie',
    {
        "key":"a",
        "value":"1",
        "expire":1417072380,
    },
    function(res){
        if(res.code == 0)
            alert('OK');
        else
            alert('fail');
    }
);

9.1.6. 获取Cookies值

CcjJSBridge.call(
    'getCookie',
    data,
    function(res){}
);

data结构：

Name	Type	Desc
key	String	需要获得的Cookie key
domain	String	需要获得的Cookie domain，默认为当前网站域名

返回res内容：

Name	Type	Desc
code	int	0-成功、406-获取Cookie值失败、444-不存在此方法
value	String	获得的value值

9.1.5.1. 调用示例

CcjJSBridge.call(
    'getCookie',
    {
        "key":"a",
        "domain":".qq.com",
    },
    function(res){
        if(res.code == 0)
            alert('the cookie value:'+res.value);
        else
            alert('fail');
    }
);

9.1.6. 支付

CcjJSBridge.call(
    'pay',
    data,
    function(res){}
);

data结构：

Name	Type	Desc
platform	String	支付平台：WXPAY-微信支付、ALIPAY-支付宝、UNIONPAY-银联支付
orderInfo	String	支付订单信息

返回res内容：

Name	Type	Desc
code	int	0-成功、318-取消支付、408-支付出错、444-不存在此方法

9.1.7. Web登录成功传递信息给Native

CcjJSBridge.call(
    'syncLogin',
    data,
    function(res){}
);

data结构：

Name	Type	Desc
token	String	楚楚街商城登录成功后传递的token

返回res内容：

Name	Type	Desc
code	int	0-成功、410-同步登录状态出错、444-不存在此方法

9.1.8. JS获得客户端信息

CcjJSBridge.call(
    'getClientInfo',
    function(res){}
);

返回res内容：

Name	Type	Desc
code	int	0-成功、444-不存在此方法
value	Client	客户端信息

Client数据结构：
见Client结构定义

9.1.9. 调用Native的TEMPLATE、QUERY

CcjJSBridge.call(
    'callTemplate',
    data
);

data结构：

Name	Type	Desc
template	String	Native的TEMPLATE，如JKJ
query	String	QUERY，如{"module":"99"}

返回res内容：

没有callback

9.1.10. 调用微店Native登录接口

CcjJSBridge.call(
    'shopLogin',
    function(res){}
);

返回res内容：

Name	Type	Desc
code	int	0-成功、444-不存在此方法
value	Client	客户端信息，如果登录成功，则shopToken、userId应为正确的值

Client数据结构：
见Client结构定义

楚楚街APP新版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. 返回结构

3.5. 配置信息

3.5.1. 请求参数

3.5.2. 返回结构

4. 请求方法

4.1. API地址

4.2. 请求参数

4.2.1. 请求示例

4.3. 返回结果

4.4. 关于分页

5. 模块调用

5.1. 微店Native

5.2. WebView

5.3. 其他Native接口 调用做活

5.3.1. 应用场景

6. 模块整理

6.1. 服务器模块整理

6.2. APP模板整理

7. 调用地址

8. 推送

8.1. 推送数据结构

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

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