## 一、基礎(chǔ)文檔

## 1.1 平臺概況

### 1.1.1 初識數(shù)環(huán)通開放平臺

數(shù)環(huán)通開放平臺（Solinkup Open Platform）沉淀了數(shù)環(huán)通業(yè)務(wù)的基礎(chǔ)能力，將數(shù)環(huán)通的能力對外開放，提供給生態(tài)合作伙伴參與服務(wù)數(shù)環(huán)通各類場景，如 API、消息推送等。
同時數(shù)環(huán)通開放平臺也為開發(fā)者提供大量的商業(yè)機(jī)會和清晰的盈利模式。如：

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

### 1.1.2 了解平臺特點(diǎn)

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

### 1.1.3 深入平臺開發(fā)

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

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

## 二、產(chǎn)品功能

### 1.2.1  入駐流程

#### 1.2.1.1 簡介

本文旨在給開發(fā)者介紹數(shù)環(huán)通開放平臺的入駐流程

#### 1.2.1.2 注冊數(shù)環(huán)通帳號

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

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

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

[點(diǎn)此立即注冊](http://www.bus6a.cn/workbench/register)

#### 1.2.1.3 購買付費(fèi)版產(chǎn)品

您可以直接聯(lián)系在線客服或者銷售人員進(jìn)行開通

#### 1.2.1.4 提交認(rèn)證信息（暫不需要）

**1、開發(fā)者需提交的認(rèn)證信息，規(guī)范如下：**

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

**2、相關(guān)資質(zhì)上傳要求如下，如若不符，出示審核駁回意見：**

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

**3、開發(fā)者提交認(rèn)證信息后，平臺會在 10 個工作日內(nèi)進(jìn)行審核**
如若審核不通過，開發(fā)者需要重新提交認(rèn)證信息，重新審核

**4、只有認(rèn)證審核通過后，開發(fā)者才能創(chuàng)建應(yīng)用，如未完成認(rèn)證時，會有如下圖提示：**

#### 1.2.1.5 創(chuàng)建應(yīng)用

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

### 1.2.2 授權(quán)介紹

#### 1.2.2.1 概述

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

#### 1.2.2.2 接入類型介紹

數(shù)環(huán)通開放平臺目前支持 Oauth2 和 ApiSecret 兩種方式。

* Oauth2 **授權(quán)流程如下所示：**

```
開始 -> ISV服務(wù)商：創(chuàng)建應(yīng)用（接入方式選擇Oauth2） -> 商家：訂購服務(wù) ->  商家：同意授權(quán) -> ISV服務(wù)商：通過code換取token ->  ISV服務(wù)商：通過token，openId調(diào)用開放api -> 結(jié)束
```

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

#### 開發(fā)者配置

**1、開發(fā)者在創(chuàng)建工具型應(yīng)用時，須填寫回調(diào)地址**

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

**2、在「應(yīng)用后臺-應(yīng)用概覽」頁面，可查看回調(diào)地址，支持編輯修改**

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

**注：該回調(diào)地址用于接收平臺給應(yīng)用發(fā)的授權(quán)相關(guān)消息和訂購相關(guān)消息，非接口的消息推送**

#### 上架應(yīng)用（暫不需要）

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

Tips：

* 應(yīng)用使用地址會被用來攜帶 code。商家打開授權(quán)開關(guān)或點(diǎn)擊“去使用”按鈕，均會打開應(yīng)用使用地址，并在最后帶上 code
* 建議填寫為對應(yīng)服務(wù)的落地使用頁，同時地址參數(shù)中能標(biāo)識數(shù)環(huán)通來源

2、申請后，會進(jìn)入上架審核，平臺 1～3 個工作日內(nèi)會審核完畢

#### 授權(quán)

開發(fā)者拼接授權(quán) URL，引導(dǎo)商家點(diǎn)擊。商家使用組織主賬號登錄，確定授權(quán)

* **應(yīng)用成功上架后，開發(fā)者拼接授權(quán) URL**

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

**Tips：**

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

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

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

* **引導(dǎo)商家通過瀏覽器訪問以上 url，用戶登錄數(shù)環(huán)通帳號，點(diǎn)“確認(rèn)授權(quán)”按鈕，即可進(jìn)入授權(quán)頁面**

#### 獲取授權(quán) code

**1、組織確認(rèn)授權(quán)成功后，會自動打開應(yīng)用使用地址，此時平臺會把授權(quán) code 帶到使用地址的 url 后面。**
**2、開發(fā)者獲取到 code，并使用該 code 換取 accessToken。**

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

#### 獲取 accessToken

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

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

**0、公共參數(shù)**
參照其他業(yè)務(wù) API 接口，API 接口的公共參數(shù)一致

**1、業(yè)務(wù)參數(shù)**

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

**2、調(diào)用示例**

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

**3、響應(yīng)參數(shù)**

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

**4、響應(yīng)示例**

```json
{
    "requestId": "258dc56f-48b0-469a-8b41-ebd1270d7b80",
    "success": true,
    "code": "__200OK",
    "msgCode": "result.success",
    "message": "執(zhí)行成功",
    "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、公共參數(shù)**
參照其他業(yè)務(wù) API 接口，API 接口的公共參數(shù)一致

**1、請求參數(shù)**

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

Tips：

1. 在 accessToken 過期前 1h 之前，ISV 使用 refreshToken 刷新時，會返回原來的 accessToken 和 refreshToken，但是二者有效期不會變；
2. 在 accessToken 過期前 1h 之內(nèi)，ISV 使用 refreshToken 刷新時，會返回新的 accessToken 和 refreshToken，但是原來的 accessToken 和 refreshToken 繼續(xù)有效一個小時；
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、響應(yīng)參數(shù)**

**4、響應(yīng)示例**

* ApiSecret **授權(quán)流程如下所示：**

```
開始 -> ISV服務(wù)商：創(chuàng)建應(yīng)用（接入方式選擇ApiSecret） -> 商家：訂購服務(wù) ->  商家：同意授權(quán) -> ISV服務(wù)商：通過用戶唯一標(biāo)識（例如用戶手機(jī)號）注冊數(shù)環(huán)通帳號 ->  ISV服務(wù)商：通過token，openId調(diào)用開放api -> 結(jié)束
```

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

#### 開發(fā)者配置

**1、開發(fā)者在創(chuàng)建工具型應(yīng)用時，選擇接入方式**

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

#### 上架應(yīng)用（暫不需要）

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

Tips：

2、申請后，會進(jìn)入上架審核，平臺 1～3 個工作日內(nèi)會審核完畢

#### 調(diào)用開放注冊接口

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

**0、公共參數(shù)**
參照其他業(yè)務(wù) API 接口，API 接口的公共參數(shù)一致

**1、業(yè)務(wù)參數(shù)**

| **名稱** | **類型** | **是否必須** | **描述**    |
| ---------------- | ---------------- | -------------------- | ------------------- |
| outerId        | string         | 是                 | 手機(jī)號等外部標(biāo)識  |
| outerIdType    | string         | 是                 | mobile            |
| method         | string         | 是                 | registerByOuterId |

**2、調(diào)用示例**

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

**3、響應(yīng)參數(shù)**

開放平臺簡介