權限、錯誤與限制

權限（scope）

用戶端在登記時申請權限；會員在授權同意頁面上看到這些權限。

Scope	對象	內容
profile:read	會員	GET /v1/me——姓名、電子郵件地址、聯絡方式、出生資訊、稅號（如有），以及當事人的身份識別方式（codicefiscale_check）
profile:write	會員	PATCH /v1/me——電話、性別，以及身份識別資訊：出生日期、出生地和出生國、稅號（可選，可以之後再補充；會重新驗證）
membership:read	會員	GET /v1/me/membership、/events、/statuto、/card
membership:request	會員	POST /v1/me/membership——入會申請
statuto:accept	會員	POST /v1/me/membership/statuto/accept
network:manage	會員	會員對加入網路的同意（即將推出）
memberships:read	用戶端	GET /v1/memberships/{id}/status
verify:read	用戶端	超出匿名配額的會員卡核驗
identity:signup	用戶端	POST /v1/signup——代表會員建立帳戶（伺服器整合）
enroll:write	用戶端	POST /v1/enroll——提交入會申請，有無稅號均可（指南）
events:read	會員	GET /v1/events、/v1/events/{slug}、/eligibility——包括僅限會員的活動（指南）
registrations:read	會員、用戶端	GET /v1/me/registrations（會員）；GET /v1/events/{slug}/registrations（用戶端，不含個人資料）
registrations:write	會員、用戶端	POST /v1/events/{slug}/registrations 和 DELETE /v1/me/registrations/{id}（會員）；POST …/registrations/guest（用戶端）
checkins:write	用戶端	POST /v1/checkins——憑會員卡或報名辦理入場登記
webhooks:manage	用戶端	即將推出

公開用戶端或原生用戶端只能申請會員權限；“用戶端”權限需要機密用戶端。尚未入會的人只能授予入會相關的權限（profile:*、membership:read、membership:request、statuto:accept）。

錯誤

錯誤回應為 application/problem+json（RFC 9457）：

{
  "type": "https://developers.vimine.network/errors/insufficient_scope",
  "title": "Forbidden",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "Missing scope: profile:write",
  "request_id": "…"
}

code 是穩定的：請以它作為分支依據。errors[] 隨 validation_failed 和 identification_required 一起傳回（{ field, code }）。codicefiscale_mismatch 記錄——稅號與當事人的出生資訊不一致——還帶有 mismatches、hints 和 confirmable：當 confirmable 為 true 時，當事人可以確認該稅號，並帶上 codicefiscale_confirmed: true 重複請求（參見沒有義大利稅號的會員）。OAuth 端點（/v1/oauth/token、/revoke）以 OAuth 格式傳回（{ error, error_description }）。

code	含義
missing_token、invalid_token、token_expired	401——請重新登入（SDK 會自動重新整理並重試）
insufficient_scope	403——權杖缺少該權限
api_disabled	403——協會未開通 API，或不接受申請
plan_limit	403——協會的方案已容納不下更多會員（顯示表單前請先檢查 aps.accepting_requests）
not_available	403——協會目前不接受申請：尚未接受平臺協議或尚未登記章程、尚未準備就緒，或只接納受邀請的人（內測）；detail 會說明是哪種情況。在 POST /v1/signup 上：內測期間帳戶只能憑邀請建立
not_found	404——其他協會的資源也傳回此錯誤
validation_failed	422——參見 errors[]（required、invalid、invalid_codicefiscale、帶 confirmable 的 codicefiscale_mismatch…）
identification_required	在 POST /v1/me/membership 上為 422，在 POST /v1/enroll/confirm 上為 409——當事人尚未識別身份：需要稅號，或出生日期、出生地和出生國；errors[] 列出缺少的內容
statuto_outdated、statuto_required	422——指明現行章程的版本（detail）
rate_limited	429——請等待 Retry-After
unavailable	503——請稍後重試

OAuth：invalid_grant（授權碼或重新整理權杖無效、已過期或被重複使用）、invalid_client、invalid_scope、unauthorized_client（用戶端等待開通）、access_denied（會員已取消）。

在 SDK 中，以上所有錯誤都是帶有相同 code 的 VimineError。

內測

Vimine 正處於內測階段：個人和協會都憑邀請加入。對用戶端而言，這意味著：

• POST /v1/signup 傳回 403 not_available，不建立任何內容，除非 Vimine 已為您的協會開放公開入會；
• 只接納受邀請者的協會，其公開資料中帶有 aps.invitation_only: true 和 aps.accepting_requests: false（association(slug)）；POST /v1/enroll 和 POST /v1/me/membership 傳回 403 not_available。受到邀請的人透過郵件中收到的連結入會；
• 沙箱保持開放：測試用戶端照常工作。

顯示入會表單之前，請先檢查 aps.accepting_requests——內測期間如此，其他情況也一樣；<vimine-events> 和 <vimine-enroll> 已經這樣做了。

限制

• 按 IP 位址計：敏感端點（會員卡核驗、稅號、權杖）每分鐘 60 次請求，其餘端點每分鐘 120 次；回應中帶有 RateLimit-* 和 Retry-After。
• POST /v1/me/membership 接受 Idempotency-Key：24 小時內使用相同的鍵會傳回相同的回應（SDK 會為每次呼叫產生一個）。
• 經過驗證的回應為 Cache-Control: no-store。
• 每個回應都帶有 request_id：報告問題時請註明它。