## 一、基礎文檔

## 1.1 平臺概況

### 1.1.1 初識數環通開放平臺

數環通開放平臺（Solinkup Open Platform）沉淀了數環通業務的基礎能力，將數環通的能力對外開放，提供給生態合作伙伴參與服務數環通各類場景，如 API、消息推送等。
同時數環通開放平臺也為開發者提供大量的商業機會和清晰的盈利模式。如：

* **大量的商業機會：** 商家會有多樣化需求，無論你是第三方開發者（ISV）、傳統軟件廠商、行業型網站或者大商家，都能在數環通開放平臺上找到合適的業務方向。
* **清晰的盈利模式：** 開發者基于開放能力完成應用開發，上架到服務市場，通過服務市場的應用銷售分成、軟件直接銷售收入等獲得回報。

### 1.1.2 了解平臺特點

* **業務強大、商機無限：**
  數環通依托于各類平臺，擁有上億的潛在用戶數，快速增長業務給商家、開發者帶來了無限的商機。
* **開放規模大、程度深、限制少：**
  數環通開放平臺對外開放涵蓋了數環通核心流程引擎、業務模板的主要流程，日均 API 調用量超十萬。我們會持續去開放更多的生態能力去服務開發者，幫助開發者實現各類的系統定制。
* **合作形式豐富：**
  數環通開放平臺是基于各類平臺的綜合開放平臺，我們平臺以把業務開放到盡可能多的領域為宗旨。目前，已經為合作伙伴提供了以下的合作形式：商家自用型應用、第三方工具型應用，未來還會開放更多的應用類目，為用戶提供多樣化的應用。
* **系統安全穩定：**
  數環通開放平臺是基于 OAuth 2.0 授權，針對用戶數據加密，安全可靠；日均數十萬級 API 調用量、平均延遲低于 100ms、系統穩定性高。

### 1.1.3 深入平臺開發

數環通開放平臺主要提供兩種業務接入模式，軟件服務商身份接入模式和商家自研身份接入模式。無論您是第三方開發者（ISV）還是商家，都能基于開放電商開放平臺找到適合自己的業務方向。

* **軟件服務商接入模式：**
  數環通開放平臺提供的豐富 API 涵蓋數環通各個核心業務流程，基于這些能力可以為商家提供各類應用，解決各個平臺，數據打通等各方面的問題。
* **商家自研接入模式：**
  沒有開發能力的商家可以在服務市場購買服務商開發的服務，然后直接使用服務進行商家業務經營管理。有一定 IT 研發能力的商家，可根據自己的定制業務場景，直接入駐平臺創建商家自用型應用，然后集成到自己的商家管理系統進行統一業務運營管理，通過對數據進行管理來發掘更多的潛在價值。

## 二、產品功能

### 1.2.1  入駐流程

#### 1.2.1.1 簡介

本文旨在給開發者介紹數環通開放平臺的入駐流程

#### 1.2.1.2 注冊數環通帳號

![1662344313881.jpg](/media/202307/2023-07-24_1448560.6632589764617729.png "1662344313881.jpg")

**1、手機號碼** （注：如果你是自研商家，請務必使用組織管理人手機號注冊）
如何查看組織管理人手機號

**2、短信驗證碼：支持 6 位短信驗證碼**

