Événements et inscriptions

Les événements qu’une association publie depuis sa console sont sur l’API selon le même principe que les cartes : un contenu headless (titre, résumé, description en markdown, images, lieu, dates, liens) et la disponibilité en temps réel par type d’inscription — jamais qui est inscrit. Le vocabulaire est celui du tiers secteur italien : une inscription (iscrizione) et, quand il y a un montant, une contribution (contributo).

Avant de commencer

Votre client a besoin des autorisations events:read, registrations:read et registrations:write (voir Autorisations, erreurs et limites). Pour faire des essais sans toucher aux données réelles, utilisez la sandbox : l’association jumelle peut publier des événements comme la vraie.

Deux visibilités

visibility	Qui le voit	Qui s’inscrit
members_only (par défaut)	seulement avec un jeton de membre ou le client de l’association	les membres avec une carte valable
public	tout le monde, sans connexion : GET /v1/aps/{slug}/events	les membres et — quand le type d’inscription n’exige pas de carte — les invités

Un événement public montre aux visiteurs de votre site le contenu et les types d’inscription avec les places restantes ; les événements réservés aux membres n’apparaissent qu’après la connexion.

Afficher les événements

page publique, sans connexion

import { publicApi } from '@vimine/sdk';
const api = publicApi();
const { items } = await api.events.list('your-slug', { filter: 'upcoming' });
const event = await api.events.get('your-slug', 'jazz-night');

après Se connecter avec Vimine (événements réservés aux membres compris)

const { items } = await vimine.events.list();           // events:read
const event = await vimine.events.get('jazz-night');

Chaque événement porte registration_types[] : amount (0 = gratuit), currency, remaining (places restantes, null = illimitées), open et — quand il n’est pas ouvert — reason (sold_out, registration_not_open, registration_closed). status vaut published, completed (la date est passée) ou cancelled.

Sans écrire de code : l’élément <vimine-events> affiche la liste avec les boutons d’inscription.

Une personne qui n’est pas encore membre

Un événement public atteint aussi des personnes qui ne sont pas membres : c’est le moment où une personne décide de le devenir. La page d’adhésion de l’association sur Vimine s’ouvre avec l’événement, et la personne adhère et réserve en une seule étape :

https://app.vimine.network/enroll/your-slug?event=jazz-night

la même adresse, depuis votre code

import { eventEnrollUrl } from '@vimine/sdk/elements';
const url = eventEnrollUrl('https://app.vimine.network', 'your-slug', 'jazz-night', 'en');

Ce que devient la place dépend de l’état de l’adhésion, et la page le dit à la personne :

L’adhésion	La place
est active tout de suite (carte gratuite, sans approbation)	confirmée, quand l’inscription à l’événement est gratuite
attend l’approbation ou la cotisation	pour une inscription réservée aux membres : retenue jusqu’à ce que la carte soit active, puis, si elle est gratuite, confirmée d’elle-même. Pour une inscription ouverte à tous : confirmée tout de suite, comme pour un non-membre
l’inscription à l’événement demande une contribution	retenue jusqu’à l’échéance fixée par l’association : confirmée quand celle-ci enregistre la contribution
l’adresse e-mail n’est pas encore confirmée	rien n’est retenu : la place est demandée quand la personne confirme son adresse depuis le lien reçu par e-mail, et un e-mail lui dit comment cela s’est passé

Une personne déjà membre utilise la même page : elle se connecte et réserve d’un seul bouton, sans rien remplir (&signin=1 ouvre tout de suite la connexion). Cela s’applique aux événements public publiés et encore à venir : avec tout autre slug, la page est la page d’adhésion ordinaire.

La page publique de l’événement sur Vimine (/agenda/your-slug/jazz-night) et <vimine-events> offrent déjà aux visiteurs cette porte d’entrée : Adhérer à l’association et réserver.

Inscrire un membre

Avant d’afficher le bouton, demandez à l’API si le membre peut s’inscrire — la réponse dit pourquoi il ne le peut pas :

const { can_register, types } = await vimine.events.eligibility('jazz-night');
// types[i].reasons: membership_required, membership_not_active, membership_not_yet_valid, sold_out, max_per_user, registration_closed, …

