# 接口鉴权说明

## 一、接入必读

- 【接口鉴权】所有业务接口都需要携带有效的accessToken才可以调用，开发者需要缓存access_token，有效期为<span style="color:red;">2小时</span>，当access_token失效或过期时，需要重新获取。

![](https://cdn-goods.dustess.com/W00000001384/goods/g/b/g/8/gbg8jpdylst1673516587540.png)

- 【加密解密】<span style="color:red;">密文数据仅用于</span>尘锋联系人管理部分接口<span style="color:red;">主动向贵司服务端推送变更事件；主动请求接口时请传递明文。</span>
- 【BASE_URL】`https://qw-openapi-tx.dustess.com/`
- 【调用频率】每个接口都有不同的<span style="color:red;">调用次数</span>/<span style="color:red;">分钟</span>，请根据频率限制合理规划后端逻辑

---

## 二、获取鉴权accessToken
### 1、进入SCRM管理后台

- 您需要通过【PC版企业微信】-【工作台】-【尘锋SCRM】跳转至“尘锋SCRM管理后台”。

![image.png](https://cdn-goods.dustess.com/W00000001384/goods/n/e/y/u/neyuiexmoym1673516592736.png)<br>

### 2、配置白名单IP，获取参数`ClientID`和`ClientSecret`

- 在SCRM管理后台内找到【配置】-【系统设置】-【系统对接】模块，选择进入`“基础信息配置”`，

        完成`ClientID、ClientSecret、白名单IP地址列表`的配置；

    ![image.png](https://cdn-goods.dustess.com/W00000001384/goods/9/6/v/n/96vnxjrqk1j1673516596556.png)<br>
:::caution[]
若暂时不确定对SCRM系统发起请求的服务器出口IP或者其他情况，可先设置为`0.0.0.0`调试,后期根据第三方系统的实际情况进行调整；
:::
### 3、调用接口生成 accessToken

:::caution[]
    获取token时如报错`config not found`,排查步骤如下：
    1、确认系统对接-基础信息界面的配置未被正确提交保存，需要提交之后方可生效；
    2、`ClientID`以及`ClientSecret`输入错误，推荐提交保存配置后直接从目标页面复制对应内容；
:::

```js
POST https://qw-openapi-tx.dustess.com/auth/v1/access_token/token
```
**接口限制**:每分钟调用60次;

- JSON请求参数

| 请求参数名   | 类型   | 说明         |
| ------------ | ------ | ------------ |
| clientid     | String | 客户端ID     |
| clientsecret | String | 客户端Secret |

- curl-请求示例
```bash
curl --location --request POST ' https://qw-openapi-tx.dustess.com/auth/v1/access_token/token' \
--header 'Content-Type: application/json' \
--data-raw '{
    "clientid":"cfGyeasdwdLb",
    "clientsecret":"lBp5FWAxxxxxxxxM60t521731BV1QoJ1J"
}'
```

- 成功响应

成功响应 - Success 200

| 响应参数名       | 类型   | 说明                                                                                                                |
| ---------------- | ------ | ------------------------------------------------------------------------------------------------------------------- |
| code             | String | 返回码（详情查看全局错误码说明）                                                                                    |
| msg              | String | 返回消息                                                                                                            |
| data             | Object | 返回数据                                                                                                            |
| data.accessToken | String | accessToken token有效时间为2个小时，2小时过了可以在用10分钟，两小时内重复请求生成同一token，两个小时之后生成新token |
| data.expiresIn   | String | 过期时间                                                                                                            |

- 结构体JSON-返回示例
```json
{
    "code": 0,
    "msg": "OK",
    "data": {
        "accessToken": "eyJhbGciOiJIUzI1NxIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2Mzk3NDM3NDg0NjI5OTMzMzQsImlhdCI6MTYzOTczNTk0ODQ2Mjk5MzMzNCwiaWQiOiJXMDAwMDAwMDAwODIifQ.ILBGXHoBkKQVdY6VAesw8cHaLQm6qfWw8kE87Llvo4o",
        "expiresIn": "2021-12-17 20:12:28"
    }
}
```