《云上城手机客户端接口规范v》

1、文件编号：JHDZ/SJ 密 级： 云上城手机客户端接口规范（第一期）项目名称：云上城项目代号：XXX版 本：V1.0编制单位：平台运营编制日期：2014-08-06编制审核批准生效日期版 本 变 更 记 录版本/状态作者参与者完成时间变更内容1.0/草稿袁少2014-08-06云上城手机客户端接口规范 目 录1 文档概述11.1 编写目的11.2 术语定义11.3 参考资料11.4 使用对象12 接口定义12.1 通讯方式12.2 协议说明22.2.1 回应报文必填JSON属性项22.2.2 result结果返回值定义22.2.3 部分属性规格22.2.4 JSON内容说明32.2.5 接口

2、添加与更改约定32.3 通用接口定义32.3.1 列表信息通用属性定义32.4 首页42.4.1 顶部Flash图片42.4.2 中间服务列表52.4.3 滚动分享信息62.4.4 最新通知72.4.5 推送服务信息列表82.5 Flash详情102.6 最新通知102.6.1 列表102.6.2 详情112.7 快送服务132.7.1 列表132.7.2 详情142.7.3 预约152.8 服务预约172.8.1 列表172.8.2 详情182.8.3 预约192.9 维修服务212.10 投诉建议222.11 物业账单232.11.1 列表232.11.2 详情列表252.12 房屋出租2

3、62.12.1 小区列表262.12.2 出租列表272.12.3 详情292.12.4 发布312.13 甜甜圈322.13.1 最新帖子322.13.2 帖子详情342.13.3 帖子评论362.13.4 发表帖子3类别列表3发表帖子382.13.5 所有评论392.13.6 评论详情412.13.7 评论412.13.8 我的帖子412.14 登录注册412.14.1 小区列表信息412.14.2 获取短信验证码412.14.3 注册登录412.15 个人中心412.15.1 修改基本资料41II云上城手机客户端规范 1 文档概述1.1 编写目的本规范

4、定义了手机客户端Android与IOS和服务器端之间的通讯的接口规范，明确协议参数及典型业务和数据流程。1.2 术语定义英文缩写英文全称中文翻译1.3 参考资料序号参 考 文 献来源发行日期1.4 使用对象Android工程师、IOS工程师、JAVA工程师。2 接口定义2.1 通讯方式采用HTTP/TCP方式通信，JSON承载数据。2.2 协议说明2.2.1 回应报文必填JSON属性项属性名类型属性说明备注resultint结果返回值0：成功，其他失败messageString结果描述不成功时，此信息可能会直接提示给用户，因此必须友好、清晰、明了。2.2.2 result结果返回值定义错误码描

5、述备注0成功1参数不对包括类型不对，格式不对，参数不全9服务器异常2.2.3 部分属性规格接口属性命名遵守类属性命名规则，请看平台运营部Java编码规范.doc。属性规格描述时间YYYY-MM-dd HH:mm:ss默认时间格式金额单位：元2.2.4 JSON内容说明（1） JSON数据，不能通过手工拼接，必须用JSON工具类生成，避免不必要的错误。（2） JSON内容，前后避免有空格出现。（3） JSON特殊字符需要转义。2.2.5 接口添加与更改约定（1） 接口添加，接口属性添加，接口的更改，接口属性的更改都必须先更新此文档，由相关负责人审核通过后，再通知相关人员实施。保证接口与代码一致性

6、。2.3 通用接口定义2.3.1 列表信息通用属性定义属性名类型属性说明备注titlePicPathString标题图片路径titleString标题linkString详情链接summaryString概要描述实现建议：为减少代码量，相同属性抽取出来封装作为基类，其他类继承基类拓展个性属性。2.4 首页2.4.1 顶部Flash图片接口说明展示顶部flash接口方向手机客户端 -> 服务器系统接口地址待定接口参数参数名类型参数说明请求内容JSON格式返回结果JSON格式"result":"0","message":"

7、成功","list":"picPath":""link":"?id=101","picPath":""link":"?id=102"属性名类型属性说明resultString返回值0 成功messageString结果描述list 列表属性picPathString图片路径linkString详情链接说明：目前为静态化。需要动态化，则使用此接口。后台要提供录入数据的界面。Link详情链接由服务器组装，通过此链接请求服务器可以返

