## 一、API 調用指南

### 1.1.1 前言

數環通開放平臺的 API 是基于 HTTP 協議來調用的。

### 1.1.2 調用流程

組裝參數 > 生成簽名 > 拼裝 HTTP 請求 > 發起 HTTP 請求 > 獲得 HTTP 響應 > 解析 json 結果

### 1.1.3 調用地址

數環通開放平臺目前只提供正式環境給開發者，API 調用地址為如下，請訪問時拼接對應方法 URL：

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

### 1.1.4  調用方式

POST 方式

### 1.1.5 公共參數

調用任何一個 API 都必須傳入的參數，目前支持的公共參數有：

| **參數名稱** | **參數類型** | **是否必須** | **示例值**                             | **參數描述**                                                                          |
| -------------------- | -------------------- | -------------------- | ---------------------------------------------- | --------------------------------------------------------------------------------------------- |
| method             | string             | 是                 | getAccessToken                               | 調用的 API 接口名稱                                                                         |
| appKey             | string             | 是                 | AppKey@AAC3CEDBA71B4CC6AEAB1DDADD6A6D8F      | 應用創建完成后被分配的 key                                                                  |
| accessToken        | string             | 是                 | AccessToken@3a859c26d23348dc9844acac0a533697 | 用于調用 API 的 accessToken                                                                 |
| timestamp          | long               | 是                 | 1651218530319                                | 時間戳，格式為 ms，和服務器時間相差超過 5 分鐘會報錯                                        |
| version            | string             | 是                 | 1                                            | API 協議版本，當前版本為 1                                                                  |
| sign               | string             | 是                 | 簽名算法參照下面的介紹                       | 輸入參數簽名結果                                                                            |
| signMethod         | String             | 是                 | hmac-sha256                                  | 簽名算法類型 1. hmac-sha256，采用 hmac_sha_256 算法簽名（推薦）；2. md5，采用 md5 算法簽名。 |

* method、appKey、accessToken、timestamp、version、signMethod 采用 body 方式傳遞。
* sign 采用 header 方式傳遞。

### 1.1.6 業務參數

API 調用除了必須包含公共參數外，如果 API 本身有業務級的參數也必須傳入。
每個 API 的業務參數請參考 數環通開放 API 文檔

### 1.1.7 簽名算法

為了防止 API 調用過程中被黑客惡意篡改，調用任何一個 API 都需要攜帶簽名；服務端會根據請求參數，對簽名進行驗證，簽名不合法的請求將會被拒絕。
目前支持的簽名算法為 **hmac-sha256（推薦）、md5** 兩種。

下面以 PHP 為例，詳細解析一下簽名算法：
**STEP1：序列化參數**
將參數序列化成 JSON 格式，并滿足下面幾個要求：

* 保證 JSON 所有層級上 Key 的有序性

```
// 序列化前的對象 
$a1 = array( 
    "c" => 3, 
    "b" => 2, 
    "a" => array( 
       "c" => 3, 
       "b" => 2, 
       "a" => 1, 
    ), 
); 
// 序列化后的結果 
// {"a":{"a":1,"b":2,"c":3},"b":2,"c":3}
```

* 保證 JSON 的所有數值不帶多余的小數點

```
// 序列化前的對象
$a2 = array(
    "a" => 1.0,
);
// 序列化后的結果
// {"a":1}
```

* 禁用 Html Escape，保證轉義邏輯與示例代碼一致

```
$a3 = array(
    'a' => "&<>='/? 漢 ??",// 附加符號、中日韓、Emoji 都不轉義
);
// 序列化后的結果
// {"a":"&<>='/? 漢 ??"}
```

**STEP2：計算簽名**

* **拼接請求參數**

將 accessToken、appKey、method、signMethod、timestamp、version參數以及請求中的其他所有參數的鍵值對按字典排序順序依次拼接拼接
如下：

```
$paramPattern = 'accessToken'.$accessToken.'appKey'.$appKey.'method'.$method.'signMethod'.$signMethod.'timestamp'.$timestamp.'version'.$version; 
// 拼接后的格式差不多是這樣： 
// accessToken***appKey***method***timestamp***version*
```

* **在上一步基礎上，在頭尾拼接 app_secret**

```
$signPattern = $appSecret.$paramPattern.$appSecret; 
// 拼接后的格式差不多是這樣： 
$signPattern = AppSecret@88f78c12b63148ae8c7d71d0c8c3e518accessTokenAccessToken@3a859c26d23348dc9844acac0a533697appKeyAppKey@4FF354C41EBF4187BA148E00E3EFED69methodloginByOpenIdsignMethodmd5timestamp1651218530319v1AppSecret@88f78c12b63148ae8c7d71d0c8c3e518
```

* **使用 hmac-sha256 算法，計算簽名串**

```
$sign = hash_hmac("sha256", $signPattern);
```

**STEP3：將簽名放置到 http 請求頭中**

### 1.1.8 簽名算法代碼示例

