外包大赛八维通接口规范

八维通应用服务接口规范八维通科技有限公司接口规范页码：71/16外包大赛八维通接口规范V1.0八维通科技有限公司2019年11月

文档修订记录版本编号*变化状态简要说明（变更内容和变更范围）日期变更人批准日期批准人0.1新增创建2019-11-19李远翼*变化状态：C-建立，M-修改，A-增加，D-删除

目录TOC\o"1-4"\h\u八维通科技有限公司 11 概述 52 接口协议 52.1 接口协议格式 52.2 接口调用规范 52.2.1 调用入口 52.2.2 HTTP请求头 52.2.3 HTTP应答头 62.2.4 请求公共参数 62.2.5 应答公共参数 62.3 签名算法 62.4 验签过程 72.5 加密算法 72.6 错误代码定义 72.7 约定 83 业务字典定义 83.1 城市ID定义 83.2 服务类型定义 93.3 站点、线路定义 93.3.1 无锡（3202） 93.4 行程状态定义 113.5 行程支付类型定义 114 接口定义 114.1 用户模块 114.1.1 获取用户信息 114.2 行程模块 124.2.1 行程列表 124.2.2 行程详情 144.3 消息模块 164.3.1 消息推送 164.3.2 根据消息类型获取消息（行程通知） 174.4 其他模块 184.4.1 查询地铁路线站点 184.4.2 查询用户画像信息 195 基础数据定义 205.1 用户基础信息 205.2 用户画像信息 21