8、回详情信息。2.4.2 中间服务列表接口说明中间服务列表接口方向手机客户端 -> 服务器系统接口地址待定接口参数参数名类型参数说明请求内容JSON格式返回结果JSON格式"result":"0","message":"成功","list":"title":"标题1","titlePicPath":" ","link":"?id=101","title"

9、:"标题2","titlePicPath":""link":"?id=102"属性名类型属性说明resultString返回值0 成功messageString结果描述list 列表属性titlePicPathString标题图片路径linkString链接titleString标题说明：目前为静态化。需要动态化，则使用此接口。2.4.3 滚动分享信息接口说明中间的滚动用户分享信息接口方向手机客户端 -> 服务器系统接口地址待定接口参数参数名类型参数说明请求内容JSON格式返回结果JSON格式&qu

10、ot;result":"0","message":"成功","list":"title":"标题1","titlePicPath":""summary":"概要1","link":"?id=101","typeDesc":"分享","publishTime":"两天前",&quo

11、t;title":"标题2","titlePicPath":""summary":"概要2","link":"?id=102","typeDesc":"跳蚤市场","publishTime":"一天前"属性名类型属性说明resultString返回值0 成功messageString结果描述list 列表属性titleString标题titlePicPathString标题图片

12、路径summaryString概要linkString链接typeDescString类型描述publishTimeString发布时间：格式：X天前说明：2.4.4 最新通知接口说明首页最新通知接口方向手机客户端 -> 服务器系统接口地址待定接口参数参数名类型参数说明请求内容JSON格式返回结果JSON格式"result":"0","message":"成功","list":"title":"标题1","titlePicPath"

13、;:""summary":"概要1","link":"?id=101","typeDesc":"头条","publishTime":"08-08","title":"标题2","titlePicPath":""summary":"概要2","link":"?id=102",&qu

14、ot;typeDesc":"精选","publishTime":"08-09"属性名类型属性说明resultString返回值0 成功1 失败messageString结果描述list 列表属性titleString标题titlePicPathString标题图片路径summaryString概要linkString链接publishTimeString发布时间格式：MM-dd typeDescString类型描述说明：显示记录条数由服务器端控制。默认按最新时间排序。2.4.5 推送服务信息列表接口说明首页下面的推送的 用户

15、服务信息列表接口方向手机客户端 -> 服务器系统接口地址待定接口参数参数名类型参数说明userIdString用户唯一标识请求内容JSON格式"userId":"1001" 返回结果JSON格式"result":"0","message":"成功","list":"title":"标题1","titlePicPath":""summary":"概要1&

16、quot;,"link":"?id=101","noDealNum":"1","processingNum":"1","waitEvaluateNum":"1","title":"标题2","titlePicPath":""summary":"概要2","link":"?id=102",&

17、quot;noDealNum":"1","processingNum":"1","waitEvaluateNum":"1"属性名类型属性说明resultString返回值0 成功messageString结果描述list 列表属性titleString标题titlePicPathString标题图片路径summaryString概要linkString链接noDealNumint未处理数量processingNumint处理中数量waitEvaluateNumint待评价数量说明：用户

18、登录后才可以显示出其对应的推送服务信息。记录条数由服务器端控制。2.5 Flash详情2.6 最新通知2.6.1 列表接口说明点击获取最新通知列表接口方向手机客户端 -> 服务器系统接口地址待定接口参数参数名类型参数说明pageIndexint每几页pageSizeint每页显示记录数请求内容JSON格式 "pageIndex":"1","pageSize":"10", 返回结果JSON格式"result":"0","message":"成

19、功","list":"title":"标题1","titlePicPath":""summary":"概要1","link":"?id=101","typeDesc":"头条","publishTime":"08-08 10:10","title":"标题2","titlePicPath&

20、quot;:""summary":"概要2","link":"?id=102","typeDesc":"精选","publishTime":"08-08 10:10"属性名类型属性说明resultString返回值0 成功messageString结果描述list 列表对象属性titleString标题titlePicPathString标题图片路径summaryString概要linkString链接publishTimeS

21、tring创建时间格式： MM-dd HH:mmtypeDescString类型描述说明：如果顶部需要放置头条，默认第一条为头条。2.6.2 详情接口说明点击列表获取详情接口方向手机客户端 -> 服务器系统接口地址列表中的link接口参数参数名类型参数说明请求内容JSON格式返回结果JSON格式 "result":"0","message":"成功","id":"101","title":"标题","typeDesc&q

