# 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-hant/start/overview.md): Vimine API 能為協會的開發者提供什麼，以及開始之前需要了解的概念。
- [登記用戶端](https://developers.vimine.network/zh-hant/start/register-a-client.md): 理事會成員如何在“開發者”頁面登記一個整合，選擇哪種類型，以及究竟需要登記哪些內容。
- [安裝 SDK](https://developers.vimine.network/zh-hant/start/install.md): @vimine/sdk 套件、它的三個入口，以及執行要求。

## 指南

- [使用 Vimine 登入](https://developers.vimine.network/zh-hant/guides/sign-in.md): 從點選到回呼的 OAuth 2.1 + PKCE 流程、工作階段、API 呼叫和登出，使用或不使用 SDK。
- [沙箱與測試用戶端](https://developers.vimine.network/zh-hant/guides/sandbox.md): 含各種狀態虛構會員的孿生協會、測試用戶端，以及重設。
- [伺服器整合](https://developers.vimine.network/zh-hant/guides/server.md): 用於協會自有系統的機密用戶端、client_credentials、會員卡狀態、secret 輪換。
- [入會審核與生效](https://developers.vimine.network/zh-hant/guides/admission.md): 協會如何接納會員，何時繳納會費，會員卡何時在入場時有效——以及該如何告知從您的網站申請入會的人。
- [沒有義大利稅號的會員](https://developers.vimine.network/zh-hant/guides/members-without-cf.md): 識別一個人，可以透過稅號，也可以透過出生日期、出生地和出生國。在國外出生的人要傳送什麼，不一致的稅號如何確認，入場時要顯示什麼。
- [語言](https://developers.vimine.network/zh-hant/guides/languages.md): 用 ?locale= 取得協會文案的其他語言版本，從 locale 和 locales 判斷實際傳回了什麼，告訴 Vimine 用哪種語言給某人寫信。絕不使用機器翻譯。
- [嵌入與會員卡核驗](https://developers.vimine.network/zh-hant/guides/embed-and-verify.md): 您網站上的入會表單、協會的公開資料，以及線上和離線的會員卡核驗。
- [活動與報名](https://developers.vimine.network/zh-hant/guides/events.md): 在您的網站上發布協會的活動，讓會員報名（公開活動也允許嘉賓報名），並用核驗會員卡的同一個掃描器辦理入場登記。
- [WordPress 外掛](https://developers.vimine.network/zh-hant/guides/wordpress.md): 在協會的 WordPress 網站上實現使用 Vimine 登入、會員卡和入會——無需編寫程式碼。
- [權限、錯誤與限制](https://developers.vimine.network/zh-hant/guides/scopes-and-errors.md): scope 一覽表、帶穩定錯誤碼的錯誤格式（RFC 9457）、速率限制。

## SDK

- [Vimine（瀏覽器）](https://developers.vimine.network/zh-hant/sdk/browser.md): @vimine/sdk 中 Vimine 類別的參考——登入、工作階段、API 呼叫、儲存。
- [React](https://developers.vimine.network/zh-hant/sdk/react.md): @vimine/sdk/react 中的 VimineProvider、useVimine 和 SignInButton。
- [元素（低程式碼）](https://developers.vimine.network/zh-hant/sdk/elements.md): <vimine-sign-in>、<vimine-card> 和 <vimine-enroll> 自訂元素——一個 HTML 標籤即可，無需框架。
- [VimineServer](https://developers.vimine.network/zh-hant/sdk/server.md): @vimine/sdk/server 中供機密用戶端使用的 VimineServer 類別的參考。
- [公開 API](https://developers.vimine.network/zh-hant/sdk/public.md): publicApi()——會員卡核驗、協會的公開資料、稅號、公開金鑰。無需憑證。
- [錯誤](https://developers.vimine.network/zh-hant/sdk/errors.md): VimineError——API 和 SDK 可能拒絕的一切都使用同一種錯誤型別，並帶有穩定的錯誤碼。
- [型別](https://developers.vimine.network/zh-hant/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-hant/api/console/): Try the calls against the sandbox with a test client.

## Optional

- [Everything in one file](https://developers.vimine.network/zh-hant/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-hans/llms.txt): The same pages in 简体中文.