```
package com.shuhuan.ipaas.gateway.entity.oauth;

import com.shuhuan.ipaas.core.encryption.Md5Util;
import org.apache.commons.lang3.StringUtils;
import org.springframework.util.Assert;

import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;
import java.util.Base64;
import java.util.Map;
import java.util.Objects;
import java.util.TreeMap;

/**
 * @Description: 開放平臺加簽代碼 demo
 * @Author gaofeng
 * @Date 8/18/22 5:26 PM
 **/
public class OpenSignDemo {

private static String appKey = "appKey";
    private static String openId = "openId";
    private static String method = "method";
    private static String version = "version";
    private static String timestamp = "timestamp";
    private static String accessToken = "accessToken";
    private static String redirectUrl = "redirectUrl";
    private static String authCode = "authCode";
    private static String signMethod = "signMethod";
    private static String appSecret = "appSecret";

public static void main(String[] args) {
        Map<String, Object> params = buildInput();
        String sign = getSign(params);
    }

public static Map<String, Object> buildInput() {
        Map<String, Object> result = new TreeMap<>();
        if (StringUtils.isNotEmpty(appKey)) {
            result.put("appKey", appKey);
        }
        if (StringUtils.isNotEmpty(openId)) {
            result.put("openId", openId);
        }
        if (StringUtils.isNotEmpty(method)) {
            result.put("method", method);
        }
        if (StringUtils.isNotEmpty(version)) {
            result.put("version", version);
        }
        if (Objects.nonNull(timestamp)) {
            result.put("timestamp", timestamp);
        }
        if (StringUtils.isNotEmpty(accessToken)) {
            result.put("accessToken", accessToken);
        }
        if (StringUtils.isNotEmpty(redirectUrl)) {
            result.put("redirectUrl", redirectUrl);
        }
        if (StringUtils.isNotEmpty(authCode)) {
            result.put("authCode", authCode);
        }
        if (StringUtils.isNotEmpty(signMethod)) {
            result.put("signMethod", signMethod);
        }
        return result;
    }

/**
     * 驗簽
     *
     * @param inputParams
     */
    public static String getSign(Map<String, Object> inputParams) {
        String calculateSign = null;
        String signPattern = null;
        StringBuffer paramJoin = new StringBuffer();
        inputParams.forEach((key, value) -> paramJoin.append(key).append(value));
        signPattern = appSecret + paramJoin.toString() + appSecret;
        calculateSign = calculateSign(signMethod, signPattern);
        return calculateSign;
    }

public static String calculateSign(String signMethod, String origin){
        switch (signMethod){
            case "MD5":return encryptMd5(origin);
            case "base64":return Base64.getEncoder().encodeToString(origin.getBytes());
            case "sha256":return SHA(origin, "SHA-256");
            default:return Md5Util.encryptMd5(origin);
        }
    }

/**
     * MD5 加密
     * @param sourceStr
     * @return
     */
    public static String encryptMd5(String sourceStr) {
        // 用于加密的字符
        String result = "";
        try {
            MessageDigest md = MessageDigest.getInstance("MD5");
            md.update(sourceStr.getBytes());
            byte b[] = md.digest();
            int i;
            StringBuffer buf = new StringBuffer("");
            for (int offset = 0; offset < b.length; offset++) {
                i = b[offset];
                if (i < 0) {
                    i += 256;
                }
                if (i < 16) {
                    buf.append("0");
                }
                buf.append(Integer.toHexString(i));
            }
            result = buf.toString();
        } catch (NoSuchAlgorithmException e) {
            e.printStackTrace();
        }
        return result;
    }

/**
     * 字符串 SHA 加密
     *
     * @param strText
     * @return
     */
    private static String SHA(final String strText, final String strType) {
        // 返回值
        String strResult = null;

// 是否是有效字符串
        if (strText != null && strText.length() > 0) {
            try {
                // SHA 加密開始
                // 創建加密對象 并傳入加密類型
                MessageDigest messageDigest = MessageDigest.getInstance(strType);
                // 傳入要加密的字符串
                messageDigest.update(strText.getBytes());
                // 得到 byte 類型結果
                byte byteBuffer[] = messageDigest.digest();

// 將 byte 轉換爲 string
                StringBuffer strHexString = new StringBuffer();
                // 遍歷 byte buffer
                for (int i = 0; i < byteBuffer.length; i++) {
                    String hex = Integer.toHexString(0xff & byteBuffer[i]);
                    if (hex.length() == 1) {
                        strHexString.append('0');
                    }
                    strHexString.append(hex);
                }
                // 得到返回結果
                strResult = strHexString.toString();
            } catch (NoSuchAlgorithmException e) {
                e.printStackTrace();
            }
        }

return strResult;
    }

}
```

## 二、API 文檔

### 1.2.1 授權 API

#### 獲取 accessToken：

/openapi/oauth2/getAccessToken

請求示例

```
{
    "appKey": "AppKey@0A03EDEB29654A9CAE2A7D9F1A8F487E",
    "method": "getAccessToken",
    "timestamp": "1652413038144",
    "authCode": "AuthCode@4c28f9e17178416f8cc918539fc1975b",
    "version": "1"
}
```

響應示例

```
{
    "requestId": "d20e2ef1-a9dc-4607-92fa-8f0b0c5a5270",
    "success": true,
    "code": "__200OK",
    "msgCode": "result.success",
    "message": "執行成功",
    "data": {
        "openId": "OpenId@128D573F0EB6405EAF334A731E31BFF3",
        "accessToken": "AccessToken@3299a7f3e52649f3bd51bd9d0d7f63c5",
        "refreshToken": "RefreshToken@BEEC8358E6544FEDA7FB4197ADE3D920",
        "accessTokenExpired": 1653018049464,
        "refreshTokenExpired": 1652428181000
    },
    "pager": null
}
```

#### 刷新 AccessToken

/openapi/oauth2/refreshAccessToken

請求示例

```
{
    "appKey":"shuhuan",
    "method":"refreshAccessToken",
    "timestamp":"1652176558967",
    "refreshToken":"RefreshToken@BEEC8358E6544FEDA7FB4197ADE3D920",
    "version":"1"
}
```

響應示例

### 1.2.2 模板 API

#### 獲取模板列表

/openapi/oauth2/${appKey}/template/list

請求示例

```
/openapi/oauth2/AppKey@4FF354C41EBF4187BA148E00E3EFED69/template/list
```

響應示例

