# 概览

> Vimine API 能为协会的开发者提供什么，以及开始之前需要了解的概念。

URL: https://developers.vimine.network/zh-hans/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-hans/start/register-a-client/)。
- **权限（scope）**：令牌能做什么，例如 `profile:read`、`membership:read`、`membership:request` 等。会员在授权同意页面上看到并授予这些权限。完整列表见[权限、错误与限制](https://developers.vimine.network/zh-hans/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_…`），以二维码形式显示，带有有效时间窗口；每次状态变化时都会轮换，而且无论如何每 90 天轮换一次。
- **沙盒**：一个孪生协会，含各种状态的虚构会员，测试客户端在其中立即生效。参见[沙盒与测试客户端](https://developers.vimine.network/zh-hans/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-hans/llms.txt`：Markdown 页面索引及需遵守的规则；`llms-full.txt`：全部内容合为一个文件；每个页面都有 Markdown 版本：`/zh-hans/guides/sign-in/` → `/zh-hans/guides/sign-in.md` |

## 下一步

1. 在管理后台中[登记客户端](https://developers.vimine.network/zh-hans/start/register-a-client/)。
2. [安装 SDK](https://developers.vimine.network/zh-hans/start/install/)。
3. 按照[使用 Vimine 登录](https://developers.vimine.network/zh-hans/guides/sign-in/)操作；如果您为协会自己的系统开发，请参阅[服务器集成](https://developers.vimine.network/zh-hans/guides/server/)。