# Panoramica

> Cosa offre l'API di Vimine a chi sviluppa per un'associazione, e i concetti da conoscere prima di iniziare.

URL: https://developers.vimine.network/start/overview/

Vimine è la piattaforma di tesseramento per APS ed enti del Terzo Settore. Ogni associazione ha i suoi
soci, le sue tessere, il suo statuto; con l'API un sito o un'app **dell'associazione, o per l'associazione**
può usare tutto questo senza rifare nulla.

## Cosa puoi fare

| | Come | Con che credenziali |
|---|---|---|
| **Accedi con Vimine** — i soci entrano nel tuo sito con il loro account | OAuth 2.1 + PKCE, pagina di accesso e consenso su vimine.network | un client *pubblico* o *nativo* (solo `client_id`) |
| **API del socio** — profilo, tessera e verdetto, richiesta di tesseramento, statuto, app collegate | `GET /v1/me`, `/v1/me/membership`, … con il token del socio | i permessi che il socio ha concesso |
| **Integrazioni server** — i sistemi dell'associazione leggono lo stato delle tessere | `client_credentials` | un client *riservato* (`client_id` + `client_secret`) |
| **Verifica tessere** — «questa tessera è attiva adesso?», anche offline | `GET /v1/verify/{card_token}`, chiavi pubbliche Ed25519 | nessuna |
| **Profilo pubblico e tesseramento** — grafica, tipi di tessera, statuto in vigore; modulo di iscrizione | `GET /v1/aps/{slug}`, pagina `enroll` incorporabile | nessuna |

## I concetti

- **Associazione e slug.** Ogni associazione ha uno *slug* (`https://app.vimine.network/enroll/<slug>`); i
  client appartengono a un'associazione e i token che emettono valgono solo per quella.
- **Client.** Un'integrazione registrata dalla console **Sviluppatori** dell'app Vimine: ha un tipo (sito web,
  app nativa, server), un ambiente (*Test* o *Produzione*), dei redirect URI, delle origini ammesse e i permessi
  che può chiedere. Vedi [Registra un client](https://developers.vimine.network/start/register-a-client/).
- **Permessi (scope).** Cosa un token può fare: `profile:read`, `membership:read`, `membership:request`, … Il
  socio li vede e li concede sulla pagina di consenso. Tabella completa in
  [Permessi, errori e limiti](https://developers.vimine.network/guides/scopes-and-errors/).
- **Token.** L'access token del socio dura 10 minuti; il refresh token ruota a ogni uso e dura 30 giorni (14 di
  inattività). Il token di un client riservato dura 1 ora. L'SDK rinnova tutto da solo.
- **`sub`.** L'identificativo del socio che vedi nei token e in `/v1/me` (`vms_…`) è **specifico per la tua
  associazione**: stabile nel tempo, diverso in ogni associazione, mai un id interno.
- **Verdetto.** Ciò che conta allo scanner: `valid`, `expired`, `statuto_required` (la riaccettazione dello
  statuto è scaduta) o `inactive`.
- **Token della tessera.** La tessera digitale è un token firmato (`vmt_…`) mostrato come QR, con una finestra di
  validità; ruota a ogni cambio di stato e comunque ogni 90 giorni.
- **Sandbox.** Un'associazione gemella con soci sintetici in ogni stato, dove i client di test sono attivi
  subito. Vedi [Sandbox e client di test](https://developers.vimine.network/guides/sandbox/).

## Dove stanno le cose

| | |
|---|---|
| Pagine di accesso, consenso e uscita | `https://app.vimine.network/authorize`, `/oauth/logout` |
| API | `https://api.vimine.network/v1/…` — documento OpenAPI in `/v1/openapi.json`, discovery in `/.well-known/oauth-authorization-server` |
| Chiavi pubbliche delle tessere | `https://api.vimine.network/.well-known/vimine-card-keys.json` |
| SDK | `@vimine/sdk` su npm: `@vimine/sdk` (browser), `@vimine/sdk/react`, `@vimine/sdk/server` |
| Per un assistente di programmazione | `https://developers.vimine.network/llms.txt`: l'indice delle pagine in Markdown, con le regole da seguire; `llms-full.txt` tutto in un file; ogni pagina in Markdown, `/guides/sign-in/` → `/guides/sign-in.md` |

## Prossimi passi

1. [Registra un client](https://developers.vimine.network/start/register-a-client/) dalla console.
2. [Installa l'SDK](https://developers.vimine.network/start/install/).
3. Segui [Accedi con Vimine](https://developers.vimine.network/guides/sign-in/), oppure [Integrazioni server](https://developers.vimine.network/guides/server/) se lavori per
   i sistemi dell'associazione.