```
{
    "requestId": "02bb4640-4258-456c-a205-b25e294b03fd",
    "success": true,
    "code": "__200OK",
    "msgCode": "result.success",
    "message": "執行成功",
    "data": [
        {
            "templateId": "76f28c004b4811ec9fa40242ac120009",
            "name": "【矩易】抖店功能包",
            "description": "將矩易線上線下打通",
            "unAuthorized": [],
            "templates": null
        }
    ],
    "pager": null
}
```

#### 根據父模板 ID 刪除流程

/openapi/oauth2/deleteFlowByParentTemplateId

請求事例

```
{
  "openId":"OpenId@128D573F0EB6405EAF334A731E31BFF3",
  "parentTemplateId":"ParentTemplateId_C76E9CC62467428B827A0360588DDB7C",
  "appKey":"AppKey@AAC3CEDBA71B4CC6AEAB1DDADD6A6D8F",
  "timestamp":"1657260731000",
  "version":"1"
}
```

響應結果

```
{
    "requestId": "5df490ea-86db-4455-a0ed-02562adb0c29",
    "success": true,
    "code": "200",
    "msgCode": "result.success",
    "message": "操作成功",
    "data": null,
    "pager": null
}
```

### 1.2.3 抖店 API

**獲取抖店授權詳情**

https://api.solinkup.com/trigger/api/jinritemai/getAuthInfo/{openId}

method:getAuthInfo

請求示例

```
https://api.solinkup.com/trigger/api/jinritemai/getAuthInfo/OpenId_37127491
```

響應示例

```
{
    "requestId": "02bb4640-4258-456c-a205-b25e294b03fd",
    "success": true,
    "code": "__200OK",
    "msgCode": "result.success",
    "message": "執行成功",
    "data": [
        {
          "expire_time":"2020-12-30 00:00:00", 
          "rights_type":1, 
          "spec_type":0, 
          "spec_val":"至尊版" 
          "shop_id":124124124
        }
    ],
    "pager": null
}
```

**獲取抖店訂單列表**

https://api.solinkup.com/trigger/api/jinritemai/listOrder/{openId}

method:listOrder

輸入

| 名稱            | 類型    | 是否必須 | 備注                                                                                            |
| ----------------- | --------- | ---------- | ------------------------------------------------------------------------------------------------- |
| orderType       | Integer | 非必須   | 【訂單類型】 0、普通訂單 2、虛擬商品訂單 4、電子券（poi 核銷） 5、三方核銷                      |
| tradeType       | Integer | 非必須   | 【交易類型】 0、普通 1、拼團 2、定金預售 3、訂金找貸 4、拍賣 5、0 元單 6、回收 7、寄賣 10、樣品 |
| orderStatus     | Integer | 非必須   | 訂單狀態                                                                                        |
| createTimeStart | Long    | 必須     | 下單開始時間，秒級時間戳；最大支持查詢最近 90 天內的數據                                        |
| createTimeEnd   | Long    | 必須     | 下單結束時間，秒級時間戳；最大支持查詢最近 90 天內的數據                                        |
| page            | Integer | 非必須   | 頁碼，0 頁開始；size* page 最大不能超過 5 萬條。超過 5 萬條請使用創建時間或更新事情分割。       |
| size            | Integer | 非必須   | 單頁大小，限制 100 以內。                                                                       |

示例：

```
{
    "cipher_infos": [
        {
            "auth_id": "4915439432903042609",
            "cipher_text": "$+u8xXdX3gjEOMuebueEscdYqAAM9hOxFjucgAgydcvA=$BaNos2xvXNljXSMeQZEZlJ3tJI4oM9JPg6dIqC03Niq9Bn9bIVVUKZZpzR7wWB2DT58wAjL3UUM7Anm9Wc2FGSVG1/6anbGAQXR4lkAbkuXrZg==*CgkIARCtHCABKAESPgo8xOiuiDmw3oesarVkYjaiai4GrWDXuWEcAap69zj/Bc3CRQ6P7rx+trUfdcYOfI7LKz2LSb3crWpnb1oPGgA=$1$$"
        },
        {
            "auth_id": "4915439432903042609",
            "cipher_text": "$+u8xXdX3gjEOMuebueEscdYqAAM9hOxFjucgAgydcvA=$BaNos2xvXNljXSMeQZEZlJ3tJI4oM9JPg6dIqC03Niq9Bn9bIVVUKZZpzR7wWB2DT58wAjL3UUM7Anm9Wc2FGSVG1/6anbGAQXR4lkAbkuXrZg==*CgkIARCtHCABKAESPgo8xOiuiDmw3oesarVkYjaiai4GrWDXuWEcAap69zj/Bc3CRQ6P7rx+trUfdcYOfI7LKz2LSb3crWpnb1oPGgA=$1$$"
        }
    ]
}
```

輸出