[點此立即注冊](http://www.ztnbzvn.cn/workbench/register)

#### 1.2.1.3 購買付費版產品

您可以直接聯系在線客服或者銷售人員進行開通

#### 1.2.1.4 提交認證信息（暫不需要）

**1、開發者需提交的認證信息，規范如下：**

* 保證所填寫的全部信息真實且與實際信息對應，否則平臺會出示審核駁回意見
* 企業名稱、注冊地址、統一社會信用代碼、營業期限、法人代表人姓名、證件號碼、證件有效期要與上傳的證件照片保持一致，否則平臺會出示審核駁回意見

**2、相關資質上傳要求如下，如若不符，出示審核駁回意見：**

* 圖片清晰且邊框完整
* 提供資質附件如為復印件，須加蓋公章

**3、開發者提交認證信息后，平臺會在 10 個工作日內進行審核**
如若審核不通過，開發者需要重新提交認證信息，重新審核

**4、只有認證審核通過后，開發者才能創建應用，如未完成認證時，會有如下圖提示：**

#### 1.2.1.5 創建應用

![1662344258739.jpg](/media/202307/2023-07-24_1448560.4577850507564494.png "1662344258739.jpg")

### 1.2.2 授權介紹

#### 1.2.2.1 概述

數環通開放平臺工具型應用面向有產品、開發團隊，需要為市場上的數環通用戶，提供通用或定制的解決方案。申請工具型應用的開發者，應用申請成功后，可以擁有其對應類目的接口使用權限。應用必須上架到數環通服務市場，商家可以在服務市場訂購應用并和組織建立授權關系。只有經過商家授權才能進行數據的對接使用，可同時為大量組織提供服務。

#### 1.2.2.2 接入類型介紹

數環通開放平臺目前支持 Oauth2 和 ApiSecret 兩種方式。

* Oauth2 **授權流程如下所示：**

```
開始 -> ISV服務商：創建應用（接入方式選擇Oauth2） -> 商家：訂購服務 ->  商家：同意授權 -> ISV服務商：通過code換取token ->  ISV服務商：通過token，openId調用開放api -> 結束
```

![](https://solinkup.com/help/webfile/upload/2022/07-07/06-23-0708541162801459.png)

#### 開發者配置

**1、開發者在創建工具型應用時，須填寫回調地址**

![1662344258739.jpg](/media/202307/2023-07-24_1448560.7868748722818565.png "1662344258739.jpg")

**2、在「應用后臺-應用概覽」頁面，可查看回調地址，支持編輯修改**

![1662344258739.jpg](/media/202307/2023-07-24_1448560.5228809915252268.png "1662344258739.jpg")

**注：該回調地址用于接收平臺給應用發的授權相關消息和訂購相關消息，非接口的消息推送**

#### 上架應用（暫不需要）

1、開發測試完成后，開發者可在「應用后臺-上架管理」頁面，填寫應用使用地址，申請應用上架

Tips：

* 應用使用地址會被用來攜帶 code。商家打開授權開關或點擊“去使用”按鈕，均會打開應用使用地址，并在最后帶上 code
* 建議填寫為對應服務的落地使用頁，同時地址參數中能標識數環通來源

2、申請后，會進入上架審核，平臺 1～3 個工作日內會審核完畢

#### 授權

開發者拼接授權 URL，引導商家點擊。商家使用組織主賬號登錄，確定授權

* **應用成功上架后，開發者拼接授權 URL**

```
http://www.ztnbzvn.cn/workbench/oauth/login?appKey=xx&urlCode=xx&timestamp=xx&method=checkUrlCode&version=1&redirectUrl=yourUrl
```

**Tips：**

* **示例中的** appKey **需要替換成您應用的實際值** ，可以在【應用后臺-應用概覽】中可以查看
* timestamp 為當前時間戳毫秒數，誤差不能超過 10 分鐘
* version 目前傳 1
* urlCode 的計算規則為 MD5(appKey+appSecret+timestamp)
* redirectUrl 傳用戶授權后需要回調的頁面，可以在【應用后臺-應用概覽】中可以查看

| **名稱** | **類型** | **是否必須** | **描述**                                                                                                                |
| ---------------- | ---------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| appKey         | string         | 是                 | 在應用后臺-應用概覽中可以查看，每個應用唯一值                                                                                 |
| method         | string         | 是                 | checkUrlCode                                                                                                                  |
| version        | string         | 是                 | 1                                                                                                                             |
| timestamp      | string         | 是                 | 當前時間戳毫秒數，誤差不能前后超過 5 分鐘                                                                                     |
| urlCode        | string         | 是                 | MD5("appKey"+"appSecret"+"timestamp")，舉例：

```
MD5(AppKey@4FF354C41EBF4187BA148E00E3EFED69AppSecret_8083hfh1654487840)
```

* **引導商家通過瀏覽器訪問以上 url，用戶登錄數環通帳號，點“確認授權”按鈕，即可進入授權頁面**

#### 獲取授權 code

**1、組織確認授權成功后，會自動打開應用使用地址，此時平臺會把授權 code 帶到使用地址的 url 后面。**
**2、開發者獲取到 code，并使用該 code 換取 accessToken。**

Tips：授權碼 code 有效期為 10 分鐘，有效期內可用來換取 accessToken，不限次數；如失效，可以讓商家前往【組織后臺-> 授權管理】頁面，點擊“使用”按鈕即可

#### 獲取 accessToken

組織同意授權后，使用 POST 方式請求，使用授權 code，可獲取 accessToken；

```
https://api.solinkup.com/openapi/oauth2/getAccessToken
```

**0、公共參數**
參照其他業務 API 接口，API 接口的公共參數一致

**1、業務參數**

| **名稱** | **類型** | **是否必須** | **描述** |
| ---------------- | ---------------- | -------------------- | ---------------- |
| authCode       | string         | 是                 | 授權碼 code    |
| method         | string         | 是                 | getAccessToken |

**2、調用示例**

```json
{
    "appKey":"AppKey@4FF354C41EBF4187BA148E00E3EFED69",
    "method":"getAccessToken",
    "timestamp":"1651218530319",
    "authCode":"AuthCode@37e0107c183949178853b105b47d85c7",
    "version":"1"
}
```

**3、響應參數**

| **名稱**      | **類型** | **描述**                                                                                                              |
| --------------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| accessToken         | string         | 用于調用 API 的 accessToken過期時間為 expires_in 值可通過 refreshToken 刷新獲取新的 accessToken，過期時間仍為 expires_in 值 |
| accessTokenExpired  | number         | accessToken 接口調用憑證超時時間，單位（毫秒），默認有效期：7 天                                                            |
| openId              | string         | 用戶 ID                                                                                                                     |
| refreshToken        | string         | 用于刷新 accessToken 的刷新令牌（有效期：14 天）                                                                            |
| refreshTokenExpired | number         | accessToken 接口調用憑證超時時間，單位（毫秒），默認有效期：7 天                                                            |

**4、響應示例**

```json
{
    "requestId": "258dc56f-48b0-469a-8b41-ebd1270d7b80",
    "success": true,
    "code": "__200OK",
    "msgCode": "result.success",
    "message": "執行成功",
    "data": {
        "openId": "OpenId@128D573F0EB6405EAF334A731E31BFF3",
        "accessToken": "AccessToken@3a859c26d23348dc9844acac0a533697",
        "refreshToken": "RefreshToken@BEEC8358E6544FEDA7FB4197ADE3D920",
        "accessTokenExpired": 1651823380704,
        "refreshTokenExpired": 1652428180704
    },
    "pager": null
}
```

#### 刷新 Token

使用上述步驟中獲取到的 refreshToken，POST 方式請求，可獲取新的 accessToken：

```
https://api.solinkup.com/openapi/oauth2/refreshAccessToken
```

**0、公共參數**
參照其他業務 API 接口，API 接口的公共參數一致

**1、請求參數**

| **名稱** | **類型** | **是否必須** | **描述**                               |
| ---------------- | ---------------- | -------------------- | ---------------------------------------------- |
| method         | string         | 是                 | refreshAccessToken                           |
| refreshToken   | string         | 是                 | 刷新 accessToken 的刷新令牌（有效期：14 天） |

Tips：

1. 在 accessToken 過期前 1h 之前，ISV 使用 refreshToken 刷新時，會返回原來的 accessToken 和 refreshToken，但是二者有效期不會變；
2. 在 accessToken 過期前 1h 之內，ISV 使用 refreshToken 刷新時，會返回新的 accessToken 和 refreshToken，但是原來的 accessToken 和 refreshToken 繼續有效一個小時；
3. 在 accessToken 過期后，ISV 使用 refreshToken 刷新時，將獲得新的 acces_token 和 refreshToken，同時原來的 acces_token 和 refreshToken 失效；

**2、請求示例**

```json
{
    "appKey":"AppKey@4FF354C41EBF4187BA148E00E3EFED69",
    "method":"refreshAccessToken",
    "timestamp":"1650615919168",
    "refreshToken": "RefreshToken@BEEC8358E6544FEDA7FB4197ADE3D920",
    "version":"1"
}
```

**3、響應參數**

**4、響應示例**

* ApiSecret **授權流程如下所示：**

```
開始 -> ISV服務商：創建應用（接入方式選擇ApiSecret） -> 商家：訂購服務 ->  商家：同意授權 -> ISV服務商：通過用戶唯一標識（例如用戶手機號）注冊數環通帳號 ->  ISV服務商：通過token，openId調用開放api -> 結束
```

![](/media/202307/2023-07-24_1448570.03701290695318393.png)

#### 開發者配置

**1、開發者在創建工具型應用時，選擇接入方式**

![1662344258739.jpg](/media/202307/2023-07-24_1448570.18826931650126832.png "1662344258739.jpg")

#### 上架應用（暫不需要）

1、開發測試完成后，開發者可在「應用后臺-上架管理」頁面，填寫應用使用地址，申請應用上架

Tips：

2、申請后，會進入上架審核，平臺 1～3 個工作日內會審核完畢

#### 調用開放注冊接口

```
https://api.solinkup.com/openapi/oauth2/registerByOuterId
```

**0、公共參數**
參照其他業務 API 接口，API 接口的公共參數一致

**1、業務參數**

| **名稱** | **類型** | **是否必須** | **描述**    |
| ---------------- | ---------------- | -------------------- | ------------------- |
| outerId        | string         | 是                 | 手機號等外部標識  |
| outerIdType    | string         | 是                 | mobile            |
| method         | string         | 是                 | registerByOuterId |

**2、調用示例**

```json
{
    "appKey":"AppKey@4FF354C41EBF4187BA148E00E3EFED69",
    "method":"registerByOuterId",
    "timestamp":"1651218530319",
    "outerId":"15111901148",
    "outerIdType":"mobile",
    "version":"1"
}
```

**3、響應參數**

開放平臺簡介