Skip to main content
Version: 简体中文

开放与集成

1.概述​

为了更好地支撑客户个性化的业务需求，DM Hub REST API 可以通过编程的方式与 DM Hub 交互。使用 Open API 来做客户、客户行为、客户标签、客户群组、订单等数据的接入和导出。使用 API 前，需要在 DM Hub 创建应用，获取应用对应的 App ID 和 App Secret 用于 API 接口的调用。

2.API 与应用的版本​

目前系统的接口版本为 API v2，相应创建的应用也是 v2 版本。如果您目前使用的 API 接口还是 v1 版本，请注意创建的应用也必须是旧版本。
APIv1 模块将于 2023 年 07 月 01 日正式下线，下线后请使用 APIv2 进行数据对接。如果 APIv2 无法满足您的要求，请提交需求工单，我们尽快排期。

  • 应用权限：新旧版本应用权限分类不同

  • IP 白名单：旧版本的 IP 白名单为全局设置，对所有应用生效；新版本可以单独为每一个应用设置对应的 IP 白名单

  • API：旧版本应用需要配合 API v1 使用，新版本应用需要配合 API v2 使用

注意：在旧版本应用列表中，可以将某个应用迁移至新版本，迁移并不改变 App ID 和 App Secret，迁移后需要调用 API 2.0 来实现相关功能，在弹窗界面中可以设置相关接口权限，迁移完成后可以在新版本界面里继续设置应用的 IP 白名单。

3.操作入口​

应用集成的功能入口：【系统设置】-【系统集成】-【应用集成】，或是左侧菜单导航【应用与集成】-【开放与集成】

ap3

进入后默认显示的是新版本应用，可切换到旧版应用

ap4

4.旧版应用​

4.1 新建应用​

进入应用集成界面，点击【切换至旧版】进入旧版应用集成。创建应用时，可依次填写以下信息，其中应用权限需要读还是写权限，请查看对应 API 的权限限制。

ap7

点击确定后，可以查看到该应用的 App ID 和 App Secret，请妥善保管 App Secret，为了保证账户安全，关闭窗口后，App Secret 将不再显示，如需获取需要重新生成新的 App Secret

ap8

注意：为了确保账户安全，关闭该信息弹窗后，应用秘钥将永远无法二次显示，请妥善保管好应用秘钥。

在应用列表页可以重置 App Secret。

4.2 添加 IP 白名单​

在应用列表页，点击【设置白名单】，最近拦截的 IP 地址默认进行统计和展示，若需要可以直接加入白名单

ap9

4.3 迁移至新版本​

在应用列表页，点击【迁移至新版本】。迁移并不改变 App ID 和 App Secret，迁移后需要调用 API 2.0 来实现相关功能，下面可以设置相关接口权限，迁移完成后可以在新版本界面里设置应用的 IP 白名单。

ap10

5.新版应用​

5.1 版本与 URI​

DM Hub REST API 第 2 版是最新版，其地址结构具有以下形式：

https://api.convertlab.com/v2/{RESOURCE_PATH}

其中 RESOURCE_PATH 是具体资源的 API 路径。

5.2 创建应用​

进入应用集成，创建应用，设置 IP 白名单。

ap5 ap6

创建应用后，妥善保管应用 ID（App ID）和应用密钥（App Secret）。

5.3 获取 access_token​

DM Hub REST API 使用 OAuth v2.0 协议做认证授权协议。访问 DM Hub REST API 时需要携带访问令牌（access_token）作为认证凭证。 开发者需要妥善保存。access_token 的有效期为 2 小时，需要定时刷新。

请求方式 GET https://api.convertlab.com/v2/oauth2/token?app_id={APPID}&secret={SECRET}&grant_type=client_credentials 请求示例 请求地址

GET https://api.convertlab.com/v2/oauth2/token?app_id={APPID}&secret={SECRET}&grant_type=client_credentials
参数必填描述
app_id是应用的 App ID
secret是应用的 App Secret
grant_type是授权类型，这里必须是 client_credentials

返回示例

{
  "access_token": "dae7*********************e486",
  "expires_in": 7200
}
参数类型描述
access_tokenString接口调用凭证
expires_inString接口调用凭证有效时间