API数据服务接口开发指南.docx
《API数据服务接口开发指南.docx》由会员分享，可在线阅读，更多相关《API数据服务接口开发指南.docx（23页珍藏版）》请在冰点文库上搜索。
API数据服务接口开发指南
Target-S
外部接口说明书
上海四键信息技术
FourthButton,Inc.
日期:
2016-05-19
变更记录
序号
说明
变更人
时间
1引言
1.1概述
略
1.2名词缩写及定义
名词缩写
定义
VIN
17位国际VIN码规则
TSS
Target-SSystem
TSM
Target-SModel
CCA
外部系统，用于拨打电话给客户的系统
FTPMonitor
文件监视器，用于监测文件夹中是否存在文件，如果存在文件，则读取文件内容并通知TSS做相应处理
ES
ExternalSystem外部系统
1.3历史变更
序号
说明
变更人
时间
1
2
3
4
5
2开发规范
2.1通信方式
1）业务请求是HTTP协议请求，客户端以POST方式发送到服务平台。
2）参数名称和参数说明中规定的固定值必须与列表中完全一致（大小写敏感）。
3）目前接口支持签名方法：
MD5的签名。
2.2接口说明
2.2.1返回参数
通用返回数据格式：
字段名
类型
是否必输
说明
responseCode
String
Y
请求操作相应码。
操作成功返回0，操作失败响应码见通用响应码说明
errorMessage
String
N
当responseCode不为0时，该参数不能为空，返回操作失败原因
2.2.2通用返回码说明
响应码
说明
0
成功（接收成功、执行成功）
1
失败（接收失败、执行失败、拨打失败）
2
错误：
缺失必选参数：
%s，请参考API文档
3
错误：
参数%s：
%s存在非法字符，请参考API文档例如：
“参数VIN：
123￥DFG9871SER~23存在非法字符。
”
4
错误：
参数%s：
%s位数不正确，请参考API文档
5
错误：
结束时间小于开始时间，请参考API文档
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，请检查
16
错误：
号码%s为空号
17
错误：
号码%s无人接听
18
错误：
%s:
%s不存在
19
错误：
参数%s：
%s格式错误，请参考API文档
99
超时
3数据服务接口
3.1importCustomerAndVHLData（FTPMonitor-TSS）
接口名称
importCustomerAndVHLData
调用方
FTPMonitor
服务方
TSS
接口描述
监视器监控某个指定文件夹，如果有文件，则读取文件，并调用该接口，将客户数据和对应的车辆数据存储到TSS数据库中
URL
/tss/importData/V1/importCustomerAndVHLData
接口类型
RESTFul
内容格式
JSON
版本号
V1
请求方法
POST
输入参数
参数代码
参数名称
数据类型
必输
参数说明
total
总数
int
Y
客户和车辆配对总计
customerVHLDataList
客户、车辆、服务状态信息列表
List
Y
数据类型参照4.1.1
输出参数
参数代码
参数名称
数据类型
必输
参数说明
responseCode
返回码
int
Y
参照返回值说明
errorMessage
错误信息
string
N
当请求异常时，将返回error信息
返回值说明
序号
responseCode
errorMessage
说明
1
0
无
2
2
错误：
缺失必选参数：
count
缺失count
3
2
错误：
缺失必选参数：
customerVHLList
缺失customerVHLList
4
2
错误：
缺失必选参数：
NO
缺失NO
5
3
错误：
参数NO：
%s存在非法字符，请参考API文档
参数NO为全数字组成
6
9
错误：
序号%s中缺失必选参数：
customerInfo
7
9
错误：
序号%s中缺失必选参数：
customerName
customerInfo中的所有必输项相同，都有缺失必选项参数错误
8
10
错误：
序号%s中参数ownership：
%s存在非法字符，请参考API文档
ownership范围如下：
1：
个人；2：
公司
9
10
错误：
序号%s中参数IDType：
%s存在非法字符，请参考API文档
IDType范围如下：
1：
身份证；2：
组织机构代码证；3：
护照；4：
军官证
10
9
错误：
序号%s中缺失必选参数：
VHLInfo
11
9
错误：
序号%s中缺失必选参数：
VIN
VHLInfo中的所有必输项相同，都有缺失必选项参数错误
12
10
错误：
序号%s中参数VIN：
%s存在非法字符，请参考API文档
参数VIN值由字母和数字组成
13
11
错误：
序号%s中参数VIN：
%s位数不正确，请参考API文档
定义长度为17位
14
13
错误：
序号%s参数OEM：
%s不存在，请参考API文档
VHLInfo中Band、Series、Type、Color、dealerName与OEM相同，都有不存在错误
15
14
错误：
序号%s中参数PurcaseDate：
%s格式错误，请参考API文档
格式为YYYY/MM/DD
16
9
错误：
序号%s中缺失必选参数：
serviceStatus
17
9
错误：
序号%s中缺失必选参数：
isFreeService
serviceStatus中的所有必输项相同，都有缺失必选项参数错误
18
10
错误：
序号%s中参数isFreeService：
%s存在非法字符，请参考API文档
参数isFreeService必须数字
serviceStatus中所有int类型的数据都有此错误
19
14
错误：
序号%s中参数remainingServiceDate：
%s格式错误，请参考API文档
格式为YYYY/MM/DD
20
15
错误：
预计总数：
[total]，实际总数：
[customerVHLDataList.size（）]，请检查
例：
错误：
预计总数：
1000，实际总数：
990，请检查
21
99
超时
超时
3.2createLeads（TSS-TSM）
接口名称
createLeads
调用方
TSS
服务方
TSM
接口描述
TSS将最新的客户静态信息、车辆静态信息和车辆服务状态信息导入到TSM，生成对应的Leads
URL
/tsm/createLeads/V1/createLeads
接口类型
RESTFul
内容格式
JSON
版本号
V1
请求方法
POST
输入参数
参数代码
参数名称
数据类型
必输
参数说明
total
总数
int
Y
需要生成Leads的总数
customerVHLList
客户、车辆、服务状态信息列表
List
Y
数据类型参照4.1.1
输出参数
参数代码
参数名称
数据类型
必输
参数说明
responseCode
返回码
int
Y
参照返回值说明
errorMessage
错误信息
string
N
当请求异常时，将返回error信息
total
生成Leads总数
int
Y
若为异常，则total为0
leadsList
对应的Leads信息
List
N
数据类型参照4.1.5
返回值说明
序号
responseCode
errorMessage
说明
1
0
无
2
2
错误：
缺失必选参数：
count
缺失count
3
2
错误：
缺失必选参数：
customerVHLList
缺失customerVHLList
4
2
错误：
缺失必选参数：
NO
缺失NO
5
3
错误：
参数NO：
%s存在非法字符，请参考API文档
参数NO为全数字组成
6
9
错误：
序号%s中缺失必选参数：
customer
7
9
错误：
序号%s中缺失必选参数：
customerName
customer中的所有必输项相同，都有缺失必选项参数错误
8
10
错误：
序号%s中参数ownership：
%s存在非法字符，请参考API文档
ownership范围如下：
1：
个人；2：
公司
9
10
错误：
序号%s中参数IDType：
%s存在非法字符，请参考API文档
IDType范围如下：
1：
身份证；2：
组织机构代码证；3：
护照；4：
军官证
10
9
错误：
序号%s中缺失必选参数：
VHLInfo
11
9
错误：
序号%s中缺失必选参数：
VIN
VHLInfo中的所有必输项相同，都有缺失必选项参数错误
12
10
错误：
序号%s中参数VIN：
%s存在非法字符，请参考API文档
参数VIN值由字母和数字组成
13
11
错误：
序号%s中参数VIN：
%s位数不正确，请参考API文档
定义长度为17位
14
13
错误：
序号%s参数OEM：
%s不存在，请参考API文档
VHLInfo中Band、Series、Type、Color、dealerName与OEM相同，都有不存在错误
15
14
错误：
序号%s中参数PurcaseDate：
%s格式错误，请参考API文档
格式为YYYY/MM/DD
16
9
错误：
序号%s中缺失必选参数：
serviceStatus
17
9
错误：
序号%s中缺失必选参数：
isFreeService
serviceStatus中的所有必输项相同，都有缺失必选项参数错误
18
10
错误：
序号%s中参数isFreeService：
%s存在非法字符，请参考API文档
参数isFreeService必须数字
serviceStatus中所有int类型的数据都有此错误
19
14
错误：
序号%s中参数remainingServiceDate：
%s格式错误，请参考API文档
格式为YYYY/MM/DD
20
15
错误：
预计总数：
[total]，实际总数：
[customerVHLDataList.size（）]，请检查
例：
错误：
预计总数：
1000，实际总数：
990，请检查
21
99
超时
超时
3.3callTheCustomer（TSS-CCA）
接口名称
callTheCustomer
调用方
TSS
服务方
CCA
接口描述
将TSS中的客户电话传输到CCA，触发CCA拨打电话给客户
URL
/cca/cti/V1/callTheCustomer
接口类型
RESTFul
内容格式
JSON
版本号
V1
请求方法
POST
输入参数
参数代码
参数名称
数据类型
必输
参数说明
VIN
车架号
string
Y
callNumber
电话号码
string
Y
需要拨打的电话号码
输出参数
参数代码
参数名称
数据类型
必输
参数说明
responseCode
返回码
int
Y
参照返回值说明
errorMessage
错误信息
string
N
当请求异常时，将返回error信息
返回值说明
序号
responseCode
errorMessage
说明
1
0
无
2
2
错误：
缺失必选参数：
VIN
缺失VIN
3
2
错误：
缺失必选参数：
callNumber
缺失callNumber
4
3
错误：
参数callNumber：
%s存在非法字符，请参考API文档
电话号码存在～！
@#￥%&×（）等非法字符
5
16
错误：
号码%s为空号
6
17
错误：
号码%s无人接听
7
99
超时
超时
3.4fishTheCall（CCA-TSS）
接口名称
fishTheCall
调用方
CCA
服务方
TSS
接口描述
销售与客户交流结束后，将通话开始时间、结束时间返回给TSS
URL
/tss/cti/V1/fishTheCall
接口类型
RESTFul
内容格式
JSON
版本号
V1
请求方法
POST
输入参数
参数代码
参数名称
数据类型
必输
参数说明
VIN
车架号
string
Y
callNumber
电话号码
string
Y
需要拨打的电话号码
startDate
通话开始时间
datetime
Y
YYYY/MM/DDHH:
mm:
SS
endDate
通话开始结束时间
datetime
Y
YYYY/MM/DDHH:
mm:
SS
输出参数
参数代码
参数名称
数据类型
必输
参数说明
responseCode
返回码
int
Y
参照返回值说明
errorMessage
错误信息
string
N
当请求异常时，将返回error信息
返回值说明
序号
responseCode
errorMessage
说明
1
0
无
2
2
错误：
缺失必选参数：
VIN
缺失VIN
3
2
错误：
缺失必选参数：
callNumber
缺失callNumber
4
2
错误：
缺失必选参数：
startDate
缺失startDate
5
2
错误：
缺失必选参数：
endDate
缺失endDate
6
18
错误：
VIN:
%s不存在
7
3
错误：
参数callNumber：
%s存在非法字符，请参考API文档
电话号码存在～！
@#￥%&×（）等非法字符
8
19
错误：
参数startDate：
%s格式错误，请参考API文档
YYYY/MM/DDHH:
mm:
SS
9
19
错误：
参数endDate：
%s格式错误，请参考API文档
YYYY/MM/DDHH:
mm:
SS
10
99
超时
超时
3.5searchPastPackage（TSS-ES）
接口名称
searchPastPackage
调用方
TSS
服务方
ES
接口描述
TSS通过VIN查询外部系统，获取到该VIN对应的历史套餐列表
URL
/es/vehicle/V1/searchPastPackage
接口类型
RESTFul
内容格式
JSON
版本号
V1
请求方法
POST
输入参数
参数代码
参数名称
数据类型
必输
参数说明
VIN
车架号
string
Y
输出参数
参数代码
参数名称
数据类型
必输
参数说明
responseCode
返回码
int
Y
参照返回值说明
errorMessage
错误信息
string
N
当请求异常时，将返回error信息
packageList
套餐列表
list
N
参照4.1.6
当responseCode为0时，packageList不为空
返回值说明
序号
responseCode
errorMessage
说明
1
0
无
2
18
错误：
VIN:
%s不存在
3
2
错误：
缺失必选参数：
packageList，请参考API文档
4
99
超时
超时
3.6searchServiceStatus（TSS-ES）
接口名称
searchServiceStatus
调用方
TSS
服务方
ES
接口描述
TSS通过VIN查询外部系统，获取到该VIN对应的当前服务状态信息
URL
/es/vehicle/V1/searchServiceStatus
接口类型
RESTFul
内容格式
JSON
版本号
V1
请求方法
POST
输入参数
参数代码
参数名称
数据类型
必输
参数说明
VIN
车架号
string
Y
输出参数
参数代码
参数名称
数据类型
必输
参数说明
responseCode
返回码
int
Y
参照返回值说明
errorMessage
错误信息
string
N
当请求异常时，将返回error信息
serviceStatus
服务状态
serviceStatus
N
参照4.1.4
当responseCode为0时，serviceStatus不为空
返回值说明
序号
responseCode
errorMessage
说明
1
0
无
2
18
错误：
VIN:
%s不存在
3
2
错误：
缺失必选参数：
serviceStatus，请参考API文档
4
99
超时
超时
4附录
4.1数据结构描述
4.1.1customerVHLData
列表名
customerVHLData客户对应车辆和服务状态信息集合
No
参数代码
参数名称
数据类型
必选
参数说明
1
NO
序号
int
Y
2
customerInfo
客户静态信息
customer
Y
参照4.1.2
3
VHLInfo
车辆静态信息
VHLInfo
Y
参照4.1.3
4
serviceStatus
车辆服务状态信息
serviceStatus
Y
参照4.1.4
4.1.2customerInfo
列表名
customerInfo客户静态信息
No
参数代码
参数名称
数据类型
必选
参数说明
1
customerID
客户ID
string
N/Y
当在TSS中创建客户时为空，其他情况下，必须有唯一数值
2
customerName
客户名称
string
Y
3
renewalTimes
续约次数
int
N
4
mobileNumber
联系电话
string
Y
5
IDType
证件类型
int
N
1：
身份证；2：
组织机构代码证；3：
护照；4：
军官证
6
IDNumber
证件号码
string
N
7
gender
客户性别
int
N
1：
男；2：
女
8
ownership
账号类型
int
Y
1：
个人；2：
公司
9
homeNumber
家庭电话
string
N
10
bacKUpNumber1
备用电话1
string
N
11
bacKUpNumber2
备用电话2
string
N
12
email
邮箱
string
N
13
emergencyContact
紧急联系人
string
N
14
emergencyContactNumber
紧急联系人电话
string
N
15
wechat
微信号
string
N
16
companyName
公司名称
string
N/Y
当账号类型为公司时，该字段为必输字段
17
companyNumber
公司电话
string
N/Y
当账号类型为公司时，该字段为必输字段
18
companyAddress
公司地址
string
N/Y
当账号类型为公司时，该字段为必输字段
4.1.3VHLInfo
列表名
VHLInfo车辆静态信息
No
参数代码
参数名称
数据类型
必选
参数说明
1
VIN
车架号
string
Y
2
OEM
厂商
string
Y
3
Band
品牌
string
Y
4
Series
车系
string
Y
5
Type
车型
string
Y
6
Color
颜色
string
Y
7
dealerName
经销商名称
string
Y
8
dealerPhoneNumber
经销商电话
string
Y
9
dealerAddress
经销商地址
string
Y
10
License
车牌号
string
N
11
MDN
车载电话
string
N
12
PurcaseDate
购买时间
datetime
Y
YYYY/MM/DD
4.1.4serviceStatus
列表名
serviceStatus车辆服务状态信息
No
参数代码
参数名称
数据类型
必选
参数说明
1
isFreeService
是否处于免费服务期
int
Y
1：
在；2：
不在
2
remainingServiceDate
服务到期时间
datetime
Y
YYYY/MM/DD
3
activeProduct
当前套餐名称
string
Y
4
dataUsed
当月花费流量
int
Y
单位:
GB
5
minutesUsed
当月花费分钟数
int
Y
单位：
分钟
6
POISearch
POI搜索次数
int
Y
7
remoteLock_unlock
远程解闭锁次数
int
Y
8
autoAlert
自动报警次数
int
Y
9
roadsideAssistance
道路救援次数
int
Y
10
emergencyAssistance
紧急救援次数
int
Y
11
ACRAssistance
碰撞自动救援次数
int
Y
12
升级会员 