VimineServer

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

Para os sistemas da própria associação: um cliente confidencial que se autentica com client_credentials, lê o status das carteirinhas e opera o seu sandbox. Node ≥ 18. O segredo nunca deve chegar a um navegador.

Opções

Opção	Tipo	Padrão
clientId	string	—	obrigatório
clientSecret	string	—	obrigatório; vms_… ou vms_test_…
scopes	Scope[]	todos os registrados	um subconjunto a pedir
apiUrl	string	https://api.vimine.network
fetch	typeof fetch	globalThis.fetch

Métodos

token()

Um access token de cliente (client_credentials, HTTP Basic), guardado em cache até 30 segundos antes de vencer (1 hora); uma única requisição mesmo com chamadas concorrentes.

request(path, init?)

Uma chamada autenticada com Authorization: Bearer; JSON na ida e na volta; erros como VimineError. Um 401 (credenciais rotacionadas ou revogadas) é repetido uma vez com um token novo.

memberships.status(id)

Status de uma carteirinha da associação, sem dados pessoais (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?)

Cria uma conta Vimine para uma pessoa (identity:signup): ela recebe o e-mail para confirmar o endereço e escolher uma senha. Responde sempre { status: 'accepted' } — se o endereço já tinha uma conta não é revelado a você (o dono dele é avisado, por e-mail). opts.idempotencyKey (gerada quando ausente).

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

enroll(input, opts?)

Envia um pedido de adesão para uma pessoa (enroll:write): um endereço novo recebe uma conta e um pedido pendente; o dono de uma conta existente recebe, em vez disso, um link de confirmação (nada é gravado até ele usá-lo). accept_statuto (a versão em vigor) é obrigatório; privacy_notice também, quando a associação publica um aviso aos seus associados (association(slug).privacy_notice): a pessoa o lê no seu site e você passa a versão mostrada. Veja Integrações de servidor.

A pessoa é identificada por codicefiscale ou por dob + birthplace + birth_country — nunca por nenhum dos dois (422, uma entrada required para cada dado de nascimento que falta). Um código que não confere com os dados de nascimento é uma entrada codicefiscale_mismatch em err.errors, com mismatches, hints e confirmable: quando confirmable é true e a pessoa confirma, repita com codicefiscale_confirmed: true. address (MemberAddress) quando a associação coleta o endereço dos seus associados (aps.member_address). Veja Associados sem código fiscal.

// com código fiscal
await vimineServer.enroll({ ...person, codicefiscale: 'RSSMRA80A01H501U', accept_statuto: { version: 3 }, privacy_notice: { version: 2 } }, { idempotencyKey: 'order-42' });
// sem código: data, local e país de nascimento
await vimineServer.enroll({ ...person, dob: '1985-03-10', birthplace: 'Lyon', birth_country: 'FR', accept_statuto: { version: 3 }, privacy_notice: { version: 2 } });

checkins.create(token)

Registra um check-in na entrada a partir do token lido no QR (checkins:write). Uma carteirinha responde { kind: 'card', verdict, status, membership_id, valid_until, valid_from, identity_check, checked_in_at } — identity_check: 'pending' é uma observação a mostrar para quem cuida da entrada, não faz parte do verdict e não restringe nada (guia); o QR de uma inscrição em evento responde { kind: 'registration', verdict, registration_id, event, first, membership_verdict, … } (veja Eventos e inscrições).

events

events.list(params?) · events.get(slug) — os eventos publicados da associação, incluindo os só para associados (qualquer token de cliente).

registrations

registrations.listForEvent(slug, { status?, limit?, cursor? })	as inscrições de um evento: id, status, tipo, carteirinha, check-in — sem dados pessoais (registrations:read, planos com listas via API)
registrations.guest(slug, { email, first_name, last_name, registration_type, note? }, opts?)	inscreve um convidado sem conta num evento público; sempre { status: 'accepted' }; Idempotency-Key gerada (veja convidados)

memberships.list(params?)

As carteirinhas da associação (memberships:read, planos com listas): { items: [{ id, status, verdict, membership_type, issued_at, valid_until, updated_at }], next_cursor }; params: status, updated_since, limit, cursor.

sandbox.members() · sandbox.reset()

Só para clientes de teste: os associados sintéticos do sandbox e a redefinição (nova senha compartilhada, devolvida uma vez). Um cliente de produção recebe 403.

public

Os endpoints públicos, sem credenciais: veja publicApi.

Um exemplo de middleware

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;
    }
});