# 登記用戶端

> 理事會成員如何在“開發者”頁面登記一個整合，選擇哪種類型，以及究竟需要登記哪些內容。

URL: https://developers.vimine.network/zh-hant/start/register-a-client/

每個整合都是一個**用戶端**，在 Vimine 應用的**開發者**頁面中登記。該頁面僅供協會理事會使用：如果您不是理事會成員，請找一位理事會成員為您登記用戶端，並把登入憑證交給您。

沒有協會——代理機構、外掛開發者、想試用 API 的人——可以向平台申請**開發者邀請**：您將擁有一個屬於自己的[沙箱](https://developers.vimine.network/zh-hant/guides/sandbox/)，即一個有虛構會員的測試協會，並在其中自行登記測試用戶端，同時接受開發者條款。正式環境用戶端仍歸您為之工作的協會所有。

## 用戶端類型

| 類型 | 用於 | 憑證 | 說明 |
|---|---|---|---|
| **網站**（公開） | 瀏覽器中的頁面 | 僅 `client_id` | 必須使用 PKCE；`https` 重新導向 URI 須完全一致 |
| **原生應用** | 行動或桌面應用 | 僅 `client_id` | 同上；使用回送位址重新導向（`http://127.0.0.1:{port}/…`）或自訂協定 |
| **伺服器**（機密） | 協會的後端系統 | `client_id` + `client_secret` | secret 只顯示一次；絕不能出現在瀏覽器中 |

公開用戶端和原生用戶端實作**使用 Vimine 登入**，並以會員的權杖呼叫 API。機密用戶端還可以自行驗證（`client_credentials`），以使用“用戶端”權限，例如讀取會員卡狀態。

## 環境

| 環境 | 位於何處 | 何時生效 |
|---|---|---|
| **測試** | 在協會的[沙箱](https://developers.vimine.network/zh-hant/guides/sandbox/)中（按需建立） | **立即** |
| **生產** | 在真實協會中 | 由 Vimine 開通之後：您會收到一封電子郵件 |

測試用戶端簽發的權杖帶有 `mode: "test"`，無法觸及真實協會。它們的機密憑證以 `vms_test_` 開頭。

## 需要登記的內容

1. **名稱**——會員將在授權同意頁面上看到的名稱（“*名稱*想要存取您的個人資料……”）。
2. **類型**和**環境**。
3. **重新導向 URI**——登入後 Vimine 可以把瀏覽器送回的頁面。比對是**完全一致**的（協定、主機、埠、路徑）：請登記您將使用的每一個回呼頁面。
4. **允許的來源**——您的頁面在瀏覽器中呼叫 API 時所在的來源（`https://www.example.org`）。它們用於 CORS，也是登出後允許重新導向的目標（`post_logout_redirect_uri`）。
5. **權限**——該整合可以申請的 scope。只申請您需要的：會員會看到全部權限。公開用戶端或原生用戶端只能擁有會員權限；“用戶端”權限需要機密用戶端。清單見[權限、錯誤與限制](https://developers.vimine.network/zh-hant/guides/scopes-and-errors/)。

建立時您會獲得 `client_id`（`vmc_…`），機密用戶端還會獲得 `client_secret`（`vms_…`），它**只顯示一次**。對於測試用戶端，頁面還會顯示沙箱中的虛構會員及其密碼。

## 生命週期

- **重新產生 secret**——新的 secret 只顯示一次；**舊的 secret 繼續有效 24 小時**，因此您可以在不中斷服務的情況下更新系統。
- **暫停**——用戶端的權杖停止工作，直到您將它恢復。是否恢復由理事會決定。
- **撤銷**——不可逆：該用戶端的所有工作階段立即結束，會員在自己的已連結應用程式中也不再看到它。
- 會員可以隨時在個人專區的**已連結的應用程式**中撤回同意：該用戶端針對該會員的工作階段隨即結束。

:::tip[本機開發]
**測試**用戶端可以使用 `http://localhost:…` 形式的重新導向 URI 和來源：這是正常的開發方式。生產環境中只能使用 `https`（原生應用的回送位址除外）。
:::