VimineServer

import { VimineServer } from '@vimine/sdk/server';
const vimineServer = new VimineServer({ clientId: 'vmc_…', clientSecret: process.env.VIMINE_SECRET });

用於協會自己的系統：一個透過 client_credentials 驗證的機密用戶端，讀取會員卡狀態並操作其沙箱。需要 Node ≥ 18。secret 絕不能出現在瀏覽器中。

選項

選項	型別	預設值
clientId	string	—	必填
clientSecret	string	—	必填；vms_… 或 vms_test_…
scopes	Scope[]	所有已登記的權限	要申請的子集
apiUrl	string	https://api.vimine.network
fetch	typeof fetch	globalThis.fetch

方法

token()

用戶端存取權杖（client_credentials，HTTP Basic），快取至到期（1 小時）前 30 秒；即使被並行呼叫，也只發出一次請求。

request(path, init?)

一次帶 Authorization: Bearer、經過驗證的呼叫；輸入輸出均為 JSON；錯誤以 VimineError 拋出。收到 401（憑證已輪換或已撤銷）時，用新權杖重試一次。

memberships.status(id)

協會某個會員資格的狀態，不含個人資料（memberships:read）：

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

signup(input, opts?)

為某人建立 Vimine 帳戶（identity:signup）：當事人會收到郵件，用於確認電子郵件地址並設定密碼。始終傳回 { status: 'accepted' }——不會告訴您該地址是否已有帳戶（信箱的所有者會透過郵件得知）。opts.idempotencyKey（未提供時自動產生）。

await vimineServer.signup({ email: 'mario.rossi@example.org', first_name: 'Mario', last_name: 'Rossi', phone: '+39 …' });

enroll(input, opts?)

為某人提交入會申請（enroll:write）：新地址會獲得一個帳戶和一份待處理的申請；已有帳戶的所有者則會收到一個確認連結（在其使用連結之前不寫入任何內容）。accept_statuto（現行版本）為必填；當協會發布了給會員的隱私權聲明時（association(slug).privacy_notice），privacy_notice 也為必填：當事人在您的網站上閱讀後，您傳入所展示的版本。參見伺服器整合。

識別當事人，要麼透過 codicefiscale，要麼透過 dob + birthplace + birth_country——兩者不能都沒有（422，每缺少一項出生資訊就有一條 required）。稅號與出生資訊不一致時，err.errors 中會有一條 codicefiscale_mismatch 記錄，帶有 mismatches、hints 和 confirmable：當 confirmable 為 true 且當事人確認時，請帶上 codicefiscale_confirmed: true 重複呼叫。如果協會登記會員的地址（aps.member_address），請傳入 address（MemberAddress）。參見沒有義大利稅號的會員。

// 有稅號
await vimineServer.enroll({ ...person, codicefiscale: 'RSSMRA80A01H501U', accept_statuto: { version: 3 }, privacy_notice: { version: 2 } }, { idempotencyKey: 'order-42' });
// 沒有稅號：出生日期、出生地和出生國
await vimineServer.enroll({ ...person, dob: '1985-03-10', birthplace: 'Lyon', birth_country: 'FR', accept_statuto: { version: 3 }, privacy_notice: { version: 2 } });

checkins.create(token)

用從 QR Code 中讀取的權杖記錄一次入場登記（checkins:write）。會員卡傳回 { kind: 'card', verdict, status, membership_id, valid_until, valid_from, identity_check, checked_in_at }——identity_check: 'pending' 是需要顯示給入口值班人員的提示，它不屬於 verdict，也不限制任何操作（指南）；活動報名的 QR Code 傳回 { kind: 'registration', verdict, registration_id, event, first, membership_verdict, … }（參見活動與報名）。

events

events.list(params?) · events.get(slug)——協會已發布的活動，包括僅限會員的活動（任何用戶端權杖均可）。

registrations

registrations.listForEvent(slug, { status?, limit?, cursor? })	某個活動的報名：id、狀態、類型、會員資格、入場登記——不含個人資料（registrations:read，適用於支援 API 清單的方案）
registrations.guest(slug, { email, first_name, last_name, registration_type, note? }, opts?)	為沒有帳戶的嘉賓報名公開活動；始終傳回 { status: 'accepted' }；自動產生 Idempotency-Key（參見嘉賓）

memberships.list(params?)

協會的會員資格清單（memberships:read，適用於支援清單的方案）：{ items: [{ id, status, verdict, membership_type, issued_at, valid_until, updated_at }], next_cursor }；params：status、updated_since、limit、cursor。

sandbox.members() · sandbox.reset()

僅限測試用戶端：沙箱中的虛構會員，以及重設（新的共用密碼，只傳回一次）。生產用戶端會得到 403。

public

無需憑證的公開端點：參見 publicApi。

中介軟體範例

express.js

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

const vimineServer = new VimineServer({ clientId: process.env.VIMINE_CLIENT_ID, clientSecret: process.env.VIMINE_SECRET });
const app = express();

app.get('/cards/:id/status', async (req, res) => {
    try {
        const { status, verdict, valid_until } = await vimineServer.memberships.status(req.params.id);
        res.json({ status, verdict, valid_until });
    } catch (err) {
        if (err instanceof VimineError && err.code === 'not_found') return res.status(404).end();
        throw err;
    }
});