# Vimine 开发者文档

> Vimine is the membership platform for Italian associations (APS) and Third Sector organisations. For developers working for an association: Sign in with Vimine (OAuth 2.1 + PKCE), the member API, server integrations, card verification, the public profile and the enrolment form — with the JavaScript SDK `@vimine/sdk`, the OpenAPI 3.1 reference and these guides.

Rules for code assistants:

- The `client_secret` (`vms_…`) never goes into code that runs in a browser or an app: websites and apps are public clients, using authorization code + PKCE (S256) and a `state` compared on return.
- Members sign in only on Vimine's page (`https://app.vimine.network/authorize`), reached by a redirect: never a credentials form on your site, never in an iframe.
- The secret lives only on a server: `client_credentials` for the association's own systems; HTTP Basic directly only where the reference allows it, never from a browser.
- Start with a test client in the association's sandbox (synthetic members, active at once); a production client works after Vimine activates it.
- Use the SDK (`@vimine/sdk`, `@vimine/sdk/react`, `@vimine/sdk/server`) instead of rewriting the OAuth flow; tokens stay in `sessionStorage` (per tab) unless you choose otherwise knowingly.
- Check `aps.accepting_requests` before showing an enrolment form; retry a membership request (`POST /v1/me/membership`) with the same `Idempotency-Key`, never a new one.
- Errors are `application/problem+json` (RFC 9457) with a stable `code`: branch on the `code`, not the text, and quote the `request_id` when you report a problem.
- Ask only for the scopes you need: the member sees each one on the consent page.
- Never combine data from different associations: a member's `sub` differs from one association to the next, and the developer terms forbid correlating them.

## 入门

- [概览](https://developers.vimine.network/zh-hans/start/overview.md): Vimine API 能为协会的开发者提供什么，以及开始之前需要了解的概念。
- [登记客户端](https://developers.vimine.network/zh-hans/start/register-a-client.md): 理事会成员如何在“开发者”页面登记一个集成，选择哪种类型，以及究竟需要登记哪些内容。
- [安装 SDK](https://developers.vimine.network/zh-hans/start/install.md): @vimine/sdk 软件包、它的三个入口，以及运行要求。

## 指南

- [使用 Vimine 登录](https://developers.vimine.network/zh-hans/guides/sign-in.md): 从点击到回调的 OAuth 2.1 + PKCE 流程、会话、API 调用和退出登录，使用或不使用 SDK。
- [沙盒与测试客户端](https://developers.vimine.network/zh-hans/guides/sandbox.md): 含各种状态虚构会员的孪生协会、测试客户端，以及重置。
- [服务器集成](https://developers.vimine.network/zh-hans/guides/server.md): 用于协会自有系统的机密客户端、client_credentials、会员卡状态、secret 轮换。
- [入会审批与生效](https://developers.vimine.network/zh-hans/guides/admission.md): 协会如何接纳会员，何时缴纳会费，会员卡何时在入场时有效——以及该如何告知从您的网站申请入会的人。
- [没有意大利税号的会员](https://developers.vimine.network/zh-hans/guides/members-without-cf.md): 识别一个人，可以通过税号，也可以通过出生日期、出生地和出生国。在国外出生的人要发送什么，不一致的税号如何确认，入场时要显示什么。
- [语言](https://developers.vimine.network/zh-hans/guides/languages.md): 用 ?locale= 获取协会文案的其他语言版本，从 locale 和 locales 判断实际返回了什么，告诉 Vimine 用哪种语言给某人写信。绝不使用机器翻译。
- [嵌入与会员卡核验](https://developers.vimine.network/zh-hans/guides/embed-and-verify.md): 您网站上的入会表单、协会的公开资料，以及在线和离线的会员卡核验。
- [活动与报名](https://developers.vimine.network/zh-hans/guides/events.md): 在您的网站上发布协会的活动，让会员报名（公开活动也允许嘉宾报名），并用核验会员卡的同一个扫码器办理入场登记。
- [WordPress 插件](https://developers.vimine.network/zh-hans/guides/wordpress.md): 在协会的 WordPress 网站上实现使用 Vimine 登录、会员卡和入会——无需编写代码。
- [权限、错误与限制](https://developers.vimine.network/zh-hans/guides/scopes-and-errors.md): scope 一览表、带稳定错误码的错误格式（RFC 9457）、速率限制。

## SDK

- [Vimine（浏览器）](https://developers.vimine.network/zh-hans/sdk/browser.md): @vimine/sdk 中 Vimine 类的参考——登录、会话、API 调用、存储。
- [React](https://developers.vimine.network/zh-hans/sdk/react.md): @vimine/sdk/react 中的 VimineProvider、useVimine 和 SignInButton。
- [元素（低代码）](https://developers.vimine.network/zh-hans/sdk/elements.md): <vimine-sign-in>、<vimine-card> 和 <vimine-enroll> 自定义元素——一个 HTML 标签即可，无需框架。
- [VimineServer](https://developers.vimine.network/zh-hans/sdk/server.md): @vimine/sdk/server 中供机密客户端使用的 VimineServer 类的参考。
- [公开 API](https://developers.vimine.network/zh-hans/sdk/public.md): publicApi()——会员卡核验、协会的公开资料、税号、公钥。无需凭据。
- [错误](https://developers.vimine.network/zh-hans/sdk/errors.md): VimineError——API 和 SDK 可能拒绝的一切都使用同一种错误类型，并带有稳定的错误码。
- [类型](https://developers.vimine.network/zh-hans/sdk/types.md): SDK 的 TypeScript 类型——与 API v1 相同的 JSON 结构，字段名保持不变。

## HTTP API

- [OpenAPI 3.1 document](https://api.vimine.network/v1/openapi.json): The whole API: paths, scopes, schemas and errors.
- [OAuth discovery (RFC 8414)](https://api.vimine.network/.well-known/oauth-authorization-server): Authorization, token and revocation endpoints; supported PKCE methods and scopes.
- [Interactive console](https://developers.vimine.network/zh-hans/api/console/): Try the calls against the sandbox with a test client.

## Optional

- [Everything in one file](https://developers.vimine.network/zh-hans/llms-full.txt): Every page in this language in a single Markdown file.
- [@vimine/sdk on npm](https://www.npmjs.com/package/@vimine/sdk): The SDK: browser, React and server.
- [Italiano](https://developers.vimine.network/llms.txt): The same pages in Italiano.
- [English](https://developers.vimine.network/en/llms.txt): The same pages in English.
- [Français](https://developers.vimine.network/fr/llms.txt): The same pages in Français.
- [Español](https://developers.vimine.network/es/llms.txt): The same pages in Español.
- [Deutsch](https://developers.vimine.network/de/llms.txt): The same pages in Deutsch.
- [Português (Brasil)](https://developers.vimine.network/pt/llms.txt): The same pages in Português (Brasil).
- [繁體中文](https://developers.vimine.network/zh-hant/llms.txt): The same pages in 繁體中文.