API数据服务接口开发指引

1、四键信息FOURTH BUTTON. INCTa r g e t - S外部接口说明书上海四键信息技术Fourth Butt on,Inc.日期:2016-05-19变更记录序号说明变更人时间目录1 引言 11.1 概述 . 11.2 名词缩写及定义 . 11.3 历史变更. 12 开发规范 . 22.1 通信方式. 22.2 接口说明. 22.2.1 返回参数 . 22.2.2 通用返回码说明 . 23 数据服务接口 . 43.1 importCustomerAndVHLData( FTP Monitor-TSS ) 43.2 createLeads (TSS-TSM) . 53.3 lea

2、ds 需要外部文件导入的，是修改 leads 状态码？ 错误 ! 未定义书签。3.4 callTheCustomer(TSS-CCA) . 73.5 fishTheCall (CCA-TSS) . 84 附录 114.1 数据结构描述 . 114.1.1 customerVHLData . 114.1.2 customerInfo . 114.1.3 VHLInfo . 124.1.4 serviceStatus . 134.1.5 leadsInfo . 134.2HTTP返回值处理策略 141引言1.1概述略1.2名词缩写及定义名词缩写定义VIN17位国际VIN码规则TSSTarget-S

3、 SystemTSMTarget-S ModelCCA外部系统，用于拨打电话给客户的系统FTP Mon itor文件监视器，用于监测文件夹中是否存在文件，如果存在文件，则读取 文件内容并通知 TSS做相应处理ESExternal System外部系统1.3历史变更序号说明变更人时间123452开发规范2.1通信方式1）业务请求是HTTP协议请求，客户端以 POST方式发送到服务平台。2）参数名称和参数说明中规定的固定值必须与列表中完全一致（大小写敏感）3） 目前接口支持签名方法：MD5的签名。2.2接口说明2.2.1返回参数通用返回数据格式：字段名类型是否必输:说明resp on seCode

4、Stri ngY请求操作相应码。操作成功返回0,操作失败响应码见通用响应码说明errorMessageStri ngN当responseCode 不为0时，该参数不能 为空，返回操作失败原因2.2.2通用返回码说明响应码说明0成功（接收成功、执行成功）1失败（接收失败、执行失败、拨打失败）2错误：缺失必选参数：s,请参考API文档3错误：参数s： %s存在非法字符，请参考 API文档 例如：“参数VIN : 123 ¥ DFG9871SER23 存在非法字符。”4错误参数s： %s位数不正确，请参考 API文档5错误结束时间小于开始时间，请参考API文档6错误开始时间大于当前时间，请

5、参考API文档7错误参数 s： %s大于s,请参考 API文档8错误参数s： %s不存在，请参考 API文档9错误序号%s中缺失必选参数： s,请参考API文档10错误如：序号%s中参数s： %s存在非法字符，请参考API文档 例“参数 VIN : 123 ¥ DFG9871SER23存在非法字符。”11错误序号%s中参数%s： %s位数不正确，请参考 API文档12错误序号%s参数s： %s大于%s,请参考 API文档13错误序号%s参数s： %s不存在，请参考 API文档14错误序号%s中参数%s： %s格式错误，请参考 API文档15错误预计总数： s,实际总数s,请检查16错

6、误号码s为空号17错误号码%s无人接听18错误%s:%s不存在19错误参数s： %s格式错误，请参考 API文档99超时3数据服务接口3.1 importCustomerAndVHLData (FTP Monitor-TSS )接口名称importCustomerA ndVHLData调用方FTP服务方 TSSMo nitor接口描述监视器监控某个指定文件夹，如果有文件，则读取文件，并调用该接口，将 客户数据和对应的车辆数据存储到TSS数据库中URL/tss/importData/V1/importCustomerA ndVHLData接口类型RESTFul内容格式JSON版本号V1请求方法P

