接入指南

DM Hub REST API让您能够通过编程的方式与DM Hub交互。使用Open API来做客户、客户行为、客户标签、客户群组、订单等数据的接入和导出。

版本与URI

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

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

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

创建应用

在开始使用REST API之前需要先创建一个应用，以获取App ID和App Secret。具体请进入 DM Hub > 设置中心 > 应用集成。

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

获取Access Token

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

HTTP Header中的参数

• Authorization

  app_id和secret应该通过HTTP基本认证的方式传递，即Header的内容为Basic Base64Encode(app_id:secret)

• Content-Type

  该值必须为application/x-www-form-urlencoded

请求体中的参数

• grant_type

  该值为client_credentials

请求方式: POST https://api.convertlab.com/v2/oauth2/token

请求示例:

curl -XPOST 'https://api.convertlab.com/v2/oauth2/token' \
-H 'Authorization: Basic Y2wwMGI4MTU3MWQ4OTE2ZDI6MTZkYzU5ODUzNTgxZmNlNWI5MjFkMmU4OGRlN2RjYjU2ZTRiMzA1YQ==' \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials'

返回示例:

{
  "access_token": "dae7*********************e486",
  "expires_in": 7200
}

Access Token的使用

访问DM Hub REST API时，访问令牌需要以Bearer认证的方式携带在HTTP Authorization头内，如Authorization: Bearer {ACCESS_TOKEN}。以curl方式查询客户接口为例，做一个简单介绍：

curl -H "Authorization: Bearer {ACCESS_TOKEN}" https://api.convertlab.com/v2/customers

这里的ACCESS_TOKEN，就是上文获取的access_token。

URL参数注意事项

在使用http协议进行传参时，如果请求的参数带有一些特殊字符，如 +，%,=等，如果没有进行URL编码可能在发送请求的时候，后端例如Java的web的httpServletRequest会对取出来的参数自动进行URLDecode操作，得到的值和我们的原本想传的参数不是同一个了，例如http的get请求， https://api.convertlab.com/v2/customers?mobile=+8615900000000 ，mobile参数中，带有+号，+号在http传参中属于特殊字符，所以在后端会被自动识别成空格。 所以使用get请求，或者post请求时（如没有采用form-urlencode的形式），如果参数中含有特殊字符，需要进行URL编码。

初始化SDK示例

Gradle中引入依赖

程序中初始化SDK