> For the complete documentation index, see [llms.txt](https://www.pionex.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://www.pionex.com/docs/api-docs/zh-hant/partner-api/partner-guide.md).

# 從這裡開始：UID 驗證

合作夥伴可以驗證某個 Pionex UID 是否屬於透過其邀請連結註冊的用戶。請根據您希望用戶如何完成驗證，選擇以下兩種整合方案之一。

| 方案                                 | 適用對象                         | 運作方式                                                                         |
| ---------------------------------- | ---------------------------- | ---------------------------------------------------------------------------- |
| **Pionex 託管的社群機器人（Community Bot）** | 希望使用現成解決方案、不想自行建置驗證系統的合作夥伴。  | 由 Pionex 透過 Telegram 或 Discord 處理驗證流程。驗證透過的用戶會收到 Telegram 群組邀請或 Discord 身分組。 |
| **直接整合合作夥伴 API（Partner API）**      | 已擁有網站、應用程式、會員系統或其他用戶流程的合作夥伴。 | 您的系統將 UID 提交至合作夥伴 API，並在自己的產品中處理驗證結果。無需 Telegram 或 Discord 機器人。              |

兩種方案皆使用相同的合作夥伴邀請關係與資格規則。以下章節分別說明各自的設定方式。

## 驗證規則

只有在所有設定的條件都滿足時，驗證才會成功：

1. UID 必須恰好為八位數字。
2. 該用戶透過合作夥伴的邀請連結註冊。
3. 若已設定 **Min Balance**，該用戶以 USDT 計算的帳戶總資產需達到或超過該數值。
4. 該 UID 尚未被相同的設定驗證過。同一個 UID 仍可使用不同的設定再次驗證。

## 方案一：Pionex 託管的社群機器人

當您不想自行建置或維護 UID 驗證介面時，請選擇此方案。Pionex 透過 Telegram 或 Discord 提供用戶流程。

### 申請社群機器人權限

社群機器人僅開放給已核准的合作夥伴。請聯繫 Pionex 客服或您的 BD 代表以申請權限。

權限開通後，**Community Bot** 會出現在合作夥伴後台（Partner Web）的導覽列中。

### 管理機器人

合作夥伴可在 **Partner Web > Community Bot** 中建立並管理最多 10 個機器人。

<div align="left"><figure><img src="https://2358638672-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F22Do5YLaknl8Xug7cEIS%2Fuploads%2Fgit-blob-1b45d86850ff2da55a52629f644810a3c3e73584%2Fbot-management.png?alt=media" alt="社群機器人管理頁面"><figcaption><p>在 Partner Web 中管理合作夥伴機器人。</p></figcaption></figure></div>

| 操作      | 描述                             |
| ------- | ------------------------------ |
| 啟用 / 停用 | 啟動或暫停機器人。                      |
| 編輯      | 更新設定。平台與機器人令牌無法變更。更新後機器人會重新啟動。 |
| 記錄      | 查看該機器人的驗證記錄。                   |
| 刪除      | 刪除機器人。                         |

機器人狀態：

| 狀態       | 描述                 |
| -------- | ------------------ |
| Running  | 機器人正常運作中。          |
| Disabled | 機器人已被手動暫停。         |
| Error    | 機器人意外停止，通常是因為令牌無效。 |

### 建立 Telegram 或 Discord 機器人

前往 **Bot Management > Create Bot**。

<div align="left"><figure><img src="https://2358638672-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F22Do5YLaknl8Xug7cEIS%2Fuploads%2Fgit-blob-47ae0f33188947fdd7fd56ceded0a542a6be7cd4%2Fcreate-bot.png?alt=media" alt="建立合作夥伴機器人表單" width="500"><figcaption><p>建立 Telegram 或 Discord 合作夥伴機器人。</p></figcaption></figure></div>

| 欄位                 | 必填         | 描述                                |
| ------------------ | ---------- | --------------------------------- |
| Bot Name           | 是          | 用於在 Partner Web 中識別機器人的顯示名稱。      |
| Platform           | 是          | 選擇 `Telegram` 或 `Discord`。        |
| Bot Token          | 是          | Telegram 或 Discord 機器人的令牌。        |
| Group Chat ID      | 僅 Telegram | 用於在驗證成功後生成邀請連結的 Telegram 群組 ID。   |
| Verified Role Name | 僅 Discord  | 驗證成功後授予的 Discord 身分組。             |
| Signup URL         | 否          | 包含您邀請碼的 Pionex 註冊連結。驗證失敗時會顯示。     |
| Language           | 否          | 預設語言：`en`、`zh`、`es` 或 `de`。       |
| Min Balance        | 否          | 以 USDT 計算的帳戶最低總餘額。設為 `0` 可略過餘額檢查。 |

#### Telegram 要求

* 將機器人加入目標群組並設為管理員。
* 授予機器人邀請用戶的權限。

#### Discord 要求

* 啟用 **MESSAGE CONTENT INTENT** 與 **SERVER MEMBERS INTENT**。
* 授予機器人 **Manage Roles** 權限。
* 將機器人的身分組置於其將授予的身分組之上。
* 建立機器人後，在 Discord 中執行 `/verify_channel #channel-name` 以發布驗證按鈕。

### Telegram 用戶流程

1. 用戶與機器人開啟私訊並發送 `/start`。
2. 用戶選擇 **ALREADY PIONEX USER** 並提交 UID。
3. 機器人驗證該 UID。
4. 驗證成功後，用戶會收到群組邀請連結，該連結有效期為一小時且僅能使用一次。

若驗證失敗，機器人會顯示原因與已設定的註冊連結。用戶可發送 `/language` 以變更機器人語言。

<div align="left"><figure><img src="https://2358638672-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F22Do5YLaknl8Xug7cEIS%2Fuploads%2Fgit-blob-56b41fef350f2fe173dc677c3ab56630e1636c72%2Ftelegram-verification.png?alt=media" alt="Telegram 合作夥伴機器人驗證流程" width="320"><figcaption><p>Telegram 驗證成功後會回傳一次性的群組邀請連結。</p></figcaption></figure></div>

### Discord 用戶流程

1. 用戶在已設定的驗證頻道中點擊 **Pionex** 按鈕。
2. 用戶輸入 UID 並在五分鐘內確認。
3. 機器人驗證該 UID 並自動授予已設定的身分組。

驗證訊息僅對該用戶可見。驗證失敗時會顯示錯誤且不會授予身分組。

<div align="left"><figure><img src="https://2358638672-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F22Do5YLaknl8Xug7cEIS%2Fuploads%2Fgit-blob-9d136c781b26e1457646795ab2ada8e80b6f7a3d%2Fdiscord-verification.png?alt=media" alt="Discord 合作夥伴機器人驗證流程"><figcaption><p>Discord 驗證成功後會授予已設定的身分組。</p></figcaption></figure></div>

Discord 管理員指令：

| 指令                          | 描述           |
| --------------------------- | ------------ |
| `/verify_channel #channel`  | 在頻道中發布驗證按鈕。  |
| `/set_grant_role role-name` | 變更驗證後授予的身分組。 |
| `/admin_stats`              | 查看驗證統計。      |
| `/admin_config`             | 查看機器人設定。     |
| `/help`                     | 查看可用指令。      |
| `/status`                   | 查看驗證狀態。      |

## 方案二：直接整合合作夥伴 API

當您已擁有網站、應用程式、會員系統或其他用戶流程時，請選擇此方案。您的後端直接呼叫合作夥伴 API，並自行決定如何處理驗證結果。

您無需建立或運營 Telegram 或 Discord 機器人。用戶在整個驗證流程中皆保持在您自己的產品內。

直接整合流程如下：

`您的產品 > 將 UID 提交至合作夥伴 API > 接收資格結果 > 繼續您自己的用戶流程`

### 申請合作夥伴 API 權限

直接 API 整合需要具備 **合作夥伴讀取（Partner reading）** 權限的 Pionex API 金鑰。請依照 [建立 API Key](/docs/api-docs/zh-hant/can-kao/api-key-guide.md)，啟用 **合作夥伴讀取** 與 **啟用讀取**，並等待核准。

若無法選取 **合作夥伴讀取**，請聯繫 Pionex 客服或您的 BD 代表。

<div align="left"><figure><img src="https://2358638672-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F22Do5YLaknl8Xug7cEIS%2Fuploads%2Fgit-blob-6d3a2215dde096a1cdcdf1d9f02ef9bd4f09975a%2Fcreate-api-key.png?alt=media" alt="建立具有合作夥伴讀取權限的 API 金鑰"><figcaption><p>建立 API 金鑰時啟用合作夥伴讀取權限。</p></figcaption></figure></div>

### 建立 Open API 設定

在呼叫資格端點之前，請先在 Partner Web 中建立一個 Open API 設定：

1. 前往 **Bot Management > Create Bot**。
2. 將 **Platform** 設為 `Open API`。
3. 輸入 **Bot Name**。
4. 可選擇設定 **Min Balance**。設為 `0` 可略過餘額檢查。
5. 建立機器人並複製其 `bot_id`。

Partner Web 將此設定稱為 **Open API Bot**，但它並非聊天機器人。它不需要機器人令牌、不會啟動 Telegram 或 Discord 程序，也不提供使用者介面。它僅儲存驗證設定，並提供合作夥伴 API 所需的 `bot_id`。

<div align="left"><figure><img src="https://2358638672-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F22Do5YLaknl8Xug7cEIS%2Fuploads%2Fgit-blob-79d04e028e400ecb0b958050e823ab39347a0a73%2Fget_bot_id.png?alt=media" alt="在 Partner Web 中找到合作夥伴 Bot ID" width="500"><figcaption><p>從 Partner Web 複製 bot ID 以用於 API 請求。</p></figcaption></figure></div>

### 呼叫合作夥伴 API

從您的後端，使用該用戶的 UID 與上述建立的 `bot_id` 呼叫 `GET /api/v1/partner/kol/checkQualification`。該端點會檢查邀請關係，以及儲存在 Open API 設定中的資格條件。

關於身份驗證、參數與回應欄位，請參閱 [合作夥伴 API 參考](https://www.pionex.com/docs/api-docs/zh-hant/partner-api/general-info)。

當您還需要被邀請用戶的交易量統計時，請使用 `GET /api/v1/partner/kol/inviteTradeStat`。

## 疑難排解

| 適用對象  | 問題                  | 解決方法                                          |
| ----- | ------------------- | --------------------------------------------- |
| 社群機器人 | 機器人狀態為 `Error`      | 通常是令牌無效。請刪除機器人並使用新令牌重新建立。                     |
| 社群機器人 | 未授予 Discord 身分組     | 檢查 **Manage Roles** 權限，並確認機器人的身分組位於將授予的身分組之上。 |
| 社群機器人 | Telegram 驗證成功但未收到邀請 | 確認 Group Chat ID，並確保機器人是具備邀請用戶權限的群組管理員。       |
| 兩種方案  | UID 驗證失敗            | 確認 UID 為八位數字、用戶透過合作夥伴連結註冊，且滿足餘額要求。            |
| 社群機器人 | 需變更機器人令牌            | 令牌無法編輯。請刪除機器人並重新建立。                           |
| 兩種方案  | 用戶需要再次驗證            | 每個設定下一個 UID 只能驗證一次，但可使用不同的設定再次驗證。             |