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

## 1.1 平臺(tái)概況

### 1.1.1 初識(shí)數(shù)環(huán)通開(kāi)放平臺(tái)

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

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

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

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

### 1.1.3 深入平臺(tái)開(kāi)發(fā)

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

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

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

### 1.2.1  入駐流程

#### 1.2.1.1 簡(jiǎn)介

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

#### 1.2.1.2 注冊(cè)數(shù)環(huán)通帳號(hào)

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

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

**2、短信驗(yàn)證碼：支持 6 位短信驗(yàn)證碼**

[點(diǎn)此立即注冊(cè)](http://www.xmfmdq.com/workbench/register)

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

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

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

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

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

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

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

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

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

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

#### 1.2.2.2 接入類(lèi)型介紹

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

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

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

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

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

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

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

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

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

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

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

1、開(kāi)發(fā)測(cè)試完成后，開(kāi)發(fā)者可在「應(yīng)用后臺(tái)-上架管理」頁(yè)面，填寫(xiě)應(yīng)用使用地址，申請(qǐng)應(yīng)用上架

Tips：

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

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

#### 授權(quán)

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

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

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

**Tips：**

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

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

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

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

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

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

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

#### 獲取 accessToken

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

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

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

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

| **名稱(chēng)** | **類(lèi)型** | **是否必須** | **描述** |
| ---------------- | ---------------- | -------------------- | ---------------- |
| 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ù)**

| **名稱(chēng)**      | **類(lèi)型** | **描述**                                                                                                              |
| --------------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| accessToken         | string         | 用于調(diào)用 API 的 accessToken過(guò)期時(shí)間為 expires_in 值可通過(guò) refreshToken 刷新獲取新的 accessToken，過(guò)期時(shí)間仍為 expires_in 值 |
| accessTokenExpired  | number         | accessToken 接口調(diào)用憑證超時(shí)時(shí)間，單位（毫秒），默認(rèn)有效期：7 天                                                            |
| openId              | string         | 用戶(hù) ID                                                                                                                     |
| refreshToken        | string         | 用于刷新 accessToken 的刷新令牌（有效期：14 天）                                                                            |
| refreshTokenExpired | number         | accessToken 接口調(diào)用憑證超時(shí)時(shí)間，單位（毫秒），默認(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 方式請(qǐng)求，可獲取新的 accessToken：

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

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

**1、請(qǐng)求參數(shù)**

| **名稱(chēng)** | **類(lèi)型** | **是否必須** | **描述**                               |
| ---------------- | ---------------- | -------------------- | ---------------------------------------------- |
| method         | string         | 是                 | refreshAccessToken                           |
| refreshToken   | string         | 是                 | 刷新 accessToken 的刷新令牌（有效期：14 天） |

Tips：

1. 在 accessToken 過(guò)期前 1h 之前，ISV 使用 refreshToken 刷新時(shí)，會(huì)返回原來(lái)的 accessToken 和 refreshToken，但是二者有效期不會(huì)變；
2. 在 accessToken 過(guò)期前 1h 之內(nèi)，ISV 使用 refreshToken 刷新時(shí)，會(huì)返回新的 accessToken 和 refreshToken，但是原來(lái)的 accessToken 和 refreshToken 繼續(xù)有效一個(gè)小時(shí)；
3. 在 accessToken 過(guò)期后，ISV 使用 refreshToken 刷新時(shí)，將獲得新的 acces_token 和 refreshToken，同時(shí)原來(lái)的 acces_token 和 refreshToken 失效；

**2、請(qǐng)求示例**

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

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

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

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

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

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

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

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

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

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

Tips：

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

#### 調(diào)用開(kāi)放注冊(cè)接口

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

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

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

| **名稱(chēng)** | **類(lèi)型** | **是否必須** | **描述**    |
| ---------------- | ---------------- | -------------------- | ------------------- |
| outerId        | string         | 是                 | 手機(jī)號(hào)等外部標(biāo)識(shí)  |
| 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ù)**

開(kāi)放平臺(tái)簡(jiǎn)介