| 名稱                                                                                                | 類型    | 示例值 | 備注            |
| ----------------------------------------------------------------------------------------------------- | --------- | -------- | ----------------- |
| page                                                                                                | Integer | 0      | 頁數，從 0 開始 |
| size                                                                                                | Integer | 50     | 單頁大小        |
| total                                                                                               | Integer | 100    | 總訂單數        |
| shop_order_list                                                                                     | number  | 0      | 訂單信息        |
| * [https://op.jinritemai.com/docs/api-docs/15/1342](https://op.jinritemai.com/docs/api-docs/15/1342) |

示例：

```
{"data":{"page":"0","shop_order_list":[{"app_id":"43545454556","appointment_ship_time":"1617355413","b_type":"1","b_type_desc":"抖音","biz":"1","biz_desc":"魯班","buyer_words":"要 xxx","cancel_reason":"不想要","channel_payment_no":"PAY234532534534","create_time":"1617355413","d_car_shop_biz_data":{"coupon_right":[{"quota":"1","right_name":"現金抵扣","right_type":"1"}],"poi_addr":"中關村 XXX","poi_adname":"金城江區","poi_city_name":"河池市","poi_id":"22535659043973690","poi_name":"XXXX 門店","poi_pname":"廣西壯族自治區","poi_tel":"12345678901"},"doudian_open_id":"#zuLyd4U4J3p+czzXkwg+ZQ673h7KTcrKOddb5iPGAAE0K3MYJmgXEXof9LDtoScAfMKvdVRqpAL4CEI3SrLwYATIzTF9Qw==","encrypt_post_receiver":"張三","encrypt_post_tel":"12345678911","exp_ship_time":"1617355413","finish_time":"1617355413","logistics_info":[{"company":"shunfeng","company_name":"順豐","delivery_id":"shunfeng_3617355413","product_info":[{"outer_sku_id":"sdfa","price":"1000","product_count":"2","product_id":"3473196049974326153","product_id_str":"3473196049974326153","product_name":"蘋果","sku_id":"3254535","sku_order_id":"4781320682406083640","sku_specs":[{"name":"顏色","value":"藍"}]}],"ship_time":"1617355413","tracking_no":"3617355413"}],"main_status":"103","main_status_desc":"部分支付","modify_amount":"-10","modify_post_amount":"-1","open_id":"23431434","order_amount":"600","order_expire_time":"1800","order_id":"4781320682406083640","order_level":"2","order_phase_list":[{"campaign_id":"3214324342342","channel_payment_no":"PAY34243247134325","current_phase":"1","current_phase_status_desc":"已開始但未支付","pay_success":"true","phase_close_time":"1617355413","phase_open_time":"1617355413","phase_order_amount":"100","phase_order_id":"4781320682406083640","phase_pay_amount":"100","phase_pay_time":"1617355413","phase_pay_type":"1","phase_payable_price":"100","phase_post_amount":"100","phase_promotion_amount":"100","phase_sum_amount":"100","sku_order_id":"4781320682406083640","sku_price":"100","total_phase":"2"}],"order_status":"3","order_status_desc":"待支付","order_type":"0","order_type_desc":"普通訂單","pay_amount":"500","pay_time":"1617355413","pay_type":"1","platform_cost_amount":"100","post_addr":{"city":{"id":"110000","name":"市轄區"},"encrypt_detail":"丹棱街 1 號","province":{"id":"110000","name":"北京市"},"street":{"id":"110000","name":"中關村街道"},"town":{"id":"110000","name":"海淀區"}},"post_amount":"10","post_insurance_amount":"10","post_origin_amount":"100","post_promotion_amount":"100","promotion_amount":"1000","promotion_pay_amount":"10","promotion_platform_amount":"100","promotion_redpack_amount":"100","promotion_redpack_platform_amount":"100","promotion_redpack_talent_amount":"100","promotion_shop_amount":"100","promotion_talent_amount":"100","seller_remark_stars":"1","seller_words":"注意 XX","serial_number_list":"[\"546443524543534\",\"646443524543534\"]","ship_time":"1617355413","shop_cost_amount":"100","shop_id":"77977","shop_name":"劉好好嚴選","shop_order_tag_ui":[{"help_doc":"http://","key":"sug_home_deliver","text":"建議音尊達"}],"sku_order_list":[{"account_list":{"account_info":[{"account_name":"測試","account_type":"1","encrypt_account_id":"15678909876"}]},"ad_env_type":"live","after_sale_info":{"after_sale_status":"6","after_sale_type":"1","refund_status":"1"},"app_id":"43545454556","appointment_ship_time":"1617355413","author_id":"324234453","author_name":"XXXX","b_type":"1","b_type_desc":"抖音","biz":"1","biz_desc":"魯班","bundle_sku_info":[{"code":"M8-1234-101","item_num":"1","picture_url":"https://lf3-cm.ecombdstatic.com/obj/temai/df9426c9e41521588fe0ffbf424b6b72c559ad47www800-800","product_id":"3520562294461467753","product_name":"測試非賣品創建商品","sku_id":"1719024557525047"}],"c_biz":"1","c_biz_desc":"精選聯盟","cancel_reason":"不想要","card_voucher":{"valid_days":"15","valid_end":"1646063999","valid_start":"1646063000"},"channel_payment_no":"PAY234532534534","cid":"43545454556","code":"djfafj","confirm_receipt_time":"1617355413","content_id":"43545454556","create_time":"1617355413","encrypt_post_receiver":"張三","encrypt_post_tel":"12345678911","exp_ship_time":"1617355413","finish_time":"1617355413","first_cid":"20005","fourth_cid":"20174","given_product_type":"FREE","goods_type":"1","has_tax":"true","inventory_list":[{"count":"2","inventory_type":"1","inventory_type_desc":"普通庫存","out_warehouse_id":"3254234234234","warehouse_id":"3141234234324"}],"inventory_type":"2","inventory_type_desc":"普通庫存","is_comment":"1","item_num":"2","logistics_receipt_time":"1617355413","main_status":"103","main_status_desc":"部分支付","master_sku_order_id":"1","modify_amount":"-10","modify_post_amount":"-1","need_serial_number":"false","order_amount":"600","order_expire_time":"1800","order_id":"4781320682406083640","order_level":"3","order_status":"3","order_status_desc":"待支付","order_type":"0","order_type_desc":"普通訂單","origin_amount":"100","origin_id":"43545454556","out_product_id":"432655662343","out_sku_id":"43564553","out_warehouse_ids":"[\"49574835439\",\"954764056\"]","page_id":"43545454556","parent_order_id":"4781320682406083640","pay_amount":"500","pay_time":"1617355413","pay_type":"1","platform_cost_amount":"100","post_addr":{"city":{"id":"110000","name":"市轄區"},"encrypt_detail":"丹棱街 1 號","province":{"id":"110000","name":"北京市"},"street":{"id":"110000","name":"中關村街道"},"town":{"id":"110000","name":"海淀區"}},"post_amount":"1","post_insurance_amount":"10","pre_sale_type":"1","product_id":"3473196049974326153","product_id_str":"3473196049974326153","product_name":"衣服","product_pic":"https:xxxxx","promotion_amount":"1000","promotion_pay_amount":"10","promotion_platform_amount":"100","promotion_redpack_amount":"100","promotion_redpack_platform_amount":"100","promotion_redpack_talent_amount":"100","promotion_shop_amount":"100","promotion_talent_amount":"100","receive_type":"1","reduce_stock_type":"1","reduce_stock_type_desc":"下單減庫存","room_id":"43545454556","room_id_str":"147319604997432615","second_cid":"20174","send_pay":"1","send_pay_desc":"魯班廣告","ship_time":"1617355413","shop_cost_amount":"100","sku_id":"3254535","sku_order_tag_ui":[{"extra":"{\"key\":\"value\"}","help_doc":"https://school.jinritemai.com/doudian/web/article/101835?from=shop_article","hover_text":"該商品需要送到質檢中心，質檢完成后發給用戶該商品需要送到質檢中心，質檢完成后發給用戶","key":"pre_sale_label","sort":"1","tag_type":"orange","text":"全款預售"}],"source_platform":"XXX","spec":[{"name":"顏色","value":"藍"}],"sub_b_type":"1","sub_b_type_desc":"小程序","sum_amount":"200","supplier_id":"fsgfgsdg","theme_type":"1","theme_type_desc":"直播間","third_cid":"20174","trade_type":"1","trade_type_desc":"拼團","update_time":"1617355413","video_id":"43545454556","warehouse_ids":"[\"49574835439\",\"954764056\"]"}],"sub_b_type":"1","sub_b_type_desc":"小程序","total_promotion_amount":"100","trade_type":"1","trade_type_desc":"拼團","update_time":"1617355413","user_id_info":{"encrypt_id_card_name":"#zuLyd4U4J3p+czzXkwg+ZQ673h7KTcrKOddb5iPGAAE0K3MYJmgXEXof9LDtoScAfMKvdVRqpAL4CEI3SrLwYATIzTF9Qw==","encrypt_id_card_no":"#zuLyd4U4J3p+czzXkwg+ZQ673h7KTcrKOddb5iPGAAE0K3MYJmgXEXof9LDtoScAfMKvdVRqpAL4CEI3SrLwYATIzTF9Qw=="},"user_tag_ui":[{"key":"user_profile_buy_frequency","text":"服務優先"}]}],"size":"20","total":"1000"},"err_no":0,"message":"success","code":10000,"msg":"success","sub_code":"","sub_msg":""}
```

**獲取抖店訂單詳情**

https://api.solinkup.com/trigger/api/jinritemai/detailOrder/{openId}

method:detailOrder

輸入

| 名稱    | 類型   | 是否必須 | 備注   |
| --------- | -------- | ---------- | -------- |
| orderId | String | 必須     | 訂單號 |

示例：

```
{
    "orderId": "28711g12831780"
}
```

輸出

| 名稱                                                                                            | 類型    | 示例值 | 備注    |
| ------------------------------------------------------------------------------------------------- | --------- | -------- | --------- |
| shop_id                                                                                         | Integer | 77977  | 店鋪 ID |
| [https://op.jinritemai.com/docs/api-docs/15/1343](https://op.jinritemai.com/docs/api-docs/15/1343) |

示例：

```

**獲取抖店訂單敏感信息**

https://api.solinkup.com/trigger/api/jinritemai/batchDecrypts/{openId}

method:batchDecrypts

輸入

| 名稱            | 類型   | 是否必須 | 備注                                   |
| ----------------- | -------- | ---------- | ---------------------------------------- |
| cipher_infos    | list   | 必須     | 待解密的密文列表，每次調用不超過 50 條 |
| * auth_id     | String | 必須     | 業務標識，value 為抖音訂單號           |
| * cipher_text | String | 必須     | 密文                                   |

示例：

輸出

| 名稱               | 類型   | 示例值                                | 備注       |
| -------------------- | -------- | --------------------------------------- | ------------ |
| decrypt_infos      | list   | -                                     | 解密列表   |
| * auth_id        | String | 123                                   | 鑒權 id    |
| * decrypt_text   | String | 密文                                  | 密文       |
| * err_no         | number | 0                                     | 錯誤碼     |
| * err_msg        | String | 錯誤描述                              | 錯誤描述   |
| * is_virtual_tel | Bool   | false 為真實手機號，true 為虛擬手機號 | 手機號描述 |

示例：

```
{
    "data" : {
      "decrypt_infos": [
          {
              "auth_id": "4915439432903042609",
              "decrypt_text": "",
              "err_msg": "訂單已關閉，不允許解密",
              "cipher_text": "$+u8xXdX3gjEOMuebueEscdYqAAM9hOxFjucgAgydcvA=$BaNos2xvXNljXSMeQZEZlJ3tJI4oM9JPg6dIqC03Niq9Bn9bIVVUKZZpzR7wWB2DT58wAjL3UUM7Anm9Wc2FGSVG1/6anbGAQXR4lkAbkuXrZg==*CgkIARCtHCABKAESPgo8xOiuiDmw3oesarVkYjaiai4GrWDXuWEcAap69zj/Bc3CRQ6P7rx+trUfdcYOfI7LKz2LSb3crWpnb1oPGgA=$1$$",
              "is_virtual_tel": false,
              "err_no": 200001
          }
      ]
    }
}
```

### 1.2.4 巨量千川 API

**獲取廣告賬戶數據**

https://api.solinkup.com/trigger/api/juliangqianchuan/getAdvertiser/{openId}

method:getAdvertiser

輸入參數

| **字段**                                                                                                            | **類型** | **描述**                                                                                                                                                                                                                                      |
| --------------------------------------------------------------------------------------------------------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| advertiser_id 必填                                                                                                         | number         | 千川廣告主賬戶 id                                                                                                                                                                                                                                   |
| start_date 必填                                                                                                            | string         | 開始時間，格式 2021-04-05                                                                                                                                                                                                                            |
| end_date 必填                                                                                                              | string         | 結束時間，格式 2021-04-05，時間跨度不能超過 180 天                                                                                                                                                                                                     |
| fields 必填                                                                                                                | string[]       | 需要查詢的[消耗指標](https://open.oceanengine.com/doc/index.html?key=qianchuan&type=api&id=1697528651668495)                                                                                                                                           |
| filtering 必填                                                                                                             | object         | 過濾條件                                                                                                                                                                                                                                            |
| * marketing_goal 必填                                                                                                    | string         | 營銷目標，允許值：ALL：全部 VIDEO_PROM_GOODS：短視頻帶貨 LIVE_PROM_GOODS：直播間帶貨                                                                                                                                                               |
| * order_platform                                                                                                        | string         | 下單平臺，允許值：ALL：全部 QIANCHUAN： 千川 pc（默認）ECP_AWEME：小店隨心推                                                                                                                                                                      |
| * marketing_scene                                                                                                       | string         | 營銷場景，允許值：ALL：全部 FEED： 通投廣告 SEARCH：搜索廣告注意：當下單平臺為“小店隨心推”時，不支持                                                                                                                                            |
| * promotion_way                                                                                                         | string         | 推廣方式，允許值：STANDARD：專業推廣 SIMPLE： 極速推廣注意：當下單平臺為“小店隨心推”時，不支持                                                                                                                                                  |
| * smart_bid_type                                                                                                        | string         | 投放場景（投放方式），允許值：SMART_BID_CUSTOM：控成本投放 SMART_BID_CONSERVATIVE： 放量投放注意：當下單平臺為“小店隨心推”或營銷場景為“搜索廣告”時，不支持                                                                                    |
| * status                                                                                                                | string         | 按計劃狀態過濾，不傳入即默認返回“全部（包含已刪除）”，其他規則詳見[【附錄-廣告計劃查詢狀態】](https://open.oceanengine.com/labels/12/docs/1697577930691592)（暫不支持“系統暫停”和“在投計劃配額超限”）注意：當下單平臺為“小店隨心推”時，不支持 |
| * aweme_ids                                                                                                             | number[]       | 按抖音 id 過濾，即關聯的抖音號                                                                                                                                                                                                                      |
| order_field                                                                                                               | string         | 排序字段，允許值參考[數據指標](https://open.oceanengine.com/labels/12/docs/1697528651668495)，默認不傳為 stat_cost                                                                                                                                      |
| order_type                                                                                                                | string         | 排序方式，允許值：ASC 升序（默認）、DESC 降序                                                                                                                                                                                                        |
| page                                                                                                                      | number         | 頁碼，默認為 1                                                                                                                                                                                                                                       |
| page_size                                                                                                                 | number         | 頁面大小，默認為 10，取值范圍：1-500                                                                                                                                                                                                                 |
| [https://open.oceanengine.com/labels/12/docs/1697466393573376](https://open.oceanengine.com/labels/12/docs/1697466393573376) |

請求參數示例：

```
{
    "advertiser_id": ADVERTISER_ID,
    "start_date": "2021-04-10",
    "end_date": "2021-04-21",
    "fields":["stat_cost","show_cnt", "ctr", "cpm_platform", "click_cnt", "pay_order_count", "create_order_amount", "pay_order_roi", "create_order_count", "pay_order_amount", "create_order_roi", "dy_follow"],
    "filtering": {
        "marketing_goal": "ALL"
    }
}
```

輸出參數

| **字段**                                                                                                            | **類型** | **描述**                                                                            |
| --------------------------------------------------------------------------------------------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------- |
| code                                                                                                                      | number         | 返回碼,詳見[【附錄-返回碼】](https://open.oceanengine.com/labels/12/docs/1699633774328846)   |
| message                                                                                                                   | string         | 返回信息,詳見[【附錄-返回碼】](https://open.oceanengine.com/labels/12/docs/1699633774328846) |
| request_id                                                                                                                | string         | 請求日志 id                                                                               |
| data                                                                                                                      | json           | 返回數據                                                                                  |
| * list                                                                                                                  | object[]       | 數據列表                                                                                  |
| * advertiser_id                                                                                                         | number         | 廣告主 id                                                                                 |
| * stat_cost                                                                                                             | float          | 消耗                                                                                      |
| * show_cnt                                                                                                              | number         | 展示次數                                                                                  |
| * ctr                                                                                                                   | float          | 點擊率                                                                                    |
| * cpm_platform                                                                                                          | float          | 平均千次展示費用                                                                          |
| * click_cnt                                                                                                             | number         | 點擊次數                                                                                  |
| * pay_order_count                                                                                                       | number         | 成交訂單數                                                                                |
| * create_order_amount                                                                                                   | float          | 下單成交金額                                                                              |
| * create_order_count                                                                                                    | number         | 下單訂單數                                                                                |
| * pay_order_amount                                                                                                      | float          | 成交訂單金額                                                                              |
| * create_order_roi                                                                                                      | float          | 下單 roi                                                                                  |
| * dy_follow                                                                                                             | number         | 新增粉絲數                                                                                |
| * prepay_and_pay_order_roi                                                                                              | float          | 支付 roi                                                                                  |
| * prepay_order_count                                                                                                    | number         | 廣告預售訂單數                                                                            |
| * prepay_order_amount                                                                                                   | float          | 廣告預售訂單金額                                                                          |
| * total_play                                                                                                            | number         | 播放數                                                                                    |
| * play_duration_3s                                                                                                      | number         | 3s 播放數                                                                                 |
| * play_25_feed_break                                                                                                    | number         | 25% 進度播放數                                                                            |
| * play_50_feed_break                                                                                                    | number         | 50% 進度播放數                                                                            |
| * play_75_feed_break                                                                                                    | number         | 75% 進度播放數                                                                            |
| * play_over                                                                                                             | number         | 播放完成數                                                                                |
| * play_over_rate                                                                                                        | float          | 完播率                                                                                    |
| * page_info                                                                                                             | object         | 分頁信息                                                                                  |
| * page                                                                                                                  | number         | 頁碼                                                                                      |
| * page_size                                                                                                             | number         | 頁面大小                                                                                  |
| * total_number                                                                                                          | number         | 總數                                                                                      |
| * total_page                                                                                                            | number         | 總頁數                                                                                    |
| [https://open.oceanengine.com/labels/12/docs/1697466393573376](https://open.oceanengine.com/labels/12/docs/1697466393573376) |

示例：

```
HTTPS/1.1 200 OK
{
    "code": 0,
    "message": "OK",
    "request_id": "202105121550530102121931590100C8D5",
    "data": {
        "list": [
            {
                "cpm_platform": 16.66,
                "advertiser_id": 11111111,
                "pay_order_roi": 16.66,
                "pay_order_count": 5968,
                "click_cnt": 666666,
                "stat_cost": 16.66,
                "create_order_amount": 16.66,
                "show_cnt": 6666,
                "dy_follow": 6069,
                "create_order_count": 6666,
                "ctr": 16.66,
                "create_order_roi": 16.66,
                "pay_order_amount": 16.66
            }
        ],
        "page_info": {
            "page_size": 10,
            "total_page": 1,
            "total_number": 1,
            "page": 1
        }
    }
}
```

**獲取廣告計劃數據**

https://api.solinkup.com/trigger/api/juliangqianchuan/getReportAd/{openId}

method:getReportAd

輸入參數

| **字段**                                                                                                            | **類型** | **描述**                                                                                                                                                                                                                                      |
| --------------------------------------------------------------------------------------------------------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| advertiser_id 必填                                                                                                         | number         | 廣告主 id                                                                                                                                                                                                                                           |
| start_date 必填                                                                                                            | string         | 開始時間，格式 2021-04-05                                                                                                                                                                                                                            |
| end_date 必填                                                                                                              | string         | 結束時間，格式 2021-04-05，時間跨度不能超過 180 天                                                                                                                                                                                                     |
| fields 必填                                                                                                                | string[]       | 需要查詢的消耗指標，不同營銷目的支持消耗指標不同，具體可參考[【應答字段描述】](https://open.oceanengine.com/doc/index.html?key=qianchuan&type=api&id=1697528651668495)                                                                                 |
| filtering 必填                                                                                                             | object         | 過濾條件                                                                                                                                                                                                                                            |
| * ad_ids                                                                                                                | number[]       | 廣告計劃 id 列表，最多支持 100 個                                                                                                                                                                                                                   |
| * marketing_goal 必填                                                                                                    | string         | 營銷目標，允許值：VIDEO_PROM_GOODS：短視頻帶貨 LIVE_PROM_GOODS：直播間帶貨 ALL：不限                                                                                                                                                               |
| * order_platform                                                                                                        | string         | 下單平臺，允許值：ALL：全部 QIANCHUAN： 千川 pc（默認）ECP_AWEME：小店隨心推                                                                                                                                                                      |
| * marketing_scene                                                                                                       | string         | 營銷場景，允許值：ALL：全部 FEED： 通投廣告 SEARCH：搜索廣告注意：當下單平臺為“小店隨心推”時，不支持                                                                                                                                            |
| * promotion_way                                                                                                         | string         | 推廣方式，允許值：STANDARD：專業推廣 SIMPLE： 極速推廣注意：當下單平臺為“小店隨心推”時，不支持                                                                                                                                                  |
| * smart_bid_type                                                                                                        | string         | 投放場景（投放方式），允許值：SMART_BID_CUSTOM：控成本投放 SMART_BID_CONSERVATIVE： 放量投放注意：當下單平臺為“小店隨心推”或營銷場景為“搜索廣告”時，不支持                                                                                    |
| * status                                                                                                                | string         | 按計劃狀態過濾，不傳入即默認返回“全部（包含已刪除）”，其他規則詳見[【附錄-廣告計劃查詢狀態】](https://open.oceanengine.com/labels/12/docs/1697577930691592)（暫不支持“系統暫停”和“在投計劃配額超限”）注意：當下單平臺為“小店隨心推”時，不支持 |
| order_field                                                                                                               | string         | 排序字段，允許值參考[數據指標](https://open.oceanengine.com/labels/12/docs/1697528651668495)，默認不傳為 stat_cost                                                                                                                                      |
| order_type                                                                                                                | string         | 排序方式，允許值：ASC 升序（默認）、DESC 降序                                                                                                                                                                                                        |
| page                                                                                                                      | number         | 頁碼，默認為 1                                                                                                                                                                                                                                       |
| page_size                                                                                                                 | number         | 頁面大小，默認為 10，取值范圍：1-500                                                                                                                                                                                                                 |
| [https://open.oceanengine.com/labels/12/docs/1697466415173644](https://open.oceanengine.com/labels/12/docs/1697466415173644) |

請求參數示例：

輸出參數

| **字段**                     | **類型** | **描述**                                                                            |
| ------------------------------------ | ---------------- | ------------------------------------------------------------------------------------------- |
| code                               | number         | 返回碼,詳見[【附錄-返回碼】](https://open.oceanengine.com/labels/12/docs/1699633774328846)   |
| message                            | string         | 返回信息,詳見[【附錄-返回碼】](https://open.oceanengine.com/labels/12/docs/1699633774328846) |
| request_id                         | string         | 請求日志 id                                                                               |
| data                               | json           | 返回數據                                                                                  |
| * list                           | object[]       | 數據列表                                                                                  |
| * advertiser_id                  | number         | 廣告主 id                                                                                 |
| * ad_id                          | number         | 廣告計劃 id                                                                               |
| * stat_cost                      | float          | 消耗                                                                                      |
| * show_cnt                       | number         | 展示次數                                                                                  |
| * ctr                            | float          | 點擊率                                                                                    |
| * cpm_platform                   | float          | 平均千次展示費用                                                                          |
| * click_cnt                      | number         | 點擊次數                                                                                  |
| * pay_order_count                | number         | 成交訂單數                                                                                |
| * create_order_amount            | float          | 下單成交金額                                                                              |
| * create_order_count             | number         | 下單訂單數                                                                                |
| * pay_order_amount               | float          | 成交訂單金額                                                                              |
| * create_order_roi               | float          | 下單 roi                                                                                  |
| * prepay_and_pay_order_roi       | float          | 支付 roi                                                                                  |
| * prepay_order_count             | number         | 廣告預售訂單數                                                                            |
| * prepay_order_amount            | float          | 廣告預售訂單金額                                                                          |
| * dy_follow                      | number         | 新增粉絲數                                                                                |
| * convert_cnt                    | number         | 轉化數                                                                                    |
| * convert_cost                   | float          | 轉化成本                                                                                  |
| * convert_rate                   | float          | 轉化率                                                                                    |
| * dy_share                       | number         | 分享次數。直播間帶貨：LIVE_PROM_GOODS 不支持該指標                                         |
| * dy_comment                     | number         | 評論次數。直播間帶貨：LIVE_PROM_GOODS 不支持該指標                                         |
| * dy_like                        | number         | 點贊次數。直播間帶貨：LIVE_PROM_GOODS 不支持該指標                                         |
| * live_pay_order_cost_per_order  | float          | 成交客單價。短視頻帶貨：VIDEO_PROM_GOODS 不支持該指標                                      |
| * luban_live_enter_cnt           | number         | 直播間觀看人次。短視頻帶貨：VIDEO_PROM_GOODS 不支持該指標                                  |
| * live_watch_one_minute_count    | number         | 直播間超過 1 分鐘觀看人次。短視頻帶貨：VIDEO_PROM_GOODS 不支持該指標                       |
| * live_fans_club_join_cnt        | number         | 直播間新加團人次。短視頻帶貨：VIDEO_PROM_GOODS 不支持該指標                                |
| * luban_live_slidecart_click_cnt | number         | 直播間查看購物車次數。短視頻帶貨：VIDEO_PROM_GOODS 不支持該指標                            |
| * luban_live_click_product_cnt   | number         | 直播間商品點擊次數。短視頻帶貨：VIDEO_PROM_GOODS 不支持該指標                              |
| * luban_live_comment_cnt         | number         | 直播間評論次數。短視頻帶貨：VIDEO_PROM_GOODS 不支持該指標                                  |
| * luban_live_share_cnt           | number         | 直播間分享次數。短視頻帶貨：VIDEO_PROM_GOODS 不支持該指標                                  |
| * luban_live_gift_cnt            | number         | 直播間打賞次數。短視頻帶貨：VIDEO_PROM_GOODS 不支持該指標                                  |
| * luban_live_gift_amount         | float          | 直播間音浪收入。短視頻帶貨：VIDEO_PROM_GOODS 不支持該指標                                  |
| * total_play                     | number         | 播放數                                                                                    |
| * play_duration_3s               | number         | 3s 播放數                                                                                 |
| * play_25_feed_break             | number         | 25% 進度播放數                                                                            |
| * play_50_feed_break             | number         | 50% 進度播放數                                                                            |
| * play_75_feed_break             | number         | 75% 進度播放數                                                                            |
| * play_over                      | number         | 播放完成數                                                                                |
| * play_over_rate                 | float          | 完播率                                                                                    |
| * page_info                      | object         | 分頁信息                                                                                  |
| * page                           | number         | 頁碼                                                                                      |
| * page_size                      | number         | 頁面大小                                                                                  |
| * total_number                   | number         | 總數                                                                                      |
| * total_page                     | number         | 總頁數                                                                                    |

示例：

```
HTTPS/1.1 200 OK
{
    "code": 0,
    "message": "OK",
    "request_id": "202105121658260102121830214A01E03A",
    "data": {
        "list": [
            {
                "cpm_platform": 16.66,
                "ad_id": 11111111111,
                "advertiser_id": 1111111111111,
                "pay_order_roi": 16.66,
                "pay_order_count": 66,
                "click_cnt": 66,
                "stat_cost": 16.66,
                "create_order_amount":16.66,
                "show_cnt": 66,
                "dy_follow": 66,
                "create_order_count": 66,
                "ctr": 16.66,
                "create_order_roi": 16.66,
                "pay_order_amount": 16.66
            }
        ],
        "page_info": {
            "page_size": 10,
            "total_page": 1,
            "total_number": 1,
            "page": 1
        }
    }
}
```

接入教程