api接口文档
-
2023年3月5日发(作者：珍惜粮食拒绝浪费)API数据服务接口开发指南
2四键信息
Target-S
外部接口说明书
Target-S外部接口说明书
3四键信息
上海四键信息技术
FourthButton,Inc.
日期:2016-05-19
变更记录
序号说明变更人时间
4四键信息
5四键信息
6四键信息
1四键信息
1引言
1.1概述
略
1.2名词缩写及定义
名词缩
写
定义
VIN
17位国际VIN码规则
TSSTarget-SSystem
TSMTarget-SModel
CCA
外部系统，用于拨打电话给客户的系
统
FTP
Monitor
文件监视器，用于监测文件夹中是否
存在文件，如果存在文件，则读取文
件内容并通知TSS做相应处理
ES
ExternalSystem外部系统
1.3历史变更
序
号
说明变更人时间
Target-S外部接口说明书
2四键信息
1
2
3
4
5
Target-S外部接口说明书
3四键信息
2开发规范
2.1通信方式
1）业务请求是HTTP协议请求，客户端以POST
方式发送到服务平台。
2）参数名称和参数说明中规定的固定值必须
与列表中完全一致（大小写敏感）。
3）目前接口支持签名方法：MD5的签名。
2.2接口说明
2.2.1返回参数
通用返回数据格式：
字段名类型是
否
必
输
说明
responseCodeStringY
请求操作相应码。
操作成功返回0，
操作失败响应码见
Target-S外部接口说明书
4四键信息
通用响应码说明
errorMessageStringN
当responseCode
不为0时，该参数
不能为空，返回操
作失败原因
2.2.2通用返回码说明
响应码说明
0
成功（接收成功、执行成功）
1
失败（接收失败、执行失败、拨打
失败）
2
错误：缺失必选参数：%s，请参考
API文档
3
错误：参数%s：%s存在非法字符，
请参考API文档例如：“参数VIN：
123￥DFG9871SER~23存在非法字
符。”
4
错误：参数%s：%s位数不正确，请
参考API文档
5
错误：结束时间小于开始时间，请
参考API文档
Target-S外部接口说明书
5四键信息
6
错误：开始时间大于当前时间，请
参考API文档
7
错误：参数%s：%s大于%s，请参考
API文档
8
错误：参数%s：%s不存在，请参考
API文档
9
错误：序号%s中缺失必选参数：%s，
请参考API文档
10
错误：序号%s中参数%s：%s存在
非法字符，请参考API文档例如：
“参数VIN：123￥DFG9871SER~23
存在非法字符。”
11
错误：序号%s中参数%s：%s位数
不正确，请参考API文档
12
错误：序号%s参数%s：%s大于%s，
请参考API文档
13
错误：序号%s参数%s：%s不存在，
请参考API文档
14
错误：序号%s中参数%s：%s格式
错误，请参考API文档
15
错误：预计总数：%s，实际总数%s，
Target-S外部接口说明书
6四键信息
请检查
16
错误：号码%s为空号
17
错误：号码%s无人接听
18
错误：%s:%s不存在
19
错误：参数%s：%s格式错误，请参
考API文档
99
超时
Target-S外部接口说明书
7四键信息
3数据服务接口
3.1importCustomerAndVHLData（FTPMonitor-TSS）
接口
名称
importCustom
erAndVHLData
调用
方
FTP
Moni
tor
服
务
方
TSS
接口
描述
监视器监控某个指定文件夹，如果有文
件，则读取文件，并调用该接口，将客
户数据和对应的车辆数据存储到TSS数
据库中
URL
/tss/importData/V1/importCustom
erAndVHLData
接口
类型
RESTFul
内容
格式
JSON
版本
号
V1
请求
方法
POST
输入
参数
参数代
码
参数
名称
数据
类型
必
输
参数说明
total
总数
intY
客户和车辆
配对总计
Target-S外部接口说明书
8四键信息
custom
erVHLD
ataLis
t
客户、
车辆、
服务
状态
信息
列表
List
tome rVHL Data > Y 数据类型参 照4.1.1 输出 参数 参数代 码 参数 名称 数据 类型 必 输 参数说明 respon seCode 返回 码 intY 参照返回值 说明 errorM essage 错误 信息 stri ng N 当请求异常 时，将返回 error信息 返回值说明 序 号 respon seCode errorMessa ge 说明 10 无 22 错误：缺失必 选参数： count 缺失count Target-S外部接口说明书 9四键信息 32 错误：缺失必 选参数： customerVH LList 缺失 customerVHLLis t 42 错误：缺失必 选参数：NO 缺失NO 53 错误：参数 NO：%s存在 非法字符，请 参考API文 档 参数NO为全数字 组成 69 错误：序号%s 中缺失必选 参数： customerIn fo 79 错误：序号%s 中缺失必选 参数： customerNa me customerInfo中 的所有必输项相 同，都有缺失必选 项参数错误 Target-S外部接口说明书 10四键信息 810 错误：序号%s 中参数 ownership ：%s存在非 法字符，请参 考API文档 ownership范围如下： 1：个人；2：公司 910 错误：序号%s 中参数 IDType：%s 存在非法字 符，请参考 API文档 IDType范围如下： 1：身份证；2：组 织机构代码证；3： 护照；4：军官证 109 错误：序号%s 中缺失必选 参数： VHLInfo 119 错误：序号%s 中缺失必选 参数：VIN VHLInfo中的所有 必输项相同，都有 缺失必选项参数错 误 1210 错误：序号%s参数VIN值由字母 Target-S外部接口说明书 11四键信息 中参数 VIN：%s存在 非法字符，请 参考API文 档 和数字组成 1311 错误：序号%s 中参数 VIN：%s位数 不正确，请参 考API文档 定义长度为17位 1413 错误：序号%s 参数OEM：%s 不存在，请参 考API文档 VHLInfo中Band、 Series、Type、 Color、 dealerName与 OEM相同，都有不 存在错误 1514 错误：序号%s 中参数 PurcaseDat e：%s格式错 误，请参考 格式为 YYYY/MM/DD Target-S外部接口说明书 12四键信息 API文档 169 错误：序号%s 中缺失必选 参数： serviceSta tus 179 错误：序号%s 中缺失必选 参数： isFreeServ ice serviceStatus 中的所有必输项相 同，都有缺失必选 项参数错误 1810 错误：序号%s 中参数 isFreeServ ice：%s存在 非法字符，请 参考API文 档 参数 isFreeService 必须数字 serviceStatus 中所有int类型的 数据都有此错误 1914 错误：序号%s 中参数 remainingS 格式为 YYYY/MM/DD Target-S外部接口说明书 13四键信息 3.2createLeads（TSS-TSM） erviceDate ：%s格式错 误，请参考 API文档 2015 错误：预计总 数： [total]，实 际总数： [customerV HLDataList .size()]， 请检查 例： 错误：预计总数： 1000，实际总数： 990，请检查 2199 超时超时 接口 名称 createLeads 调用 方 TSS 服 务 方 TSM 接口 描述 TSS将最新的客户静态信息、车辆静态 信息和车辆服务状态信息导入到TSM， 生成对应的Leads Target-S外部接口说明书 14四键信息 URL /tsm/createLeads/V1/createLeads 接口 类型 RESTFul 内容 格式 JSON 版本 号 V1 请求 方法 POST 输入 参数 参数代 码 参数 名称 数据 类型 必 输 参数说明 total 总数 intY 需要生成 Leads的总 数 custom erVHLL ist 客户、 车辆、 服务 状态 信息 列表 List tome rVHL Data > Y 数据类型参 照4.1.1 输出 参数 参数代 码 参数 名称 数据 类型 必 输 参数说明 respon seCode 返回 码 intY 参照返回值 说明 errorM 错误 striN 当请求异常 Target-S外部接口说明书 15四键信息 essage 信息 ng 时，将返回 error信息 total 生成 Lead s总 数 intY 若为异常， 则total为 0 leadsL ist 对应 的 Lead s信 息 List dsIn fo> N 数据类型参 照4.1.5 返回值说明 序 号 respon seCode errorMessa ge 说明 10 无 22 错误：缺失必 选参数： count 缺失count 32 错误：缺失必 选参数： 缺失 customerVHLLis Target-S外部接口说明书 16四键信息 customerVH LList t 42 错误：缺失必 选参数：NO 缺失NO 53 错误：参数 NO：%s存在 非法字符，请 参考API文 档 参数NO为全数字 组成 69 错误：序号%s 中缺失必选 参数： customer 79 错误：序号%s 中缺失必选 参数： customerNa me customer中的所 有必输项相同，都 有缺失必选项参数 错误 810 错误：序号%s 中参数 ownership ownership范围如下： 1：个人；2：公司 Target-S外部接口说明书 17四键信息 ：%s存在非 法字符，请参 考API文档 910 错误：序号%s 中参数 IDType：%s存在 非法字符，请 参考API文 档 IDType范围如下： 1：身份证；2：组 织机构代码证；3： 护照；4：军官证 109 错误：序号%s 中缺失必选 参数： VHLInfo 119 错误：序号%s 中缺失必选 参数：VIN VHLInfo中的所有 必输项相同，都有 缺失必选项参数错 误 1210 错误：序号%s 中参数 VIN：%s存在 非法字符，请 参数VIN值由字母 和数字组成 Target-S外部接口说明书 18四键信息 参考API文 档 1311 错误：序号%s 中参数 VIN：%s位数 不正确，请参 考API文档 定义长度为17位 1413 错误：序号%s 参数OEM：%s 不存在，请参 考API文档 VHLInfo中Band、 Series、Type、 Color、 dealerName与 OEM相同，都有不 存在错误 1514 错误：序号%s 中参数 PurcaseDat e：%s格式错 误，请参考 API文档 格式为 YYYY/MM/DD 169 错误：序号%s 中缺失必选 Target-S外部接口说明书 19四键信息 参数： serviceSta tus 179 错误：序号%s 中缺失必选 参数： isFreeServ ice serviceStatus 中的所有必输项相 同，都有缺失必选 项参数错误 1810 错误：序号%s 中参数 isFreeServ ice：%s存在 非法字符，请 参考API文 档 参数 isFreeService 必须数字 serviceStatus 中所有int类型的 数据都有此错误 1914 错误：序号%s 中参数 remainingS erviceDate ：%s格式错 误，请参考 格式为 YYYY/MM/DD Target-S外部接口说明书 20四键信息 3.3callTheCustomer(TSS-CCA) API文档 2015 错误：预计总 数： [total]，实 际总数： [customerV HLDataList .size()]， 请检查 例： 错误：预计总数： 1000，实际总数： 990，请检查 2199 超时超时 接口 名称 callTheCusto mer 调用 方 TSS 服 务 方 CCA 接口 描述 将TSS中的客户电话传输到CCA，触发 CCA拨打电话给客户 URL /cca/cti/V1/callTheCustomer 接口 类型 RESTFul 内容 格式 JSON 版本 V1 请求 POST Target-S外部接口说明书 21四键信息 号方法 输入 参数 参数代 码 参数 名称 数据 类型 必 输 参数说明 VIN 车架 号 stri ng Y callNu mber 电话 号码 stri ng Y 需要拨打的 电话号码 输出 参数 参数代 码 参数 名称 数据 类型 必 输 参数说明 respon seCode 返回 码 intY 参照返回值 说明 errorM essage 错误 信息 stri ng N 当请求异常 时，将返回 error信息 返回值说明 序 号 respon seCode errorMessa ge 说明 10 无 22 错误：缺失必 选参数：VIN 缺失VIN Target-S外部接口说明书 22四键信息 3.4fishTheCall（CCA-TSS） 32 错误：缺失必 选参数： callNumber 缺失callNumber 43 错误：参数 callNumber ：%s存在非 法字符，请参 考API文档 电话号码存在～！ @#￥%&×（）等非 法字符 516 错误：号码%s 为空号 617 错误：号码%s 无人接听 799 超时超时 接口 名称 fishTheCall 调用 方 CCA 服 务 方 TSS 接口 描述 销售与客户交流结束后，将通话开始时 间、结束时间返回给TSS URL /tss/cti/V1/fishTheCall Target-S外部接口说明书 23四键信息 接口 类型 RESTFul 内容 格式 JSON 版本 号 V1 请求 方法 POST 输入 参数 参数代 码 参数 名称 数据 类型 必 输 参数说明 VIN 车架 号 stri ng Y callNu mber 电话 号码 stri ng Y 需要拨打的 电话号码 startD ate 通话 开始 时间 date time Y YYYY/MM/D DHH:mm:SS endDat e 通话 开始 结束 时间 date time Y YYYY/MM/D DHH:mm:SS 输出 参数 参数代 码 参数 名称 数据 类型 必 输 参数说明 respon seCode 返回 码 intY 参照返回值 说明 Target-S外部接口说明书 24四键信息 errorM essage 错误 信息 stri ng N 当请求异常 时，将返回 error信息 返回值说明 序 号 respon seCode errorMessa ge 说明 10 无 22 错误：缺失必 选参数：VIN 缺失VIN 32 错误：缺失必 选参数： callNumber 缺失callNumber 42 错误：缺失必 选参数： startDate 缺失startDate 52 错误：缺失必 选参数： endDate 缺失endDate 618 错误：VIN:%s 不存在 Target-S外部接口说明书 25四键信息 3.5searchPastPackage（TSS-ES） 73 错误：参数 callNumber ：%s存在非 法字符，请参 考API文档 电话号码存在～！ @#￥%&×（）等非 法字符 819 错误：参数 startDate ：%s格式错 误，请参考 API文档 YYYY/MM/DD HH:mm:SS 919 错误：参数 endDate：%s 格式错误，请 参考API文 档 YYYY/MM/DD HH:mm:SS 1099 超时超时 接口 名称 searchPastPa ckage 调用 方 TSS 服 务 方 ES Target-S外部接口说明书 26四键信息 接口 描述 TSS通过VIN查询外部系统，获取到该 VIN对应的历史套餐列表 URL /es/vehicle/V1/searchPastPackag e 接口 类型 RESTFul 内容 格式 JSON 版本 号 V1 请求 方法 POST 输入 参数 参数代 码 参数 名称 数据 类型 必 输 参数说明 VIN 车架 号 stri ng Y 输出 参数 参数代 码 参数 名称 数据 类型 必 输 参数说明 respon seCode 返回 码 intY 参照返回值 说明 errorM essage 错误 信息 stri ng N 当请求异常 时，将返回 error信息 packag eList 套餐 列表 list N 参照4.1.6 当 Target-S外部接口说明书 27四键信息 3.6searchServiceStatus（TSS-ES） kage > responseC ode为0时， packageLi st不为空 返回值说明 序 号 respon seCode errorMessa ge 说明 10 无 218 错误：VIN:%s 不存在 32 错误：缺失必 选参数： packageLis t，请参考 API文档 499 超时超时 接口 名称 searchServic eStatus 调用 方 TSS 服 务 ES Target-S外部接口说明书 28四键信息 方 接口 描述 TSS通过VIN查询外部系统，获取到该 VIN对应的当前服务状态信息 URL /es/vehicle/V1/searchServiceSta tus 接口 类型 RESTFul 内容 格式 JSON 版本 号 V1 请求 方法 POST 输入 参数 参数代 码 参数 名称 数据 类型 必 输 参数说明 VIN 车架 号 stri ng Y 输出 参数 参数代 码 参数 名称 数据 类型 必 输 参数说明 respon seCode 返回 码 intY 参照返回值 说明 errorM essage 错误 信息 stri ng N 当请求异常 时，将返回 error信息 servic 服务 servN 参照4.1.4 Target-S外部接口说明书 29四键信息 eStatu s 状态 iceS tatu s 当 responseC ode为0时， serviceSt atus不为 空 返回值说明 序 号 respon seCode errorMessa ge 说明 10 无 218 错误：VIN:%s 不存在 32 错误：缺失必 选参数： serviceSta tus，请参考 API文档 499 超时超时 Target-S外部接口说明书 30四键信息 4附录 4.1数据结构描述 4.1.1customerVHLData 列表名 customerVHLData客户对应车辆 和服务状态信息集合 No 参数 代码 参数名称 数据 类型 必 选 参数说明 1NO 序号 intY 2 custo merIn fo 客户静态 信息 cust omer Y 参照4.1.2 3 VHLIn fo 车辆静态 信息 VHLI nfo Y 参照4.1.3 4 servi ceSta tus 车辆服务 状态信息 serv iceS tatu s Y 参照4.1.4 Target-S外部接口说明书 31四键信息 4.1.2customerInfo 列表名customerInfo客户静态信息 No 参数 代码 参数名称 数据 类型 必 选 参数说明 1 custo merID 客户ID stri ng N/ Y 当在TSS中创 建客户时为 空，其他情况 下，必须有唯 一数值 2 custo merNa me 客户名称 stri ng Y 3 renew alTim es 续约次数intN 4 mobil eNumb er 联系电话 stri ng Y 5 IDTyp e 证件类型intN 1：身份证；2： 组织机构代 码证；3：护 Target-S外部接口说明书 32四键信息 照；4：军官 证 6 IDNum ber 证件号码 stri ng N 7 gende r 客户性别intN 1：男；2：女 8 owner ship 账号类型intY 1：个人；2： 公司 9 homeN umber 家庭电话 stri ng N 10 bacKU pNumb er1 备用电话1 stri ng N 11 bacKU pNumb er2 备用电话2 stri ng N 12email邮箱 stri ng N 13 emerg encyC ontac 紧急联系人 stri ng N Target-S外部接口说明书 33四键信息 t 14 emerg encyC ontac tNumb er 紧急联系人电话 stri ng N 15 wecha t 微信号 stri ng N 16 compa nyNam e 公司名称 stri ng N/ Y 当账号类型 为公司时，该 字段为必输 字段 17 compa nyNum ber 公司电话 stri ng N/ Y 当账号类型 为公司时，该 字段为必输 字段 18 compa nyAdd ress 公司地址 stri ng N/ Y 当账号类型 为公司时，该 字段为必输 字段 Target-S外部接口说明书 34四键信息 4.1.3VHLInfo 列表名VHLInfo车辆静态信息 No 参数 代码 参数名称 数据 类型 必 选 参数说明 1VIN车架号 stri ng Y 2OEM厂商 stri ng Y 3Band品牌 stri ng Y 4 Serie s 车系 stri ng Y 5Type车型 stri ng Y 6Color颜色 stri ng Y 7 deale rName 经销商名称 stri ng Y 8 deale rPhon eNumb 经销商电话 stri ng Y Target-S外部接口说明书 35四键信息 er 9 deale rAddr ess 经销商地址 stri ng Y 10 Licen se 车牌号 stri ng N 11MDN车载电话 stri ng N 12 Purca seDat e 购买时间 date time YYYYY/MM/DD 4.1.4serviceStatus 列表名 serviceStatus车辆服务状态信 息 No 参数 代码 参数名称 数据 类型 必 选 参数说明 1 isFre eServ ice 是否处于免费服务期intY 1：在；2：不 在 2remai服务到期时间dateYYYYY/MM/DD Target-S外部接口说明书 36四键信息 ningS ervic eDate time 3 activ eProd uct 当前套餐名称 stri ng Y 4 dataU sed 当月花费流量intY 单位:GB 5 minut esUse d 当月花费分钟数intY 单位：分钟 6 POISe arch POI搜索次数intY 7 remot eLock _unlo ck 远程解闭锁次数intY 8 autoA lert 自动报警次数intY 9 roads ideAs 道路救援次数intY Target-S外部接口说明书 37四键信息 sista nce 10 emerg encyA ssist ance 紧急救援次数intY 11 ACRAs sista nce 碰撞自动救援次数intY 12 desti natio nDown loads 目的地下载次数intY 13 parki ngInd icati on 停车位置提示次数intY 14 remot eHorn ingFl ashin 闪灯鸣笛次数intY Target-S外部接口说明书 38四键信息 g 15SVT被盗车辆跟踪次数intY 16 trave lCons ultat ion 旅游咨询次数intY 17 sendT oCar 发送到车次数intY 4.1.5leadsInfo 列表名leadsInfo对应leads信息 No 参数 代码 参数名称 数据 类型 必 选 参数说明 1 leads ID Leads ID stri ng Y 2 VINVIN stri ng Y 3 custo merID 客户ID stri ng Y 4 leads Statu Leads状 态 intY 1：待分配；2： 新建；3：执 Target-S外部接口说明书 39四键信息 s 行中；4：关 闭 5 renew alPos sibil ity 续约指数 stri ng Y 6 custo merSt atusL V1 一级客户 状态 stri ng N 7 custo merSt atusL V2 二级客户 状态 stri ng N 8 leads Owner Leads归 属 stri ng N 用户ID 4.1.6package 列表名package套餐信息 No 参数 代码 参数名称 数据 类型 必 选 参数说明 Target-S外部接口说明书 40四键信息 1 packa geNam e 套餐名称 stri ng Y 2 start Date 套餐开始 时间 stri ng Y 3 endDa te 套餐结束 时间 stri ng Y 4.2HTTP返回值处理策略 HTTPCode错误说明处置策略 302 重定向不会出现 401 认证失败 403 没权限 404 资源找不到重试 500 资源服务器错误重试 503 资源暂时不可用重试 响应超时时间：20秒 连接超时时间：20秒 重试策略：等待30秒后重试，无限次数重试 最大并发线程：50个