Eventos e inscrições

Os eventos que uma associação publica pelo seu console estão na API com o mesmo princípio das carteirinhas: conteúdo headless (título, resumo, descrição em markdown, imagens, local, datas, links) e disponibilidade em tempo real por tipo de inscrição — nunca quem está inscrito. O vocabulário é o do terceiro setor italiano: uma inscrição (iscrizione) e, quando há um valor, uma contribuição (contributo).

Antes de começar

O seu cliente precisa das permissões events:read, registrations:read e registrations:write (veja Escopos, erros e limites). Para experimentar sem tocar em dados reais, use o sandbox: a associação gêmea pode publicar eventos como a real.

Duas visibilidades

visibility	Quem vê	Quem se inscreve
members_only (padrão)	só com um token de associado ou com o cliente da própria associação	associados com uma carteirinha válida
public	qualquer pessoa, sem login: GET /v1/aps/{slug}/events	associados e — quando o tipo de inscrição não exige carteirinha — convidados

Um evento público mostra aos visitantes do seu site o conteúdo e os tipos de inscrição com as vagas restantes; os eventos só para associados aparecem apenas depois do login.

Mostrar os eventos

página pública, sem login

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');

depois do Entrar com Vimine (incluindo os eventos só para associados)

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

Cada evento traz registration_types[]: amount (0 = gratuito), currency, remaining (vagas restantes, null = ilimitadas), open e — quando não está aberto — reason (sold_out, registration_not_open, registration_closed). status é published, completed (a data já passou) ou cancelled.

Sem escrever código: o elemento <vimine-events> mostra a lista com os botões de inscrição.

Quem ainda não é associado

Um evento público também chega a quem não é associado: é o momento em que uma pessoa decide se tornar um. A página de adesão da associação no Vimine se abre com o evento, e a pessoa se associa e reserva num só passo:

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

o mesmo endereço, a partir do seu código

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

O que acontece com a vaga depende da situação da adesão, e a página informa a pessoa:

A adesão	A vaga
fica ativa na hora (carteirinha gratuita, sem aprovação)	confirmada, quando a inscrição no evento é gratuita
aguarda a aprovação ou a taxa	para uma inscrição só para associados: guardada até a carteirinha ficar ativa, e então, quando é gratuita, confirmada sozinha. Para uma inscrição aberta a todos: confirmada na hora, como para quem não é associado
a inscrição no evento pede uma contribuição	guardada até o prazo definido pela associação: confirmada quando ela registra a contribuição
o endereço de e-mail ainda não foi confirmado	nada é guardado: a vaga é pedida quando a pessoa confirma o endereço pelo link do e-mail, e um e-mail conta a ela como foi

Quem já é associado usa a mesma página: entra e reserva com um botão, sem nada para preencher (&signin=1 abre o login na hora). Isso vale para os eventos public publicados e que ainda não aconteceram: com qualquer outro slug, a página é a página de adesão comum.

A página pública do evento no Vimine (/agenda/your-slug/jazz-night) e o <vimine-events> já oferecem aos visitantes esse caminho: Associe-se e reserve.

Inscrever um associado

Antes de mostrar o botão, pergunte à API se o associado pode se inscrever — a resposta diz por que não:

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, …

Depois faça a inscrição (registrations:write):

const reg = await vimine.registrations.create('jazz-night', { registration_type: types[0].uid, note: 'Vou com a minha irmã' });
if (reg.status === 'confirmed') drawQr(reg.token);           // tipo gratuito: confirmada, QR pronto
if (reg.status === 'reserved') show(reg.payment_instructions); // com contribuição: reservada até o pagamento

• Um tipo gratuito confirma na hora e devolve token: o conteúdo do QR que o associado mostra na entrada (desenhe-o você mesmo, com a biblioteca que preferir).
• Um tipo com contribuição reserva a vaga (reserved_until) e devolve as instruções de pagamento da associação; a secretaria confirma quando registra a contribuição — o associado recebe um e-mail e a partir daí vimine.registrations.get(id) traz o token. Os pagamentos com cartão chegam com o Stripe.
• Se a carteirinha do associado ainda está aguardando a ativação, a inscrição fica reserved e se confirma sozinha quando a carteirinha fica ativa.
• 422 not_eligible traz em errors[] os mesmos motivos da chamada de elegibilidade.

As inscrições do associado: vimine.registrations.list({ filter: 'upcoming' }); o cancelamento dentro da janela do evento (registration.cancellation_hours horas antes do início): vimine.registrations.cancel(id) — depois, 409 window_closed.

Convidados (eventos públicos)

Um visitante sem conta Vimine pode se inscrever num evento público, num tipo de inscrição que não exige carteirinha, a partir do seu servidor (cliente confidencial, registrations:write):

servidor

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

Nenhuma conta é criada. O convidado recebe um e-mail com um link de confirmação (válido por 24 horas) que leva à página do evento no Vimine: com um tipo gratuito a vaga é confirmada ali e o QR aparece na hora; com uma contribuição a vaga fica reservada com as instruções de pagamento. Se preferir hospedar você mesmo a página de confirmação, consuma o token do link com api.confirmRegistration(token).

Quando a vaga é confirmada — na hora com um tipo gratuito, quando a contribuição é registrada nos outros casos — o convidado recebe um segundo e-mail com um link próprio: ele abre a página do evento com o QR para mostrar na entrada, e funciona até o fim do evento (um evento adiado o mantém). Um convidado não tem área pessoal: o link é a vaga dele, nunca o QR em si (um e-mail encaminhado não é uma vaga). Se você hospedar essa página, leia a vaga com api.viewRegistration(token) (SDK desde a 0.3.2).

A resposta é sempre 202 { status: 'accepted' }: a API nunca revela se um endereço já está cadastrado. Os problemas de elegibilidade (sold_out, membership_required para um tipo só para associados) são 422.

Impostos

Pelo Código do Terceiro Setor italiano, as contribuições de quem não é associado são receitas comerciais: o console avisa isso quando um evento se torna público, e cada contribuição é classificada automaticamente a partir da carteirinha que a inscrição tinha no momento do pagamento.

Na entrada

O QR da inscrição é um token assinado como o da carteirinha: o mesmo leitor e a mesma chamada o aceitam.

servidor (catraca, leitor, balcão)

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 na primeira passagem; r.membership_verdict quando o tipo exige uma carteirinha
}

A verificação pública também responde a um token de inscrição: GET /v1/verify/{token} → { status, kind: 'registration', event: { slug, starts_at } }, sem dados pessoais.

Pelo seu back office

As inscrições de um evento — id, status, tipo, carteirinha, check-in, sem dados pessoais — são srv.registrations.listForEvent(slug, { status, limit, cursor }) (registrations:read, planos com listas via API). Os nomes ficam no console da associação.

Referências

• SDK do navegador · SDK de servidor · <vimine-events> · Tipos
• API HTTP: as operações com as tags events e registrations na referência.