API数据服务接口开发指南

1、四键信息FOURTHBUTTON.INCTarget-S外部接口说明书上海四键信息技术FourthButton,Inc.日期：2016-05-19变更记录序号说明变更人时间1 弓I言11.1 概述11.2 名词缩写及定义12 历史变更1开发规范22.1 通信方式22.2 接口说明2返回参数2通用返回码说明2数据服务接口4importCustomerAndVHLData(FTPMonitor-TSS)4createLeads(TSS-TSM5leads需要外部文件导入的，是修改leads状态码？错误！未定义书签。3 callTheCustomer(TSS-CCA)7fishTheCall(CCA

2、-TSS8附录113.1.1 数据结构描述11customerVHLData11customerInfo11VHLInfo12serviceStatus13leadsInfo133.2 HTTPB回值处理策略141引言1.1概述略1.2名词缩写及定义名词缩写定义VIN17位国际VIN码规则TSSTarget-SSystemTSMTarget-SModelCCA外部系统，用于拨打电话给客户的系统FTPMonitor文件监视器，用于监测文件夹中是否存在文件，如果存在文件，则读取文件内容并通知TSS做相应处理ESExternalSystem外部系统1.3历史变更序号说明变更人时间123452开发规范

3、2.1通信方式1）业务请求是HTTP协议请求，客户端以POSTT式发送到服务平台。2）参数名称和参数说明中规定的固定值必须与列表中完全一致（大小写敏感）3）目前接口支持签名方法：MD5W签名。2.2接口说明2.2.1返回参数通用返回数据格式：字段名类型是否必输:说明responseCodeStringY请求操作相应码。操作成功返回0,操作失败响应码见通用响应码说明errorMessageStringN当responseCode不为0时，该参数不能为空，返回操作失败原因2.2.2通用返回码说明响应码说明0成功（接收成功、执行成功）1失败（接收失败、执行失败、拨打失败）2错误：缺失必选参数:%s，

4、龄考API文档3错误：参数s：%s非法字符，请参考API文档例如：“参数VIN:123DFG9871SER23存在非法字符。”4错误参数s：%s位数和确，请参考API文档5错误结束时间小于开始时间，请参考API文档6错误开始时间大于当前时间，请参考API文档7错误参数s：%s大于s，伯考API文档8错误参数s：%s不存在，请参考API文档9错误序号$中缺失必选参数：s，龄考API文档10错误如：序号s中参数s：%s非法字符，请参考API文档例“参数VIN:123DFG9871SER23存在非法字符。”11错误序号s中参数%s：%s位数加确，请参考API文档12错误序号s参数s：%s大于s，龄考

5、API文档13错误序号s参数s：%s不存在，请参考API文档14错误序号s中参数s：%s格式错误，请参考API文档15错误预计总数：s,实际总数s,请检查16错误号码%$为空号17错误号码，无人接听18错误%s:%s不存在19错误参数s：%s格式错误，请参考API文档99超时3数据服务接口3.1 importCustomerAndVHLData(FTPMonitor-TSS)接口名称importCustomerAndVHLData调用方FTP服务方TSSMonitor接口描述监视器监控某个指定文件夹，如果有文件，则读取文件，并调用该接口，将客户数据和对应的车辆数据存储到TSS数据库中URL/t

6、ss/importData/V1/importCustomerAndVHLData接口类型RESTFul内容格式JSON版本号V1请求方法POST输入参数参数代码参数名称数据类型必输参数说明total总数intY客户和车辆配对总计customerVHLDataList客户、车辆、服务状态信息列表ListY数据类型参照4.1.1输出参数参数代码参数名称数据类型必输参数说明responseCode返回码intY参照返回值说明errorMessage错误信息stringN当请求异常时，将返回error信息返回值说明序号responseCodeerrorMessage说明10无22铅快：缺失必选参数：

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

8、Type范围如下：1:身份证；2:组织机构代码证；3:护照；4：军官证109错误：序号s中缺失必选参数：VHLInfo119错误：序号s中缺失必选参数：VINVHLInfo中的所有必输项相同，都有缺失必选项参数错误1210错误：序号%s中参数VIN:%$存在非法字符，龄考API文档参数VIN值由子母和数子组成1311错误：序号%s中参数VIN:%s位数不止确，请亲API文档定义长度为17位1413错误：序号s参数OEM%s不存在，请参考API文档VHLInfo中Band、Series、Type、Color、dealerName与OEMt目同，都有小存在错误1514错误：序号%s中参数Purca

9、seDate:%s格式错误，请参考API文档格式为YYYY/MM/DD169错误：序号s中缺失必选参数:serviceStatus179错误：序号s中缺失必选参数：isFreeServiceserviceStatus中的所有必输项相同，都有缺失必选项参数错误1810错误：序号%s中参数isFreeService:%s存在非法字符，请参考API文档参数isFreeService必须数字serviceStatus中所有int类型的数据都有此错误1914错误：序号%s中参数remainingServiceDate:%s格式#日快，清奔方API文档格式为YYYY/MM/DD2015错误：预计总数：to

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

11、客户、车辆、服务状态信息列表ListY数据类型参照4.1.1输出参数参数代码参数名称数据类型必输参数说明responseCode返回码intY参照返回值说明errorMessage错误信息stringN当请求异常时，将返回error信息total生成Leads总数intY右为异常，则total为0leadsList对应的Leads信息ListN数据类型参照4.1.5返回值说明序号responseCodeerrorMessage说明10无22铅快：缺失必选参数：count缺失count32铅快：缺失必选参数：customerVHLList缺失customerVHLList42错误：缺失必选参数：

12、NO缺失NO53错误：参数NO%s存在非法字符，请参考API文档参数NO为全数字组成69错误：序号s中缺失必选参数:customer79错误：序号s中缺失必选参数：customerNamecustomer中的所有必输项相同，都有缺失必选项参数错误810错误：序号%s中参数ownership:%s在非法字符，请参考API文档ownership范围如下:1:个人；2:公司910错误：序号%s中参数IDType:%s存在非法子符，龄考API文档IDType范围如下：1:身份证；2:组织机构代码证；3:护照；4:军官证109错误：序号s中缺失必选参数：VHLInfo119错误：序号s中缺失必选参数：V

13、INVHLInfo中的所有必输项相同，都有缺失必选项参数错误1210错误：序号%s中参数VIN:%$存在非法字符，龄考API文档参数VIN值由子母和数子组成1311错误：序号%s中参数VIN:%s位数不止确，请亲API文档定义长度为17位1413错误：序号s参数OEM%s不存在，请参考API文档VHLInfo中Band、Series、Type、Color、dealerName与OEMt目同，都有小存在错误1514错误：序号%s中参数PurcaseDate:%s格式错误，请参考API文档格式为YYYY/MM/DD169错误：序号s中缺失必选参数:serviceStatus179错误：序号s中缺失

14、必选参数：isFreeServiceserviceStatus中的所有必输项相同，都有缺失必选项参数错误1810错误：序号%s中参数isFreeService:%s存在非法字符，请参考API文档参数isFreeService必须数字serviceStatus中所有int类型的数据都有此错误1914错误：序号%s中参数remainingServiceDate:%s格式#日快，清奔方API文档格式为YYYY/MM/DD2015错误：预计总数：total,实际总数：customerVHLDataList.size(),请检查例：错误：预计总数：1000,实际总数：990,请检查2199超时超时3.3

15、 callTheCustomer(TSS-CCA)接口名称callTheCustomer调用方TSS服务方CCA接口描述将TSS中的客户电话传输到CCA触发CCA拨打电话给客户URL/cca/cti/V1/callTheCustomer接口类型RESTFul内容格式JSON版本号V1请求方法POST输入参数参数代码参数名称数据类型必输参数说明VIN车架号stringYcallNumber电话号码stringY需要拨打的电话号码输出参数参数代码参数名称数据类型必输参数说明responseCode返回码intY参照返回值说明errorMessage错误信息stringN当请求异常时，将返回erro

16、r信息返回值说明序号responseCodeerrorMessage说明10无22错误：缺失必选参数:VIN缺失VIN32错误：缺失必选参数：callNumber缺失callNumber43错误：参数callNumber:%s存在非法字符，请参考API文档电话号码存在！叔%&()等非法字符516错误：号码s为空号617错误：号码，无人接听799超时超时3.4 fishTheCall(CCA-TSS接口名称fishTheCall调用方CCA服务方TSS接口描述销售与客户交流结束后，将通话开始时间、结束时间返回给TSSURL/tss/cti/V1/fishTheCall接口类型RESTFul内容格

17、式JSON版本号V1请求方法POST输入参数参数代码参数名称数据类型必输参数说明VIN车架号stringYcallNumber电话号码stringY需要拨打的电话号码startDate通话开始时间datetimeYYYYY/MM/DDHH:mm:SSendDate通话开始结束时间datetimeYYYYY/MM/DDHH:mm:SS输出参数参数代码参数名称数据类型必输参数说明responseCode返回码intY参照返回值说明errorMessage错误信息stringN当请求异常时，将返回error信息返回值说明序号responseCodeerrorMessage说明10无22错误：缺失必选

18、参数:VIN缺失VIN32错误：缺失必选参数：callNumber缺失callNumber42错误：缺失必选参数：startDate缺失startDate52错误：缺失必选参数：endDate缺失endDate618错误：VIN:%s不存在73错误：参数callNumber:%s存在非法字符，请参考API文档电话号码存在！叔&()等非法字符819错误：参数YYYY/MM/DDHH:mm:SSstartDate:%s格式错误，请参考API文档919错误：参数endDate:%s格式错误，请参考API文档YYYY/MM/DDHH:mm:SS1099超时超时3.5 searchPastPackage

19、(TSS-ES接口名称searchPastPackage调用方TSS服务方ES接口描述TSS通过VIN查询外部系统，获取到该VIN对应的历史套餐列表URL/es/vehicle/V1/searchPastPackage接口类型RESTFul内容格式JSON版本号V1请求方法POST输入参数参数代码参数名称数据类型必输参数说明VIN车架号stringY输出参数参数代码参数名称数据类型必输参数说明responseCode返回码intY参照返回值说明errorMessage错误信息stringN当请求异常时，将返回error信息packageList套餐列表listN参照4.1.6当response

20、Code为0时，packageList不为空返回值说明序号responseCodeerrorMessage说明10无218错误：VIN:%s不存在32错误：缺失必选参数：packageList,请参考API文档499超时超时3.6 searchServiceStatus(TSS-ES接口名称searchServiceStatus调用方TSS服务方ES接口描述TSS通过VIN查询外部系统，获取到该VIN对应的当前服务状态信息URL/es/vehicle/V1/searchServiceStatus接口类型RESTFul内容格式JSON版本号V1请求方法POST输入参数参数代码参数名称数据类型必输

21、参数说明VIN车架号stringY输出参数参数代码参数名称数据类型必输参数说明responseCode返回码intY参照返回值说明errorMessage错误信息stringN当请求异常时，将返回error信息serviceStatus服务状态servicestatusN参照4.1.4当responseCode为0时,serviceStatus不为空返回值说明序号responseCodeerrorMessage说明10无218错误：VIN:%s不存在32错误：缺失必选参数：serviceStatus,请参考API文档499超时超时4.1.1 4附录4.1数据结构描述customerVHLDat

22、a列表名customerVHLData客户对应车辆和服务状态信息集合No参数代码参数名称数据类型必选参数说明1NO序号intY2customerinfo客户静态信息customerY参照4.1.23VHLInfo车辆静态信息VHLInfoY参照4.1.34serviceStatus车辆服务状态信息serviceStatusY参照.2 customerinfo列表名customerInfo客户静态信息No参数代码参数名称数据类型必选参数说明1customeriD客户IDstringN/Y当在TSS中创建客户时为空，其他情况下，必须有唯一数值2customerName客户名称str

23、ingY3renewalTimes续约次数intN4mobileNumber联系电话stringY5IDType证件类型intN1:身份证；2:组织机构代码证；3:护照；4:军官证6IDNumber证件号码stringN7gender客户性别intN1:男；2:女8ownership账号类型intY1:个人；2:公司9homeNumber家庭电话stringN10bacKUpNumber1备用电话1stringN11bacKUpNumber2备用电话2stringN12email邮箱stringN13emergencyContact紧急联系人stringN14emergencyContactN

24、umber紧急联系人电话stringN15wechat微信号stringN16companyName公司名称stringN/Y当账号类型为公司时，该字段为必输字段17companyNumber公司电话stringN/Y当账号类型为公司时，该字段为必输字段18companyAddress公司地址stringN/Y当账号类型为公司时，该字段为必输字段4.1.3 VHLInfo列表名VHLInfo车辆静态信息No参数代码参数名称数据类型必选参数说明1VIN车架号stringY2OEM厂商stringY3Band品牌stringY4Series车系stringY5Type车型stringY6Color

25、颜色stringY7dealerName经销商名称stringY8dealerPhoneNumber经销商电话stringY9dealerAddress经销商地址stringY10License车牌号stringN11MDN车载电话stringN12PurcaseDate购买时间datetimeYYYYY/MM/DD4.1.4 serviceStatus列表名serviceStatus车辆服务状态信息No参数代码参数名称数据类型必选参数说明1isFreeService是否处于免费服务期intY1:在；2:不在2remainingServiceDate服务到期时间datetimeYYYYY/MM/DD3activeProduct当前套餐名称stringY4dataUsed当月花费流量intY单位:GB5minutesUsed当月花费分钟数intY单位：分钟6POISearc