7、OST输入参数参数代码参数名称数据类型必输参数说明total总数intY客户和车辆配对总计customerVHLD ataList客户、车辆、 服务状态信 息列表List<cus tomerVHL Data>Y数据类型参照4.1.1输出参数参数代码参数名称数据类型必输参数说明resp on seCode返回码intY参照返回值说明errorMessage错误信息stri ngN当请求异常时，将返回error 信息返回值说明序号respon seCodeerrorMessage说明10无22错误：缺失必选参数：cou nt缺失count32错误：缺失必选参数：customerVHLL

8、ist缺失 customerVHLList42错误：缺失必选参数：NO缺失NO53错误：参数NO %s存在 非法字符，请参考 API文 档参数NO为全数字组成69错误：序号%s中缺失必选参数：customerI nfo79错误：序号%s中缺失必选参数：customerNamecustomerI nfo中的所有必输项相同，都有缺失必选项参数错误810错误：序号%s中参数ownership : %s存在非法字符，请参考API文档own ership 范围如下：1:个人；2:公司910错误：序号%s中参数IDType : %s存在非法字 符，请参考API文档IDType范围如下：1：身份证；2:组织

9、机构代码证；3 : 护照；4:军官证109错误：序号%s中缺失必选参数：VHLI nfo119错误：序号%s中缺失必选参数：VINVHLI nfo 中的所有必输项相同，都 有缺失必选项参数错误1210错误：序号%s中参数VIN : %s存在非法字符， 请参考API文档参数VIN值由字母和数字组成1311错误：序号%s中参数VIN : %s位数不正确，请 参考API文档定义长度为17位1413错误：序号s参数OEM%s 不存在，请参考API文档VHLI nfo 中 Ba nd、Series、Type、 Color、dealerName 与 OEM相同， 都有不存在错误1514错误：序号%s中参数

10、PurcaseDate : %s 格式错 误，请参考API文档格式为 YYYY/MM/DD169错误：序号%s中缺失必选参数：serviceStatus179错误：序号%s中缺失必选参数：isFreeServiceserviceStatus中的所有必输项相同，都有缺失必选项参数错误1810错误：序号%s中参数 isFreeService: %s存在非法字符，请参考 API文 档参数isFreeService必须数字serviceStatus中所有int类型的数据都有此错误1914错误：序号%s中参数remai nin gServiceDate:%s格式错误，请参考API文档格式为 YYYY/M

