# Ammissione e attivazione

> Come un'associazione ammette i soci, quando si versa la quota, quando la tessera vale alla porta — e cosa dire a chi si iscrive dal tuo sito.

URL: https://developers.vimine.network/guides/admission/

Diventare socio non è un pagamento: è un **atto dell'associazione**. Per il Codice del Terzo settore (art. 23) è
l'organo di amministrazione ad accogliere la domanda, salvo che lo statuto disponga diversamente. Ogni associazione
su Vimine dichiara come ammette i propri soci, e la tua integrazione lo legge prima ancora di mostrare il modulo.

## Cosa aspettarsi, prima di chiedere

```
GET https://api.vimine.network/v1/aps/{slug}
→ { "aps": { …, "admission": { "model": "board", "delay_hours": 24 }, "approval_required": true } }
```

| `admission.model` | Cosa succede a una domanda |
| --- | --- |
| `board` | resta **in attesa** finché il consiglio (o chi ne ha la delega) non la accoglie; la quota si versa **dopo** l'ammissione |
| `provisional` | il socio è ammesso subito, in via provvisoria; il consiglio ratifica più tardi |
| `automatic` | l'adesione è attiva appena le condizioni sono soddisfatte: subito se gratuita, al versamento della quota se a pagamento |

`delay_hours` sono le ore tra l'ammissione e una **tessera utilizzabile** (0 = subito). È una cautela che molte
associazioni con una sede aperta al pubblico adottano: l'adesione è attiva dall'ammissione, ma la tessera vale alla
porta solo dopo. Dillo a chi si iscrive: *«la tessera sarà utilizzabile dopo 24 ore»* evita una discussione
all'ingresso.

`approval_required` resta per compatibilità: vale `true` quando il modello è `board`. Leggi `admission`.

## Le risposte a una domanda

`POST /v1/me/membership`, `POST /v1/enroll/confirm` e `GET /v1/me/membership` dicono la stessa cosa, con gli stessi
campi:

| Campo | Significato |
| --- | --- |
| `status` | `pending` · `active` · `suspended` · `revoked` · `rejected` |
| `pending_reasons` | perché è ancora in attesa, **nell'ordine**: `approval` (l'associazione deve decidere), poi `payment` (la quota). Vuoto quando è attiva |
| `payment_open` | la quota si può versare adesso? `false` finché manca l'ammissione: **l'ammissione apre il pagamento** |
| `valid_from` | da quando la tessera è utilizzabile, per un'adesione attiva dentro l'intervallo; `null` altrimenti |
| `usable` *(solo `GET /v1/me/membership`)* | la tessera vale alla porta in questo momento |
| `card` *(solo `GET /v1/me/membership`)* | il token firmato — `null` finché l'adesione non è attiva |

Con il modello `board` e un tipo a pagamento la sequenza è:

1. domanda → `pending`, `["approval", "payment"]`, `payment_open: false` — **non mostrare** istruzioni o pulsanti di
   pagamento;
2. l'associazione accoglie la domanda → `["payment"]`, `payment_open: true` — ora sì; l'interessato riceve anche
   un'e-mail;
3. quota registrata → `active`, eventualmente con un `valid_from` nel futuro;
4. passato `valid_from` → `usable: true`, e la tessera risponde `valid` a chi la verifica.

Prima ancora dell'ammissione, chi chiede una tessera deve essere **identificato** — con un codice fiscale oppure con
data, luogo e Stato di nascita: un profilo che non lo è risponde `identification_required`. Da lì in poi l'ammissione
è la stessa per tutti, con o senza codice fiscale (vedi [Soci senza codice fiscale](https://developers.vimine.network/guides/members-without-cf/)).

## Quando la domanda non è accolta

`rejected` è un esito a sé: non è una revoca (che esclude chi era socio), è una domanda **non accolta**. La decisione
è motivata e comunicata all'interessato dall'associazione, che entro sessanta giorni può chiedere che si pronunci
l'assemblea. Per la tua integrazione: nessuna tessera, nessun pagamento da proporre, e il messaggio giusto è
rimandare all'associazione.

## Tessera attiva, non ancora utilizzabile

Dentro l'intervallo la tessera **esiste** — il socio la vede, la salva nel Wallet — ma non vale ancora:

- `GET /v1/me/membership` → `status: "active"`, `verdict: "not_yet_valid"`, `usable: false`, `valid_from`;
- `GET /v1/verify/{token}` → `{ "status": "inactive", "reason": "not_yet_valid", "valid_from": "…" }`;
- `POST /v1/checkins` → `verdict: "not_yet_valid"` con `valid_from`; **la scansione viene registrata comunque**;
- il token porta lo stesso istante in `nbf`: uno scanner offline arriva alla stessa risposta da solo (vedi
  [Embed e verifica tessere](https://developers.vimine.network/guides/embed-and-verify/)).

Per gli eventi riservati ai soci, l'idoneità risponde `membership_not_yet_valid` se l'evento comincia prima di
`valid_from`; per tutto ciò che comincia dopo, il socio si iscrive normalmente.

## Cosa è cambiato (versione 2026-09-19)

Tutto additivo, ma visibile a chi confronta valori:

- `status` può valere **`rejected`**; `verdict` può valere **`not_yet_valid`**; `reason` di `/v1/verify` anche
  `not_yet_valid`;
- `pending_reasons` è **ordinato** (`approval` prima di `payment`): prima l'ordine non era significativo;
- nuovi campi `admission`, `payment_open`, `valid_from`, `usable`; `payment_instructions` arriva solo quando il
  pagamento è aperto;
- `card` è `null` — e `/v1/me/membership/card`, `card.svg`, `card/email`, `wallet/google` rispondono
  `409 not_active` — finché l'adesione non è attiva;
- nuovo motivo di non idoneità agli eventi: `membership_not_yet_valid`.