API数据服务接口开发指南.docx

Target-S
外部接口说明书

四键信息技术
Fourth Button, Inc.
日期: 2016-05-19
变更记录
序号
说明
变更人
时间

目录
1 引言 1
1.1 概述 1
1.2 名词缩写与定义 1
1.3 历史变更 1
2 开发规 2
2.1 通信方式 2
2.2 接口说明 2
2.2.1 返回参数 2
2.2.2 通用返回码说明 2
3 数据服务接口 4
3.1 importCustomerAndVHLData〔FTP Monitor-TSS〕 4
3.2 createLeads〔TSS-TSM〕 5
3.3 leads 需要外部文件导入的，是修改leads状态码？ 7
3.4 callTheCustomer(TSS-CCA) 8
3.5 fishTheCall〔CCA-TSS〕 9
4 附录 11
4.1 数据结构描述 11
4.1.1 customerVHLData 11
4.1.2 customerInfo 11
4.1.3 VHLInfo 12
4.1.4 serviceStatus 13
4.1.5 leadsInfo 13
4.2 HTTP返回值处理策略 14

13 / 15
1 引言
1.1 概述
略
1.2 名词缩写与定义
名词缩写
定义
VIN
17位国际VIN码规那么
TSS
Target-S System
TSM
Target-S Model
CCA
外部系统，用于拨打给客户的系统
FTP Monitor
文件监视器，用于监测文件夹中是否存在文件，如果存在文件，那么读取文件容并通知TSS做相应处理
ES
External System 外部系统
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.1 importCustomerAndVHLData〔FTP Monitor-TSS〕
接口名称
importCustomerAndVHLData
调用方
FTP Monitor
服务方
TSS
接口描述
监视器监控某个指定文件夹，如果有文件，那么读取文件，并调用该接口，将客户数据和对应的车辆数据存储到TSS数据库中
URL
/tss/importData/V1/importCustomerAndVHLData
接口类型
RESTFul
容格式
JSON
版本号
V1
请求方法
POST
输入参数
参数代码
参数名称
数据类型
必输
参数说明
total
总数
int
Y
客户和车辆配对总计
customerVHLDataList
客户、车辆、服务状态信息列表
List<customerVHLData>
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.2 createLeads〔TSS-TSM〕
接口名称
createLeads
调用方
TSS
服务方
TSM
接口描述
TSS将最新的客户静态信息、车辆静态信息和车辆服务状态信息导入到TSM，生成对应的Leads
URL
/tsm/createLeads/V1/createLeads
接口类型
RESTFul
容格式
JSON
版本号
V1
请求方法
POST
输入参数
参数代码
参数名称
数据类型
必输
参数说明
total
总数
int
Y
需要生成Leads的总数
customerVHLList
客户、车辆、服务状态信息列表
List<customerVHLData>
Y
数据类型参照4.1.1
输出参数
参数代码
参数名称
数据类型
必输
参数说明
responseCode
返回码
int
Y
参照返回值说明
errorMessage
错误信息
string
N
当请求异常时，将返回error信息
total
生成Leads总数
int
Y
假设为异常，那么total为0
leadsList
对应的Leads信息
List<leadsInfo>
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.3 callTheCustomer(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.4 fishTheCall〔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/DD HH:mm:SS
endDate
通话开始完毕时间
datetime
Y
YYYY/MM/DD HH: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/DD HH:mm:SS
9
19
错误：参数endDate：%s格式错误，请参考API文档
YYYY/MM/DD HH:mm:SS
10
99
超时
超时

3.5 searchPastPackage〔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<package>
N
参照4.1.6
当responseCode为0时，packageList不为空

返回值说明
序号
responseCode
errorMessage
说明
1
0
无

2
18
错误：VIN:%s不存在

3
2
错误：缺失必选参数：packageList，请参考API文档

4
99
超时
超时

3.6 searchServiceStatus〔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.1 customerVHLData
列表名
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.2 customerInfo
列表名
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.3 VHLInfo
列表名
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.4 serviceStatus
列表名
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

15
SVT
被盗车辆跟踪次数
int
Y

16
travelConsultation
旅游咨询次数
int
Y

17
sendToCar
发送到车次数
int
Y

4.1.5 leadsInfo
列表名
leadsInfo对应leads信息
No
参数代码
参数名称
数据类型
必选
参数说明
1
leadsID
Leads ID
string
Y

2
VIN
VIN
string
Y

3
customerID
客户ID
string
Y

4
leadsStatus
Leads状态
int
Y
1：待分配；2：新建；3：执行中；4：关闭
5
renewalPossibility
续约指数
string
Y

6
customerStatusLV1
一级客户状态
string
N

7
customerStatusLV2
二级客户状态
string
N

8
leadsOwner
Leads归属
string
N
用户ID

4.1.6 package
列表名
package套餐信息
No
参数代码
参数名称
数据类型
必选
参数说明
1
packageName
套餐名称
string
Y

2
startDate
套餐开始时间
string
Y

3
endDate
套餐完毕时间
string
Y

4.2 HTTP返回值处理策略
HTTP Code
错误说明
处置策略

302
重定向
不会出现

401
认证失败

403
没权限

404
资源找不到
重试

500
资源服务器错误
重试

503
资源暂时不可用
重试

响应超时20秒
连接超时20秒
重试策略：等待30秒后重试，无限次数重试
最大并发线程：50个