1、对接说明
1.1 编码格式
通信报文的文字编码格式全部采用UTF-8格式。
1.2 接口调用方式
统一采用POST访问的方式
1.3 接口调用地址
测试地址:https://xtapp.zkcrm.com:444/sync.aspx
1.4 身份验证
每个企业账号拥有一个唯一的Key值,通过传递Key值进行身份验证
1.5 返回信息
返回内容统一为JSON格式,如下表示例
参数名称 |
描述 |
IsSuccess |
是否成功 |
Message |
详细描述 |
Data |
返回内容(部分接口不返回该参数) |
返回示例代码:
{"IsSuccess":false,"Message":"合同客户不允许为空且该客户必须存在系统中"}
2、接口部分
2.1 获取日程安排信息
为必填字段,非必填字段可不传;获取日程安排信息时必须指定日期。
字段名 |
描述 |
Category |
标识需要进行的操作,当前调用为:GetCalendar |
Key |
身份验证秘钥 |
Data |
获取日程所需要传递的信息 |
字段名 |
描述 |
Date |
指定某一天的日程,格式要求为yyyy-MM-dd |
User |
指定某个人员的日程 |
Page |
显示第几页,需传递数字 |
PageSize |
每页显示多少条记录,需传递数字 |
|
Json示例
返回内容的Data说明
字段名 |
描述 |
Id |
日程ID |
User |
人员名称 |
Subject |
主题 |
Memo |
详细内容 |
StartTime |
日程开始时间 |
EndTime |
日程结束时间 |
返回示例
2.2 保存日程安排信息
为必填字段,非必填字段可不传;日程安排信息中的Id为必填字段,若为新增日程,则传递0,否则则按照Id值进行日程的修改。
字段名 |
描述 |
Category |
标识需要进行的操作,当前调用为:SaveCalendar |
Key |
身份验证秘钥 |
Data |
需要保存的日程安排信息 |
字段名 |
描述 |
Id |
日程安排ID |
User |
人员(此处的人员名称需与员工表中的名称保持一致) |
Subject |
主题 |
Memo |
详细内容(若不传递该参数,则详细内容与主题一致) |
StartTime |
开始时间(yyyy-MM-dd HH:mm) |
EndTime |
结束时间(yyyy-MM-dd HH:mm) |
Completed |
是否已完成(0或者1,如不需要做出修改,该参数可不传递) |
|
Json示例
2.3 获取客户列表
为必填字段,非必填字段可不传;获取客户信息时必须指定筛选字段和关键字,如需要查找公司名称包含“上古软件”的客户,则FilterField传递Name,Keyword传递“上古软件”。
字段名 |
描述 |
Category |
标识需要进行的操作,当前调用为:GetCustomer |
Key |
身份验证秘钥 |
Data |
获取客户所需要传递的信息 |
字段名 |
描述 |
FilterField |
进行筛选的字段,多个条件用半角逗号隔开,如 Province,User 查看字段 |
Keyword |
筛选的关键字,多个条件用半角逗号隔开,且数量必须与FilterField保持一致,如 福建,谭朗 |
Fields |
需要获取的字段,若不传递则显示默认字段,传递内容示例:Id,Name,Number,Mobile,Tel |
Page |
显示第几页,需传递数字 |
PageSize |
每页显示多少条记录,需传递数字 |
|
Json示例
返回内容的Data说明
字段名 |
描述 |
Id |
客户ID |
Number |
客户编号 |
Name |
客户名称 |
Contact |
主联系人 |
Tel |
电话 |
Mobile |
手机号码 |
Email |
邮箱地址 |
Type |
客户类型 |
Province |
省份 |
City |
城市 |
Address |
地址 |
User |
客户的业务员 |
返回示例
2.4 保存客户信息
为必填字段,非必填字段可不传;接口调用动作默认为新增客户,当客户信息中的客户编号(Number)字段进行了传递且该编号的客户已存在系统中时,当前调用将更改为更新客户。
字段名 |
描述 |
Category |
标识需要进行的操作,当前调用为:SaveCustomer |
Key |
身份验证秘钥 |
Data |
需要保存的客户信息 |
字段名 |
描述 |
Number |
客户编号 |
Name |
客户名称 |
Contact |
联系人 |
Tel |
电话号码 |
Mobile |
手机号码 |
Email |
邮箱地址 |
Type |
客户类型,该字段内容必须保持与字典表一致,否则该字段无法保存 |
Origin |
客户来源,该字段内容必须保持与字典表一致,否则该字段无法保存 |
Province |
省份 |
City |
城市 |
Region |
区域 |
User |
业务员,人员名称必须与员工表中的名称一致,否则无法保存 |
Address |
地址 |
Label |
客户标签 |
ServiceUser |
售后人员,人员名称必须与员工表中的名称一致,否则无法保存 |
Memo |
备注信息 |
CustomFields |
扩展字段 |
字段名 |
描述 |
扩展字段1 |
|
扩展字段2 |
|
|
如果为客户建立了扩展字段,则按照建立的扩展字段的名称来进行传递,如建立了“客户行业”、“企业规模”两个字段,则传递内容为"CustomFields": {"客户行业":"生产制作","企业规模":"100人左右"} |
|
|
Json示例
2.7 获取产品列表
为必填字段,非必填字段可不传;
字段名 |
描述 |
Category |
标识需要进行的操作,当前调用为:GetProduct |
Key |
身份验证秘钥 |
Data |
获取产品所需要传递的信息 |
字段名 |
描述 |
FilterField |
进行筛选的字段,多个条件用半角逗号隔开,且数量必须与FilterField保持一致,如 Name,TypeName 查看字段 |
Keyword |
筛选的关键字,多个条件用半角逗号隔开,且数量必须与FilterField保持一致,如 内存,计算机配件 |
Fields |
需要获取的字段,若不传递则显示默认字段,传递内容示例:Id,Code,Name,TypeName,Price,Unit,Memo |
Page |
显示第几页,需传递数字 |
PageSize |
每页显示多少条记录,需传递数字 |
|
Json示例
返回内容的Data说明
字段名 |
描述 |
Id |
产品ID |
Code |
产品编号 |
Name |
产品名称 |
TypeName |
产品类型 |
Price |
售价 |
Unit |
单位 |
Memo |
详细描述 |
返回示例
2.8 保存产品信息
为必填字段,非必填字段可不传;接口调用动作默认为新增产品,当产品信息中的产品编码(Code)字段进行了传递且该编码的产品已存在系统中时,当前调用将更改为更新产品信息。
字段名 |
描述 |
Category |
标识需要进行的操作,当前调用为:SaveProduct |
Key |
身份验证秘钥 |
Data |
需要保存的产品信息 |
字段名 |
描述 |
Code |
产品编码 |
Name |
产品名称 |
Type |
产品类型 |
Price |
产品售价(要求必须为数字) |
Cost |
产品成本(要求必须为数字) |
Memo |
备注信息 |
CustomFields |
扩展字段 |
字段名 |
描述 |
扩展字段1 |
|
扩展字段2 |
|
|
如果为产品建立了扩展字段,则按照建立的扩展字段的名称来进行传递,如建立了“产品尺寸”、“产品属性”两个字段,则传递内容为"CustomFields": {"产品尺寸":"240mm*175mm","产品属性":"成套件"} |
|
|
Json示例
2.9 获取销售机会列表
为必填字段,非必填字段可不传;获取销售机会信息时可以指定筛选字段和关键字,也可以指定销售机会的创建时间区间,如需要查找“上古软件”的销售机会,则FilterField传递CustomerName,Keyword传递“上古软件”。
字段名 |
描述 |
Category |
标识需要进行的操作,当前调用为:GetProject |
Key |
身份验证秘钥 |
Data |
获取销售机会所需要传递的信息 |
字段名 |
描述 |
FilterField |
进行筛选的字段,多个条件用半角逗号隔开,如 CustomerName,UserName 查看字段 |
Keyword |
筛选的关键字,多个条件用半角逗号隔开,且数量必须与FilterField保持一致,如 可可食品,卢青梅 |
StartDate |
指定销售机会创建时间区间的开始日期(yyyy-MM-dd) |
EndDate |
指定销售机会创建时间区间的结束时间(yyyy-MM-dd) |
Fields |
需要获取的字段,若不传递则显示默认字段,传递内容示例:Id,CustomerName,Name,CreateDate,Status,StageName,EstimatePrice,EstimateDate,UserName,Memo |
Page |
显示第几页,需传递数字 |
PageSize |
每页显示多少条记录,需传递数字 |
|
Json示例
返回内容的Data说明
字段名 |
描述 |
Id |
销售机会ID |
CustomerId |
客户ID |
Name |
销售机会名称 |
CustomerName |
客户名称 |
CreateDate |
成交时间 |
Status |
销售机会状态 |
StageName |
销售机会阶段 |
EstimatePrice |
预计成交金额 |
EstimateDate |
预计成交日期 |
UserName |
负责人 |
Memo |
详细描述 |
返回示例
2.10 获取销售机会详情
为必填字段,非必填字段可不传;
字段名 |
描述 |
Category |
标识需要进行的操作,当前调用为:GetProjectDetail |
Key |
身份验证秘钥 |
Data |
获取销售机会详情所需要传递的信息 |
字段名 |
描述 |
Id |
传递需要获取销售机会的ID(与下方的销售机会名称进行2选1即可) |
Name |
传递需要获取销售机会的名称(与上方的销售机会ID进行2选1即可) |
|
Json示例
返回内容的Data说明
字段名 |
描述 |
Id |
销售机会ID |
Name |
销售机会名称 |
CustomerId |
客户ID |
CustomerName |
客户名称 |
CreateDate |
创建日期 |
Status |
销售机会状态 |
StageName |
销售机会阶段 |
EstimatePrice |
预计成交金额 |
EstimateDate |
预计成交日期 |
UserName |
负责人 |
Memo |
备注 |
扩展字段内容 |
根据已建立的销售机会扩展字段的内容进行展现...... |
Product |
销售机会的报价产品信息 |
字段名 |
描述 |
ProductName |
产品名称 |
ProductTypeName |
产品类型 |
Price |
单价 |
Amount |
数量 |
Discount |
折扣 |
SalesPrice |
合计价格 |
Memo |
产品备注 |
|
返回示例
2.11 获取合同列表
为必填字段,非必填字段可不传;获取合同信息时可以指定筛选字段和关键字,也可以指定合同的成交时间区间,如需要查找“上古软件”的合同,则FilterField传递CustomerName,Keyword传递“上古软件”。
字段名 |
描述 |
Category |
标识需要进行的操作,当前调用为:GetOrder |
Key |
身份验证秘钥 |
Data |
获取合同所需要传递的信息 |
字段名 |
描述 |
FilterField |
进行筛选的字段,多个条件用半角逗号隔开,如 CustomerName,SubmitUserName 查看字段 |
Keyword |
筛选的关键字,多个条件用半角逗号隔开,且数量必须与FilterField保持一致,如 可可食品,卢青梅 |
StartDate |
指定合同成交时间区间的开始日期(yyyy-MM-dd) |
EndDate |
指定合同成交时间区间的结束时间(yyyy-MM-dd) |
Fields |
需要获取的字段,若不传递则显示默认字段,传递内容示例:Id,CustomerName,Name,SubmitDate,OrderPrice,SubmitUserName,StatusName,Memo |
Page |
显示第几页,需传递数字 |
PageSize |
每页显示多少条记录,需传递数字 |
|
Json示例
返回内容的Data说明
字段名 |
描述 |
Id |
合同ID |
CustomerId |
客户ID |
Name |
合同名称 |
CustomerName |
客户名称 |
SubmitDate |
成交时间 |
OrderPrice |
合同金额 |
StatusName |
合同状态 |
SubmitUserName |
促成人员名称 |
Memo |
备注 |
返回示例
2.12 获取合同详情
为必填字段,非必填字段可不传;
字段名 |
描述 |
Category |
标识需要进行的操作,当前调用为:GetOrderDetail |
Key |
身份验证秘钥 |
Data |
获取合同详情所需要传递的信息 |
字段名 |
描述 |
Id |
传递需要获取合同的ID(与下方的合同名称进行2选1即可) |
Name |
传递需要获取合同的名称(与上方的合同ID进行2选1即可) |
|
Json示例
返回内容的Data说明
字段名 |
描述 |
Id |
合同ID |
Name |
合同名称 |
CustomerId |
客户ID |
CustomerName |
客户名称 |
StatusName |
合同状态 |
OrderPrice |
合同金额 |
SubmitDate |
成交时间 |
SubmitUserName |
促成人员名称 |
ServiceUserName |
服务人员名称 |
ExpireDate |
服务到期日期 |
Memo |
备注 |
扩展字段内容 |
根据已建立的合同扩展字段的内容进行展现...... |
Product |
合同产品信息 |
字段名 |
描述 |
ProductName |
产品名称 |
ProductTypeName |
产品类型 |
Price |
单价 |
Amount |
数量 |
Discount |
折扣 |
SalesPrice |
合计价格 |
UnitCost |
单位成本 |
Cost |
合计成本 |
Profit |
毛利 |
Memo |
产品备注 |
|
返回示例
2.13 保存合同信息
为必填字段,非必填字段可不传;接口调用动作默认为新增合同,当合同信息中的合同名称(Name)字段进行了传递且该名称的合同已存在系统中时,当前调用将更改为更新合同。
字段名 |
描述 |
Category |
标识需要进行的操作,当前调用为:SaveOrder |
Key |
身份验证秘钥 |
Data |
需要保存的合同信息 |
字段名 |
描述 |
Customer |
合同所属客户的名称,客户必须与系统中已存的客户名称一致,否则不予保存 |
Name |
合同名称 |
Status |
合同状态,该字段内容必须保持与字典表一致,否则该字段无法保存 |
User |
促成人员,人员名称必须与员工表中的名称一致,否则该字段无法保存 |
ServiceUser |
服务人员,人员名称必须与员工表中的名称一致,否则该字段无法保存 |
SubmitDate |
成交时间,请填写日期格式内容,如:2021-09-17 |
ExpireDate |
服务到期日期,请填写日期格式内容,如:2021-09-17 |
PayType |
付款方式 |
Memo |
详细描述 |
CustomFields |
扩展字段 |
字段名 |
描述 |
扩展字段1 |
|
扩展字段2 |
|
|
如果为合同建立了扩展字段,则按照建立的扩展字段的名称来进行传递,如建立了“合同类型”、“结算方式”两个字段,则传递内容为"CustomFields": {"合同类型":"框架合同","结算方式":"月结"} |
|
Product |
合同产品(允许传递多个产品) |
字段名 |
描述 |
ProductName |
产品名称,该字段内容必须与产品表中的产品名称一致,否则无法保存 |
Amount |
数量,请填写数值 |
Price |
销售单价,请填写数值 |
Discount |
折扣,请填写数值,如八折,则填写0.8 |
UnitCost |
单位成本,请填写数值 |
CustomFields |
扩展字段 |
字段名 |
描述 |
扩展字段1 |
|
扩展字段2 |
|
|
如果为合同产品建立了扩展字段,则按照建立的扩展字段的名称来进行传递,如建立了“产品型号”、“产品尺寸”两个字段,则传递内容为"CustomFields": {"产品型号":"A-23013","产品尺寸":"160cm*300cm"} |
|
|
|
Json示例
2.14 验证用户身份
为必填字段,非必填字段可不传。
字段名 |
描述 |
Category |
标识需要进行的操作,当前调用为:VerifyUser |
Key |
身份验证秘钥 |
Data |
获取日程所需要传递的信息 |
字段名 |
描述 |
Account |
用户名称 |
Password |
用户密码 |
|
Json示例
返回内容的Data说明
字段名 |
描述 |
Id |
人员ID |
Name |
人员名称 |
Account |
用户账号 |
Group |
所在部门 |
Title |
职位 |
Tel |
电话 |
Mobile |
手机 |
Email |
邮箱 |
WXUserId |
微信用户ID |
Token |
用户身份加密代码 |
返回示例