概述本文档为八维通与外部系统的接口说明，文档定义了双方系统的接口流程、接口协议、接口数据内容，作为为双方系统接口对接的设计、开发以及测试依据。接口协议接口协议格式接口采用HTTP协议，使用POST方式提交，请求参数字符集编码为UTF-8，返回结果默认为JSON格式，如有特殊格式会在具体的接口定义中明确说明。接口调用规范调用入口接口调用地址：http://IP:PORT/api/[rest]，rest地址在各接口中明确。HTTP请求头名称类型长度说明appidstringF32八维通分配给开发者/商户的appidtokenstringF32用户登录后返回的token，需要用户授权的接口必须传此参数randomStringF172加密后的随机码，当报文中有需要加密的字段的时候需要传此参数sequencestringF24yyyyMMddHHmmss+10位数字（在一定时间内不重复），仅作为接口调用跟踪用途，不作为业务用途，业务流水在业务接口中定义。versionstringV6App版本号，如：1.2、1.1.11。signaturestringF172签名，由请求方生成，参见《签名算法》deviceIdstringF64设备iddeviceTypestringF64设备类型appTypestringF64app类型cityIdstringF64城市idbundleIdstringF64app唯一标识userIdstringF64用户IDHTTP应答头名称类型长度说明sequencestringF24原样返回合作机构的流水signaturestringF172签名，由应答方生成，参见《签名算法》请求公共参数名称类型长度说明应答公共参数名称类型长度说明errcodestringF4错误代码errmsgstringV256错误代码描述签名算法为了防止API调用过程中被黑客恶意篡改，调用任何一个API都需要携带签名，服务端会根据请求参数，对签名进行验证，签名不合法的请求将会被拒绝。目前支持的签名算法采用MD5，签名大体过程如下：转换：将请求参数转换为json消息。摘要：把转换好的字符串采用utf-8编码，使用摘要算法对编码后的字节流进行摘要。使用MD5算法，对转换后的字符串进行摘要，如：md5(json)；将摘要得到的字节流结果使用十六进制大写表示，如：hex(“helloworld”.getBytes(“utf-8”))=“68656C6C6F776F726C64”签名：使用加密算法对摘要后的16进制文本进行加密。使用RSA算法，1024位，填充方式采用RSA/ECB/PKCS1Padding，如RSA(“68656C6C6F776F726C64”,key)。验签过程摘要：将接收到的请求报文json采用utf-8编码，使用摘要算法对编码后的字节流进行摘要。使用MD5算法，对请求报文进行摘要，如：md5(json)将摘要得到的字节流结果使用十六进制大写表示，如：A=hex(“helloworld”.getBytes(“utf-8”))=“68656C6C6F776F726C64”解密签名：使用加密算法对报文头中的签名进行解密。使用RSA算法，如B=RSA(“68656C6C6F776F726C64”,key)验签：比对摘要得到的十六进制字符串A和解密后的签名B是否一致，若一致则验签成功。加密算法为了防止敏感信息泄露，敏感字段需要加密传输，加密算法RSA+AES。请求报文：合作商户生成8位数字+字母组合随机码，并使用八维通公布的公钥进行加密，将加密后的随机码放置在报文中的random字段。使用AES算法对敏感字段（登陆中的密码）进行加密。A=AES.encryptToHex(password,random)应答报文：使用请求报文中的random进行用AES算法解密。password=AES.decryptFromHex(A,random)注：AES算法使用AES/ECB/PKCS5Padding方式，128位秘钥。错误代码定义编码含义0000处理成功0001appid不合法0002签名验证失败0003没有权限0004参数错误0005登录已失效，请重新登录。0006接口不存在0009App唯一标识为空！0010处理失败0011必填参数不能为空0012输入参数不正确0013终端识别码错误0014城市选择错误0015该城市仅向内测用户开放，请选择其他城市0016该功能仅向内测用户开放0017系统繁忙，请稍候再试0901系统异常0902数据为空0088版本号不支持9999未知错误约定本文档中使用的时间统一采用YYYY/MM/DDHH24:MI:SS格式。每次交互设置交易时限【交限时限定为30秒】，如接口发起方在交易时限内未收到接口服务应答包，则交易失败，接口发起方应停止接收。对于耗时的业务，需考虑异步回调通知的方式。在本文档中以表格的形式表示JSON格式，以下为表格中对元素约束（出现次数）的表示方法的描述：符号含义?0..1，可选项*0..n，可以没有，也可以有多项（数组）+1..n，至少有1项，也可以有多项（数组）1数字1，代表必须且只能填1项另外，在报文格式的宽度中，“F”指固定长度，“V”表示可变长度。业务字典定义城市ID定义字段名称约定：CITY_ID数据项取值类型长度描述全国86天津12无锡3202苏州3205福州3501服务类型定义字段名称约定：SERVICE_ID数据项取值类型长度描述不限002不限地铁012地铁公交022公交自行车032自行车高铁062高铁站点、线路定义字段名称约定：STATION_NO无锡（3202）CITY_IDSTATION_IDSTATION_NAMESTATION_NO32021363613991735290堰桥10132021363613991735290锡北运河10232021363613991735290西漳10332021363613991735290天一10432021363613991735300刘潭10532021363613991735300庄前10632021363613991735300民丰10732021363613991735300无锡火车站10832021363613991735300胜利门10932021363613991735300三阳广场11032021363613991735300南禅寺11132021363613991735300谈渡桥11232021363613991735300太湖广场11332021363613991735300清名桥11432021363613991735310人民医院11532021363613991735310华清大桥11632021363613991735310扬名11732021363613991735310南湖家园11832021363613991735310塘铁桥11932021363613991735310金匮公园12032021363613991735310市民中心12132021363613991735310文化宫12232021363613991735310江南大学12332021363613991735310长广溪12432021363613991735320梅园开原寺20132021363613991735320荣巷20232021363613991735320小桃源20332021363613991735320河埒口20432021363613991735320大王基20532021363613991735320梁溪大桥20632021363613991735320五爱广场20732021363613991735320东林广场20932021363613991735320上马墩21032021363613991735320靖海21132021363613991735330广益21232021363613991735330柏庄21332021363613991735330东亭21432021363613991735330庄桥21532021363613991735330云林21632021363613991735330九里河公园21732021363613991735330查桥21832021363613991735330映月湖公园21932021363613991735330迎宾广场22032021363613991735330无锡东站22132021363613991735340安镇22232021363613991735340苹果园22332021363613991735340天安门22332021363613991735340土桥22332021363613991735340东直门22332021363613991735340复兴门22332021363613991735340建国门22332021363613991735340安河桥北22332021363613991735340西直门22332021363613991735340天宫院223行程状态定义字段名称约定：status数据项取值类型长度描述未进站0Integer3行程中1Integer3待支付2Integer3已付款3Integer3行程支付类型定义字段名称约定：pay_type_h5，over_time_pay_type_h5数据项取值类型长度描述次卡0Integer3现金2Integer3乘车票31Integer3绑卡支付8Integer3支付宝代扣9Integer3微信代扣10Integer3接口定义用户模块获取用户信息URI/app/user/getUserInfo功能描述获取用户信息备注为了和新协议的编码规范一致，采用a_b下划线的形式请求内容：父元素名称元素名称约束类型宽度参数描述备注user_id?IntegerF16用户idterm_type?integerF2终端类型终端类型0安卓1苹果--device_typeterm_token?stringV32设备唯一id终端识别码--divice_id应答内容：父元素名称元素名称约束类型宽度参数描述备注result*struct-返回结果resultuser1struct-用户信息引REF_Ref485821255\r\h5.1用户基础信息resulttoken1stringV32token信息返回码：编码说明0000处理成功0001处理失败0100您还不是会员，现在去注册吧。0131用户id为空行程模块行程列表URI/app/trip/baseTriplist功能描述用户行程列表的获取请求内容：父元素名称元素名称约束类型宽度参数描述备注service_id？stringV4服务id参考字典服务类型trip_flag1stringF4行程标识00：全部01：行程中02：已完成page_no1integerV11当前页码,从1开始page_size1integerV11每页记录数应答内容：父元素名称元素名称约束类型宽度参数描述备注page1struct-页pagetotal_count1integerV11总条数pagepage_no1integerV11当前页码,从1开始pagepage_size1integerV11每页记录数pagetotal_page1integerV11总页数pagerows*struct-记录列表行程本身的信息rowstrip_no？stringV20行程单号rowscity_id1integerF20城市idrowsservice_id1stringV4服务id参考字典服务类型rowsin_station_id1stringV20进站站点idrowsin_station_name1stringV20进站站点名称rowsin_line_id1stringV20线路id(进)rowsin_line_name1stringV2线路名称（进）rowsin_time1stringV20进站时间yyyy/MM/ddHH:mm:ssrowsout_station_id1stringV20出站站点idrowsout_station_name1stringV20出站站点名称rowsout_line_id1stringV20线路id(出)rowsout_line_name1stringV20线路名称（出）rowsout_time1stringV20出站时间yyyy/MM/ddHH:mm:ssrowsmileage1integerF2里程rowsstatus1stringF2行程状态参考字典行程状态行程总的扣费信息rowstrip_total_fee1integerF8行程总基础费用单位：分rowstrip_total_actual_fee1integerF8行程支付实际总费用单位：次或者分正常扣费信息rowsamount1integerF8实际支付金额行程支付费用：单位：次或者分备注：次为计次卡的次数rowsbase_fee1integerF8标准费用行程基础费用：单位：分rowspay_type1integerF1支付类型0-次卡1-金额rowspay_type_h51integerF1支付类型H5页面专用，参考字典行程支付类型rowspay_time1stringV20支付时间yyyy/MM/ddHH:mm:ssrowsbill_id1stringF20正常扣费的账单id行程详情URI/app/trip/getBaseTrip功能描述用户行程详情获取备注要考虑超时扣罚时有两笔扣款，接口如何调整、APP端如何展示请求内容：父元素名称元素名称约束类型宽度参数描述备注trip_no1stringV16行程单号service_id1stringF4服务id参考字典服务类型应答内容：父元素名称元素名称约束类型宽度参数描述备注trip*struct-行程记录行程本身的信息triptrip_no？stringV20行程单号tripconsumer_id1longV20计费侧行程号tripcity_id1integerF20城市idtripservice_id1stringV4服务id参考字典服务类型tripin_station_id1stringV20进站站点idtripin_station_name1stringV20进站站点名称tripin_line_id1stringV20线路id(进)tripin_line_name1stringV2线路名称（进）tripin_time1stringV20进站时间yyyy/MM/ddHH:mm:sstripout_station_id1stringV20出站站点idtripout_station_name1stringV20出站站点名称tripout_line_id1stringV20线路id(出)tripout_line_name1stringV20线路名称（出）tripout_time1stringV20出站时间yyyy/MM/ddHH:mm:sstripmileage1integerF2里程tripstatus1stringF2行程状态参考字典行程状态行程总的扣费信息triptrip_total_fee1integerF8行程总基础费用单位：分triptrip_total_actual_fee1integerF8行程支付实际总费用单位：次或者分正常扣费信息tripamount1integerF8实际支付金额行程支付费用：单位：次或者分备注：次为计次卡的次数tripbase_fee1integerF8标准费用行程基础费用：单位：分trippay_result1integerF8扣费结果1-支付成功2-支付失败trippay_type1integerF1支付类型0-次卡1-金额trippay_type_h51integerF1支付类型H5页面专用，参考字典行程支付类型trippay_time1stringV20支付时间yyyy/MM/ddHH:mm:sstripbill_id1stringF20正常扣费的账单id消息模块消息推送URI/app/message/push功能描述消息推送请求内容：父元素名称元素名称约束类型宽度参数描述备注msg_type1integerV1消息类型消息类型4：服务消息relation_id？stringV20业务id关联的业务id–测试可以随便输入，不超过64位eg:订单idmsg_title1stringF19消息标题eg.系统消息msg_content1stringF19消息内容推送主要内容remark？stringV20备注备注信息应答内容：父元素名称元素名称约束类型宽度参数描述备注返回码：编码说明根据消息类型获取消息（行程通知）URI/app/message/list/by/type功能描述根据消息类型获取消息，更新消息是否已读请求内容：父元素名称元素名称约束类型宽度参数描述备注user_id1bigintV64用户Idmsg_type1intF1消息类型消息类型0：支付消息1：行程通知current_page1intV11当前页page_size1intV11每页显示数应答内容：父元素名称元素名称约束类型宽度参数描述备注messages1struct-返回消息内容messagesrow*struct-每条消息内容rowsend_id1LongF20消息idrowuser_id1LongF20用户idrowmsg_type1IntegerF1消息类型0-支付消息1-行程消息rowmsg_title1StringF64消息标题rowmsg_content1StringV512消息内容rowrelation_id1StringF1关联的业务编号rowrequest_time1dateF19发送时间格式：yyyy/MM/ddHH:mm:ssrowread_status1IntegerF1阅读状态0-未读1-已读rowcity_id1IntegerF8城市idrowservice_id1StringF2服务类型参考字典服务类型返回码：编码说明其他模块查询地铁路线站点URI/metro/station/find功能描述查询地铁路线请求内容：父元素名称元素名称约束类型宽度参数描述备注ver？stringF32新版本标识eg:msx-2.0city_id1intV11城市IDlast_line_time?datetimeF19线路最后更新的时间--不传，代表全量更新yyyy/MM/ddHH:mm:sslast_station_time?datetimeF19站点最后更新时间--不传代表全量更新yyyy/MM/ddHH:mm:ss应答内容：父元素名称元素名称约束类型宽度参数描述备注page1struct-页pageline_sta*struct-线路站点line_staline_id1integerV11线路Idline_staline_name1stringV11线路名称line_staline_modify_status1stringF4线路更新状态1-新增2-修改3-删除line_stastation*struct-站点数据stationstation_id1integerV20站点idstationstation_name1stringF1站点名称stationstation_no1integerF1站点编号stationstation_phone1stringV20站点电话stationstation_modify_status1stringF4站点更新状态1-新增2-修改3-删除pagesta_chg1longF32站点表最后更新时间戳--2017.08.10上线版本以后加入，老版本忽略pageline_chg1longF32线路表最后更新时间戳--2017.08.10上线版本以后加入，老版本忽略pagerel_chg1longF32线路站点关系表最后更新时间戳--2017.08.10上线版本以后加入，老版本忽略pagelast_line_time1datetimeF19线路最后更新的时间--yyyy/MM/ddHH:mm:sspagelast_station_time1datetimeF19站点最后更新时间--yyyy/MM/ddHH:mm:ss返回码：编码说明查询用户画像信息URI/portrait/getUserPortrait功能描述查询用户画像标签请求内容：父元素名称元素名称约束类型宽度参数描述备注city_id1intV11城市ID应答内容：父元素名称元素名称约束类型宽度参数描述备注resultportrais1struct-用户画像标签信息引5.2用户画像信息返回码：编码说明基础数据定义用户基础信息元素名称类型约束宽度参数描述备注userstruct1-user_idinteger1F16用户iduser_namestring1V64用户姓名sexinteger？F2用户性别0-保密1-男2-女mobile_phonestr