伺服器整合

對於協會自己的系統——管理軟體、閘門、CMS 外掛——使用帶有 client_id + client_secret 的機密用戶端。secret 只顯示一次，絕不能出現在瀏覽器中。

驗證

import { VimineServer } from '@vimine/sdk/server';

const vimineServer = new VimineServer({
    clientId: 'vmc_…',
    clientSecret: process.env.VIMINE_SECRET,
    scopes: ['memberships:read']
});
const token = await vimineServer.token();      // client_credentials — 1 小時有效的權杖，自動續期

不使用 SDK 時：POST /v1/oauth/token，帶上 grant_type=client_credentials 和 HTTP Basic client_id:client_secret（或在請求本文中傳 client_id/client_secret）：

curl -u "vmc_…:vms_…" -d "grant_type=client_credentials&scope=memberships:read" \
     https://api.vimine.network/v1/oauth/token

在讀取端點（/v1/memberships/{id}/status、/v1/memberships）上，也可以直接使用 HTTP Basic，無需先取得權杖，方便硬體和低程式碼平臺——但絕不能在瀏覽器中這樣做。

會員卡狀態

const s = await vimineServer.memberships.status('membership-uuid');
// { id, status: 'active', verdict: 'valid', valid_until: '2027-…', membership_type: { cod: 'ORD' } }

不含任何個人資料：只有狀態和有效期。id 是會員在自己的會員卡上看到的 id（透過“使用 Vimine 登入”獲得的 membership.id），或您的系統在登記該會員卡時收到的 id。

如需核驗入場時出示的會員卡，請改用 QR Code 中的權杖呼叫 /v1/verify/{card_token}：它完全不需要驗證。

從您的系統為會員辦理入會

擁有 identity:signup 和 enroll:write 後，您的管理系統可以建立帳戶並提交入會申請，無需當事人經過 Vimine：當事人會透過電子郵件收到連結，用於確認電子郵件地址並設定密碼。

// 僅建立帳戶（此人尚未入會）
await vimineServer.signup({ email: 'mario.rossi@example.org', first_name: 'Mario', last_name: 'Rossi' });

// 帳戶 + 待處理的入會申請，由秘書處在 Vimine 管理後臺中批准
const { statuto, membership_types } = await vimineServer.public.association('your-slug');
await vimineServer.enroll({
    email: 'mario.rossi@example.org',
    first_name: 'Mario',
    last_name: 'Rossi',
    codicefiscale: 'RSSMRA80A01H501U',      // 可選：沒有稅號時，需要 dob + birthplace + birth_country
    dob: '1980-01-01', birthplace: 'Roma', birth_country: 'IT',
    gender: 'M',                              // 僅用於統計：不與稅號比對
    membership_type: membership_types[0].uid, // 只有一種類型時可省略
    accept_statuto: { version: statuto.version, sha256: statuto.sha256 },
    privacy_notice: privacy_notice && { version: privacy_notice.version, sha256: privacy_notice.sha256 } // 協會發布了隱私權聲明時必填
});

無論該地址背後是什麼情況，回應始終是 202 { status: 'accepted' }：您無法得知某個電子郵件地址是否已有 Vimine 帳戶（只有信箱的所有者會透過郵件得知）。具體來說：

新地址 → 建立帳戶；使用 enroll 時，還會建立一份待處理的入會申請；傳送歡迎郵件，附帶電子郵件地址確認；
已註冊的地址 → 使用 enroll 時不寫入任何內容：信箱所有者會收到一個“確認您向 <協會> 提交的申請”的連結，有效期 24 小時，只有在他使用該連結後才會建立申請。如果他已經是會員，則什麼也不會發生；
422 錯誤只與您的請求資料有關（帶 errors[].field 的 validation_failed、statuto_outdated、invalid_type）；協會不接受申請時傳回 403 api_disabled；在內測期間帳戶只能憑邀請建立，此時傳回 403 not_available。

