如何进行线索OpenAPI对接

2023-06-12 43367

准备工作

1. 登录爱番番申请API授权

授权是指授予某个APP调用某个API的权限，APP在获得API的授权之后才能调用API。当前爱番番Open API处于邀请开放制，我们会尽快反馈您的申请。

申请入口：

2. 查看文档，调用接口

以上步骤完成后，您已完成调用爱番番API的准备工作。您可以查阅爱番番目前开放的API列表见爱番番API列表，然后可以前往“进行首个API调用”进行进一步学习了解。

进行首个API调用

1. 确认要调用的接口（需先申请授权）

调用API名称	详细介绍
线索导入	通过该API，可将其他系统的线索创建到爱番番
线索更新	通过该API，可更新爱番番线索基本信息
线索导出	通过该API，可查询导出爱番番线索管家中线索的基本信息
.......	.......

更多接口可查阅爱番番API在线列表。可以通过百度云在线调用或者通过工具调用。

2. 了解必要的接口规范

爱番番API遵循业内普遍接受RESTful的设计风格，调用API前您需要了解：

设置URL地址

所有请求须使用HTTPS协议，统一的请求地址前缀为：https://api-aifanfan.baidu.com

每个接口都带有v1、v2等版本号，url path都使用小写字母。比如线索接口为https://api-aifanfan.baidu.com/v1/leads

设置Http方法

Http方法	URL路径	说明
GET	https://api-aifanfan.baidu.com/v1/leads/{id}	获取某个指定对象的信息
GET	https://api-aifanfan.baidu.com/v1/leads	获取指定对象信息的列表
POST	https://api-aifanfan.baidu.com/v1/leads	新建一个对象
PATCH	https://api-aifanfan.baidu.com/v1/leads/{id}	更新指定对象的部分信息
PUT	https://api-aifanfan.baidu.com/v1/leads/{id}	更新指定对象的全部信息
DELETE	https://api-aifanfan.baidu.com/v1/leads/{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即可。

设置Body

body信息的填写参考具体接口的定义。比如创建线索时的Body示例为：

{
  "businessParam": {
    "leadsGroup": 1,
    "region": 385,
    "address": "北京市-海淀区-上地十街10号",
    "remark": "唐朝浪漫主义诗人",
    "name": "李白",
    "mobilePhone": [
      "13661236633",
      "13661236634"
    ],
    "gender": 1,
    "birthday": "1993-01-01",
    "email": "libai@baidu.com",
    "wechat": "litaibai",
    "qq": "1554343100",
    "telephone": "010-82071163",
    "company": "百度",
    "companyPhone": "010-82071163",
    "companyEmail": "libaicompany@baidu.com",
    "companyWebsite": "www.baidu.com"
  }
}

如涉及自定义字段请查阅开启线索自定义字段的场景下如何使用线索API

解析状态码和返回值

解析请求成功时的状态码

GET 请求执行成功并返回相应数据，状态码200 --OK
POST 对象创建成功并返回相应资源数据, 创建完成后响应头中应该携带头标 Location ，指向新建资源的地址, 状态码201 CREATE
PATCH、PUT 对象更新成功，返回响应的数据，状态码201 ，如果不返回相应资源数据，状态码204 No Content
DELETE 请求执行成功，不返回相应资源数据状态码204 No Content

解析请求成功时的返回值

HTTP code: 200
Response Body:{"leadsId":1533871293736708}

解析请求失败时的状态码

code	http状态码	说明
BadRequest	400	请求参数存在错误，如必须参数缺失，参数不符合预期范围等
Unauthorized	401	没有权限
NotFound	404	资源不存在
Conflict	409	资源冲突，重复的资源
UnprocessableEntity	422	请求格式正确，但是由于含有语义错误，无法响应
PreconditionRequired	428	要求先决条件，如果想要请求能成功必须满足一些预设的条件
InternalError	500	服务异常

解析请求失败时的返回值

HTTP code: 400
Response Body:{"code": "BadRequest","message": "字段校验未通过！","target": "businessParam","detail": [{"code": "NullValue","target": "name","message": "姓名不能为空"}]}

3. 通过百度云在线调用API

您可以前往百度云上爱番番API在线列表，输入您申请的Access Key和Secret Key，发起在线调用。

4. 通过代码调用API

您可以前往百度云上爱番番API在线列表，查看java sdk示例代码（目前只提供java sdk版本）。

5. 通过工具如postman调用API

设置X-Bce-Signature时，签名生成可参考生成签名示例代码。

场景解决方案

1. 开启线索自定义字段的场景下如何使用线索API

您可以查阅开启线索自定义字段的场景下如何使用线索API

2. 自动旅程场景下自定义动作

您可以查阅自动旅程Webhook

Webhook对接说明

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

附录

1. 省市地域代码

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

本文导读