API pública

Ver como Markdown

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

Los endpoints que no necesitan ni credenciales ni inicio de sesión. Se pueden usar desde cualquier página, desde un escáner, desde un servidor. publicApi({ apiUrl?, fetch? }) acepta las mismas opciones de red que las demás clases.

Método	Endpoint
`verifyCard(cardToken)`	`GET /v1/verify/{card_token}`	«¿este carné está activo ahora mismo?» — solo el estado y el final de la validez
`association(slug, { locale }?)`	`GET /v1/aps/{slug}`	perfil público: imagen, tipos de carné con sus cuotas, estatuto en vigor, cómo admite a los socios, si recoge su dirección (`member_address`)
`validateFiscalCode(input)`	`POST /v1/validate/fiscal-code`	estructura y carácter de control; con los datos personales, también su coherencia — y lo que contiene el código (`birth_date`, `birth_country`). Para una persona nacida en el extranjero, envía `country`
`cardKeys()`	`GET /v1/card-keys`	las claves públicas (JWKS, Ed25519) que verifican los tokens sin conexión
`confirmEnrollment(token, identification?, address?)`	`POST /v1/enroll/confirm`	consume el token del enlace «confirma tu solicitud» que se envía cuando un sistema inscribe una cuenta existente; después de un `409 identification_required` se repite con `identification`, después de un `409 address_required` con `address`
`events.list(slug, params?)` · `events.get(slug, event, { locale }?)`	`GET /v1/aps/{slug}/events[/{event}]`	los eventos públicos de una asociación, con las plazas que quedan por tipo (guía)
`confirmRegistration(token)`	`POST /v1/registrations/confirm`	consume el token del enlace «confirma tu inscripción» de un invitado: la inscripción, con el `token` del QR cuando está confirmada
`viewRegistration(token)`	`POST /v1/registrations/view`	lee la plaza que hay detrás del enlace propio de un invitado (el correo que confirma la plaza): su estado y, mientras está confirmada, el `token` del QR; funciona hasta que el evento termina (desde la 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);   // desde el enlace recibido por correo
// { status: 'pending', already: false, association: { name, slug } } — 400 invalid_token si ha caducado, 409 statuto_outdated

// 409 identification_required: la cuenta no está identificada; err.errors indica lo que falta. Pídelo y repite:
await api.confirmEnrollment(token, { dob: '1985-03-10', birthplace: 'Lyon', birth_country: 'FR' });

// 409 address_required: la asociación pide una dirección a todos sus socios. Pídela y repite (con la identificación, si ya se dio):
await api.confirmEnrollment(token, undefined, { line: 'Via Roma 1', postal_code: '20100', city: 'Milano', province: 'MI' });

El código fiscal es opcional: error es invalid, mismatch o null, y hints contiene names_swapped cuando el código coincide al intercambiar apellidos y nombre. Los datos de nacimiento de identification y la dirección viajan en el cuerpo de la petición, nunca en el enlace. Consulta Socios sin código fiscal.

Las claves cambian pocas veces: guárdalas en caché y vuelve a cargarlas una vez al día, o cuando encuentres un kid desconocido. El resto de la verificación sin conexión está en Integración y verificación de carnés.

Estos endpoints tienen un límite por IP (60 peticiones por minuto en la verificación y en el código fiscal): para volúmenes mayores, usa un cliente confidencial con verify:read.