简介
爱番番有拓客、线索管家2个子产品，潜客API支持通过系统开发对接的形式，将您的客户数据接入爱番番CDP，然后使用拓客产品功能开展私域营销。
潜客API
通过该API可以将潜在客户、线索等接入拓客，然后使用拓客开展营销。
线索API
通过该API可以将线索客户接入线索管家，然后使用线索管家跟进线索。
准备工作
1.开通百度云账号
爱番番open API统一通过百度云对外提供服务。API调用前，需要先创建账号，具体见开发前必读。
2.确认要调用的接口
| 调用API名称 | 详细介绍 |
|---|---|
| Profile创建 | 将租户自有数据或自有系统数据上报到爱番番CDP |
| 创建自定义属性 | 为潜客创建自定义属性 |
| 更新自定义属性 | 更新自定义属性的信息 |
| … | … |
更多接口可查阅爱番番API列表，潜客API部分。
3.联系我们申请API授权
授权是指授予某个APP应用调用某个API的权限，提供APP应用信息，经过审批并开通API的授权之后才能调用API。当前API处于内测阶段，您可以联系我们开通授权。
需要提供的信息如下：
| 申请人 | 申请人姓名 |
|---|---|
| 联系人电话 | 电话号码 |
| 申请的API | 具体的api接口 |
| 待授权APPID | 在百度云创建的APPID |
| 待授权ak | 在百度云创建的APPkey |
| 预估访问量 | 每天的调用次数 |
开发前必读
1.了解必要的接口规范
爱番番API遵循业内普遍接受RESTful的设计风格，调用API前您需要了解：
设置URL地址
所有请求须使用HTTPS协议，统一的请求地址前缀为：https://api-aifanfan.baidu.com。
每个接口都带有v1、v2等版本号，url path都使用小写字母。比如潜客创建接口为https://api-aifanfan.baidu.com/v1/profiles。
设置Http方法
Get为查询接口，post为创建接口，patch为修改接口。
以潜客创建API为例，其中profiles为潜客创建的endpoints。
| Http方法 | URL路径 | 说明 |
|---|---|---|
| GET | https://api-aifanfan.baidu.com/v1/profiles/{id} | 获取某个指定对象的信息 |
| GET | hhttps://api-aifanfan.baidu.com/v1/profiles | 获取指定对象信息的列表 |
| POST | https://api-aifanfan.baidu.com/v1/profiles | 新建一个对象 |
| PATCH | https://api-aifanfan.baidu.com/v1/profiles/{id} | 更新指定对象的部分信息 |
设置Header
Content-Type：application/json;charset=UTF-8。使用JSON作为消息体的数据交换格式，所有的请求必须申明JSON Schema，且字符集指定为UTF-8。
X-Bce-Stage：标识要访问哪个环境的API，目前支持三种环境：release（线上）、 pre-release（预发布）、 test（测试），默认是线上环境。
X-Bce-Signature：访问对应API所需的签名信息，根据已授权app的ak,sk,及签名算法生成。可参考百度云生成认证字符串。注：如果通过java sdk调用，不需要设置X-Bce-Signature，设置Access Key和Secret Key即可。
2.API调用方式
通过百度云在线调用API
您可以前往百度云上爱番番API在线列表，输入您申请的Access Key和Secret Key，发起在线调用。
通过代码调用API
您可以前往百度云上爱番番API在线列表，查看java sdk示例代码（目前只提供java sdk版本）。
通过工具如postman调用API
设置X-Bce-Signature时，签名生成可参考生成签名示例代码。
潜客创建API
将租户自有数据或自有系统数据上报到爱番番CDP。
请求
（POST）https://api-aifanfan.baidu.com/ v1/ profiles
Body
{
"identities":[
{
"type":"leads_id",
"id":"15974778053230010",
"source":{
"primary":true,
"source":"OWN_SYSTEM",
"sourceId":"-1"
}
},
{
"type":"phone",
"id":"15129030111",
"source":{
"primary":true,
"source":"OWN_SYSTEM",
"sourceId":"-1"
}
},
{
"type":"enterprise_id",
"id":"15974778053230010",
"source":{
"primary":false,
"source":"OWN_SYSTEM",
"sourceId":"-1"
},
"modelType":"B"
}
],
"data":{
"name":"测试自定义api3",
"gender":"未知",
"accountName":"测试B/C",
"companyWebsite":"www.baidu.com"
},
"schemaId":"p_aff_profile"
}返回值
成功示例
HTTP/1.1 200 OK
Response Body:
{
"affId":"1642009771101528",
"accountId":"1642009771101535"
}失败示例
HTTP code: 400
Response Body:
{
"code":"BadRequest",
"msg":"Multiple errors in dataInputDto",
"target":"dataInputDto",
"detail":[
{
"code":"9533",
"target":"type",
"message":"数据：上报信息身份不存在"
}
]
}
错误码
| 错误码 | 错误描述 | HTTP状态码 | 中文解释 |
|---|---|---|---|
| 9530 | 数据导入异常 | 400 | 数据导入异常 |
| 9531 | 上报信息身份为空 | 400 | 上报信息身份为空 |
| 9532 | 上报信息数据为空 | 400 | 上报信息数据为空 |
| 9533 | 上报信息身份不存在 | 400 | 上报信息身份不存在 |
| 9534 | 当前租户可用身份为空 | 400 | 当前租户可用身份为空 |
| 9535 | 当前租户未开通拓客专业版 | 400 | 当前租户未开通拓客专业版 |
| 9536 | 上报信息的身份ID为空 | 400 | 上报信息的身份ID为空 |
| 9537 | 上报信息的身份数据中B模型的身份为空 | 400 | 上报信息的身份数据中B模型的身份为空 |
| 9538 | 上报信息的身份来源错误 | 400 | 上报信息的身份来源错误 |
| 9540 | 上报数据长度超过默认值500KB | 400 | 上报数据长度超过默认值500KB |
| 9830 | 字符字段类型异常 | 400 | 字符字段类型异常 |
| 9831 | 数值字段为空 | 400 | 数值字段为空 |
| 9832 | 数值字段类型异常 | 400 | 数值字段类型异常 |
| 9833 | 日期字段类型异常 | 400 | 日期字段类型异常 |
| 9834 | 多值字段为空 | 400 | 多值字段为空 |
场景解决方案
1.自定义潜客属性
若潜客API提供的通用属性字段无法满足您的数据需求，您可以自定义要接入的潜客的属性字段。
自定义的方法，可在百度智能云中查阅自定义潜客属性。
2.订阅潜客事件
接入的潜客经过营销触达，发生的营销互动行为事件，可以通过Webhook方式订阅查询。
Webhook的相关配置，您可以查阅Webhook功能设置。