22、uot;:"精选","publishTime":"2014-08-08 10:10:00","content":"详情内容","picNum":"1","list":"picPath":""picPath":"属性名类型属性说明resultString返回值0 成功messageString结果描述idStringIDtitleString标题titlePicPathStrin

23、g标题图片路径publishTimeString创建时间格式：YYYY-MM-dd HH:mm:sstypeDescString类型描述contentString详情描述picNumint图片数量list 图片列表属性picPathString图片路径说明：content详情描述，可能嵌有HTML标签。2.7 快送服务2.7.1 列表接口说明点击首页“快送服务”，获取最新服务列表接口方向手机客户端 -> 服务器系统接口地址待定接口参数参数名类型参数说明pageIndexint每几页pageSizeint每页显示记录数请求内容JSON格式 "pageIndex":&qu

24、ot;1","pageSize":"10", 返回结果JSON格式"result":"0","message":"成功","phone":"quot;,"list":"title":"标题1","titlePicPath":""summary":"概要1","link&q

25、uot;:"?id=101","price":"10","specifications":"10升","title":"标题2","titlePicPath":""summary":"概要2","link":"?id=102","price":"10","specifications":&

26、quot;10升"属性名类型属性说明resultString返回值0 成功messageString结果描述phoneString服务热线list 列表对象属性titleString标题titlePicPathString标题图片路径summaryString概要linkString详情链接priceint价格，单位：元specificationsString规格2.7.2 详情接口说明点击列表获取详情接口方向手机客户端 -> 服务器系统接口地址列表中的link接口参数参数名类型参数说明请求内容JSON格式返回结果JSON格式 "result":"

27、0","message":"成功","id":"101","title":"标题","price":"20","specifications":"20公斤","content":"详情内容","picNum":"1","list":"picPath":"&qu

28、ot;picPath":"属性名类型属性说明resultString返回值0 成功messageString结果描述idStringIDtitleString标题priceint价格，单位：元specificationsString规格contentString详情描述picNumint图片数量list 图片列表属性picPathString图片路径说明：content详情描述，可能嵌有HTML标签。2.7.3 预约接口说明点击选择数量，选择时间进行预约服务接口方向手机客户端 -> 服务器系统接口地址待定接口参数参数名类型参数说明userIdString用户唯一标识o

29、rderTimeString预约时间 格式：YYYY-MM-DD HH:mm:sslist 列表对象属性idString服务IDnumberint数量请求内容JSON格式 "userId":"1001", "orderTime":"2014-08-07 13:40:00","list":"id":"101","number":"1","id":"102","numbe

30、r":"2"返回结果JSON格式 "result":"0","message":"成功","orderNo":"10121"属性名类型属性说明resultString返回值0 成功messageString结果描述orderNoString单号，result=0成功时才有值2.8 服务预约2.8.1 列表接口说明点击首页“服务预约”，获取最新服务列表接口方向手机客户端 -> 服务器系统接口地址待定接口参数参数名类型参数说明pageIndex

31、int每几页pageSizeint每页显示记录数请求内容JSON格式 "pageIndex":"1","pageSize":"10", 返回结果JSON格式"result":"0","message":"成功","phone":"quot;"list":"id":"102","title":"

32、标题1","titlePicPath":""summary":"概要1","link":"?id=101","fee":"50元/平方","mobile":"quot;,"id":"103","title":"标题2","titlePicPath":""summ

33、ary":"概要2","link":"?id=102","fee":"500元/月（可面议）","mobile":"quot;属性名类型属性说明resultString返回值0 成功1 失败messageString结果描述phoneString服务热线list 列表对象属性titleString标题titlePicPathString标题图片路径summaryString概要linkString详情链接feeString费用说

34、明 mobileString联系电话2.8.2 详情接口说明点击列表获取详情接口方向手机客户端 -> 服务器系统接口地址列表中的link接口参数参数名类型参数说明请求内容JSON格式返回结果JSON格式 "result":"0","message":"成功","id":"101","title":"标题","fee":"20元50元","mobile":"076

35、9-22992888","content":"详情内容","picNum":"1","list":"picPath":""picPath":"属性名类型属性说明resultString返回值0 成功messageString结果描述idStringIDtitleString标题feeString费用说明 mobileString联系电话picNumint图片数量contentString详情描述list 图片列表属性 picP

