# 概覽

> Vimine API 能為協會的開發者提供什麼，以及開始之前需要了解的概念。

URL: https://developers.vimine.network/zh-hant/start/overview/

Vimine 是專為義大利 APS（社會促進協會）和第三部門機構設計的會員管理平臺。每個協會都有自己的會員、自己的會員卡、自己的章程（statuto）；藉助 API，**協會自己的、或為協會開發的**網站或應用無需重做任何東西，即可使用這一切。

## 您可以做什麼

| | 方式 | 使用哪種憑證 |
|---|---|---|
| **使用 Vimine 登入**——會員用自己的帳戶登入您的網站 | OAuth 2.1 + PKCE，登入和授權同意頁面位於 vimine.network | *公開*或*原生*用戶端（僅 `client_id`） |
| **會員 API**——個人資料、會員卡和判定結果、入會申請、章程、已連結的應用程式 | 使用會員的權杖呼叫 `GET /v1/me`、`/v1/me/membership` 等 | 會員授予的權限 |
| **伺服器整合**——協會自己的系統讀取會員卡狀態 | `client_credentials` | *機密*用戶端（`client_id` + `client_secret`） |
| **會員卡核驗**——“這張會員卡現在有效嗎？”，也可離線核驗 | `GET /v1/verify/{card_token}`，Ed25519 公開金鑰 | 無 |
| **公開資料與入會**——品牌形象、會員卡類型、現行章程；入會表單 | `GET /v1/aps/{slug}`，可嵌入的 `enroll` 頁面 | 無 |

## 概念

- **協會與 slug**：每個協會都有一個 *slug*（`https://app.vimine.network/enroll/<slug>`）；用戶端屬於某一個協會，透過它獲得的權杖只對該協會有效。
- **用戶端**：在 Vimine 應用的**開發者**頁面中登記的一個整合。它有類型（網站、原生應用、伺服器）、環境（*測試*或*生產*）、重新導向 URI、允許的來源，以及它可以申請的權限。參見[登記用戶端](https://developers.vimine.network/zh-hant/start/register-a-client/)。
- **權限（scope）**：權杖能做什麼，例如 `profile:read`、`membership:read`、`membership:request` 等。會員在授權同意頁面上看到並授予這些權限。完整清單見[權限、錯誤與限制](https://developers.vimine.network/zh-hant/guides/scopes-and-errors/)。
- **權杖**：會員的存取權杖（access token）有效期為 10 分鐘；重新整理權杖（refresh token）每次使用都會輪換，有效期為 30 天（閒置 14 天即失效）。機密用戶端的權杖有效期為 1 小時。SDK 會自動完成所有續期。
- **`sub`**：您在權杖和 `/v1/me` 中看到的會員識別碼（`vms_…`）**專屬於您的協會**：長期穩定，在每個協會中都不同，絕不是內部 id。
- **判定（verdict）**：入場時真正要看的結果，即 `valid`、`expired`、`statuto_required`（重新接受章程已逾期）或 `inactive`。
- **會員卡權杖**：數位會員卡是一個簽名權杖（`vmt_…`），以 QR Code 形式顯示，帶有有效時段；每次狀態變化時都會輪換，而且無論如何每 90 天輪換一次。
- **沙箱**：一個孿生協會，含各種狀態的虛構會員，測試用戶端在其中立即生效。參見[沙箱與測試用戶端](https://developers.vimine.network/zh-hant/guides/sandbox/)。

## 各項資源的位置

| | |
|---|---|
| 登入、授權同意和登出頁面 | `https://app.vimine.network/authorize`、`/oauth/logout` |
| API | `https://api.vimine.network/v1/…`——OpenAPI 文件位於 `/v1/openapi.json`，發現端點（discovery）位於 `/.well-known/oauth-authorization-server` |
| 會員卡公開金鑰 | `https://api.vimine.network/.well-known/vimine-card-keys.json` |
| SDK | npm 上的 `@vimine/sdk`：`@vimine/sdk`（瀏覽器）、`@vimine/sdk/react`、`@vimine/sdk/server` |
| 程式設計助理 | `https://developers.vimine.network/zh-hant/llms.txt`：Markdown 頁面索引及需遵守的規則；`llms-full.txt`：全部內容合為一個檔案；每個頁面都有 Markdown 版本：`/zh-hant/guides/sign-in/` → `/zh-hant/guides/sign-in.md` |

## 下一步

1. 在管理後臺中[登記用戶端](https://developers.vimine.network/zh-hant/start/register-a-client/)。
2. [安裝 SDK](https://developers.vimine.network/zh-hant/start/install/)。
3. 按照[使用 Vimine 登入](https://developers.vimine.network/zh-hant/guides/sign-in/)操作；如果您為協會自己的系統開發，請參閱[伺服器整合](https://developers.vimine.network/zh-hant/guides/server/)。