識別一個人，要麼依靠稅號，要麼依靠出生日期、出生地和出生國（dob、birthplace、birth_country）——兩者不能都沒有：沒有稅號時，每缺少一項出生資訊，errors[] 中就有一條 required。對於在國外出生的人，請務必傳送 birth_country：他們的稅號中只包含國家。稅號與出生資訊不一致時，傳回 422，其中一條 codicefiscale_mismatch 帶有 mismatches、hints 和 confirmable：當 confirmable 為 true 時，當事人可以確認該稅號，您再帶上 codicefiscale_confirmed: true 重複呼叫。如果協會登記會員的地址（公開資料中的 aps.member_address），請加上 address。如果協會收集監護人（行使父母責任者）的資訊（aps.collects_guardian_data），且根據 dob 此人為未成年人，則 guardian 為必填——first_name、last_name、relation，可選 codicefiscale、email、phone——否則傳回 422，並帶有 guardian: required。完整流程見沒有義大利稅號的會員。

accept_statuto 必須指明現行章程：請在您的網站上向當事人展示章程（可在 association(slug) 中找到；文字和文件在 GET /v1/aps/{slug}/statuto），並傳入其接受的版本。未登記可讀章程的協會會傳回 accepting_requests: false，申請則傳回 403 not_available。協會給會員的隱私權聲明也是如此（association(slug) 中的 privacy_notice，文字在 GET /v1/aps/{slug}/privacy-notice）：協會發布了隱私權聲明時，申請必須指明當事人閱讀的版本，否則傳回 422（缺少 privacy_notice 或 privacy_notice_outdated）；閱讀確認以當事人的名義記錄，並註明您的用戶端。規則相同的可選項：accept_terms 和 acknowledge_privacy（帳戶使用條款和平臺的隱私權聲明，GET /v1/legal/{kind}），在當事人已於您的網站上接受時傳入。這些呼叫是冪等的：SDK 會為每次呼叫產生一個 Idempotency-Key，您也可以傳入自己的鍵（{ idempotencyKey: 'order-42' }），以便在逾時後安全地重試。郵件有傳送配額（每個地址每天 3 封），沙箱中從不傳送郵件。

入場登記

擁有 checkins:write 後，入口處的裝置透過傳送從會員卡 QR Code 中讀取的權杖（而不是某個識別碼）來記錄會員的通行：回應只有判定結果，不含任何個人資料。可以直接使用 HTTP Basic，方便硬體和低程式碼平臺。

const r = await vimineServer.checkins.create('vmt_…');   // { verdict: 'valid' | 'expired' | 'not_yet_valid' | 'statuto_required' | 'inactive', status, membership_id, valid_until, identity_check, checked_in_at }

curl -u "vmc_…:vms_…" -H "Content-Type: application/json" -d '{"token":"vmt_…"}' https://api.vimine.network/v1/checkins

請求本文為 { "token": "vmt_…" }——從 QR Code 中讀取的權杖，可以來自會員卡，也可以來自活動報名；僅對會員卡而言，card 也可作為別名使用。

格式錯誤或偽造的權杖傳回 422 invalid_card；其他協會的會員卡則是“找不到”。

identity_check: 'pending' 是給入口值班人員的提示：該會員沒有可核實的稅號，協會中也還沒有人檢視過其證件。請把它顯示出來；它不屬於 verdict，也不限制任何操作（參見身份核對）。

會員卡清單（Pro 和 Network 方案）

vimineServer.memberships.list({ status?, updated_since?, limit?, cursor? }) 分頁傳回（next_cursor）id、狀態和日期——絕不含個人資料。使用 updated_since 只同步發生變化的內容。在不包含此功能的方案上，回應為 403 plan_limit。

secret 輪換

在管理後臺中（“重新產生 secret”）：新的 secret 只顯示一次，舊的 secret 繼續有效 24 小時，因此您可以在不中斷服務的情況下更新系統。如果懷疑 secret 已外洩，請撤銷該用戶端：它的所有工作階段會立即結束。

安全

secret 多次輸錯，用戶端會被鎖定 15 分鐘。
每個權杖都繫結在用戶端所屬的協會上：其他協會的會員卡只會顯示為“找不到”。
使用剛輪換的憑證收到 401 時，SDK 會用新權杖重試一次。
回應採用 application/problem+json（參見權限、錯誤與限制）。