如何进行潜客OpenAPI对接

2021-09-22 1873

简介

爱番番有拓客、线索管家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功能设置

Webhook对接说明

您可以查阅Webhook对接说明文档

附录

省市地域代码

您可以查阅:API字段码表-地域