Puis inscrivez-le (registrations:write) :

const reg = await vimine.registrations.create('jazz-night', { registration_type: types[0].uid, note: 'Je viens avec ma sœur' });
if (reg.status === 'confirmed') drawQr(reg.token);           // type gratuit : confirmée, QR prêt
if (reg.status === 'reserved') show(reg.payment_instructions); // contribution : réservée jusqu’au paiement

• Un type gratuit confirme tout de suite et renvoie token : le contenu du QR que le membre présente à l’entrée (dessinez-le vous-même, avec la bibliothèque que vous préférez).
• Un type avec contribution réserve la place (reserved_until) et renvoie les instructions de paiement de l’association ; le secrétariat confirme quand il enregistre la contribution — le membre reçoit un e-mail et, à partir de là, vimine.registrations.get(id) porte le token. Les paiements par carte bancaire arrivent avec Stripe.
• Si la carte du membre attend encore son activation, l’inscription reste reserved et se confirme d’elle-même quand la carte devient active.
• 422 not_eligible porte dans errors[] les mêmes raisons que l’appel d’éligibilité.

Les inscriptions du membre : vimine.registrations.list({ filter: 'upcoming' }) ; l’annulation dans la fenêtre de l’événement (registration.cancellation_hours heures avant le début) : vimine.registrations.cancel(id) — plus tard, 409 window_closed.

Invités (événements publics)

Un visiteur sans compte Vimine peut s’inscrire à un événement public, sur un type d’inscription qui n’exige pas de carte, depuis votre serveur (client confidentiel, registrations:write) :

server

await srv.registrations.guest('jazz-night', { email, first_name, last_name, registration_type });
// → { status: 'accepted' }, toujours

Aucun compte n’est créé. L’invité reçoit un e-mail avec un lien de confirmation (valable 24 heures) qui mène à la page de l’événement sur Vimine : avec un type gratuit, la place y est confirmée et le QR affiché tout de suite ; avec une contribution, la place reste réservée avec les instructions de paiement. Si vous préférez héberger vous-même la page de confirmation, consommez le jeton du lien avec api.confirmRegistration(token).

Une fois la place confirmée — tout de suite avec un type gratuit, quand la contribution est enregistrée sinon — l’invité reçoit un second e-mail avec son propre lien : il ouvre la page de l’événement avec le QR à présenter à l’entrée, et il fonctionne jusqu’à la fin de l’événement (un événement reporté le conserve). Un invité n’a pas d’espace personnel : le lien est sa place, jamais le QR lui-même (un e-mail transféré n’est pas une place). Si vous hébergez vous-même cette page, lisez la place avec api.viewRegistration(token) (SDK depuis 0.3.2).

La réponse est toujours 202 { status: 'accepted' } : l’API ne révèle jamais si une adresse est déjà inscrite. Les problèmes d’éligibilité (sold_out, membership_required pour un type réservé aux membres) sont des 422.

Fiscalité

Selon le Code du tiers secteur italien, les contributions des non-membres sont des recettes commerciales : la console le signale quand un événement est rendu public, et chaque contribution est classée automatiquement d’après l’adhésion qu’avait l’inscription au moment du paiement.

À l’entrée

Le QR d’une inscription est un jeton signé comme celui de la carte : le même scanner et le même appel l’acceptent.

server (tourniquet, scanner, accueil)

const r = await srv.checkins.create(scannedToken);
if (r.kind === 'registration') {
    // r.verdict: valid | already_checked_in | not_confirmed | cancelled | event_cancelled | membership_invalid
    // r.first : true au premier passage ; r.membership_verdict quand le type exige une carte
}

La vérification publique répond aussi pour un jeton d’inscription : GET /v1/verify/{token} → { status, kind: 'registration', event: { slug, starts_at } }, sans données personnelles.

Depuis votre back-office

Les inscriptions d’un événement — identifiant, état, type, adhésion, entrée, sans données personnelles — sont srv.registrations.listForEvent(slug, { status, limit, cursor }) (registrations:read, formules avec listes via l’API). Les noms restent dans la console de l’association.

Références

• SDK navigateur · SDK serveur · <vimine-events> · Types
• API HTTP : les opérations étiquetées events et registrations dans la référence.