36、athString图片路径属性说明：content详情描述，可能嵌有HTML标签。2.8.3 预约接口说明点击选择数量，选择时间进行预约服务接口方向手机客户端 -> 服务器系统接口地址待定接口参数参数名类型参数说明userIdString用户唯一标识orderTimeString预约时间 格式：YYYY-MM-DD HH:mm:sslist 列表对象属性idString服务ID请求内容JSON格式 "userId":"1001", "orderTime":"2014-08-07 13:40:00","

37、;list":"id":"101","id":"102"返回结果JSON格式 "result":"0","message":"成功","orderNo":"10121"属性名类型属性说明resultString返回值0 成功messageString结果描述orderNoString单号，result=0成功时才有值2.9 维修服务接口说明点击选择数量，选择时间进行预约服务接口方向手机客

38、户端 -> 服务器系统接口地址待定接口参数参数名类型参数说明userIdString用户唯一标识orderTimeString预约时间 格式：YYYY-MM-DD HH:mm:ssexplainString说明haveMaterialint是否自带材料 1是，0否list 列表对象属性pictrueString图片信息请求内容JSON格式 "userId":"1001", "orderTime":"2014-08-07 13:40:00","explain":"说点什么"

39、;,"haveMaterial":"1","list":"pictrue":"xxxx","pictrue":"xxxx"返回结果JSON格式 "result":"0","message":"成功","orderNo":"10121"属性名类型属性说明resultString返回值0 成功1 失败messageString结果描述orde

40、rNoString单号，result=0成功时才有值说明：目前是点击拍照或选择相册时，上传暂时图片文件到服务器端，边选择边上传还是提交一起上传呢，待定。2.10 投诉建议接口说明点击选择数量，选择时间进行预约服务接口方向手机客户端 -> 服务器系统接口地址待定接口参数参数名类型参数说明userIdString用户唯一标识explainString建议内容list 列表对象属性pictrueString图片信息请求内容JSON格式 "userId":"1001", "explain":"说点什么","

41、list":"pictrue":"xxxx","pictrue":"xxxx"返回结果JSON格式 "result":"0","message":"成功","orderNo":"10121"属性名类型属性说明resultString返回值0 成功1 失败messageString结果描述orderNoString单号，result=0成功时才有值说明：目前是点击拍照或选择相册时，上传暂时

42、图片文件到服务器端，边选择边上传还是提交一起上传呢，待定。2.11 物业账单2.11.1 列表接口说明点击首页“物业账单”，获取最新服务列表接口方向手机客户端 -> 服务器系统接口地址待定接口参数参数名类型参数说明pageIndexint每几页pageSizeint每页显示记录数userIdString用户唯一标识typeint0本月费用1历史欠费2历史缴费请求内容JSON格式 "pageIndex":"1","pageSize":"10", "userId":"101"

43、;, "type":"1"返回结果JSON格式"result":"0","message":"成功","title":"比克大厦单元10602","haveToPay":"20","list":"payType":"水费","money":"100","link":"&

44、quot;,"payTime":"2014-08-08 11:00:00","payType":"电费","money":"150","link":"","payTime":"2014-08-08 11:00:00"属性名类型属性说明resultString返回值0 成功messageString结果描述titleString标题：用户住宅信息haveToPayint需要缴费金额，单位：元list

45、 列表对象属性payTypeString费用类型moneyString金额，单元：元payTimeString交费时间：格式：YYYY-MM-dd HH:mm:sslinkString详情链接2.11.2 详情列表接口说明点击列表项的“详情”，获取最新详细列表接口方向手机客户端 -> 服务器系统接口地址待定接口参数参数名类型参数说明pageIndexint每几页pageSizeint每页显示记录数userIdString用户唯一标识请求内容JSON格式 "pageIndex":"1","pageSize":"10&qu

46、ot;, "userId":"101"返回结果JSON格式"result":"0","message":"成功","list":"payType":"水费","money":"100","month":"一月","payType":"电费","money":"150&q

47、uot;,"month":"一月"属性名类型属性说明resultString返回值0 成功1 失败messageString结果描述list 列表对象属性payTypeString费用类型moneyString金额，单元：元monthString月份2.12 房屋出租2.12.1 小区列表接口说明点击首页“房屋出租”，获取最新服务列表接口方向手机客户端 -> 服务器系统接口地址待定接口参数参数名类型参数说明userIdString用户唯一标识请求内容JSON格式 " userId":"101" 返回结果JSO

