API数据服务接口开发指南.docx
《API数据服务接口开发指南.docx》由会员分享,可在线阅读,更多相关《API数据服务接口开发指南.docx(22页珍藏版)》请在冰豆网上搜索。
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
数据类型参照
输出参数
参数代码
参数名称
数据类型
必输
参数说明
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],实际总数:
[()],请检查
例:
错误:
预计总数:
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
数据类型参照
输出参数
参数代码
参数名称
数据类型
必输
参数说明
responseCode
返回码
int
Y
参照返回值说明
errorMessage
错误信息
string
N
当请求异常时,将返回error信息
total
生成Leads总数
int
Y
若为异常,则total为0
leadsList
对应的Leads信息
List
N
数据类型参照
返回值说明
序号
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],实际总数:
[()],请检查
例:
错误:
预计总数:
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
参照当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
参照当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
参照
车辆静态信息
VHLInfo
Y
参照
车辆服务状态信息
serviceStatus
Y
参照
4.1.2
列表名
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
destinationDownloads
目的地下载次数
int
Y
13
parkingIndication
停车位置提示次数
int
Y
14
remoteHorningFlashing
闪灯鸣笛次数
int
Y