客户资料同步接口

注意:本接口的使用需要进行接口鉴权

客户资料同步接口文档共分为两部分:

第一部分:将您系统内的客户资料同步到七陌系统

第二部分:将客户的资料信息变更推送给第三方系统

1.获取客户数据库版本号、字段结构接口

  • HTTP请求方式:POST

  • 请求url:

{HOST}/v20170418/customer/getTemplate/ACCOUNTID?sig=SIG

  • 请求时请将{HOST}换成对接数据查询中获取到的请求域名,ACCOUNTID替换为账户编号,SIG是根据鉴权规则生成的,请看鉴权文档,查看具体的生成规则

  • 鉴权方式:接口鉴权

  • 请求频次限制:20次/每分钟

请求体:

响应码:

代码 含义
200 请求成功
400 请求体参数错误
403 接口访问频次达到上限
500 服务器错误

返回200事例:

返回400事例:

{
    "code": 400,
    "message": "Please check your parameters"
}

返回403事例:

{
    "code": 403,
    "message": "Server is busy, max request frequency is 20/min"
}

返回值

字段 含义
code 响应码
message 响应信息
data 返回数据,JSON格式

data

version 数据库版本号作用:因为客户模板字段是用户可以自己配置的,所以数据库字段经常会发生变化,为了保证客户数据和用户配置的客户模板保持一致,所以对客户模板加一个版本号字段,所有对客户数据的增删改查操作都需要带上版本号,如果该版本号和客户模板中的版本号不一致,那么该操作失败。
template_type 客户类型company:企业客户 personal:个人客户
status 客户状态,默认四个 ,必填(单选,插入、修改数据时传Key值,例如status0status0 : 普通客户status1: 银牌客户
status2: 金牌客户
status3 : VIP客户
source 数据来源,单选
stable_fields 客户默认字段,企业客户10个,个人客户13举例: "name" : 字段id "value" : 字段名称
"required" : 是否必填,requied:必填 空:非必填
"example": 字段类型、传参举例
插入、修改数据时根据"name"匹配字段
custom_fields 自定义字段 数量不限插入、修改数据时根据"name"匹配字段

企业客户stable_fields

属性name 属性value 备注
name 公司名称 默认必填
title 描述
phone 联系人电话 Object数组类型[{"tel":"130xxxxxxxx","memo":"备注"}]tel: 手机号,
memo: 备注
email 联系人邮箱 Object数组类型[{"email":"example@163.com","memo":"备注"}]email: 邮箱,
memo: 备注
weixin 微信 Object数组类型:[{"num":"example001","memo":"备注"}]num: 微信号,
memo: 备注
province 直辖市带"",例如: "北京市"普通省份带"",例如: "山东省"
city 带"市",例如:"北京市", "石家庄市"
address 公司地址
note 备注
web 公司网站

个人客户stable_fields

属性name 属性value 备注
name 公司名称 默认必填
title 描述
phone 联系人电话 Object数组类型[{"tel":"130xxxxxxxx","memo":"备注"}]tel: 手机号, memo: 备注
email 联系人邮箱 Object数组类型[{"email":"example@163.com","memo":"备注"}]email: 邮箱, memo: 备注
weixin 微信 Object数组类型:[{"num":"example001","memo":"备注"}]num: 微信号,
memo: 备注
province 直辖市带"",例如: "北京市"普通省份带"",例如: "山东省"
city 带"市",例如:"北京市", "石家庄市"
address 公司地址
note 备注
web 公司网站
sex 性别 "0":"1":
age 年龄
birth 生日 Date类型,"yyyy-MM-dd"

客户自定义字段custom_fields,客户自定义字段有七种类型,分别是单行文本、多行文本、数字、日期、下拉框、复选框、单选框,每种类型的字段可以设置多个。

类型id 类型名称 备注
single 单行文本
multi 多行文本
number 数字 数据类型:String,格式:正整数,例如"23"
date 日期 数据类型:String,格式:Date "yyyy-MM-dd"
dropdown 下拉框 返回数据中带可选属性choices,例如:,"choices":{"0":"1","1":"3","2":"多次"}
checkbox 复选框 返回数据中带可选属性choices,例如:,"choices": {"0":"开朗","1":"大方","2":"顽固"}
radio 单选框 返回数据中带可选属性choices,例如:,"choices": "choices":{"0":"","1":""}

2.新增客户资料数据接口

  • HTTP请求方式:POST

  • 请求url:

{HOST}/v20170418/customer/insert/ACCOUNTID?sig=SIG

  • 请求时请将{HOST}换成对接数据查询中获取到的请求域名,ACCOUNTID替换为账户编号,SIG是根据鉴权规则生成的,请看鉴权文档,查看具体的生成规则

  • 鉴权方式:接口鉴权

  • 请求频次限制:20次/每分钟

  • 数据条数限制:每次最多插入500条客户数据

请求示例:

https://apis.7moor.com/v20170418/customer/insert/N00000000556
?sig=3E92F146297FCA751F63493877EC9719

请求体

字段 类型 备注
version String,必填 版本号,必须用获取客户资料模板中返回的version值
customers Object类型数组,必填 _id:小写的UUID,客户的唯一主键id,非必填(如不传或传值错误,则由我们系统自动生成)
status:客户状态 必填
source:数据来源
owner:归属坐席(电销业务场景下可通过传公海名称来给公海新增客户)
企业客户自定义字段传获取模板信息接口中返回的stable_fields中的字段
个人客户自定义字段传获取模板信息接口中返回的custom_fields中的字段
importSid:用户自定义访客id,关联在线客服会话用

请求体事例:

{
    "version": "201610100019",
    "customers": [
        {
            "status":"status0",
            "source":"谷歌",
            "name":"rest导入测试44444",
            "title":"标题",
            "phone":[
                {
                    "tel":"124424412345678"
                },
                {
                    "tel":"154454410202030"
                }
            ],
            "email":[
                {
                    "email":"23124@qq.com"
                },
                {
                    "email":"33440944@qq.com"
                }
            ],
            "weixin":[
                {
                    "num":"23e4"
                }
            ],
            "province":"山东省",
            "city":"德州市",
            "address":"海淀区",
            "note":"备注",
            "importSid":"shaocKf44"
        }
    ]
}

响应代码

代码 含义
200 请求成功
210 客户信息符合要求的保存成功,返回不符合要求的客户信息
400 请求参数错误
403 接口访问频次达到上限或者插入客户数据大于500
500 服务器错误

返回200事例:

{
    "code": 200,
    "message": "success!"
}

返回210事例:

{
    "code": 210,
    "message": "has some error data",
    "errorData": [
        {
            "status": "status1",
            "source": "谷歌",
            "name": "导入客户测试10",
            "title": "标题",
            "phone": [
                {
                    "tel": "13512345678"
                },
                {
                    "tel": "13010202030"
                }
            ],
            "email": [
                {
                    "email": "234@qq.com"
                },
                {
                    "email": "3444@qq.com"
                }
            ],
            "weixin": [
                {
                    "num": "23e4"
                },
                {
                    "num": "234"
                }
            ],
            "province": "山东省",
            "city": "德州市",
            "address": "海淀区",
            "note": "备注",
            "web": "www.xxx.com",
            "createTime": "2018-07-18 16:29:59",//创建时间
            "lastUpdateTime": "2018-07-18 19:36:30",//最后更新时间
            "batchNo": "20180718162916",//批次号
            "owner": "8000",//归属坐席工号
            "ownerName": "坐席8000",//归属坐席名称
            "qq账号": "666666",
            "备注": "23344",
            "年龄": "123",
            "建立时间": "2016-10-09",
            "见面次数": "2",
            "性格": [
                "0",
                "2"
            ],
            "性别": "2"
        }
    ]
}

返回400事例:

{
    "code": 400,
    "message": "Please check your parameters"
}

返回403事例:

{
    "code": 403,
    "message": "Server is busy, max request frequency is 20/min"
}

或者

{
    "code": 403,
    "message": "Insert data amount is too many, max insert amount is 100"
}

3.修改客户资料数据接口

  • HTTP请求方式:POST

  • 请求url:

{HOST}/v20170418/customer/update/ACCOUNTID?sig=SIG

  • 请求时请将{HOST}换成对接数据查询中获取到的请求域名,ACCOUNTID替换为账户编号,SIG是根据鉴权规则生成的,请看鉴权文档,查看具体的生成规则

  • 鉴权方式:接口鉴权

  • 请求频次限制:20次/每分钟

请求示例:

http://apis.7moor.com/v20170418/customer/update/N00000000556
?sig=3E92F146297FCA751F63493877EC9719

请求体:

字段 类型 备注
customer Object类型 必填 _id: 主键 必填
version:版本号 必填
status:客户状态 必填
source:数据来源
owner:归属坐席 stable_fields:固定属性,企业客户和个人客户有差别,具体属性见获取客户资料接口返回值详解
custom_fields:客户自定义属性,具体属性见获取客户资料接口返回值详解
importSid:自定义访客id,客户关联会话用的;如果该客户已经关联了访客则不做更新,返回修改客户资料成功。

请求体事例:

{
    "customer": {
        "_id": "4cf77790-8eb5-11e6-9bef-37ee1675947e",
        "version": "201610100019",
        "status": "status1",
        "source": "谷歌",
        "name": "导入客户测试10",
        "title": "标题",
        "phone": [
            {
                "tel": "13512345678"
            },
            {
                "tel": "13010202030"
            }
        ],
        "email": [
            {
                "email": "234@qq.com"
            },
            {
                "email": "3444@qq.com"
            }
        ],
        "weixin": [
            {
                "num": "23e4"
            },
            {
                "num": "234"
            }
        ],
        "province": "山东省",
        "city": "德州市",
        "address": "海淀区",
        "note": "备注",
        "web": "www.xxx.com",
        "qq账号": "666666",
        "备注": "23344",
        "年龄": "123",
        "建立时间": "2016-10-09",
        "见面次数": "2",
        "性格": [
            "0",
            "2"
        ],
        "性别": "0"
    }
}

响应代码:

代码 含义
200 请求成功
400 请求参数错误
403 接口访问频次达到上限
500 服务器错误

返回200事例:

{
    "code": 200,
    "message": "success!"
}

返回400事例:

{
    "code": 400,
    "message": "Please check your parameters"
}

返回403事例:

{
    "code": 403,
    "message": "Server is busy, max request frequency is 20/min"
}

4.删除客户资料数据接口

支持批量删除客户数据

  • HTTP请求方式:POST

  • 鉴权方式:接口鉴权

  • 请求url:{HOST}/v20170418/customer/delete/accountId?sig=SIG

  • 请求时请将{HOST}换成对接数据查询中获取到的请求域名,ACCOUNTID替换为账户编号,SIG是根据鉴权规则生成的,请看鉴权文档,查看具体的生成规则

  • 鉴权方式:接口鉴权

  • 频次限制:10次/分钟

  • 删除数据限制:每次最多删除500条客户数据

请求示例:

http://apis.7moor.com/v20170418/customer/delete/N00000000556
?sig=3E92F146297FCA751F63493877EC9719

请求体:

字段 类型 备注
ids String类型数组,必填 客户资料数据主键

请求体事例:

{
    "ids": [
        "52163270-8eb5-11e6-9bef-37ee1675947e",
        "4cf77790-8eb5-11e6-9bef-37ee1675947e"
    ]
}

响应代码:

代码 含义
200 请求成功
210 客户id正确的删除成功,返回错误的客户id
400 请求体参数错误
403 接口访问频次达到上限
500 服务器错误

返回200事例:

{
    "code": 200,
    "message": "success!"
}

返回210事例:

{
    "code": 210,
    "message": "has some error data",
    "errorData": {
        "version": "20161010009",
        "ids": [
            "4cf77790-8eb5-11e6-9bef-37ee1675947e",
            "52163270-8eb5-11e6-9bef-37ee1675947e"
        ]
    }
}

返回400事例:

{
    "code": 400,
    "message": "Please check your parameters"
}

返回403事例:

{
    "code": 403,
    "message": "Server is busy, max request frequency is 20/min"
}

或者

{
    "code": 403,
    "message": "Delete data amount is too many, max delete amount is 100"
}

5.查询客户资料数据接口

  • HTTP请求方式:POST

  • 鉴权方式:接口鉴权

  • 请求url:{HOST}/v20170418/customer/select/ACCOUNTID?sig=SIG

  • 请求时请将{HOST}换成对接数据查询中获取到的请求域名,ACCOUNTID替换为账户编号,SIG是根据鉴权规则生成的,请看鉴权文档,查看具体的生成规则

  • 频次限制:20次/每分钟

  • 查询数据限制:默认最多返回1000条数据。支持分页查询

请求url:

http://apis.7moor.com/v20170418/customer/select/N00000000556
?sig=3E92F146297FCA751F63493877EC9719

请求体

字段 类型 备注
version String 必填 版本号
_id String 非必填 客户主键
name String 非必填 公司名称
phone String 非必填 联系人电话
beginCreateTime 类型String 格式Date "yyyy-MM-dd" 非必填 大于创建时间
endCreateTime 类型String 格式Date "yyyy-MM-dd" 非必填 小于创建时间
beginLastUpdateTime 类型String 格式Date "yyyy-MM-dd" 非必填 大于最后修改时间
endLastUpdateTime 类型String 格式Date "yyyy-MM-dd" 非必填 小于最后修改时间
page int 非必填 默认1 查询第几页数据
pageSize int 非必填 默认1000 每页数量

请求体事例

{
    "version": "201610100019",
    "_id": "bfab4500-8f5a-11e6-8517-25d9c27afcd7",
    "name":"导入客户测试10",
    "phone":"13512345678",
    "beginCreateTime": "2016-10-11",
    "page": 1,
    "pageSize": 2
}

响应代码:

代码 含义
200 请求成功
400 请求体参数错误
403 接口访问频次达到上限
500 服务器错误

返回200事例:

{
    "version": "201610100019",
    "code": 200,
    "message": "success!",
    "data": [
        {
            "_id": "bfab4500-8f5a-11e6-8517-25d9c27afcd7",
            "accountId": "N00000000556",
            "createTime": "2016-10-11 10:31:00",
            "phone": [
                {
                    "tel": "13512345678",
                    "memo": ""
                },
                {
                    "tel": "13010202030",
                    "memo": ""
                }
            ],
            "email": [
                {
                    "email": "234@qq.com"
                },
                {
                    "email": "3444@qq.com"
                }
            ],
            "weixin": [
                {
                    "num": "23e4",
                    "memo": ""
                },
                {
                    "num": "234",
                    "memo": ""
                }
            ],
            "status": "status1",
            "name": "导入客户
测试10",
            "title": "标题",
            "province": "bac009de-5bfd-4f33-913e-5194eeb0f77b",
            "city": "3cd74d1b-23b6-4088-a734-7f87b0f3a720",
            "address": "海淀区",
            "note": "备注",
            "web": "www.xxx.com",
            "source": "谷歌",
            "qq账号": "666666",
            "备注": "23344",
            "年龄": "123",
            "建立>时间": "2016-10-09",
            "见面次数": "2",
            "性格": [
                "0",
                "2"
            ],
            "性别": "0"
        }
    ]
}

返回400事例:

{
    "code": 400,
    "message": "Please check your parameters"
}

返回403事例:

{
    "code": 403,
    "message": "Server is busy, max request frequency is 20/min"
}

6.云客服新增客户资料接口

注意:推送客户资料接口(6、7、8)的contentType不是application/json,而是application/x-www-form-urlencoded

接口详解:

本接口是将在七陌系统中创建的客户以一个 json array对象的方式推送给您系统,其中每一个json对象对应一个客户资料信息。

  • 请求方式:POST

  • 编码方式:UTF-8 , 使用URLDecoder.decode解码

json示例:

[
    {   
        "_id":"c45ef0d0-571b-11e8-b9ea-4d6efe70975e",//客户资料主键ID
        "owner": "8096",   //拥有该客户资料的坐席
        "createTime": "2017-09-14 22:57:34",  //创建时间
        "creator": "8096",  //创建该客户资料的坐席
        "lastUpdateTime": "2017-09-14 22:57:34",   //上次修改时间
        "accountId": "N00000003731",   //账号ID
        "eventType":"add",  //新增
        "多行文本": "多行文本文字",   // 多行文本类型的自定义字段,值为字符串
        "单行文本": "单行文本文字",    //单行文本类型的自定义字段,值为字符串
        "单选框": "单选框数值",    //单选框类型的自定义字段,值为字符串
        "复选框": ["复选框数值1","复选框数值2"], //复选框类型的自定义字段,值为数组
        "下拉框": "下拉框数值",//下拉框类型的自定义字段,值为字符串
        "日期": "2017-09-20",//日期类型的自定义字段,值为字符串
        "数据来源": "市场",  
        "客户状态": "金牌客户",
        "公司名称": "北京容联七陌",
        "描述": " 北京容联七陌公司",
        "联系人电话": [
            {
                "tel": "15223234456",
                "memo": "刘先生"
            }
        ],
        "联系人邮箱": [
            {
                "email": "test@7moor.com",
                "memo": "杨先生"
            }
        ],
        "微信": [
            {
                "num": "7moor",
                "memo": "王先生"
            }
        ],
        "chatSessionInfo":{
                "seoSource":"搜索来源",
                "seoKeywords":"搜索关键字",
                "ip":"IP地址",
                "fromUrl":"咨询页面url值",
                "fromUrlTitle":"咨询页面title"
        }
        "省": "海南省",
        "市": "乐东黎族自治县",
        "公司地址": "北京市林萃路",
        "公司网站": "http://www,7moor.com"
    }
]

示例参数解析:

其中多行文本、单行文本、单选框、复选框、下拉框、日期为自定义字段。公司名称、描述、联系人电话、联系人邮箱、微信、省、市、公司地址、公司网站为固定字段。

返回值:

客户在接受到客户资料后,返回200代表同步成功,400代表同步失败。

我们的事件推送默认支持失败重发,第三方接收消息的接口接收成功后需要返回给我们字符串200 。

如果我们推送后接口返回的值中不是字符串200,我们则认为第三方接口接收失败。进入重发流程,一条失败的消息,会在 10秒、30秒、60秒、600秒 后重发,直到第三方接口返回200。如果这4次重发都失败,我们将不会再重发。重发彻底失败的消息,我们会记录下来,第三方可以找我们索取。

7.云客服修改客户资料接口

  • 请求方式:POST

  • 编码方式:UTF-8 , 使用URLDecoder.decode解码

json示例:

[
    {   
        "_id":"c45ef0d0-571b-11e8-b9ea-4d6efe70975e",//客户资料主键ID
        "owner": "8096",   //拥有该客户资料的坐席
        "createTime": "2017-09-14 22:57:34",  //创建时间
        "creator": "8096",  //创建该客户资料的坐席
        "lastUpdateTime": "2017-09-14 22:57:34",   //上次修改时间
        "accountId": "N00000003731",   //账号ID
        "eventType":"update",  //事件类型,当前为修改客户资料,即为update
        "多行文本": "多行文本文字",   // 多行文本类型的自定义字段,值为字符串
        "单行文本": "单行文本文字",    //单行文本类型的自定义字段,值为字符串
        "单选框": "单选框数值",    //单选框类型的自定义字段,值为字符串
        "复选框": ["复选框数值1","复选框数值2"], //复选框类型的自定义字段,值为数组
        "下拉框": "下拉框数值",//下拉框类型的自定义字段,值为字符串
        "日期": "2017-09-20",//日期类型的自定义字段,值为字符串
        "数据来源": "市场",  
        "客户状态": "金牌客户",
        "公司名称": "北京容联七陌",
        "描述": " 北京容联七陌公司",
        "联系人电话": [
            {
                "tel": "15223234456",
                "memo": "刘先生"
            }
        ],
        "联系人邮箱": [
            {
                "email": "test@7moor.com",
                "memo": "杨先生"
            }
        ],
        "微信": [
            {
                "num": "7moor",
                "memo": "王先生"
            }
        ],
        "chatSessionInfo":{
                "seoSource":"搜索来源",
                "seoKeywords":"搜索关键字",
                "ip":"IP地址",
                "fromUrl":"咨询页面url值",
                "fromUrlTitle":"咨询页面title"
        }
        "省": "海南省",
        "市": "乐东黎族自治县",
        "公司地址": "北京市林萃路",
        "公司网站": "http://www,7moor.com"
    }
]

示例参数解析: 其中多行文本、单行文本、单选框、复选框、下拉框、日期为自定义字段。公司名称、描述、联系人电话、联系人邮箱、微信、省、市、公司地址、公司网站为固定字段。

返回值: 客户在接受到客户资料后,返回200代表修改成功,400代表修改失败。

8.云客服删除客户资料接口

  • 请求方式:POST

  • 编码方式:UTF-8 , 使用URLDecoder.decode解码

json示例:

[
    {   
        "_id":"c45ef0d0-571b-11e8-b9ea-4d6efe70975e",//客户资料主键ID
        "eventType":"delete"//事件类型 ,删除
    }
]

示例参数解析: 其中id为客户资料主键ID,eventType为当前事件的类型。

返回值: 客户在删除客户资料后,返回200代表修改成功,400代表修改失败。

返回顶部