48、N格式"result":"0","message":"成功","list":"name":"小区名称1","code":"100100","name":"小区名称2","code":"100200"属性名类型属性说明resultString返回值0 成功1 失败messageString结果描述list 列表对象属性nameString小

49、区名称codeString小区编码2.12.2 出租列表接口说明点击首页“房屋出租”，获取最新服务列表接口方向手机客户端 -> 服务器系统接口地址待定接口参数参数名类型参数说明pageIndexint每几页pageSizeint每页显示记录数xiaoquCodeint小区编码，可选请求内容JSON格式 "pageIndex":"1","pageSize":"10","xiaoquCode"：""返回结果JSON格式"result":"0&q

50、uot;,"message":"成功","list":"title":"标题1","titlePicPath":""summary":"概要1","link":"?id=101","price":"1000","priceUnit"："1","phone":"0769-22992

51、888","publishTime":"2014-08-08","type":"0","title":"标题2","titlePicPath":""summary":"概要2","link":"?id=102","price":"1000000","priceUnit"："1",

52、"phone":"quot;,"publishTime":"2014-08-08","type":"1"属性名类型属性说明resultString返回值0 成功1 失败messageString结果描述list 列表对象属性titleString标题titlePicPathString标题图片路径summaryString概要linkString详情链接priceString价格，单位：元priceUnitint价格单元：0每日，1每月，2每年。type=0

53、有效。phoneString联系电话publishTimeString发布时间：格式：YYYYMMDDtypeint0出租，1出售，说明：根据link链接，可查询详情信息。2.12.3 详情接口说明点击列表获取详情接口方向手机客户端 -> 服务器系统接口地址列表中的link接口参数参数名类型参数说明请求内容JSON格式返回结果JSON格式 "result":"0","message":"成功","id":"101","title":"标题&

54、quot;,"price":"2500","priceUnit":"2","phone":"quot;,"linkman":"联系人","address":"房屋地址","publishTime":"2014-08-08","content":"详情内容","type":"

55、;1","list":"picPath":""picPath":""picPath":"属性名类型属性说明resultString返回值0 成功1 失败messageString结果描述idStringIDtitleString标题priceString价格，单位：元priceUnitint价格单元：0每日，1每月，2每年。type=0有效。phoneString联系电话linkmanString联系人addressString房屋地址contentString详情publi

56、shTimeString发布时间：格式：YYYYMMDDtypeint0出租，1出售list 图片列表属性 picPathString图片路径2.12.4 发布接口说明点击“发布”接口方向手机客户端 -> 服务器系统接口地址列表中的link接口参数参数名类型参数说明userIdString用户唯一标识titleString标题priceString价格，单位：元priceUnitint价格单元：0每日，1每月，2每年。type=0有效。phoneString联系电话linkmanString联系人addressString房屋地址typeint0出租，1出售contentString内容

57、描述list 图片列表属性 picPathpicPathpicPath请求内容JSON格式"userId":"101","title":"标题","price":"2500","priceUnit":"2","phone":"quot;,"linkman":"联系人","address":"房屋地址"

58、,"content":"详情内容","type":"1","list":"picPath":""picPath":""picPath":"返回结果JSON格式 "result":"0","message":"成功","orderNo":"1001",属性名类型属性说明resultStrin

59、g返回值0 成功1 失败messageString结果描述orderNoString单号说明：目前是点击拍照或选择相册时，上传暂时图片文件到服务器端，边选择边上传还是提交一起上传呢，待定。2.13 甜甜圈2.13.1 最新帖子接口说明点击首页“最新帖子”，获取最新列表接口方向手机客户端 -> 服务器系统接口地址待定接口参数参数名类型参数说明pageIndexint每几页pageSizeint每页显示记录数请求内容JSON格式 "pageIndex":"1","pageSize":"10"返回结果JSON格式&

60、quot;result":"0","message":"成功","list":"title":"标题1","titlePicPath":""summary":"概要1","link":"?id=101","publishTime":"2014-08-08","typeDesc":"类型描述","evaluateNum":"10"," supportNum":"10","shareNum":"10","title":"标题2","titlePicPath":""summary":"概要2","link":"?id=102","publi