API pública

import { publicApi } from '@vimine/sdk';
const api = publicApi();                       // ou vimine.public / vimineServer.public

Os endpoints que não precisam nem de credenciais nem de login. Podem ser usados de qualquer página, de um leitor, de um servidor. publicApi({ apiUrl?, fetch? }) aceita as mesmas opções de rede das outras classes.

Método	Endpoint
verifyCard(cardToken)	GET /v1/verify/{card_token}	“esta carteirinha está ativa agora?” — só o status e o fim da validade
association(slug, { locale }?)	GET /v1/aps/{slug}	perfil público: identidade visual, tipos de carteirinha com as taxas, statuto em vigor, como admite os associados, se coleta o endereço deles (member_address)
validateFiscalCode(input)	POST /v1/validate/fiscal-code	estrutura e caractere de controle; com os dados pessoais, também a coerência deles — e o que o código traz (birth_date, birth_country). Para uma pessoa nascida no exterior, envie country
cardKeys()	GET /v1/card-keys	as chaves públicas (JWKS, Ed25519) que verificam os tokens off-line
confirmEnrollment(token, identification?, address?)	POST /v1/enroll/confirm	consome o token do link “confirme o seu pedido” enviado quando um sistema faz a adesão de uma conta existente; depois de um 409 identification_required é repetido com identification, depois de um 409 address_required com address
events.list(slug, params?) · events.get(slug, event, { locale }?)	GET /v1/aps/{slug}/events[/{event}]	os eventos públicos de uma associação, com as vagas restantes por tipo (guia)
confirmRegistration(token)	POST /v1/registrations/confirm	consome o token do link “confirme a sua inscrição” de um convidado: a inscrição, com o token do QR quando confirmada
viewRegistration(token)	POST /v1/registrations/view	lê a vaga por trás do link próprio de um convidado (o e-mail que confirma a vaga): o seu status e, enquanto ela estiver confirmada, o token do QR; funciona até o fim do evento (desde a 0.3.2)

const { status, valid_until } = await api.verifyCard('vmt_…');
// { status: 'active', valid_until: '2027-03-31T22:59:59.000Z' } | { status: 'inactive', reason: 'expired' }

const { aps, membership_types, statuto } = await api.association('your-slug');

const check = await api.validateFiscalCode({ code: 'RSSMRA80A01H501U', first_name: 'Mario', last_name: 'Rossi', date: '1980-01-01', place: 'Roma', country: 'IT' });
// { valid: true, error: null, mismatches: [], hints: [], birth_date: '1980-01-01', birth_country: 'IT' }
// | { valid: false, error: 'mismatch', mismatches: ['date'], hints: [], birth_date: '1980-01-01', birth_country: 'IT' }

const { keys } = await api.cardKeys();   // [{ kty: 'OKP', crv: 'Ed25519', x, kid, use: 'sig', alg: 'EdDSA' }]

const { status, already, association } = await api.confirmEnrollment(token);   // do link recebido por e-mail
// { status: 'pending', already: false, association: { name, slug } } — 400 invalid_token quando expirado, 409 statuto_outdated

// 409 identification_required: a conta não está identificada; err.errors indica o que falta. Peça os dados e repita:
await api.confirmEnrollment(token, { dob: '1985-03-10', birthplace: 'Lyon', birth_country: 'FR' });

// 409 address_required: a associação pede um endereço a todos os associados. Peça-o e repita (com a identificação, se já informada):
await api.confirmEnrollment(token, undefined, { line: 'Via Roma 1', postal_code: '20100', city: 'Milano', province: 'MI' });

O código fiscal é opcional: error é invalid, mismatch ou null, e hints traz names_swapped quando o código confere trocando sobrenome e nome. Os dados de nascimento de identification e o endereço viajam no corpo da requisição, nunca no link. Veja Associados sem código fiscal.

As chaves mudam raramente: guarde-as em cache e recarregue-as uma vez por dia, ou quando encontrar um kid desconhecido. O resto da verificação off-line está em Incorporação e verificação das carteirinhas.

Esses endpoints têm um limite por IP (60 requisições por minuto na verificação e no código fiscal): para volumes maiores, use um cliente confidencial com verify:read.