11、M/DD2015错误：预计总数：total，实际总数：customerVHLDataListsize()，请检杳例：错误：预计总数：1000 ,实际总数：990 ,请检杳2199超时超时3.2 createLeads (TSS-TSM接口名称createLeads调用方TSS服务方TSM接口描述TSS将最新的客户静态信息、车辆静态信息和车辆服务状态信息导入到TSM,生成对应的LeadsURL/tsm/createLeads/V1/createLeads接口类型RESTFul内容格式JSON版本号V1请求方法POST输入参数参数代码参数名称数据类型必输参数说明total总数intY需要生成Lea

12、ds的总数customerVHLL ist客户、车辆、 服务状态信 息列表List<cus tomerVHL DataY数据类型参照4.1.1输出参数参数代码参数名称数据类型必输参数说明resp on seCode返回码intY参照返回值说明errorMessage错误信息stri ngN当请求异常时，将返回error 信息total生成Leads总数intY右为异常，则total为0leadsList对应的Leads信息List<lea dslnfo>N数据类型参照4.1.5返回值说明序号respon seCodeerrorMessage说明10无22错误：缺失必选参数：c

13、ou nt缺失count32错误：缺失必选参数：customerVHLList缺失 customerVHLList42错误：缺失必选参数：NO缺失NO53错误：参数NO %s存在 非法字符，请参考 API文 档参数NO为全数字组成69错误：序号%s中缺失必选参数：customer79错误：序号%s中缺失必选参数：customerNamecustomer中的所有必输项相同， 都 有缺失必选项参数错误810错误：序号%s中参数 ownership : %s存在非法字符，请参考API文档ownership 范围如下：1:个人；2:公司910错误：序号%s中参数IDType :%s存在非法字符，请参考

14、API文档IDType范围如下：1:身份证；2:组织机构代码证；3 : 护照；4:军官证109错误：序号%s中缺失必选参数：VHLI nfo119错误：序号%s中缺失必选参数：VINVHLI nfo 中的所有必输项相同，都 有缺失必选项参数错误1210错误：序号%s中参数VIN : %s存在非法字符， 请参考API文档参数VIN值由字母和数字组成1311错误：序号%s中参数VIN : %s位数不正确，请 参考API文档定义长度为17位1413错误：序号s参数OEM%s 不存在，请参考API文档VHLI nfo 中 Ba nd、Series、Type、 Color、dealerName 与 OE

15、M相同， 都有不存在错误1514错误：序号%s中参数PurcaseDate : %s 格式错 误，请参考API文档格式为 YYYY/MM/DD169错误：序号%s中缺失必选参数：serviceStatus179错误：序号%s中缺失必选参数：isFreeServiceserviceStatus中的所有必输项相同，都有缺失必选项参数错误1810错误：序号%s中参数 isFreeService: %s存在非法字符，请参考 API文 档参数isFreeService必须数字serviceStatus中所有int类型的数据都有此错误1914错误：序号%s中参数 remai nin gServiceDat

16、e:%s格式错误，请参考API文档格式为 YYYY/MM/DD2015错误：预计总数：total，实际总数：customerVHLDataList size()，请检杳例：错误：预计总数：1000,实际总数：990,请检杳2199超时超时3.3 callTheCustomer(TSS-CCA)接口名称callTheCustomer调用方TSS服务方CCA接口描述将TSS中的客户电话传输到 CCA触发CCA拨打电话给客户URL/cca/cti/V1/callTheCustomer接口类型RESTFul内容格式JSON版本号V1请求方法POST输入参数参数代码参数名称数据类型必输参数说明VIN车架

17、号stri ngYcallNumber电话号码stri ngY需要拨打的电话号码输出参数参数代码参数名称数据类型必输参数说明resp on seCode返回码intY参照返回值说明errorMessage错误信息stri ngN当请求异常时，将返回error 信息返回值说明序号respon seCodeerrorMessage说明10无22错误：缺失必选参数：VIN缺失VIN32错误：缺失必选参数：callNumber缺失 callNumber43错误：参数callNumber : %s存在非 法字符，请参考API文档电话号码存在！凉& ()等非法字符516错误：号码%s为空号617错

18、误：号码%s无人接听799超时超时3.4 fishTheCall (CCA-TSS接口名称fishTheCall调用方CCA服务方TSS接口描述销售与客户交流结束后，将通话开始时间、结束时间返回给TSSURL/tss/cti/V1/fishTheCall接口类型RESTFul内容格式JSON版本号V1请求方法POST输入参数参数代码参数名称数据类型必输参数说明VIN车架号stri ngYcallNumber电话号码stri ngY需要拨打的电话号码startDate通话开始时间datetimeYYYYY/MM/DDHH:mm:SSen dDate通话开始结 束时间datetimeYYYYY/M

19、M/DDHH:mm:SS输出参数参数代码参数名称数据类型必输参数说明resp on seCode返回码intY参照返回值说明errorMessage错误信息stri ngN当请求异常时，将返回error 信息返回值说明序号respon seCodeerrorMessage说明10无22错误：缺失必选参数：VIN缺失VIN32错误：缺失必选参数：callNumber缺失 callNumber42错误：缺失必选参数：startDate缺失 startDate52错误：缺失必选参数：en dDate缺失 endDate618错误：VIN:%s不存在73错误：参数callNumber : %s存在非

20、法字符，请参考API文档电话号码存在！凉& ()等非法字符819错误：参数YYYY/MM/DD HH:mm:SSstartDate : %s 格式错误，请参考API文档919错误：参数 endDate : %s 格式错误，请参考 API文 档YYYY/MM/DD HH:mm:SS1099超时超时3.5 searchPastPackage (TSS-ES接口名称searchPastPackage调用方TSS服务方ES接口描述TSS通过VIN查询外部系统，获取到该VIN对应的历史套餐列表URL/es/vehicle/V1/searchPastPackage接口类型RESTFul内容格式JS

21、ON版本号V1请求方法POST输入参数参数代码参数名称数据类型必输参数说明VIN车架号stri ngY输出参数参数代码参数名称数据类型必输参数说明resp on seCode返回码intY参照返回值说明errorMessage错误信息stri ngN当请求异常时，将返回error 信息packageList套餐列表list<pac kage>N参照4.1.6当 responseCode 为 0 时，packageList 不为 空返回值说明序号respon seCodeerrorMessage说明10无218错误：VIN:%s不存在32错误：缺失必选参数：packageList，请

22、参考API文档499超时超时3.6 searchServiceStatus (TSS-ES接口名称searchServiceStatus调用方TSS服务方ES接口描述TSS通过VIN查询外部系统，获取到该VIN对应的当前服务状态信息URL/es/vehicle/V1/searchServiceStatus接口类型RESTFul内容格式JSON版本号V1请求方法POST输入参数参数代码参数名称数据类型必输参数说明VIN车架号stri ngY输出参数参数代码参数名称数据类型必输参数说明resp on seCode返回码intY参照返回值说明errorMessage错误信息stri ngN当请求异常

23、时，将返回error 信息serviceStatu s服务状态services tatusN参照4.1.4当 responseCode 为 0 时，serviceStatus不为空返回值说明序号respon seCodeerrorMessage说明10无218错误：VIN:%s不存在32错误：缺失必选参数：serviceStatus，请参考API文档499超时超时4附录4.1数据结构描述4.1.1 customerVHLData列表名customerVHLData客户对应车辆和服务状态信息集合No参数代码参数名称数据类型必选参数说明1NO序号intY2customerl n fo客户静态信息c

24、ustomerY参照4.1.23VHLI nfo车辆静态信息VHLI nfoY参照4.1.34serviceSta tus车辆服务状态信 息serviceSt atusY参照.2 customerl nfo列表名customerI nfo客户静态信息No参数代码参数名称数据类型必选参数说明1customerID客户IDstri ngN/Y当在TSS中创建客户时为 空，其他情况下，必须有 唯一数值2customerNa me客户名称stri ngY3ren ewalTim es续约次数intN4mobileNumber联系电话stri ngY5IDType证件类型intN1 :身

25、份证；2 :组织机构 代码证；3:护照；4 :军 官证6IDNumber证件号码stri ngN7gender客户性别intN1:男；2:女8own ership账号类型intY1:个人；2 :公司9homeNumber家庭电话stri ngN10bacKUpNumb er1备用电话1stri ngN11bacKUpNumb er2备用电话2stri ngN12email邮箱stri ngN13emerge ncyC on tact紧急联系人stri ngN14emerge ncyC on tactNumb er紧急联系人电话stri ngN15wechat微信号stri ngN16compa

26、 ny Name公司名称stri ngN/Y当账号类型为公司时，该 字段为必输字段17compa nyNum ber公司电话stri ngN/Y当账号类型为公司时，该 字段为必输字段18compa ny Address公司地址stri ngN/Y当账号类型为公司时，该 字段为必输字段4.1.3 VHLI nfo列表名VHLI nfo 车辆静态信息No参数代码参数名称数据类型必选参数说明1VIN车架号stri ngY2OEM厂商stri ngY3Band品牌stri ngY4Series车系stri ngY5Type车型stri ngY6Color颜色stri ngY7dealerName经销商

27、名称stri ngY8dealerPh on eNumber经销商电话stri ngY9dealerAddr ess经销商地址stri ngY10Lice nse车牌号stri ngN11MDN车载电话stri ngN12PurcaseDat e购买时间datetimeYYYYY/MM/DD4.1.4 serviceStatus列表名serviceStatus车辆服务状态信息No参数代码参数名称数据类型必选参数说明1isFreeServ ice是否处于免费服务期intY1:在;2:不在2rema iningS erviceDate服务到期时间datetimeYYYYY/MM/DD3activeProd uct当前套餐名称stri ngY4dataUsed当月花费流量intY单位:GB5minu tesUse d当月花费分钟数intY单