OpenAPI对接潜客

2021-09-16 593

简介

爱番番有拓客、线索管家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路径说明GEThttps://api-aifanfan.baidu.com/v1/profiles/{id}获取某个指定对象的信息GEThhttps://api-aifanfan.baidu.com/v1/profiles获取指定对象信息的列表POSThttps://api-aifanfan.baidu.com/v1/profiles新建一个对象PATCHhttps://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 OKResponse Body:
{ "affId":"1642009771101528", "accountId":"1642009771101535" }

失败示例

HTTP code: 400Response 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上报数据长度超过默认值500KB400上报数据长度超过默认值500KB9830字符字段类型异常400字符字段类型异常9831数值字段为空400数值字段为空9832数值字段类型异常400数值字段类型异常9833日期字段类型异常400日期字段类型异常9834多值字段为空400多值字段为空

场景解决方案

1.自定义潜客属性

若潜客API提供的通用属性字段无法满足您的数据需求,您可以自定义要接入的潜客的属性字段。自定义的方法,可在百度智能云中查阅自定义潜客属性

2.订阅潜客事件

接入的潜客经过营销触达,发生的营销互动行为事件,可以通过Webhook方式订阅查询。Webhook的相关配置,您可以查阅Webhook功能设置

Webhook对接说明

附录

省市地域代码

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